Metadata-Version: 2.1
Name: jhub-client
Version: 0.1.1
Summary: Library and Client for managing, benchmarking, and interacting with jupyterhub
Home-page: https://github.com/costrouc/jhub-client
Author: Christopher Ostrouchov
Author-email: chris.ostrouchov@gmail.com
License: UNKNOWN
Description: # JupyterHub Client
        
        Automation of JupyterHub
        
        # Command Line Usage
        
        Below are some example use cases of the tool. Note that with an admin
        api token you can impersonate users and create temporary
        users. Service api tokens do not have an associated user therefore
        must run as existing users or temporary users.
        
        Set the api token used for `jhub-client`.
        
        ```shell
        export JUPYTERHUB_API_TOKEN=<api-token>
        ```
        
        ## Run
        
        ```shell
        usage: __main__.py run [-h] -n NOTEBOOK [--hub HUB] [-u USERNAME]
                               [--user-options USER_OPTIONS] [--temporary-user] [-d]
                               [--stop-server] [--validate]
                               [--kernel-spec KERNEL_SPEC]
                               [--output-filename OUTPUT_FILENAME]
        
        optional arguments:
          -h, --help            show this help message and exit
          -n NOTEBOOK, --notebook NOTEBOOK
                                notebook to run
          --hub HUB             url for running jupyterhub cluster
          -u USERNAME, --username USERNAME
                                username to run notebook as
          --user-options USER_OPTIONS
                                json object representing user server options
          --temporary-user      create user temporarily if does not exist
          -d, --daemonize       run notebook asyncronously
          --stop-server         stop server after completion of notebook
          --validate            validate notebook output matches
          --kernel-spec KERNEL_SPEC
                                kernel spec to launch is not specified will use
                                default
          --output-filename OUTPUT_FILENAME
                                output filename for results of running notebook
        ```
        
        ### Run notebook as given token user syncronously
        
        You can run a given notebook as a pre-existing user syncronously. The
        api token either has to be for the given user or an admin token.
        
        ```shell
        jhubctl --verbose run --notebook <notebook> --hub <hub_url>
        ```
        
        ### Run notebook as given token user syncronously and validate notebook output matches
        
        You can run a given notebook as a pre-existing user syncronously. The
        api token either has to be for the given user or an admin token.
        
        ```shell
        jhubctl run --notebook <notebook> --hub <hub_url> --validate
        ```
        
        ### Run notebook as given token user asyncronously and shutdown server after completion
        
        You can run a given notebook as a pre-existing user asyncronously and
        stop server after completion. The api token either has to be for the
        given user or an admin token.
        
        ```shell
        jhubctl run --notebook <notebook> --hub <hub_url> --daemonize --stop-server
        ```
        
        ### Run notebook as given token user with user options
        
        While this is an advanced use case, it is often times encountered
        with kubernetes jupyerhub clusters where you may want to select a
        given profile e.g. small, medium, gpu jupyterlab session. For these
        clusters you must supply `--user-options='{"profile": 0}'` where 0 is
        replaced with the index of the profile you would like to choose. It is
        possible for other more customized jupyterhub clusters that different
        options must be used.
        
        ```shell
        jhubctl run --notebook <notebook> --hub <hub_url> --user-options='{"profile": 1}'
        ```
        
        ### Run notebook as given token user with user options
        
        You can run a given notebook with any available kernel spec.
        
        ```shell
        jhubctl run --notebook <notebook> --hub <hub_url> --kernel-spec=python3
        ```
        
        ### Run a given notebook as a temporary user
        
        Additionally you can temporarily create a user `user-<uuid>` or supply
        the temporary user's username. The username will be deleted upon
        completion. The api token requires admin permissions.
        
        ```shell
        jhubctl run --temporary-user --notebook <notebook> --hub <hub_url> [--username <username>]
        ```
        
        # Testing
        
        Bring up test jupyterhub cluster
        
        ```shell
        cd tests/assets
        docker-compose up --build
        ```
        
        Run unit tests
        
        ```shell
        pytest
        ```
        
        # FAQ
        
        ## Creating an API Token
        
        Login to the given jupyterhub cluster
        
        ![qhub login](./images/login.png)
        
        Access the hub control page. The url will be `<hub_url>/hub/home`.
        
        ![qhub home](./images/home.png)
        
        Click on `Token` in top left corner and request new api token. This
        token will have the permissions of the user. Make sure to set the
        environment variable `JUPYTERLAB_API_TOKEN` to the value of the given
        token.
        
        ![qhub token](./images/token.png)
        
        If you want to add a service token instead edit the jupyterhub
        configuration.
        
        ```python
        c.JupyterHub.services = [
         {
                'name': '<my-service-name>',
                'api_token': '<my-super-secret-long-token>',
                'oauth_no_confirm': True,
                'admin': True
            }
        ]
        ```
        
Keywords: jupyterhub,jupyter,benchmark
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3 :: Only
Description-Content-Type: text/markdown
Provides-Extra: dev
