Merge pull request #69 from jtpio/labextension

Add a JupyterLab extension for the memory usage status bar item

.github/workflows/build.yml

@@ -0,0 +1,46 @@
+name: Build
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: '*'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v2
+
+    - name: Install node
+      uses: actions/setup-node@v1
+      with:
+       node-version: '14.x'
+
+    - name: Install Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: '3.7'
+        architecture: 'x64'
+
+    - name: Install dependencies
+      run: python -m pip install jupyterlab --pre
+
+    - name: Install the extension
+      run: |
+        python -m pip install .
+
+    - name: Check the server, classic and lab extensions are installed
+      run: |
+        jupyter serverextension list 2>&1 | grep -ie "jupyter_resource_usage.*enabled"
+        jupyter server extension list 2>&1 | grep -ie "jupyter_resource_usage.*enabled"
+        jupyter nbextension list 2>&1 | grep -ie "jupyter_resource_usage/main.*enabled"
+        jupyter labextension list 2>&1 | grep -ie "@jupyter-server/resource-usage.*OK"
+        python -m jupyterlab.browser_check
+
+    - name: Lint
+      run: |
+        cd packages/labextension/
+        jlpm
+        jlpm run lint:check

.gitignore

@@ -24,10 +24,21 @@ var/
 .installed.cfg
 *.egg
 *.ipynb
+MANIFEST
 
 # IDE and code editors
 *.iml
 .idea
 .vscode
 *.code-workspace
 .history
+
+# Labextension
+*.bundle.*
+lib/
+node_modules/
+*.egg-info/
+.ipynb_checkpoints
+*.tsbuildinfo
+jupyter_resource_usage/labextension
+yarn-error.log

CONTRIBUTING.md

@@ -6,71 +6,142 @@ you can follow the [Jupyter contributor guide](https://jupyter.readthedocs.io/en
 Make sure to also follow [Project Jupyter's Code of Conduct](https://github.com/jupyter/governance/blob/master/conduct/code_of_conduct.md)
 for a friendly and welcoming collaborative environment.
 
-## Development set up
+## Setting up a development environment
 
 We recommend using [pipenv](https://docs.pipenv.org/) to make development easier.
 
-1. Clone the git repository:
+Alternatively, you can also use `conda` or `mamba` to create new virtual environments.
 
-   ```bash
-   git clone https://github.com/jupyter-server/jupyter-resource-usage
-   ```
+Clone the git repository:
 
-2. Create an environment that will hold our dependencies.
+```bash
+git clone https://github.com/jupyter-server/jupyter-resource-usage
+```
+
+Create an environment that will hold our dependencies:
+
+```bash
+cd jupyter-resource-usage
+pipenv --python 3.6
+```
 
-   ```bash
-   cd jupyter-resource-usage
-   pipenv --python 3.6
-   ```
+With conda:
 
-3. Activate the virtual environment that pipenv created for us
+```bash
+conda create -n jupyter-resource-usage -c conda-forge python
+```
 
-   ```bash
-   pipenv shell
-   ```
+Activate the virtual environment that pipenv created for us
 
-4. Do a dev install of jupyter-resource-usage and its dependencies
+```bash
+pipenv shell
+```
 
-   ```bash
-   pip install --editable .[dev]
-   ```
+With conda:
 
-5. Install and enable the nbextension for use with Jupyter Classic Notebook.
+```bash
+conda activate jupyter-resource-usage
+```
 
-   ```bash
-   jupyter nbextension install --py jupyter-resource-usage --symlink --sys-prefix
-   jupyter serverextension enable --py jupyter-resource-usage  --sys-prefix
-   jupyter nbextension enable --py jupyter-resource-usage --sys-prefix
-   ```
+Do a dev install of jupyter-resource-usage and its dependencies
 
-6. Start a Jupyter Notebook instance, open a new notebook and check out the memory usage
-   in the top right!
+```bash
+pip install --editable .[dev]
+```
 
-   ```bash
-   jupyter notebook
-   ```
+Enable the server extension:
 
-7. If you want to test the memory limit display functionality, you can do so by setting
-   the `MEM_LIMIT` environment variable (in bytes) when starting `jupyter notebook`.
+```bash
+jupyter serverextension enable --py jupyter_resource_usage  --sys-prefix
+```
 
-   ```bash
-   MEM_LIMIT=$(expr 128 \* 1024 \* 1024) jupyter notebook
-   ```
+*Note: if you're using Jupyter Server:*
 
-8. jupyter-resource-usage has adopted automatic code formatting so you shouldn't
-need to worry too much about your code style.
+```bash
+jupyter server extension enable --py jupyter_resource_usage  --sys-prefix
+```
+
+## Classic notebook extension
+
+Install and enable the nbextension for use with Jupyter Classic Notebook.
+
+```bash
+jupyter nbextension install --py jupyter_resource_usage --symlink --sys-prefix
+jupyter nbextension enable --py jupyter_resource_usage --sys-prefix
+```
+
+Start a Jupyter Notebook instance, open a new notebook and check out the memory usage in the top right!
+
+```bash
+jupyter notebook
+```
+
+If you want to test the memory limit display functionality, you can do so by setting the `MEM_LIMIT` environment variable (in bytes) when starting `jupyter notebook`.
+
+```bash
+MEM_LIMIT=$(expr 128 \* 1024 \* 1024) jupyter notebook
+```
+
+## JupyterLab extension
+
+The JupyterLab extension for `jupyter-resource-usage` was bootstrapped from the [extension cookiecutter](https://github.com/jupyterlab/extension-cookiecutter-ts), and follows the common patterns and tooling for developing extensions.
+
+```bash
+# activate the environment (conda, pipenv)
+
+# install the package in development mode
+python -m pip install -e ".[dev]"
+
+# link your development version of the extension with JupyterLab
+jupyter labextension develop . --overwrite
+
+# go to the labextension directory
+cd labextension/
+
+# Rebuild extension Typescript source after making changes
+jlpm run build
+```
+
+You can watch the source directory and run JupyterLab at the same time in different terminals to watch for changes in the extension's source and automatically rebuild the extension.
+
+```bash
+# Watch the source directory in one terminal, automatically rebuilding when needed
+jlpm run watch
+# Run JupyterLab in another terminal
+jupyter lab
+```
+
+With the watch command running, every saved change will immediately be built locally and available in your running JupyterLab. Refresh JupyterLab to load the change in your browser (you may need to wait several seconds for the extension to be rebuilt).
+
+To check the extension is correctly installed, run:
+
+```bash
+jupyter labextension list
+```
+
+It should show something like the following:
+
+```bash
+JupyterLab v3.0.0
+/path/to/env/share/jupyter/labextensions
+        jupyter-resource-usage v0.1.0 enabled OK
+```
+
+## pre-commit
+
+`jupyter-resource-usage` has adopted automatic code formatting so you shouldn't need to worry too much about your code style.
 As long as your code is valid,
 the pre-commit hook should take care of how it should look. Here is how to set up pre-commit hooks for automatic code formatting, etc.
 
-    ```bash
-    pre-commit install
-    ```
+```bash
+pre-commit install
+```
 
-    You can also invoke the pre-commit hook manually at any time with
+You can also invoke the pre-commit hook manually at any time with
 
-    ```bash
-    pre-commit run
-    ```
+```bash
+pre-commit run
+```
 
 which should run any autoformatting on your code
 and tell you about any errors it couldn't fix automatically.
@@ -82,11 +153,11 @@ hook with `pre-commit install`, you can fix everything up using
 `pre-commit run --all-files`.  You need to make the fixing commit
 yourself after that.
 
-9. It's a good idea to write tests to exercise any new features,
-or that trigger any bugs that you have fixed to catch regressions. `pytest` is used to run the test suite. You can run the tests with:
+## Tests
+
+It's a good idea to write tests to exercise any new features,
+or that trigger any bugs that you have fixed to catch regressions. `pytest` is used to run the test suite. You can run the tests with in the repo directory:
 
 ```bash
-python -m pytest -vvv jupyter-resource-usage
+python -m pytest -vvv jupyter_resource_usage
 ```
-
-in the repo directory.

MANIFEST.in

@@ -1 +1,25 @@
 include LICENSE
+
+include README.md
+include pyproject.toml
+include package.json
+include install.json
+include ts*.json
+
+recursive-include jupyter-config *.json
+
+graft jupyter_resource_usage/labextension
+graft jupyter_resource_usage/static
+
+# Javascript files
+graft src
+graft style
+prune **/node_modules
+prune lib
+
+# Patterns to exclude from any directory
+global-exclude *~
+global-exclude *.pyc
+global-exclude *.pyo
+global-exclude .git
+global-exclude .ipynb_checkpoints

install.json

@@ -0,0 +1,5 @@
+{
+  "packageManager": "python",
+  "packageName": "jupyter-resource-usage",
+  "uninstallInstructions": "Use your Python package manager (pip, conda, etc.) to uninstall the package jupyter-resource-usage"
+}

jupyter-config/jupyter_server_config.d/jupyter_resource_usage.json

@@ -0,0 +1,7 @@
+{
+  "ServerApp": {
+    "jpserver_extensions": {
+      "jupyter_resource_usage": true
+    }
+  }
+}

jupyter_resource_usage/__init__.py

@@ -1,9 +1,22 @@
+import json
+import os.path as osp
+
+from notebook.utils import url_path_join
+from tornado import ioloop
+
 from jupyter_resource_usage.api import ApiHandler
 from jupyter_resource_usage.config import ResourceUseDisplay
 from jupyter_resource_usage.metrics import PSUtilMetricsLoader
 from jupyter_resource_usage.prometheus import PrometheusHandler
-from notebook.utils import url_path_join
-from tornado import ioloop
+
+HERE = osp.abspath(osp.dirname(__file__))
+
+with open(osp.join(HERE, "labextension", "package.json")) as fid:
+    data = json.load(fid)
+
+
+def _jupyter_labextension_paths():
+    return [{"src": "labextension", "dest": data["name"]}]
 
 
 def _jupyter_server_extension_paths():

packages/labextension/.eslintignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+coverage
+**/*.d.ts
+tests

packages/labextension/.eslintrc.js

@@ -0,0 +1,35 @@
+module.exports = {
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/eslint-recommended',
+    'plugin:@typescript-eslint/recommended',
+    'plugin:prettier/recommended',
+  ],
+  parser: '@typescript-eslint/parser',
+  plugins: ['@typescript-eslint'],
+  rules: {
+    '@typescript-eslint/naming-convention': [
+      'error',
+      {
+        selector: 'interface',
+        format: ['PascalCase'],
+        custom: {
+          regex: '^I[A-Z]',
+          match: true,
+        },
+      },
+    ],
+    '@typescript-eslint/no-unused-vars': ['warn', { args: 'none' }],
+    '@typescript-eslint/no-explicit-any': 'off',
+    '@typescript-eslint/no-namespace': 'off',
+    '@typescript-eslint/no-use-before-define': 'off',
+    '@typescript-eslint/quotes': [
+      'error',
+      'single',
+      { avoidEscape: true, allowTemplateLiterals: false },
+    ],
+    curly: ['error', 'all'],
+    eqeqeq: 'error',
+    'prefer-arrow-callback': 'error',
+  },
+};

packages/labextension/.prettierignore

@@ -0,0 +1,4 @@
+node_modules
+**/node_modules
+**/lib
+**/package.json

packages/labextension/.prettierrc

@@ -0,0 +1,3 @@
+{
+  "singleQuote": true
+}