# Tooling Library for Notebooks
[](https://github.com/frequenz-floss/frequenz-lib-notebooks/actions/workflows/ci.yaml)
[](https://pypi.org/project/frequenz-lib-notebooks/)
[](https://frequenz-floss.github.io/frequenz-lib-notebooks/)
## 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](CONTRIBUTING.md).
## Quick Start
Install the package, open the example notebooks, and explore the available modules.
### Installation
```
# Choose the version you want to install
VERSION=0.9.2
pip install frequenz‑lib‑notebooks==$VERSION
```
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](https://github.com/frequenz-floss/frequenz-lib-notebooks/wiki/Frequenz-Lib-Notebooks-%E2%80%90-Overview) which has links to dedicated project pages.
The full code documentation can be accessed [here](https://frequenz-floss.github.io/frequenz-lib-notebooks/latest/).
Raw data
{
"_id": null,
"home_page": null,
"name": "frequenz-lib-notebooks",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.11",
"maintainer_email": null,
"keywords": "frequenz, python, lib, library, frequenz-lib-notebooks, tooling, notebooks",
"author": null,
"author_email": "Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>",
"download_url": "https://files.pythonhosted.org/packages/10/37/2f58ce908caff8cb2466693021abe769b2f2d3095e7514819041552cb621/frequenz_lib_notebooks-0.11.1.tar.gz",
"platform": null,
"description": "# Tooling Library for Notebooks\n\n[](https://github.com/frequenz-floss/frequenz-lib-notebooks/actions/workflows/ci.yaml)\n[](https://pypi.org/project/frequenz-lib-notebooks/)\n[](https://frequenz-floss.github.io/frequenz-lib-notebooks/)\n\n## Introduction\n\nA 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.\n\n## Supported Platforms\n\nThe following platforms are officially supported (tested):\n\n- **Python:** 3.11\n- **Operating System:** Ubuntu Linux 20.04\n- **Architectures:** amd64, arm64\n\n## Contributing\n\nIf you want to know how to build this project and contribute to it, please\ncheck out the [Contributing Guide](CONTRIBUTING.md).\n\n## Quick Start\n\nInstall the package, open the example notebooks, and explore the available modules.\n\n### Installation\n\n```\n# Choose the version you want to install\nVERSION=0.9.2\npip install frequenz\u2011lib\u2011notebooks==$VERSION\n```\n\nThen open the prebuilt example notebooks using your preferred interface:\n- Classic Notebook: `jupyter examples/`\n- JupyterLab: `jupyter-lab examples/`\n\n\u26a0\ufe0f **Note**: This project does **not** install `jupyter` or `jupyterlab` by default. You will need to install it separately if you want to run notebooks:\n\n```\npip install jupyterlab\n```\n\n### Code Examples\n\n#### \ud83d\udce7 Example 1: Generate an Alert Email (HTML Body Only)\n\nThis example shows how to:\n- Transform a `pandas` DataFrame of alert records into a structured HTML email using `generate_alert_email`.\n- Use `AlertEmailConfig` to control layout (e.g., table row limits, sorting by severity).\n- Integrate microgrid-component alerts cleanly into operational workflows (e.g., for notifications or reporting tools).\n\n```\nimport pandas as pd\nfrom IPython.display import HTML\n\nfrom frequenz.lib.notebooks.alerts.alert_email import (\n AlertEmailConfig,\n generate_alert_email,\n)\nfrom frequenz.lib.notebooks.notification_utils import format_email_preview\n\n# Example alert records dataframe\nalert_records = pd.DataFrame(\n [\n {\n \"microgrid_id\": 1,\n \"component_id\": 1,\n \"state_type\": \"error\",\n \"state_value\": \"UNDERVOLTAGE\",\n \"start_time\": \"2025-03-14 15:06:30\",\n \"end_time\": \"2025-03-14 17:00:00\",\n },\n {\n \"microgrid_id\": 2,\n \"component_id\": 1,\n \"state_type\": \"state\",\n \"state_value\": \"DISCHARGING\",\n \"start_time\": \"2025-03-14 15:06:30\",\n \"end_time\": None,\n },\n ]\n)\n\n# Configuration for email generation\nalert_email_config = AlertEmailConfig(\n displayed_rows=10,\n sort_by_severity=True,\n)\n\n# Generate the HTML body of the alert email\nhtml_email = generate_alert_email(\n alert_records=alert_records, config=alert_email_config\n)\n\n# Output the HTML # or send it via email as shown in the next example\nprint(html_email)\n\n# or preview it in a nicer format\nHTML(format_email_preview(subject=\"Alert Notification\", body_html=html_email))\n```\n\n#### \ud83d\udce8 Example 2: Compose and Send Alert Email with Attachments\nContinuing from Example 1, this snippet builds on the generated HTML email and demonstrates:\n\n- Configuring SMTP credentials and recipients.\n- Attaching both a CSV export of the alert data and optional visual plots.\n- 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!\n\n```\nimport time\nfrom datetime import datetime\n\nfrom frequenz.lib.notebooks.alerts.alert_email import ExportOptions, plot_alerts\nfrom frequenz.lib.notebooks.notification_service import (\n EmailConfig,\n EmailNotification,\n SchedulerConfig,\n)\n\n# Configuration for email notification\nemail_config = EmailConfig(\n subject=\"Critical Alert\",\n message=html_email, # Assuming that html_email already exists. See the code example above on how to generate this.\n recipients=[\"recipient@example.com\"],\n smtp_server=\"smtp.example.com\",\n smtp_port=587,\n smtp_user=\"user@example.com\",\n smtp_password=\"password\",\n from_email=\"alert@example.com\",\n scheduler=SchedulerConfig(\n send_immediately=True,\n interval=60, # send every minute\n duration=3600, # for one hour total\n ),\n)\n# The SMTP details and sender/recipient details need to be adjusted accordingly\n# note that the library provides a convenient way to validate the settings via frequenz.lib.notebooks.notification_utils.validate_email_config\n\n# Create a notification object\nemail_notification = EmailNotification(config=email_config)\n\n# optionally add attachments (a list of files)\nemail_config.attachments = None\ntimestamp = datetime.now().strftime(\"%Y%m%d_%H%M%S\")\nalert_file_name = f\"alert_details_{timestamp}.csv\"\nalert_records.to_csv(alert_file_name, index=False)\nemail_config.attachments = [alert_file_name]\n\n# Optionally create a visualisation of the alert records\nimg_path = plot_alerts(\n records=alert_records,\n plot_type=\"all\",\n export_options=ExportOptions(\n format=\"png\",\n show=True,\n ),\n)\nemail_config.attachments += img_path if img_path else []\n\n# Send one-off notification\nemail_notification.send()\n\n# Or start a periodic scheduler:\nemail_notification.start_scheduler()\ntime.sleep(300) # let it run for 5 minutes\nemail_notification.stop_scheduler()\n```\n\n## Module Overview\n\n- **Solar Maintenance App:** Interactive forecasting and visualisation tools tailored to solar installations.\n- **Notification Service:** Flexible and configurable email dispatching.\n- **Alert Email Generation:** Embed rich Plotly charts into alert emails, complete with context and summaries.\n- **Microgrid Configuration:** Manage structured microgrid metadata\u2014location, devices, etc. \u2014 consistently across notebooks.\n\nFor more details about each module/project, please refer to the overview `Wiki` [page](https://github.com/frequenz-floss/frequenz-lib-notebooks/wiki/Frequenz-Lib-Notebooks-%E2%80%90-Overview) which has links to dedicated project pages.\n\nThe full code documentation can be accessed [here](https://frequenz-floss.github.io/frequenz-lib-notebooks/latest/).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Tooling for notebooks.",
"version": "0.11.1",
"project_urls": {
"Changelog": "https://github.com/frequenz-floss/frequenz-lib-notebooks/releases",
"Documentation": "https://frequenz-floss.github.io/frequenz-lib-notebooks/",
"Issues": "https://github.com/frequenz-floss/frequenz-lib-notebooks/issues",
"Repository": "https://github.com/frequenz-floss/frequenz-lib-notebooks",
"Support": "https://github.com/frequenz-floss/frequenz-lib-notebooks/discussions/categories/support"
},
"split_keywords": [
"frequenz",
" python",
" lib",
" library",
" frequenz-lib-notebooks",
" tooling",
" notebooks"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b1118922c2870a213885f18afff6fa88620cd6043295dd4152c92f55adfd7198",
"md5": "a019323207d547c136b279d4dbfb06a7",
"sha256": "0077eb48e1c75ecca209adc08ba4134cb4bfc496a572e412d27d61cfb24051d6"
},
"downloads": -1,
"filename": "frequenz_lib_notebooks-0.11.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a019323207d547c136b279d4dbfb06a7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.11",
"size": 108776,
"upload_time": "2025-07-23T20:39:22",
"upload_time_iso_8601": "2025-07-23T20:39:22.038344Z",
"url": "https://files.pythonhosted.org/packages/b1/11/8922c2870a213885f18afff6fa88620cd6043295dd4152c92f55adfd7198/frequenz_lib_notebooks-0.11.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "10372f58ce908caff8cb2466693021abe769b2f2d3095e7514819041552cb621",
"md5": "93de7cbf5667627754ec6f1dc7d69812",
"sha256": "a5f4d3101e3b2b6a56b33dc20deba30fb29e255d2d82b40eb1b2d696a9cf9ed3"
},
"downloads": -1,
"filename": "frequenz_lib_notebooks-0.11.1.tar.gz",
"has_sig": false,
"md5_digest": "93de7cbf5667627754ec6f1dc7d69812",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.11",
"size": 1859303,
"upload_time": "2025-07-23T20:39:23",
"upload_time_iso_8601": "2025-07-23T20:39:23.440972Z",
"url": "https://files.pythonhosted.org/packages/10/37/2f58ce908caff8cb2466693021abe769b2f2d3095e7514819041552cb621/frequenz_lib_notebooks-0.11.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-23 20:39:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "frequenz-floss",
"github_project": "frequenz-lib-notebooks",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "frequenz-lib-notebooks"
}
JSON
