Merge pull request #371 from bollwyvl/gh-370-hatchling

Adopt hatchling, plugins for python package build

Author: consideRatio

.github/workflows/publish.yaml

@@ -35,14 +35,26 @@ jobs:
 
     steps:
       - uses: actions/checkout@v3
+
       - uses: actions/setup-python@v4
         with:
           python-version: "3.11"
 
+      - uses: actions/setup-node@v3
+        with:
+          cache: yarn
+          node-version: 18.x
+          registry-url: https://registry.npmjs.org
+          cache-dependency-path: labextension/yarn.lock
+
+      - name: Update root build packages
+        run: |
+          pip install --upgrade build pip
+
       - name: Build dist
         run: |
-          pip install jupyter_packaging wheel jupyterlab~=3.0
-          python setup.py sdist bdist_wheel
+          pyproject-build
+          cd dist && sha256sum * | tee SHA256SUMS
 
       - name: Check dist sizes
         run: |
@@ -53,8 +65,9 @@ jobs:
       - name: Javascript package
         run: |
           mkdir jsdist
-          cd labextension
-          jlpm pack --filename ../jsdist/labextension-jlpmpack.tgz
+          cd jsdist
+          npm pack ../labextension
+          sha256sum * | tee SHA256SUMS
 
       - name: Upload Python artifact
         uses: actions/upload-artifact@v3
@@ -112,9 +125,11 @@ jobs:
           name: jsdist
           path: jsdist
 
-      - run: npm publish --dry-run ./jsdist/labextension-jlpmpack.tgz
+      - run: |
+          npm publish --dry-run ./jsdist/jupyterhub-jupyter-server-proxy-*.tgz
 
-      - run: npm publish ./jsdist/labextension-jlpmpack.tgz
+      - run: |
+          npm publish ./jsdist/jupyterhub-jupyter-server-proxy-*.tgz
         if: startsWith(github.ref, 'refs/tags')
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/test.yaml

@@ -43,61 +43,71 @@ jobs:
 
     steps:
       - uses: actions/checkout@v3
+
       - uses: actions/setup-python@v4
         with:
           python-version: "${{ matrix.python-version }}"
 
+      - uses: actions/setup-node@v3
+        with:
+          cache: yarn
+          node-version: 18.x
+          registry-url: https://registry.npmjs.org
+          cache-dependency-path: labextension/yarn.lock
+
+      - name: Update root build packages
+        run: |
+          pip install --upgrade build pip
+
       - name: Build Python package
         run: |
-          pip install jupyter_packaging wheel jupyterlab
-          python setup.py sdist bdist_wheel
+          pyproject-build
 
-      - name: Install Python dependencies
+      - name: Install Python package
         # NOTE: See CONTRIBUTING.md for a local development setup that differs
         #       slightly from this.
         #
         #       Pytest options are set in tests/pytest.ini.
         run: |
-          pip install --upgrade pip
-          pip install jupyter_packaging jupyterlab~=${{ matrix.jupyterlab-version }}.0
-          pip install ./dist/jupyter_server_proxy-*.whl
-          pip install pytest pytest-cov pytest-html
-          # Ensure we don't accidentally depend on notebook
-          if [ "${{ matrix.jupyter-app }}" == "notebook" ]; then
-            pip install "notebook<7"
-          fi
+          pip install -vv $(ls ./dist/jupyter_server_proxy-*.whl)\[acceptance\] 'jupyterlab~=${{ matrix.jupyterlab-version }}.0'
+
+      - name: List Python packages
+        run: |
           pip freeze
+          pip check
 
       - name: Run tests
         run: |
           JUPYTER_TOKEN=secret jupyter-${{ matrix.jupyter-app }} --config=./tests/resources/jupyter_server_config.py &
           sleep 5
           cd tests
-          pytest
+          pytest -k "not acceptance"
 
       - name: Upload pytest and coverage reports
         if: always()
         uses: actions/upload-artifact@v3
         with:
-          name: unit-tests-${{ matrix.python-version }}-${{ matrix.jupyter-app }}-${{ matrix.jupyterlab-version }}-${{ github.run_number }}
+          name: |-
+            unit-tests-${{ matrix.python-version }}-${{ matrix.jupyter-app }}-${{ matrix.jupyterlab-version }}-${{ github.run_number }}
           path: |
             ./build/pytest
             ./build/coverage
 
       - name: Check the Notebook Server extension is installed
         run: |
           jupyter serverextension list
-          jupyter serverextension list 2>&1 | grep -ie "jupyter_server_proxy.*enabled" -
+          jupyter serverextension list 2>&1 | grep -iE "jupyter_server_proxy.*OK" -
 
       - name: Check the Jupyter Server extension is installed
         run: |
           pip install jupyter-server
           jupyter server extension list
-          jupyter server extension list 2>&1 | grep -ie "jupyter_server_proxy.*enabled" -
+          jupyter server extension list 2>&1 | grep -iE "jupyter_server_proxy.*OK" -
 
       - name: Install JupyterLab Extension
         if: matrix.jupyterlab-version == '2'
         run: |
+          export NODE_OPTIONS=--openssl-legacy-provider
           cd labextension
           jupyter labextension install . --no-build --debug
           jupyter lab build --minimize=False --debug
@@ -108,25 +118,21 @@ jobs:
         # jupyterlab.browser_check with jupyterlab 2 and a modern version of
         # python (3.11+).
         #
-        if: ${{ !(matrix.jupyterlab-version == '2' && startsWith(matrix.python-version, '3.1')) }}
+        if: ${{ !(matrix.jupyterlab-version == '2' && startsWith(matrix.python-version, '3.11')) }}
         run: |
           jupyter labextension list
-          jupyter labextension list 2>&1 | grep -ie '@jupyterhub/jupyter-server-proxy.*OK.*'
+          jupyter labextension list 2>&1 | grep -iE '@jupyterhub/jupyter-server-proxy.*OK.*'
           python -m jupyterlab.browser_check
 
-      - name: Install Acceptance test dependencies
-        run: |
-          # the acceptance test requires notebook to run
-          pip install "notebook<7" "robotframework-jupyterlibrary>=0.4.2"
-
       - name: Run acceptance tests
         run: |
-          pytest -k acceptance -s
+          pytest -s -k "acceptance"
 
       - name: Upload acceptance test reports
         if: always()
         uses: actions/upload-artifact@v3
         with:
-          name: acceptance-tests-${{ matrix.python-version }}-${{ matrix.jupyter-app }}-${{ matrix.jupyterlab-version }}-${{ github.run_number }}
+          name: |-
+            acceptance-tests-${{ matrix.python-version }}-${{ matrix.jupyter-app }}-${{ matrix.jupyterlab-version }}-${{ github.run_number }}
           path: |
             ./build/robot

CONTRIBUTING.md

@@ -10,7 +10,7 @@ the README.md file.
 ### Python package
 
 ```bash
-pip install -e .[test]
+pip install -e ".[test]"
 
 # explicit install needed with editable mode (-e) jupyter
 jupyter serverextension enable --sys-prefix jupyter_server_proxy
@@ -19,7 +19,7 @@ jupyter server extension enable --sys-prefix jupyter_server_proxy
 
 Before running tests, you need a server that we can test against.
 
-```
+```bash
 JUPYTER_TOKEN=secret jupyter-lab --config=./tests/resources/jupyter_server_config.py --no-browser
 ```
 
@@ -39,15 +39,15 @@ To install these in addition to the [Python package](#python-package) test
 dependencies, run:
 
 ```bash
-pip install -e .[test,acceptance]
+pip install -e ".[acceptance]"
 ```
 
 In addition, compatible versions of:
 
 - `geckodriver`
 - `firefox`
 
-Needs to be on your `$PATH` and compatible with each other.
+Need to be on your `$PATH` and compatible with each other.
 
 To run _only_ the acceptance tests, use the `-k` switch:
 
@@ -74,11 +74,47 @@ jlpm build:prod            # Build:
 jlpm install:extension     # Symlink into `{sys.prefix}/share/jupyter/labextensions`
 ```
 
-You can watch the source directory and automatically rebuild the `lib` folder:
+You can watch the source directory and automatically rebuild the `labextension/lib`
+and `jupyter_server_proxy/labextension` folders:
+
+```bash
+cd labextension
+jlpm watch
+```
+
+### Documentation
+
+The documentation uses a fairly standard [Sphinx](https://www.sphinx-doc.org)
+build chain, and requires `make` on Linux/MacOS, which cannot be installed with
+`pip`.
+
+In addition to any system packages, building the documentation requires
+additional packages. To install the needed packages:
+
+```bash
+pip install -r docs/requirements.txt
+```
+
+Once installed, enter the docs folder with:
 
 ```bash
-jlpm watch   # ... watch the source directory in another terminal tab
+cd docs
 ```
 
-However, the built-in `jupyter labextension watch` does _not_ work with this repo,
-as the `package.json` and `setup.py` would need to be at the same level.
+... then build the HTML site:
+
+```bash
+make
+```
+
+... or check that all hyperlinks can be resolved:
+
+```bash
+make linkcheck
+```
+
+... or start an auto-reloading server and open a web browser:
+
+```bash
+make devenv
+```

README.md

@@ -35,7 +35,7 @@ contains information on installation & usage.
 ## Security warning
 
 Jupyter Server Proxy is often used to start a user defined process listening to
-some network port (e.g. http://localhost:4567) for a user starting a Jupyter Server
+some network port (e.g. `http://localhost:4567`) for a user starting a Jupyter Server
 that only that user has permission to access. The user can then access the
 started process proxied through the Jupyter Server.
 
@@ -47,7 +47,7 @@ A common strategy to enforce access proxied via Jupyter Server is to start
 Jupyter Server within a container and only allow network access to the Jupyter
 Server via the container.
 
-For more insights, see [Ryan Lovetts comment about
+> For more insights, see [Ryan Lovett's comment about
 it](https://github.com/jupyterhub/jupyter-server-proxy/pull/359#issuecomment-1350118197).
 
 ## Install
@@ -58,18 +58,22 @@ it](https://github.com/jupyterhub/jupyter-server-proxy/pull/359#issuecomment-135
 
 ### Python package
 
-#### pip
+#### `pip`
 
-```
+```bash
 pip install jupyter-server-proxy
 ```
 
-#### conda
+#### `conda`
 
-```
+```bash
 conda install jupyter-server-proxy -c conda-forge
 ```
 
+#### Local development
+
+> See the [contributing guide](https://github.com/jupyterhub/jupyter-server-proxy/blob/main/CONTRIBUTING.md).
+
 ### JupyterLab extension
 
 Note that as the JupyterLab extension only is a graphical interface to
@@ -79,30 +83,27 @@ requires the python package to be installed.
 As of version 3.0.0 the Python package ships with a JupyterLab 3 compatible
 extension, making this step only needed for JupyterLab 2.
 
-```
+```bash
 jupyter labextension install @jupyterhub/jupyter-server-proxy
 ```
 
 ## Disable
 
 ### Server extension
 
-``` 
-jupyter serverextension disable jupyter_server_proxy
+```bash
+jupyter serverextension disable --sys-prefix jupyter_server_proxy
+jupyter server extension disable --sys-prefix jupyter_server_proxy
 ```
 
 ### Notebook classic extension
 
-```
-jupyter nbextension disable --py jupyter_server_proxy
+```bash
+jupyter nbextension disable --sys-prefix --py jupyter_server_proxy
 ```
 
 ### JupyterLab extension
 
-```
+```bash
 jupyter labextension disable @jupyterhub/jupyter-server-proxy
 ```
-
-## Local development
-
-See [CONTRIBUTING.md](CONTRIBUTING.md).

RELEASE.md

@@ -20,8 +20,8 @@ These are instructions on how to make a release.
    ```shell
    rm labextension/yarn.lock
 
-   pip install jupyter_packaging wheel jupyterlab~=3.0
-   python setup.py sdist bdist_wheel
+   pip install --upgrade pip build
+   pyproject-build
    ```
 
 2. Create a PR updating `docs/source/changelog.md` with [github-activity][] and

jupyter_server_proxy/etc/jupyter-server-proxy-notebookserverextension.json renamed to jupyter_server_proxy/etc/jupyter_notebook_config.d/jupyter-server-proxy.json

@@ -1,8 +1,7 @@
-# @jupyterhub/jupyter-server-proxy labextension
+# `@jupyterhub/jupyter-server-proxy`
 
-This JupyterLab extension that is bundled and requires with the PyPI package
-jupyter-server-proxy adds items to the JupyterLab [Launcher] representing the
-configured server processes.
+A JupyterLab extension that adds items to the JupyterLab [Launcher] representing the
+configured server processes managed by the python package `jupyter-server-proxy` (required).
 
 [launcher]: https://jupyterlab.readthedocs.io/en/stable/extension/extension_points.html#launcher
 
@@ -25,7 +24,7 @@ conda install jupyter-server-proxy
 ```
 
 > As a _prebuilt_ extension, it will "just work," only a simple page reload should be required
-> to see launcher items. However, a full restart of `jupyter_server` or `notebook` is required 
+> to see launcher items. However, a full restart of `jupyter_server` or `notebook` is required
 > to reload the `jupyter_server_proxy` serverextension which provides most of the functionality.
 
 ### JupyterLab 2

jupyter_server_proxy/etc/jupyter-server-proxy-jupyterserverextension.json renamed to jupyter_server_proxy/etc/jupyter_server_config.d/jupyter-server-proxy.json

@@ -38,7 +38,7 @@
     "clean:all": "jlpm run clean:lib && jlpm run clean:labextension",
     "install:extension": "jupyter labextension develop --overwrite .",
     "watch": "run-p watch:src watch:labextension",
-    "watch:src": "jlpm build:lib -w",
+    "watch:src": "jlpm build:lib -w --preserveWatchOutput",
     "watch:labextension": "jupyter labextension watch .",
     "deduplicate": "yarn-deduplicate -s fewer --fail"
   },