jupyterhub-fancy-profiles


Namejupyterhub-fancy-profiles JSON
Version 0.4.0 PyPI version JSON
download
home_pageNone
SummaryFancy Profile UI for jupyterhub-kubespawner
upload_time2024-12-19 18:01:20
maintainerNone
docs_urlNone
authorNone
requires_pythonNone
licenseNone
keywords jupyterhub
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls. 
            # `jupyterhub-fancy-profiles`

A react based, fancy implementation of user selectable profiles
for use with [jupyterhub-kubespawner](https://github.com/jupyterhub/kubespawner).

![Screenshot showing an image selector](screenshot.png)

## JupyterHub version supported

`jupyterhub-fancy-profiles` version 0.4.0 and above require JupyterHub 5. If you
are using an older version of JupyterHub, please use version 0.3.x.

## Features

1. Interpret a `profileList` given to kubespawner, and render a better looking
   and more featureful selector. This includes descriptions for various options,
   as well as better descriptions for allowing users to 'write-in' a choice.

2. If enabled, interact with a [binderhub](https://github.com/jupyterhub/binderhub/)
   deployed as a JupyterHub service to allow users to _dynamically_ build images
   they want to use, without requiring it to be pre-built.

## Limitations

1. The forms values don't remember their previous state upon refresh

## How to use

### Using with z2jh

This package can be used with any installation of KubeSpawner, but is most
commonly used with an installation of z2jh. It requires installing `jupyterhub-fancy-profiles`
in the `hub` image used by z2jh.

As a convenience, we build and push docker images that can be automatically
used with z2jh!

1. Look at the [list of available tags](https://quay.io/repository/yuvipanda/z2jh-hub-with-fancy-profiles?tab=tags)
   and find a tag that matches the version of z2jh you are using.

2. Use this image in the z2jh config. In the `values.yaml` file you pass to
   `helm`, use the following:

   ```yaml
   hub:
     image:
       name: quay.io/yuvipanda/z2jh-hub-with-fancy-profiles
       tag: <tag-from-the-list>
     extraConfig:
       01-enable-fancy-profiles: |
         from jupyterhub_fancy_profiles import setup_ui
         setup_ui(c)
   ```

3. Run a `helm upgrade` and you should have fancy profiles enabled!

### Using directly with KubeSpawner

After the package is installed, you can have kubespawner use the templates shipped
with this package to provide appropriate UI, by adding the following snippet
to your `jupyterhub_config.py` file:

```python
from jupyterhub_fancy_profiles import setup_ui
setup_ui(c)
```

The `setup_ui` function will setup all the appropriate config as needed. Currently,
it will:

1. Setup extra templates to be made available to kubespawner, to render the
   base HTML for `profile_list`.
2. Setup extra HTTP handlers, primarily for serving our static assets.

## What is in here?

The primary contents are:

1. `jupyterhub_fancy_profiles/templates` contains jinja2 templates, primarily
   `HTML` for constructing the form itself. This can contain multiple templates
   that are composed together using all of jinja2's composition features (like `include`)
2. `src/` contains JS and CSS that are packaged via standard frontend bundling
   tools (`webpack` and `babel`), outputing assets into `jupyterhub_fancy_profiles/static/`.
   This allows us to use _standard_ frontend tooling to write JS & CSS - for
   example, [xterm.js](http://xtermjs.org/) can be used without many complications.

## Why React?

> /\* If this file gets over 200 lines of code long (not counting docs / comments), start using a framework

(from the [BinderHub JS Source Code](https://github.com/jupyterhub/binderhub/blob/036877ffdf0abfde7e84f3972c7d0478cf4f7cb2/binderhub/static/js/index.js#L1))

Dear Reader, the file _did_ get more than 200 lines long, but alas there was no
time to start using a framework. Lesson learnt from that is we should use a
_very lightweight_ framework right from the start, something mainstream that
can attract frontend devs without being so fancy that nobody else can work on
it. Given the size and complexity of this - a complex UI but only a single page -
plain react without typescript seems the correct choice. We will _not_ make
this into a super-heavy, complex application - just a fairly simple one that
uses react.

## Making a Release

We have [automation](https://github.com/pypa/gh-action-pypi-publish/)
set up to make releases to [PyPI](https://pypi.org/project/jupyterhub-fancy-profiles/).
We should release early and often!

1. On your local checkout, make sure you are up to date with the `main` branch

   ```bash
   git checkout main
   git stash
   git pull upstream main # or git pull origin main, as needed
   ```

2. Create a new git tag, with the version of the release.

   ```bash
   git tag -a v<version-number>
   ```

   Leave a simple message here. While ideally a changelog would also be nice,
   at a minimum simply say `Version <version-number>`

3. Push your tag to GitHub

   ```bash
   git push origin --tags
   ```

4. That's it! A new release should be on PyPI shortly.

## Comparisons to the BinderHub UI

The BinderHub project provides a frontend that also allows end users to
build images and launch them. How do you determine when to use that UI
vs `jupyterhub-fancy-profiles` (with Dynamic Image Building integration)?

This project is still young, and these guidelines may change over time.

The _primary_ question is one of _intent_.

Are you building a _persistent JupyterHub_ with many functions (persistent home
directories, multiple profiles for images, resource requirements, strong access
control, etc) that
_also_ happens to need a way for users to dynamically build their own images?
Then use `jupyterhub-fancy-profiles` with BinderHub integration.

Are you building an _ephemeral JupyterHub_ where users may click a link and that
immediately puts them in an _ephemeral_ interactive compute session with
a particular environment and particular content? Use the BinderHub UI.

A useful rubric here is to look for persistent home directory storage. If your
users want that, you probably want to use `jupyterhub-fancy-profiles` with
BinderHub integration. If not, the BinderHub UI is more likely to be used.

## Funding

Funded in part by [GESIS](http://notebooks.gesis.org) in cooperation with
NFDI4DS [460234259](https://gepris.dfg.de/gepris/projekt/460234259?context=projekt&task=showDetail&id=460234259&)
and [CESSDA](https://www.cessda.eu).

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "jupyterhub-fancy-profiles",
    "maintainer": null,
    "docs_url": null,
    "requires_python": null,
    "maintainer_email": null,
    "keywords": "jupyterhub",
    "author": null,
    "author_email": "Yuvi <yuvipanda@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/2e/bf/bad303fb753d03d174938f9e1c702b3f2a1f46aadaedb123f5fefdc7645c/jupyterhub_fancy_profiles-0.4.0.tar.gz",
    "platform": null,
    "description": "# `jupyterhub-fancy-profiles`\n\nA react based, fancy implementation of user selectable profiles\nfor use with [jupyterhub-kubespawner](https://github.com/jupyterhub/kubespawner).\n\n![Screenshot showing an image selector](screenshot.png)\n\n## JupyterHub version supported\n\n`jupyterhub-fancy-profiles` version 0.4.0 and above require JupyterHub 5. If you\nare using an older version of JupyterHub, please use version 0.3.x.\n\n## Features\n\n1. Interpret a `profileList` given to kubespawner, and render a better looking\n   and more featureful selector. This includes descriptions for various options,\n   as well as better descriptions for allowing users to 'write-in' a choice.\n\n2. If enabled, interact with a [binderhub](https://github.com/jupyterhub/binderhub/)\n   deployed as a JupyterHub service to allow users to _dynamically_ build images\n   they want to use, without requiring it to be pre-built.\n\n## Limitations\n\n1. The forms values don't remember their previous state upon refresh\n\n## How to use\n\n### Using with z2jh\n\nThis package can be used with any installation of KubeSpawner, but is most\ncommonly used with an installation of z2jh. It requires installing `jupyterhub-fancy-profiles`\nin the `hub` image used by z2jh.\n\nAs a convenience, we build and push docker images that can be automatically\nused with z2jh!\n\n1. Look at the [list of available tags](https://quay.io/repository/yuvipanda/z2jh-hub-with-fancy-profiles?tab=tags)\n   and find a tag that matches the version of z2jh you are using.\n\n2. Use this image in the z2jh config. In the `values.yaml` file you pass to\n   `helm`, use the following:\n\n   ```yaml\n   hub:\n     image:\n       name: quay.io/yuvipanda/z2jh-hub-with-fancy-profiles\n       tag: <tag-from-the-list>\n     extraConfig:\n       01-enable-fancy-profiles: |\n         from jupyterhub_fancy_profiles import setup_ui\n         setup_ui(c)\n   ```\n\n3. Run a `helm upgrade` and you should have fancy profiles enabled!\n\n### Using directly with KubeSpawner\n\nAfter the package is installed, you can have kubespawner use the templates shipped\nwith this package to provide appropriate UI, by adding the following snippet\nto your `jupyterhub_config.py` file:\n\n```python\nfrom jupyterhub_fancy_profiles import setup_ui\nsetup_ui(c)\n```\n\nThe `setup_ui` function will setup all the appropriate config as needed. Currently,\nit will:\n\n1. Setup extra templates to be made available to kubespawner, to render the\n   base HTML for `profile_list`.\n2. Setup extra HTTP handlers, primarily for serving our static assets.\n\n## What is in here?\n\nThe primary contents are:\n\n1. `jupyterhub_fancy_profiles/templates` contains jinja2 templates, primarily\n   `HTML` for constructing the form itself. This can contain multiple templates\n   that are composed together using all of jinja2's composition features (like `include`)\n2. `src/` contains JS and CSS that are packaged via standard frontend bundling\n   tools (`webpack` and `babel`), outputing assets into `jupyterhub_fancy_profiles/static/`.\n   This allows us to use _standard_ frontend tooling to write JS & CSS - for\n   example, [xterm.js](http://xtermjs.org/) can be used without many complications.\n\n## Why React?\n\n> /\\* If this file gets over 200 lines of code long (not counting docs / comments), start using a framework\n\n(from the [BinderHub JS Source Code](https://github.com/jupyterhub/binderhub/blob/036877ffdf0abfde7e84f3972c7d0478cf4f7cb2/binderhub/static/js/index.js#L1))\n\nDear Reader, the file _did_ get more than 200 lines long, but alas there was no\ntime to start using a framework. Lesson learnt from that is we should use a\n_very lightweight_ framework right from the start, something mainstream that\ncan attract frontend devs without being so fancy that nobody else can work on\nit. Given the size and complexity of this - a complex UI but only a single page -\nplain react without typescript seems the correct choice. We will _not_ make\nthis into a super-heavy, complex application - just a fairly simple one that\nuses react.\n\n## Making a Release\n\nWe have [automation](https://github.com/pypa/gh-action-pypi-publish/)\nset up to make releases to [PyPI](https://pypi.org/project/jupyterhub-fancy-profiles/).\nWe should release early and often!\n\n1. On your local checkout, make sure you are up to date with the `main` branch\n\n   ```bash\n   git checkout main\n   git stash\n   git pull upstream main # or git pull origin main, as needed\n   ```\n\n2. Create a new git tag, with the version of the release.\n\n   ```bash\n   git tag -a v<version-number>\n   ```\n\n   Leave a simple message here. While ideally a changelog would also be nice,\n   at a minimum simply say `Version <version-number>`\n\n3. Push your tag to GitHub\n\n   ```bash\n   git push origin --tags\n   ```\n\n4. That's it! A new release should be on PyPI shortly.\n\n## Comparisons to the BinderHub UI\n\nThe BinderHub project provides a frontend that also allows end users to\nbuild images and launch them. How do you determine when to use that UI\nvs `jupyterhub-fancy-profiles` (with Dynamic Image Building integration)?\n\nThis project is still young, and these guidelines may change over time.\n\nThe _primary_ question is one of _intent_.\n\nAre you building a _persistent JupyterHub_ with many functions (persistent home\ndirectories, multiple profiles for images, resource requirements, strong access\ncontrol, etc) that\n_also_ happens to need a way for users to dynamically build their own images?\nThen use `jupyterhub-fancy-profiles` with BinderHub integration.\n\nAre you building an _ephemeral JupyterHub_ where users may click a link and that\nimmediately puts them in an _ephemeral_ interactive compute session with\na particular environment and particular content? Use the BinderHub UI.\n\nA useful rubric here is to look for persistent home directory storage. If your\nusers want that, you probably want to use `jupyterhub-fancy-profiles` with\nBinderHub integration. If not, the BinderHub UI is more likely to be used.\n\n## Funding\n\nFunded in part by [GESIS](http://notebooks.gesis.org) in cooperation with\nNFDI4DS [460234259](https://gepris.dfg.de/gepris/projekt/460234259?context=projekt&task=showDetail&id=460234259&)\nand [CESSDA](https://www.cessda.eu).\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "Fancy Profile UI for jupyterhub-kubespawner",
    "version": "0.4.0",
    "project_urls": null,
    "split_keywords": [
        "jupyterhub"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "364ad7137a70cdb67e8c5e25b133e8fd223e1a0dcac3b596aa570d3912a34220",
                "md5": "f5a5ab6dabf70234159d773b2664644a",
                "sha256": "c89a301bcd174e88df60a229fcb298f93d61ee82482fae0f4044ae9e2734cebc"
            },
            "downloads": -1,
            "filename": "jupyterhub_fancy_profiles-0.4.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "f5a5ab6dabf70234159d773b2664644a",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": null,
            "size": 983218,
            "upload_time": "2024-12-19T18:01:17",
            "upload_time_iso_8601": "2024-12-19T18:01:17.554404Z",
            "url": "https://files.pythonhosted.org/packages/36/4a/d7137a70cdb67e8c5e25b133e8fd223e1a0dcac3b596aa570d3912a34220/jupyterhub_fancy_profiles-0.4.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "2ebfbad303fb753d03d174938f9e1c702b3f2a1f46aadaedb123f5fefdc7645c",
                "md5": "9e360695a5f39dbd646851be4ef6bff8",
                "sha256": "66a024b2a23bc1d7de70e4764fdadf621ef82b325193bb23f18b033c69bc468e"
            },
            "downloads": -1,
            "filename": "jupyterhub_fancy_profiles-0.4.0.tar.gz",
            "has_sig": false,
            "md5_digest": "9e360695a5f39dbd646851be4ef6bff8",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 1273428,
            "upload_time": "2024-12-19T18:01:20",
            "upload_time_iso_8601": "2024-12-19T18:01:20.456931Z",
            "url": "https://files.pythonhosted.org/packages/2e/bf/bad303fb753d03d174938f9e1c702b3f2a1f46aadaedb123f5fefdc7645c/jupyterhub_fancy_profiles-0.4.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-12-19 18:01:20",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "lcname": "jupyterhub-fancy-profiles"
}
None
Elapsed time: 0.61287s