{"id":21044982,"url":"https://github.com/quansight/jhub-client","last_synced_at":"2025-05-15T17:33:19.366Z","repository":{"id":42072123,"uuid":"313766200","full_name":"Quansight/jhub-client","owner":"Quansight","description":"Automation of JupyterHub operations and testing","archived":false,"fork":false,"pushed_at":"2022-08-25T18:16:31.000Z","size":258,"stargazers_count":11,"open_issues_count":4,"forks_count":7,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-10-14T04:15:59.064Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Quansight.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-11-17T23:10:21.000Z","updated_at":"2023-11-09T13:53:46.000Z","dependencies_parsed_at":"2022-08-12T04:10:10.694Z","dependency_job_id":null,"html_url":"https://github.com/Quansight/jhub-client","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Quansight%2Fjhub-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Quansight%2Fjhub-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Quansight%2Fjhub-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Quansight%2Fjhub-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Quansight","download_url":"https://codeload.github.com/Quansight/jhub-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225366316,"owners_count":17463020,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-19T14:19:24.638Z","updated_at":"2024-11-19T14:19:26.017Z","avatar_url":"https://github.com/Quansight.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# JupyterHub Client\n\n![PyPI](https://img.shields.io/pypi/v/jhub-client)\n\nAutomation of JupyterHub\n\n# Install\n\n```shell\npip install jhub-client\n```\n\n# Command Line Usage\n\nBelow are some example use cases of the tool. Note that with an admin\napi token you can impersonate users and create temporary\nusers. Service api tokens do not have an associated user therefore\nmust run as existing users or temporary users.\n\nSet the api token used for `jhub-client`.\n\n```shell\nexport JUPYTERHUB_API_TOKEN=\u003capi-token\u003e\n```\n\nOptionally basic authentication can be used instead of token based\n(not recommended but needed in some use cases). In which case\n`username` and `password` are required.\n\n```shell\nexport JUPYTERHUB_USERNAME=\u003cusername\u003e\nexport JUPYTERHUB_PASSWORD=\u003cpassword\u003e\n```\n\n## Token\n\n```shell\n$ jhubctl token --help\nusage: __main__.py token [-h] [--hub HUB] [--name NAME]\n\noptional arguments:\n  -h, --help   show this help message and exit\n  --hub HUB    url for running jupyterhub cluster\n  --name NAME  name to give to jupyterhub api token\n```\n\nA simple command line utility can be used to create a token. This only\nsupports basic authentication (`username` and `password`) login to the\njupyterhub cluster.\n\n## Run\n\n```shell\n$ jhubctl run --help\nusage: __main__.py run [-h] -n NOTEBOOK [--auth-type {token,basic}] [--hub HUB] [-u USERNAME]\n                       [--user-options USER_OPTIONS] [--temporary-user] [-d] [--stop-server] [--validate]\n                       [--kernel-spec KERNEL_SPEC] [--output-filename OUTPUT_FILENAME]\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -n NOTEBOOK, --notebook NOTEBOOK\n                        notebook to run\n  --auth-type {token,basic}\n                        jupyterhub authentication type to use with default of token based\n  --hub HUB             url for running jupyterhub cluster with default of 'http://localhost:8000'\n  -u USERNAME, --username USERNAME\n                        username to run notebook as\n  --user-options USER_OPTIONS\n                        json object representing user server options\n  --temporary-user      create user temporarily if does not exist\n  -d, --daemonize       run notebook asyncronously\n  --stop-server         stop server after completion of notebook\n  --validate            validate notebook output matches\n  --kernel-spec KERNEL_SPEC\n                        kernel spec to launch is not specified will use default\n  --output-filename OUTPUT_FILENAME\n                        output filename for results of running notebook\n```\n\n### Run notebook as given token user syncronously\n\nYou can run a given notebook as a pre-existing user syncronously. The\napi token either has to be for the given user or an admin token.\n\n```shell\njhubctl --verbose run --notebook \u003cnotebook\u003e --hub \u003chub_url\u003e\n```\n\n### Run notebook as given token user syncronously and validate notebook output matches\n\nYou can run a given notebook as a pre-existing user syncronously. The\napi token either has to be for the given user or an admin token.\n\n```shell\njhubctl run --notebook \u003cnotebook\u003e --hub \u003chub_url\u003e --validate\n```\n\n### Run notebook as given token user asyncronously and shutdown server after completion\n\nYou can run a given notebook as a pre-existing user asyncronously and\nstop server after completion. The api token either has to be for the\ngiven user or an admin token.\n\n```shell\njhubctl run --notebook \u003cnotebook\u003e --hub \u003chub_url\u003e --daemonize --stop-server\n```\n\n### Run notebook as given token user with user options\n\nWhile this is an advanced use case, it is often times encountered\nwith kubernetes jupyerhub clusters where you may want to select a\ngiven profile e.g. small, medium, gpu jupyterlab session. For these\nclusters you must supply `--user-options='{\"profile\": 0}'` where 0 is\nreplaced with the index of the profile you would like to choose. It is\npossible for other more customized jupyterhub clusters that different\noptions must be used.\n\n```shell\njhubctl run --notebook \u003cnotebook\u003e --hub \u003chub_url\u003e --user-options='{\"profile\": 1}'\n```\n\n### Run notebook as given token user with user options\n\nYou can run a given notebook with any available kernel spec.\n\n```shell\njhubctl run --notebook \u003cnotebook\u003e --hub \u003chub_url\u003e --kernel-spec=python3\n```\n\n### Run a given notebook as a temporary user\n\nAdditionally you can temporarily create a user `user-\u003cuuid\u003e` or supply\nthe temporary user's username. The username will be deleted upon\ncompletion. The api token requires admin permissions.\n\n```shell\njhubctl run --temporary-user --notebook \u003cnotebook\u003e --hub \u003chub_url\u003e [--username \u003cusername\u003e]\n```\n\n# Testing\n\nBring up test jupyterhub cluster\n\n```shell\ncd tests/assets\ndocker-compose up --build\n```\n\nRun unit tests\n\n```shell\npytest\n```\n\n# FAQ\n\n## Creating an API Token\n\nLogin to the given jupyterhub cluster\n\n![qhub login](./images/login.png)\n\nAccess the hub control page. The url will be `\u003chub_url\u003e/hub/home`.\n\n![qhub home](./images/home.png)\n\nClick on `Token` in top left corner and request new api token. This\ntoken will have the permissions of the user. Make sure to set the\nenvironment variable `JUPYTERHUB_API_TOKEN` to the value of the given\ntoken.\n\n![qhub token](./images/token.png)\n\nIf you want to add a service token instead edit the jupyterhub\nconfiguration.\n\n```python\nc.JupyterHub.services = [\n {\n        'name': '\u003cmy-service-name\u003e',\n        'api_token': '\u003cmy-super-secret-long-token\u003e',\n        'oauth_no_confirm': True,\n        'admin': True\n    }\n]\n```\n\n# Code of Conduct\n\nTo guarantee a welcoming and friendly community, we require contributors to follow our [Code of Conduct](https://github.com/Quansight/.github/blob/master/CODE_OF_CONDUCT.md).\n\n# License\n\n[jhub-client](https://github.com/Quansight/jhub-client/blob/main/LICENSE)\nis BSD-3 Licensed\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquansight%2Fjhub-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fquansight%2Fjhub-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquansight%2Fjhub-client/lists"}