Better support for carbonboard (#1014)

Co-authored-by: benoit-cty <anne@onyme.fr>

Author: benoit-cty

.github/workflows/test-package.yml

@@ -27,3 +27,7 @@ jobs:
       run: uv sync --python ${{ matrix.python-version }}
     - name: Test package
       run: uv run --python ${{ matrix.python-version }} task test-package
+    - name: Install carbonboard dependencies
+      run: uv pip install --python ${{ matrix.python-version }} dash 'dash_bootstrap_components>1.0.0' fire
+    - name: Test carbonboard visualization
+      run: uv run --python ${{ matrix.python-version }} pytest -vv tests/test_viz_data.py tests/test_viz_units.py

CONTRIBUTING.md

@@ -326,13 +326,15 @@ pytest test_package_integrity.py
 To run locally the dashboard application, you can use it out on a sample data file such as the one in `examples/emissions.csv`, and run it with the following command from the code base:
 
 ```bash
-uv run --extra viz-legacy  task carbonboard --filepath="examples/emissions.csv"
+uv run --extra carbonboard task carbonboard --filepath="examples/emissions.csv"
 
 # or, if you don't want to use UV
-pip install codecarbon["viz"]
+pip install codecarbon[carbonboard]
 python codecarbon/viz/carbonboard.py --filepath="examples/emissions.csv"
 ```
 
+> **Note:** The `viz-legacy` extra is deprecated but still works for backwards compatibility. It will be removed in v4.0.0. Please use `carbonboard` instead.
+
 If you have the package installed, you can run the CLI command:
 
 ```bash

codecarbon/viz/carbonboard.py

@@ -1,6 +1,32 @@
-import dash
-import dash_bootstrap_components as dbc
-import fire
+import sys
+
+try:
+    import dash
+    import dash_bootstrap_components as dbc
+except ImportError:
+    print(
+        "\n❌ Error: Carbonboard requires additional dependencies that are not installed.\n"
+        "\nTo install them, run:\n"
+        "    pip install codecarbon[carbonboard]\n"
+        "\nOr if using uv:\n"
+        "    uv pip install codecarbon[carbonboard]\n",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+try:
+    import fire
+except ImportError:
+    print(
+        "\n❌ Error: Carbonboard requires 'fire' which is not installed.\n"
+        "\nTo install it, run:\n"
+        "    pip install codecarbon[carbonboard]\n"
+        "\nOr if using uv:\n"
+        "    uv pip install codecarbon[carbonboard]\n",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
 import pandas as pd
 from dash import dash_table as dt
 from dash import dcc

docs/edit/visualize.rst

@@ -8,6 +8,19 @@ Offline
 The package also comes with a ``Dash App`` containing illustrations to understand the emissions logged from various experiments across projects.
 The App currently consumes logged information from a CSV file, generated from an in-built logger in the package.
 
+Installation
+~~~~~~~~~~~~
+The carbonboard visualization tool requires additional dependencies. Install them with:
+
+.. code-block:: bash
+
+    pip install codecarbon[carbonboard]
+
+.. note::
+   The ``viz-legacy`` extra is deprecated but still works for backwards compatibility. It will be removed in v4.0.0. Please use ``carbonboard`` instead.
+
+Usage
+~~~~~
 The App can be run by executing the below CLI command that needs following arguments:
 
 - ``filepath`` - path to the CSV file containing logged information across experiments and projects
@@ -107,6 +120,5 @@ The app also provides a visualization of regional carbon intensity of electricit
             :alt: carbon intensity carbon_map
             :width: 750px
 
-Note that for now, all data sent to CodeCarbon API are public.
 
 

pyproject.toml

@@ -98,22 +98,16 @@ doc = [
 ]
 
 [project.optional-dependencies]
-viz-legacy = [
+carbonboard = [
     "dash",
     "dash_bootstrap_components > 1.0.0",
     "fire",
 ]
-
-viz = [
-   "mock",
-   "pytest",
-   "responses",
-   "numpy<2.0.0;python_version<'3.9'",
-   "numpy;python_version>='3.9'",
-   "psutil",
-   "requests-mock",
-   "rapidfuzz",
-   "importlib_resources;python_version<'3.9'"
+# Backwards compatibility alias - will be removed in v4.0.0
+viz-legacy = [
+    "dash",
+    "dash_bootstrap_components > 1.0.0",
+    "fire",
 ]
 api  = [
     "alembic<2.0.0",