Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

e2x-hub-announcements

License: MIT Python Version

e2x-hub-announcements is a small announcement service for JupyterHub (z2jh) deployments. Admins write an announcement in a web UI and choose which hub pages it appears on, its severity, and when it expires. It shows up on the next page load, with no hub restart.

 admin browser ──► /services/announcements/  (FastAPI service, managed by hub)
                         │ writes
                         ▼
            /srv/jupyterhub/announcements.json   (hub PVC)
                         ▲ reads on each page render
                         │
 any user ──► hub page ──┘  template_vars callables → announcement_<page>

The hub renders the banner itself through JupyterHub's stock announcement_<page> template variables. Banners need no JavaScript or polling, and spawner templates need no changes.

Status: early development (0.1.0-rc0). The sections below describe the planned interface.


What does it provide?

  • Admin service (e2x_hub_announcements.service): a FastAPI app with an admin UI and API. Admins create announcements with target pages (spawn, login, home, logout), a severity (info, warning, alert) and an expiry, preview them, and end them early.
  • Hub integration (e2x_hub_announcements.hub): configure_announcements(c, store_path=...) registers template_vars callables that read the store on each page render and return the active banners for that page.
  • page.html override (share/e2x_hub_announcements/templates/jupyterhub/): replaces only the stock announcement block, so banners render in their severity colour instead of the stock yellow warning box.

Installation

This package is not yet published. Install it from source into the hub image:

git clone https://github.com/Digiklausur/e2x-hub-announcements.git
cd e2x-hub-announcements
pip install -e .

JupyterHub integration

The same z2jh values work for any hub:

hub:
  services:
    announcements:
      url: http://hub:<port>
      command: [uvicorn, e2x_hub_announcements.service:app]
      environment:
        UVICORN_HOST: "0.0.0.0"
        UVICORN_PORT: "<port>"
        ANNOUNCEMENTS_STORE: /srv/jupyterhub/announcements.json
  extraConfig:
    10-announcements.py: |
      from e2x_hub_announcements.hub import configure_announcements
      configure_announcements(c, store_path="/srv/jupyterhub/announcements.json")

Like other managed services, it also needs a hub.service.extraPorts entry and a hub.networkPolicy.ingress rule for <port>. Give access:services!service=announcements to admins only, not to the default user role.

Severity styling and template_paths

The stock page.html wraps every announcement in a yellow alert-warning box. To show the severity colour instead, configure_announcements puts this package's page.html override first in c.JupyterHub.template_paths. Every hub page that extends page.html picks it up, including custom templates that extend templates/spawn.html.

  • Add to template_paths, don't assign it. Other config that runs after configure_announcements must use c.JupyterHub.template_paths.append(...) (or +=). An assignment like c.JupyterHub.template_paths = [...] silently removes the override. Banners then still show, but always in the yellow box.
  • Only one page.html override can apply. The override extends the stock templates/page.html directly, so it shadows any other page.html in template_paths (e.g. a theme).
  • Templates that extend templates/page.html directly (with the prefix) bypass the override.

API

All paths are relative to the service prefix (e.g. /services/announcements). Every endpoint requires access:services!service=announcements. Interactive docs are at <prefix>/docs.

Method Path Purpose
GET / Admin UI: create, preview, end and delete announcements
GET /api/announcements List all announcements (active and expired), newest first
POST /api/announcements Create an announcement (expires_at must be in the future, with a timezone)
POST /api/announcements/{id}/end Expire an announcement now
DELETE /api/announcements/{id} Remove an announcement
POST /api/preview Render the banner HTML without saving

Development

git clone https://github.com/Digiklausur/e2x-hub-announcements.git
cd e2x-hub-announcements
pip install -e ".[dev,test]"
pytest

License

This project is licensed under the MIT License - see the LICENSE file for details.

Metadata

Release files for e2x-hub-announcements 0.1.0rc0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for e2x-hub-announcements 0.1.0rc0
File Size Uploaded Provenance Actions
e2x_hub_announcements-0.1.0rc0.tar.gz 18.8 kB With provenance Details for e2x_hub_announcements-0.1.0rc0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for e2x-hub-announcements 0.1.0rc0
File Interpreter ABI Platform Actions
e2x_hub_announcements-0.1.0rc0-py3-none-any.whl Python 3 none any Details for e2x_hub_announcements-0.1.0rc0-py3-none-any.whl

Total release size: 35.8 kB

Release files / e2x_hub_announcements-0.1.0rc0.tar.gz

Download URL e2x_hub_announcements-0.1.0rc0.tar.gz
Size 18.8 kB
Tags Source
SHA-256 checksum
How to use checksums
6d6336dd32cee1efe37bb1dfc500cd223d87a88e44b4de88611540cd3783cc6d
BLAKE2b-256 checksum
How to use checksums
8c6ab2be01702f858b4e8445a81fa86c7882f4424b18fefb334062a5e97ecdbf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

Release files / e2x_hub_announcements-0.1.0rc0-py3-none-any.whl

Download URL e2x_hub_announcements-0.1.0rc0-py3-none-any.whl
Size 16.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f0f60c2f9cc6bc152ad77a248ffa483becaeaf2018f3702e668dc6645ff4442f
BLAKE2b-256 checksum
How to use checksums
7c386e93550bca1de2f4335647652f19689951148f087cd6bfe38837ce088d02
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

Security for e2x-hub-announcements 0.1.0rc0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for e2x_hub_announcements-0.1.0rc0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page