Metadata-Version: 2.4
Name: jupyterlab_wall
Version: 0.2.3
Dynamic: Keywords
Summary: A JupyterLab extension to alert users of system events.
Project-URL: Homepage, https://github.com/mlhenderson/jupyterlab_wall
Project-URL: Bug Tracker, https://github.com/mlhenderson/jupyterlab_wall/issues
Project-URL: Repository, https://github.com/mlhenderson/jupyterlab_wall.git
Author-email: Matt Henderson <mhenderson@lbl.gov>
License: *** Licence Agreement ***
        
        jupyterlab_wall Copyright (c) 2023, The Regents of the University of
        California, through Lawrence Berkeley National Laboratory (subject to
        receipt of any required approvals from the U.S. Dept. of Energy). 
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        (1) Redistributions of source code must retain the above copyright notice,
        this list of conditions and the following disclaimer.
        
        (2) Redistributions in binary form must reproduce the above copyright
        notice, this list of conditions and the following disclaimer in the
        documentation and/or other materials provided with the distribution.
        
        (3) Neither the name of the University of California, Lawrence Berkeley
        National Laboratory, U.S. Dept. of Energy nor the names of its contributors
        may be used to endorse or promote products derived from this software
        without specific prior written permission.
        
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
        ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
        LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
        CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
        SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
        INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
        CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
        ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
        POSSIBILITY OF SUCH DAMAGE.
        
        You are under no obligation whatsoever to provide any bug fixes, patches,
        or upgrades to the features, functionality or performance of the source
        code ("Enhancements") to anyone; however, if you choose to make your
        Enhancements available either publicly, or directly to Lawrence Berkeley
        National Laboratory, without imposing a separate written license agreement
        for such Enhancements, then you hereby grant the following license: a
        non-exclusive, royalty-free perpetual license to install, use, modify,
        prepare derivative works, incorporate into other computer software,
        distribute, and sublicense such enhancements or derivative works thereof,
        in binary and source code form.
License-File: LICENSE
Classifier: Framework :: Jupyter
Classifier: Framework :: Jupyter :: JupyterLab
Classifier: Framework :: Jupyter :: JupyterLab :: 4
Classifier: Framework :: Jupyter :: JupyterLab :: Extensions
Classifier: Framework :: Jupyter :: JupyterLab :: Extensions :: Prebuilt
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Requires-Dist: jupyter-server<3,>=2.0.1
Provides-Extra: test
Requires-Dist: coverage; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-asyncio; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Requires-Dist: pytest-jupyter[server]>=0.6.0; extra == 'test'
Description-Content-Type: text/markdown

# jupyterlab_wall

![Github Actions Status](https://github.com/mlhenderson/jupyterlab_wall/workflows/Build/badge.svg)
![Github Actions Status](https://github.com/mlhenderson/jupyterlab_wall/workflows/Security%20Audit/badge.svg)
![Python Coverage](https://img.shields.io/badge/coverage-90%25-success)
![JS Unit Test Coverage](https://img.shields.io/badge/JS%20unit%20coverage-80%25-success)

A JupyterLab extension to alert users of system events.

This extension is composed of a Python package named `jupyterlab_wall`
for the server extension and a NPM package named `jupyterlab-wall`
for the frontend extension.

## Requirements

- JupyterLab >= 4 < 5

## Install

```bash
pip install jupyterlab_wall
```

You will also need to define a set of alerts that should trigger, see 'jupyter_jupyterlab_wall_config.py' for examples.
This config needs to be incorporated into your jupyter_server_config.py from one of the jupyter config paths
to take effect. You can define a new jupyter_server_config.py with the contents of 'jupyter_jupyterlab_wall_config.py'.

You can see all the jupyter paths with:

```bash
jupyter --paths
```

As an example, you could copy the example alerts into your ${HOME}/.jupyter/ directory.

```bash
cp ./jupyter_jupyterlab_wall_config.py ${HOME}/.jupyter/jupyter_server_config.py
```

OR, append the example alerts to an existing file.

```bash
cat ./jupyter_jupyterlab_wall_config.py >> ${HOME}/.jupyter/jupyter_server_config.py
```

## Troubleshoot

If you are seeing the frontend extension, but it is not working, check
that the server extension is enabled:

```bash
jupyter server extension list
```

If the server extension is installed and enabled, but you are not seeing
the frontend extension, check the frontend extension is installed:

```bash
jupyter labextension list
```

You can check to see what the current alerts config is:

```bash
jupyter server --show-config
```

If there are no alerts confined, a test_alert is defined internally that you can use to verify that the extension is
working. You can create the file '/tmp/alert_test', which will trigger an alert in jupyterlab if the extension
is working correctly.

## Contributing

### Development install

Note: You will need NodeJS to build the extension package.

The `jlpm` command is JupyterLab's pinned version of
[yarn](https://yarnpkg.com/) that is installed with JupyterLab. You may use
`yarn` or `npm` in lieu of `jlpm` below.

```bash
# Clone the repo to your local environment
# Change directory to the jupyterlab_wall directory
# Install package in development mode
pip install -e .
# Link your development version of the extension with JupyterLab
jupyter labextension develop . --overwrite
# 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).

By default, the `jlpm run build` command generates the source maps for this extension to make it easier to debug using the browser dev tools. To also generate source maps for the JupyterLab core extensions, you can run the following command:

```bash
jupyter lab build --minimize=False
```

### Uninstall

```bash
pip uninstall jupyterlab_wall
```

## Testing

### Python Tests

This extension uses `pytest` for Python tests. To run the tests, install the test dependencies and run `pytest`:

```bash
pip install pytest pytest-cov pytest-jupyter
python -m pytest --cov=jupyterlab_wall jupyterlab_wall/tests
```

### JS Unit Tests

This extension uses `jest` for JavaScript/TypeScript unit tests. To run the tests:

```bash
jlpm test
```

Unit tests are located in the `tests/` directory.

### UI Tests

UI tests are powered by Playwright and Galata. To run them:

```bash
cd ui-tests
jlpm install
jlpm playwright install
jlpm test
```

These tests are automatically run in the GitHub Actions CI workflow on every push and pull request.
