Metadata-Version: 2.1
Name: callisto-jupyter-d1
Version: 0.0.5
Summary: Jupyter D1 Server for Callisto
Home-page: https://callistoapp.com
Author: Oak City Labs
Author-email: team@oakcity.io
License: UNKNOWN
Description: # jupyter_d1
        
        Jupiter Discovery One server
        
        ## Info
        
        ### Install
        
        `pip install git+https://github.com/OakCityLabs/jupyter_d1.git@branch_name#egg=jupyter_d1`
        
        Once installed, install kernel definitions with
        `jupyter_d1_install_kernels`
        
        ### Start Server
        
        `start_jupyter_d1 --port=8000 --secret_token=user_provided_secret --root_dir=/path/to/working/directory`
        
        ### Run tests
        (Requires pytest, async-asgi-testclient)
        `jupyter_d1_test`
        
        ### How Stuff Works
        
        The Jupyter D1 server sits between a REST client and a Jupyter Kernel.
        Kernels don't understand notebooks.  They just execute commands they receive.
        Jupyter D1 manages the state of the notebook, keeping track of which cell is being
         executed and updating the cells results with the kernel finishes processing.
        
        In the traditional JavaScript Jupyter client, all of this state is held in the web app.
        This makes it impossible to share that state with another client.  
        In Jupyter D1, this state is held in the D1 server and a client can connect at any time
        and ask for the current state.  
        A client may also ask that new code is executed.  The D1 server relays that to the active kernel.
        Kernel results are used to update the current model of the notebook in the D1 server and broadcast
        to clients to update UIs.
        
        Clients should connect to the notebook websocket stream where they will receive a broadcast of all
        the updates to the notebook cells.  Clients can send regular REST requests to initiate action, like
        executing a cell or changing a cell's source code.  A websocket is also avaible for the raw stream
        of kernel messages, but that's not intended for client consumption in the long term.  Kernel messages
        are more of a debugging tool.
        
        ### See Makefile for convenience commands
        
            make save_env    save current development environment using conda to environment.yml
            make load_env    create a development environment using conda from environment.yml (deletes current env definition)
            make show_env    list available conda environments
            make lint        run the linter
            make test        run pytest
            make ci_test     run the linter and then run pytest    
            make run_debug   run the 'uvicorn' server in debug mode
            make docs        open the docs in your browser (mac only, requires server running locally)
            make redoc       open the alternate docs in your browser (mac only, requires server running locally)
        
        ### Documentation
        
        * Run the server with `make run_debug`
        * Open the Swagger UI docs URL with `make docs` [link](http://localhost:8000/docs)
        * Open the ReDoc docs URL with `make docs` [link](http://localhost:8000/redoc)
        
        ### Stream listeners
        
        Run `./ws_listener.py` to echo out messages from the websocket broadcast channels.  Two options are:
        
        * `./ws_listener.py --feed stream` -- Listen to the stream of kernel messages direct from the Jupyter kernel
        * `./ws_listener.py --feed notebook` -- List to the jupyter_d1 stream of updates to notebook cells
        
        ### Paw
        
        See the included Paw file `jupyter_d1.paw` for some examples.  A simple test sequence that might represent
        what a client would do:
        
        * Open the simple notebook
        * Execute a cell by ID -- set x
        * Execute a cell by ID -- increment x
        
        This loads a notebook, executes a cell which assigns a value to `x` and then executes another cell that
        increments the value of `x`.  It's useful to have the stream listeners active to see the results.
        
        ### Testing
        
        * `make test` will pytest and report coverage
        * Just running `pytest` from the top level directory will run all the tests
        * Can specify a specific test with `pytest tests/test_notebooks_websocket.py::TestNotebookWebSocket::test_notebook`
        * VS Code should understand the tests and run them from the editor, but sometimes that seems flakey.
        * If VS Code has trouble finding tests, run `pytest --collect-only` at the cli to check for errors.
        
        ### WebDAV server
        
        * The FastAPI app instantiates a [WebDAV server](https://wsgidav.readthedocs.io/en/latest/index.html) mounted under `/dav`.
        * Currently, this exposes `/tmp` on the local machine.
        * Can be mounted via a WebDAV [client](https://en.wikipedia.org/wiki/WebDAV).
        * Eventually, this will provide clients file level access to the Jupyter working directory.
        * Current username is `user` with password `password`.
        * There is a read-only user called `readonly_user` but permission levels aren't implemented, so this user has full access.
        
        ### Static typing
        
        * Jupyter_D1 uses static typing for compatibility with FastAPI
        * The python runtime ignores type information at the moment.
        * In VS Code, you should enable the `mypy` linter to check typing.
        * [Mypy Cheatsheet](https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html)
        
        ### Authenication with shared secret
        
        * Use the shared secret from the server command line to get an access token
           * curl -H "Authorization: <SHARED_SECRET>" http://127.0.0.1:<port_number>/login/access-token
           * returns {"token":{"access_token":"**ACCESS_TOKEN**","token_type":"bearer"}}
        * Use the returned access token for subsequent requests
           * curl -H "Authorization: Bearer <**ACCESS_TOKEN**>" http://127.0.0.1:<port_number>/notebooks
        
           
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Provides-Extra: full
