Skip to main content

Tooling Library for Notebooks

Build Status PyPI Package Docs

Introduction

A modular Python toolkit designed to support notebook-based workflows. It provides reusable tools for data ingestion, transformations, visualisation, notifications, and microgrid metadata managers. These tools make the repository ideal for streamlining analytics workflows with minimal setup and building data pipelines, reporting workflows, and alert systems seamlessly in Jupyter or cloud notebooks.

Supported Platforms

The following platforms are officially supported (tested):

  • Python: 3.11
  • Operating System: Ubuntu Linux 20.04
  • Architectures: amd64, arm64

Contributing

If you want to know how to build this project and contribute to it, please check out the Contributing Guide.

Quick Start

Install the package, open the example notebooks, and explore the available modules.

Installation

# Choose the version you want to install or use the latest
pip install frequenz‑lib‑notebooks

Then open the prebuilt example notebooks using your preferred interface:

  • Classic Notebook: jupyter examples/
  • JupyterLab: jupyter-lab examples/

⚠️ Note: This project does not install jupyter or jupyterlab by default. You will need to install it separately if you want to run notebooks:

pip install jupyterlab

Code Examples

📧 Example 1: Generate an Alert Email (HTML Body Only)

This example shows how to:

  • Transform a pandas DataFrame of alert records into a structured HTML email using generate_alert_email.
  • Use AlertEmailConfig to control layout (e.g., table row limits, sorting by severity).
  • Integrate microgrid-component alerts cleanly into operational workflows (e.g., for notifications or reporting tools).
import pandas as pd
from IPython.display import HTML

from frequenz.lib.notebooks.alerts.alert_email import (
    AlertEmailConfig,
    generate_alert_email,
)
from frequenz.lib.notebooks.notification_utils import format_email_preview

# Example alert records dataframe
alert_records = pd.DataFrame(
    [
        {
            "microgrid_id": 1,
            "component_id": 1,
            "state_type": "error",
            "state_value": "UNDERVOLTAGE",
            "start_time": "2025-03-14 15:06:30",
            "end_time": "2025-03-14 17:00:00",
        },
        {
            "microgrid_id": 2,
            "component_id": 1,
            "state_type": "state",
            "state_value": "DISCHARGING",
            "start_time": "2025-03-14 15:06:30",
            "end_time": None,
        },
    ]
)

# Configuration for email generation
alert_email_config = AlertEmailConfig(
    displayed_rows=10,
    sort_by_severity=True,
)

# Generate the HTML body of the alert email
html_email = generate_alert_email(
    alert_records=alert_records, config=alert_email_config
)

# Output the HTML # or send it via email as shown in the next example
print(html_email)

# or preview it in a nicer format
HTML(format_email_preview(subject="Alert Notification", body_html=html_email))

📨 Example 2: Compose and Send Alert Email with Attachments

Continuing from Example 1, this snippet builds on the generated HTML email and demonstrates:

  • Configuring SMTP credentials and recipients.
  • Attaching both a CSV export of the alert data and optional visual plots.
  • Sending the email once or scheduling it periodically. Note that the periodic scheduling would make sense when the data also refreshes so as to not send the same email over and over again!
import time
from datetime import datetime

from frequenz.lib.notebooks.alerts.alert_email import ExportOptions, plot_alerts
from frequenz.lib.notebooks.notification_service import (
    EmailConfig,
    EmailNotification,
    SchedulerConfig,
)

# Configuration for email notification
email_config = EmailConfig(
    subject="Critical Alert",
    message=html_email,  # Assuming that html_email already exists. See the code example above on how to generate this.
    recipients=["recipient@example.com"],
    smtp_server="smtp.example.com",
    smtp_port=587,
    smtp_user="user@example.com",
    smtp_password="password",
    from_email="alert@example.com",
    scheduler=SchedulerConfig(
        send_immediately=True,
        interval=60,  # send every minute
        duration=3600,  # for one hour total
    ),
)
# The SMTP details and sender/recipient details need to be adjusted accordingly
# note that the library provides a convenient way to validate the settings via frequenz.lib.notebooks.notification_utils.validate_email_config

# Create a notification object
email_notification = EmailNotification(config=email_config)

# optionally add attachments (a list of files)
email_config.attachments = None
timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
alert_file_name = f"alert_details_{timestamp}.csv"
alert_records.to_csv(alert_file_name, index=False)
email_config.attachments = [alert_file_name]

# Optionally create a visualisation of the alert records
img_path = plot_alerts(
    records=alert_records,
    plot_type="all",
    export_options=ExportOptions(
        format="png",
        show=True,
    ),
)
email_config.attachments += img_path if img_path else []

# Send one-off notification
email_notification.send()

# Or start a periodic scheduler:
email_notification.start_scheduler()
time.sleep(300)  # let it run for 5 minutes
email_notification.stop_scheduler()

Module Overview

  • Solar Maintenance App: Interactive forecasting and visualisation tools tailored to solar installations.
  • Notification Service: Flexible and configurable email dispatching.
  • Alert Email Generation: Embed rich Plotly charts into alert emails, complete with context and summaries.
  • Microgrid Configuration: Manage structured microgrid metadata—location, devices, etc. — consistently across notebooks.

For more details about each module/project, please refer to the overview Wiki page which has links to dedicated project pages.

The full code documentation can be accessed here.

Metadata

Release files for frequenz-lib-notebooks 0.17.1

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

Source distribution (sdist)

Source distribution for frequenz-lib-notebooks 0.17.1
File Size Uploaded Provenance Actions
frequenz_lib_notebooks-0.17.1.tar.gz 3.3 MB With provenance Details for frequenz_lib_notebooks-0.17.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for frequenz-lib-notebooks 0.17.1
File Interpreter ABI Platform Actions
frequenz_lib_notebooks-0.17.1-py3-none-any.whl Python 3 none any Details for frequenz_lib_notebooks-0.17.1-py3-none-any.whl

Total release size: 3.5 MB

Release files / frequenz_lib_notebooks-0.17.1.tar.gz

Download URL frequenz_lib_notebooks-0.17.1.tar.gz
Size 3.3 MB
Tags Source
SHA-256 checksum
How to use checksums
bc3c20a2ffcb27e9e1362f66e610ca8dc0ab31d88c96efbec057a0424de7abcc
BLAKE2b-256 checksum
How to use checksums
64206aee0152af14848503e35484a210030125e53d0188859c6fdb00fdb00bc6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 9, 2026.

Transparency log

Release files / frequenz_lib_notebooks-0.17.1-py3-none-any.whl

Download URL frequenz_lib_notebooks-0.17.1-py3-none-any.whl
Size 176.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
dc536a1e58f9ad67ea4ea6494ec90936f6db5a9426d8b293abade668421157b8
BLAKE2b-256 checksum
How to use checksums
8f16a4eedd714ccfcef60e12db44713e1e20aaf8483621c819855081c1361898
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 9, 2026.

Transparency log

Security for frequenz-lib-notebooks 0.17.1

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 frequenz_lib_notebooks-0.17.1.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 9, 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

0.17.1 This release

2 release files Full provenance

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