Metadata-Version: 2.4
Name: jupyterlab_notify
Version: 3.0.0
Dynamic: Author
Dynamic: Author-email
Dynamic: Keywords
Summary: JupyterLab extension to notify cell completion
Project-URL: Homepage, https://github.com/deshaw/jupyterlab-notify
Project-URL: Bug Tracker, https://github.com/deshaw/jupyterlab-notify/issues
Project-URL: Repository, https://github.com/deshaw/jupyterlab-notify.git
License: Copyright 2021 D. E. Shaw & Co., L.P.
        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 copyright holder 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 HOLDER 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.
License-File: LICENSE.txt
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: server-side-execution
Requires-Dist: jupyter-docprovider>=1.0.0b1; extra == 'server-side-execution'
Requires-Dist: jupyter-server-nbmodel>=0.1.1a2; extra == 'server-side-execution'
Requires-Dist: jupyter-server-ydoc>=1.0.0b1; extra == 'server-side-execution'
Provides-Extra: slack
Requires-Dist: slack-sdk>=3.35.0; extra == 'slack'
Provides-Extra: test
Requires-Dist: ipython>=8.0.0; extra == 'test'
Requires-Dist: jinja2; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-asyncio; extra == 'test'
Requires-Dist: pytest-mock; extra == 'test'
Requires-Dist: pytest-tornado; extra == 'test'
Requires-Dist: slack-sdk; extra == 'test'
Description-Content-Type: text/markdown

# jupyterlab-notify

[![PyPI version][pypi-image]][pypi-url] [![PyPI DM][pypi-dm-image]][pypi-url]
[![Github Actions Status][github-status-image]][github-status-url] [![Binder][binder-image]][binder-url]

JupyterLab extension to notify cell completion

## Usage

The `jupyterlab-notify` extension allows you to receive notifications about cell execution results in JupyterLab. Notifications are configured through cell metadata or the JupyterLab interface, providing seamless integration and easier management of notification preferences. Notifications can be sent via desktop pop-ups, Slack messages, or emails, depending on your configuration.

> [!NOTE]
> JupyterLab Notify v3 supports `jupyter-server-nbmodel`(>= v0.1.1a2), enabling notifications to work even after the browser has been closed. To enable browser-less notification support, install JupyterLab Notify with server-side execution dependencies using:
>
> ```bash
> pip install jupyterlab-notify[server-side-execution]
> ```
>
> JupyterLab Notify v3 requires execution timing data, so it automatically sets `record_timing` to true in the notebook settings.

### Configuration

To configure the **jupyterlab-notify** extension for Slack and email notifications, create a configuration file and place it in a directory listed under the `config` section of `jupyter --paths` (run `jupyter --paths` to see the available locations).

Two configuration file formats are supported:

- **JSON** (`jupyter_notify_config.json`) — simple key/value format.
- **Python** (`jupyter_notify_config.py`) — uses Jupyter’s `traitlets`-based config system.

Both files define settings for the `NotificationConfig` class. You only need one.

#### Sample Configuration File

**JSON** (`~/.jupyter/jupyter_notify_config.json`):

```json
{
  "NotificationConfig": {
    "email": "example@domain.com",
    "slack_token": "xoxb-abc123-your-slack-token",
    "slack_user_id": "U98765432"
  }
}
```

**Python** (`~/.jupyter/jupyter_notify_config.py`):

```python
# Configuration file for jupyter-notify extension.

c = get_config()  # noqa

c.NotificationConfig.email = "example@domain.com"
c.NotificationConfig.slack_token = "xoxb-abc123-your-slack-token"
c.NotificationConfig.slack_user_id = "U98765432"
# Example: use a custom SMTP server on a non-default port
c.NotificationConfig.smtp_args = ["localhost", 1025]
```

- **`slack_token`**: A Slack bot token used to send notifications to your Slack workspace.

  - **How to get it**: See [Slack API Quickstart](https://api.slack.com/quickstart) to create a bot and obtain a token.
  - **Required Bot Token Scopes**: Your Slack app must have the following OAuth scopes granted under **OAuth & Permissions → Bot Token Scopes** in the [Slack API dashboard](https://api.slack.com/apps):

    | Scope               | Purpose                                                                             |
    | ------------------- | ----------------------------------------------------------------------------------- |
    | `chat:write`        | Post messages to channels or DMs the bot is a member of                             |
    | `chat:write.public` | Post to public channels without the bot needing to join first                       |
    | `im:write`          | Open direct message conversations with users (required when `slack_user_id` is set) |

- **`slack_channel_name`**: The name of the Slack channel (e.g., `"notifications"`) where messages will be posted.
- **`email`**: The email address to receive notifications.
  - **Note**: Requires an SMTP server. For setup help, see [this SMTP guide](https://mailtrap.io/blog/setup-smtp-server/).

#### Additional Configuration Options

Beyond the commonly used settings above, the following options are available for advanced use:

- **`slack_user_id`**: A Slack user ID for sending direct messages instead of channel posts (e.g., `"U12345678"`).
- **`smtp_class`**: Fully qualified name of the SMTP class (default: `"smtplib.SMTP"`).
- **`smtp_args`**: Arguments for the SMTP class constructor, as a string (default: `["localhost"]`).

These settings allow for customization, such as using a custom SMTP server or changing the SMTP port from the default `25` to others (e.g., `["localhost", 125]`), or targeting a specific Slack channel or user.

### Notification Modes

You can control when notifications are sent by setting a mode for each cell. Modes can be configured through the JupyterLab interface by clicking on the bell icon in the cell toolbar.

![image](https://github.com/deshaw/jupyterlab-notify/blob/main/docs/celltoolbar-menu-screenshot.png?raw=true)

**Supported modes include:**

- `default`: Notification is sent only if cell execution exceeds the threshold time (default: 30 seconds). No notification if execution time is below the threshold.
- `never`: Disables notifications for the cell.
- `on-error`: Sends a notification only if the cell execution fails with an error.
- `custom-timeout`: Sends a notification as soon as the cell-execution exceeds a timeout value specified for that cell. Users can either choose a pre-existing timeout value or set a custom one.

### Default Threshold

Configure the default threshold value in JupyterLab’s settings:

1. Go to Settings Editor.
2. Select Execution Notifications.
3. Set "Threshold for default notifications": 5 (in seconds) to apply to cells using the `default` mode.

### Desktop Notifications

Desktop notifications are enabled by default and appear as pop-up alerts on your system.

![image](https://github.com/deshaw/jupyterlab-notify/blob/main/docs/desktop-notification.png?raw=true)

### Slack Notifications

Slack notifications are sent to the configured channel, requiring the setup described in the Configuration section.

### Email Notifications

Email notifications are sent to the configured email address, also requiring the setup from the Configuration section.

#### Configuration warning

If your email or Slack notifications are not configured but you attempt to enable them through the settings editor, a warning will be displayed when you try to execute a cell in the JupyterLab interface.

![image](https://github.com/deshaw/jupyterlab-notify/blob/main/docs/configuration-warning-screenshot.png?raw=true)

## Troubleshoot

If you notice that the desktop notifications are not showing up, check the below:

1. Make sure JupyterLab is running in a secure context (i.e. either using HTTPS or localhost)
2. If you've previously denied notification permissions for the site, update the browser settings accordingly. In Chrome, you can do so by navigating to `Setttings -> Privacy and security -> Site Settings -> Notifications` and updating the permissions against your JupyterLab URL.
3. Verify that notifications work for your browser. You may need to configure an OS setting first. You can test on [this site](https://web-push-book.gauntface.com/demos/notification-examples/).

## Requirements

- JupyterLab >= 4.0

## Install

To install this package with [`pip`](https://pip.pypa.io/en/stable/) run

```bash
pip install jupyterlab_notify
```

To install with server-side execution dependencies run

```bash
pip install jupyterlab_notify[server-side-execution]
```

## 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_notify directory
# Install package in development mode
pip install -e .

# If you need server-side execution dependencies, install with:
pip install -e .[server-side-execution]

# If you want to install test dependencies as well, use:
pip install -e .[tests]

# 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_notify
```

## Publishing

1. Update the version in `package.json` and update the release date in `CHANGELOG.md`
2. Commit the change in step 1
3. For test release, manually trigger the [`Build and publish to PyPI` workflow](https://github.com/deshaw/jupyterlab-notify/actions/workflows/build.yml) - you need to check the `Test release` checkbox
4. Draft a new [GitHub release](https://github.com/deshaw/jupyterlab-notify/releases/new), creating an approriate version tag
5. Publish the draft and verify that the `publish` job in the build workflow passed.

### Uninstall

```bash
pip uninstall jupyterlab_notify
```

## History

The initial version of this extension was inspired by the notebook version [here](https://github.com/ShopRunner/jupyter-notify).

This plugin was contributed back to the community by the [D. E. Shaw group](https://www.deshaw.com/).

<p align="center">
    <a href="https://www.deshaw.com">
       <img src="https://www.deshaw.com/assets/logos/blue_logo_417x125.png" alt="D. E. Shaw Logo" height="75" >
    </a>
</p>

## License

This project is released under a [BSD-3-Clause license](https://github.com/deshaw/jupyterlab-notify/blob/master/LICENSE.txt).

We love contributions! Before you can contribute, please sign and submit this [Contributor License Agreement (CLA)](https://www.deshaw.com/oss/cla).
This CLA is in place to protect all users of this project.

"Jupyter" is a trademark of the NumFOCUS foundation, of which Project Jupyter is a part.

[pypi-url]: https://pypi.org/project/jupyterlab-notify
[pypi-image]: https://img.shields.io/pypi/v/jupyterlab-notify
[pypi-dm-image]: https://img.shields.io/pypi/dm/jupyterlab-notify
[github-status-image]: https://github.com/deshaw/jupyterlab-notify/workflows/Build/badge.svg
[github-status-url]: https://github.com/deshaw/jupyterlab-notify/actions?query=workflow%3ABuild
[binder-image]: https://mybinder.org/badge_logo.svg
[binder-url]: https://mybinder.org/v2/gh/deshaw/jupyterlab-notify.git/main?urlpath=lab%2Ftree%2Fnotebooks%2FNotify.ipynb
