codecarbon 3.2.9__tar.gz → 3.3.1__tar.gz

{codecarbon-3.2.9 → codecarbon-3.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecarbon
-Version: 3.2.9
+Version: 3.3.1
 Author: Mila, DataForGood, BCG GAMMA, Comet.ml, Haverford College
 License-Expression: MIT
 Project-URL: Homepage, https://codecarbon.io/
@@ -137,18 +137,19 @@ You can visualize your experiment emissions on the [dashboard](https://dashboard
 
 ## Quick links
 
-| Section | Description |
-|---------|-------------|
-| [Quickstart](https://docs.codecarbon.io/latest/tutorials/first-tracking/) | Get started in 5 minutes |
-| [Installation](https://docs.codecarbon.io/latest/how-to/installation/) | Install CodeCarbon |
-| [CLI Tutorial](https://docs.codecarbon.io/latest/tutorials/cli/) | Track emissions from the command line |
-| [Python API Tutorial](https://docs.codecarbon.io/latest/tutorials/python-api/) | Track emissions in Python code |
+| Section                                                                                               | Description                                |
+| ----------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| [Quickstart](https://docs.codecarbon.io/latest/tutorials/first-tracking/)                             | Get started in 5 minutes                   |
+| [Installation](https://docs.codecarbon.io/latest/how-to/installation/)                                | Install CodeCarbon                         |
+| [CLI Tutorial](https://docs.codecarbon.io/latest/tutorials/cli/)                                      | Track emissions from the command line      |
+| [Python API Tutorial](https://docs.codecarbon.io/latest/tutorials/python-api/)                        | Track emissions in Python code             |
 | [Comparing Model Efficiency](https://docs.codecarbon.io/latest/tutorials/comparing-model-efficiency/) | Measure carbon efficiency across ML models |
-| [API Reference](https://docs.codecarbon.io/latest/reference/api/) | Full parameter documentation |
-| [Framework examples (scikit-learn)](https://docs.codecarbon.io/latest/how-to/scikit-learn/) | Task-oriented ML framework examples |
-| [Methodology](https://docs.codecarbon.io/latest/explanation/methodology/) | How emissions are calculated |
-| [EcoLogits](https://ecologits.ai/) | Track emissions from GenAI API calls |
-| [Discord Community](https://discord.gg/GS9js2XkJR) | Chat with us and the community |
+| [API Reference](https://docs.codecarbon.io/latest/reference/api/)                                     | Full parameter documentation               |
+| [Framework examples (scikit-learn)](https://docs.codecarbon.io/latest/how-to/scikit-learn/)           | Task-oriented ML framework examples        |
+| [Methodology](https://docs.codecarbon.io/latest/explanation/methodology/)                             | How emissions are calculated               |
+| [When to use CodeCarbon vs EcoLogits](https://docs.codecarbon.io/latest/explanation/when-to-use/)     | Choose the right tool                      |
+| [EcoLogits](https://ecologits.ai/)                                                                    | Track emissions from GenAI API calls       |
+| [Discord Community](https://discord.gg/GS9js2XkJR)                                                    | Chat with us and the community             |
 
 ## Links
 
@@ -156,6 +157,7 @@ You can visualize your experiment emissions on the [dashboard](https://dashboard
 - [Dashboard](https://dashboard.codecarbon.io/) to see your emissions.
 - [Documentation](https://docs.codecarbon.io/) to learn how to use the package and our methodology.
 - [EcoLogits](https://ecologits.ai/) to track emissions from GenAI API calls (OpenAI, Anthropic, etc.).
+- [mlco2 on GitHub](https://github.com/mlco2) for our other open-source projects.
 - [GitHub](https://github.com/mlco2/codecarbon) to look at the source code and contribute.
 - [Discord](https://discord.gg/GS9js2XkJR) to chat with us.
 
@@ -210,7 +212,7 @@ If you find CodeCarbon useful for your research, you can find a citation under a
                   MinervaBooks},
   title        = {mlco2/codecarbon: v2.4.1},
   month        = may,
-  year         = 2024,
+  year         = {2024},
   publisher    = {Zenodo},
   version      = {v2.4.1},
   doi          = {10.5281/zenodo.11171501},
@@ -228,6 +230,34 @@ Codecarbon was formerly developed by volunteers from [**Mila**](http://mila.queb
 
 Now CodeCarbon is supported by [**Code Carbon**](https://www.helloasso.com/associations/code-carbon), a French non-profit organization whose mission is to accelerate the development and adoption of CodeCarbon.
 
-### Star History
-
-[![Star History Chart](https://api.star-history.com/svg?repos=mlco2/codecarbon,lfwa/carbontracker,sb-ai-lab/Eco2AI,fvaleye/tracarbon,Breakend/experiment-impact-tracker&type=Date)](https://star-history.com/#mlco2/codecarbon&lfwa/carbontracker&sb-ai-lab/Eco2AI&fvaleye/tracarbon&Breakend/experiment-impact-tracker&Date)
+## Sponsors
+
+<div align="center">
+  <a href="https://www.clever-cloud.com/">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/mlco2/codecarbon-landing-page/main/public/assets/partners/clever_cloud.png">
+      <img src="https://cdn.clever-cloud.com/uploads/2023/03/logoonwhite.svg" alt="Clever Cloud" height="48">
+    </picture>
+  </a>
+  &nbsp;&nbsp;&nbsp;
+  <a href="https://dataforgood.fr/">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/mlco2/codecarbon-landing-page/main/public/assets/partners/dataforgood.png">
+      <img src="https://dataforgood.fr/images/dataforgood.svg" alt="Data For Good" height="48">
+    </picture>
+  </a>
+  &nbsp;&nbsp;&nbsp;
+  <a href="https://github.com/">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/mlco2/codecarbon-landing-page/main/public/assets/partners/GitHub.png">
+      <img src="https://github.githubassets.com/images/modules/logos_page/GitHub-Logo.png" alt="GitHub" height="48">
+    </picture>
+  </a>
+  &nbsp;&nbsp;&nbsp;
+  <a href="https://www.mozilla.org/">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/mlco2/codecarbon-landing-page/main/public/assets/partners/mozilla.svg">
+      <img src="https://upload.wikimedia.org/wikipedia/commons/d/df/Mozilla_2024_logo.svg" alt="Mozilla" height="48">
+    </picture>
+  </a>
+</div>

{codecarbon-3.2.9 → codecarbon-3.3.1}/README.md

@@ -90,18 +90,19 @@ You can visualize your experiment emissions on the [dashboard](https://dashboard
 
 ## Quick links
 
-| Section | Description |
-|---------|-------------|
-| [Quickstart](https://docs.codecarbon.io/latest/tutorials/first-tracking/) | Get started in 5 minutes |
-| [Installation](https://docs.codecarbon.io/latest/how-to/installation/) | Install CodeCarbon |
-| [CLI Tutorial](https://docs.codecarbon.io/latest/tutorials/cli/) | Track emissions from the command line |
-| [Python API Tutorial](https://docs.codecarbon.io/latest/tutorials/python-api/) | Track emissions in Python code |
+| Section                                                                                               | Description                                |
+| ----------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| [Quickstart](https://docs.codecarbon.io/latest/tutorials/first-tracking/)                             | Get started in 5 minutes                   |
+| [Installation](https://docs.codecarbon.io/latest/how-to/installation/)                                | Install CodeCarbon                         |
+| [CLI Tutorial](https://docs.codecarbon.io/latest/tutorials/cli/)                                      | Track emissions from the command line      |
+| [Python API Tutorial](https://docs.codecarbon.io/latest/tutorials/python-api/)                        | Track emissions in Python code             |
 | [Comparing Model Efficiency](https://docs.codecarbon.io/latest/tutorials/comparing-model-efficiency/) | Measure carbon efficiency across ML models |
-| [API Reference](https://docs.codecarbon.io/latest/reference/api/) | Full parameter documentation |
-| [Framework examples (scikit-learn)](https://docs.codecarbon.io/latest/how-to/scikit-learn/) | Task-oriented ML framework examples |
-| [Methodology](https://docs.codecarbon.io/latest/explanation/methodology/) | How emissions are calculated |
-| [EcoLogits](https://ecologits.ai/) | Track emissions from GenAI API calls |
-| [Discord Community](https://discord.gg/GS9js2XkJR) | Chat with us and the community |
+| [API Reference](https://docs.codecarbon.io/latest/reference/api/)                                     | Full parameter documentation               |
+| [Framework examples (scikit-learn)](https://docs.codecarbon.io/latest/how-to/scikit-learn/)           | Task-oriented ML framework examples        |
+| [Methodology](https://docs.codecarbon.io/latest/explanation/methodology/)                             | How emissions are calculated               |
+| [When to use CodeCarbon vs EcoLogits](https://docs.codecarbon.io/latest/explanation/when-to-use/)     | Choose the right tool                      |
+| [EcoLogits](https://ecologits.ai/)                                                                    | Track emissions from GenAI API calls       |
+| [Discord Community](https://discord.gg/GS9js2XkJR)                                                    | Chat with us and the community             |
 
 ## Links
 
@@ -109,6 +110,7 @@ You can visualize your experiment emissions on the [dashboard](https://dashboard
 - [Dashboard](https://dashboard.codecarbon.io/) to see your emissions.
 - [Documentation](https://docs.codecarbon.io/) to learn how to use the package and our methodology.
 - [EcoLogits](https://ecologits.ai/) to track emissions from GenAI API calls (OpenAI, Anthropic, etc.).
+- [mlco2 on GitHub](https://github.com/mlco2) for our other open-source projects.
 - [GitHub](https://github.com/mlco2/codecarbon) to look at the source code and contribute.
 - [Discord](https://discord.gg/GS9js2XkJR) to chat with us.
 
@@ -163,7 +165,7 @@ If you find CodeCarbon useful for your research, you can find a citation under a
                   MinervaBooks},
   title        = {mlco2/codecarbon: v2.4.1},
   month        = may,
-  year         = 2024,
+  year         = {2024},
   publisher    = {Zenodo},
   version      = {v2.4.1},
   doi          = {10.5281/zenodo.11171501},
@@ -181,6 +183,34 @@ Codecarbon was formerly developed by volunteers from [**Mila**](http://mila.queb
 
 Now CodeCarbon is supported by [**Code Carbon**](https://www.helloasso.com/associations/code-carbon), a French non-profit organization whose mission is to accelerate the development and adoption of CodeCarbon.
 
-### Star History
-
-[![Star History Chart](https://api.star-history.com/svg?repos=mlco2/codecarbon,lfwa/carbontracker,sb-ai-lab/Eco2AI,fvaleye/tracarbon,Breakend/experiment-impact-tracker&type=Date)](https://star-history.com/#mlco2/codecarbon&lfwa/carbontracker&sb-ai-lab/Eco2AI&fvaleye/tracarbon&Breakend/experiment-impact-tracker&Date)
+## Sponsors
+
+<div align="center">
+  <a href="https://www.clever-cloud.com/">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/mlco2/codecarbon-landing-page/main/public/assets/partners/clever_cloud.png">
+      <img src="https://cdn.clever-cloud.com/uploads/2023/03/logoonwhite.svg" alt="Clever Cloud" height="48">
+    </picture>
+  </a>
+  &nbsp;&nbsp;&nbsp;
+  <a href="https://dataforgood.fr/">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/mlco2/codecarbon-landing-page/main/public/assets/partners/dataforgood.png">
+      <img src="https://dataforgood.fr/images/dataforgood.svg" alt="Data For Good" height="48">
+    </picture>
+  </a>
+  &nbsp;&nbsp;&nbsp;
+  <a href="https://github.com/">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/mlco2/codecarbon-landing-page/main/public/assets/partners/GitHub.png">
+      <img src="https://github.githubassets.com/images/modules/logos_page/GitHub-Logo.png" alt="GitHub" height="48">
+    </picture>
+  </a>
+  &nbsp;&nbsp;&nbsp;
+  <a href="https://www.mozilla.org/">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/mlco2/codecarbon-landing-page/main/public/assets/partners/mozilla.svg">
+      <img src="https://upload.wikimedia.org/wikipedia/commons/d/df/Mozilla_2024_logo.svg" alt="Mozilla" height="48">
+    </picture>
+  </a>
+</div>

codecarbon-3.3.1/codecarbon/_version.py

@@ -0,0 +1 @@
+__version__ = "3.3.1"

{codecarbon-3.2.9 → codecarbon-3.3.1}/codecarbon/cli/auth.py

@@ -86,8 +86,15 @@ def _discover_endpoints():
 
 def _save_credentials(tokens):
     """Save OAuth tokens to the local credentials file."""
-    with open(_CREDENTIALS_FILE, "w") as f:
-        json.dump(tokens, f)
+    try:
+        with open(_CREDENTIALS_FILE, "w") as f:
+            json.dump(tokens, f)
+    except OSError as e:
+        raise ValueError(
+            f"Could not write the credentials file {_CREDENTIALS_FILE.resolve()} "
+            f"(error: {e}). Please run the command from a directory you can "
+            "write to."
+        )
 
 
 def _load_credentials():
@@ -169,6 +176,7 @@ def authorize():
     server = HTTPServer(("localhost", _REDIRECT_PORT), _CallbackHandler)
 
     print("Opening browser for authentication...")
+    print(f"If no browser opens, copy this URL into your browser:\n{uri}")
     webbrowser.open(uri)
 
     server.handle_request()

{codecarbon-3.2.9 → codecarbon-3.3.1}/codecarbon/cli/main.py

@@ -40,6 +40,20 @@ def main():
         raise sys.exit(1)
 
 
+def _api_call(action: str, func, *args, **kwargs):
+    """
+    Run a call to the Code Carbon API, turning the errors it now raises into a
+    readable message and a clean exit instead of a traceback.
+
+    :action: what was being attempted, used as the first part of the message.
+    """
+    try:
+        return func(*args, **kwargs)
+    except Exception as e:
+        print(f"[yellow]{action}[/yellow]. (error: {e})")
+        raise typer.Exit(1)
+
+
 def _version_callback(value: bool) -> None:
     if value:
         print(f"{__app_name__} v{__version__}")
@@ -116,7 +130,7 @@ def api_get():
     api_endpoint = get_api_endpoint()
     api = ApiClient(endpoint_url=api_endpoint)
     api.set_access_token(get_access_token())
-    organizations = api.get_list_organizations()
+    organizations = _api_call("API request failed", api.get_list_organizations)
     print(organizations)
 
 
@@ -130,7 +144,7 @@ def login():
     api = ApiClient(endpoint_url=api_endpoint)
     access_token = get_access_token()
     api.set_access_token(access_token)
-    api.check_auth()
+    _api_call("Authentication check failed", api.check_auth)
 
 
 def get_api_key(project_id: str):
@@ -149,6 +163,7 @@ def get_api_key(project_id: str):
         },
         headers={"Authorization": f"Bearer {get_access_token()}"},
     )
+    req.raise_for_status()
     api_key = req.json()["token"]
     return api_key
 
@@ -212,7 +227,10 @@ def config():
     overwrite_local_config("api_endpoint", api_endpoint, path=file_path)
     api = ApiClient(endpoint_url=api_endpoint)
     api.set_access_token(get_access_token())
-    organizations = api.get_list_organizations()
+    organizations = _api_call(
+        "Could not list organizations from API. Please check your login and API endpoint",
+        api.get_list_organizations,
+    )
     org = questionary_prompt(
         "Pick existing organization from list or Create new organization ?",
         [org["name"] for org in organizations] + ["Create New Organization"],
@@ -229,18 +247,23 @@ def config():
             name=org_name,
             description=org_description,
         )
-        organization = api.create_organization(organization=organization_create)
-        if organization is None:
-            print("Error creating organization")
-            return
+        organization = _api_call(
+            "Could not create the organization",
+            api.create_organization,
+            organization=organization_create,
+        )
         print(f"Created organization : {organization}")
     else:
         organization = [orga for orga in organizations if orga["name"] == org][0]
     org_id = organization["id"]
     overwrite_local_config("organization_id", org_id, path=file_path)
 
-    projects = api.list_projects_from_organization(org_id)
-    project_names = [project["name"] for project in projects] if projects else []
+    projects = _api_call(
+        "Could not list projects from API",
+        api.list_projects_from_organization,
+        org_id,
+    )
+    project_names = [project["name"] for project in projects]
     project = questionary_prompt(
         "Pick existing project from list or Create new project ?",
         project_names + ["Create New Project"],
@@ -256,17 +279,21 @@ def config():
             description=project_description,
             organization_id=org_id,
         )
-        project = api.create_project(project=project_create)
+        project = _api_call(
+            "Could not create the project", api.create_project, project=project_create
+        )
         print(f"Created project : {project}")
     else:
         project = [p for p in projects if p["name"] == project][0]
     project_id = project["id"]
     overwrite_local_config("project_id", project_id, path=file_path)
 
-    experiments = api.list_experiments_from_project(project_id)
-    experiments_names = (
-        [experiment["name"] for experiment in experiments] if experiments else []
+    experiments = _api_call(
+        "Could not list experiments from API",
+        api.list_experiments_from_project,
+        project_id,
     )
+    experiments_names = [experiment["name"] for experiment in experiments]
 
     experiment = questionary_prompt(
         "Pick existing experiment from list or Create new experiment ?",
@@ -313,13 +340,17 @@ def config():
             cloud_provider=cloud_provider,
             cloud_region=cloud_region,
         )
-        experiment = api.add_experiment(experiment=experiment_create)
+        experiment = _api_call(
+            "Could not create the experiment",
+            api.add_experiment,
+            experiment=experiment_create,
+        )
 
     else:
         experiment = [e for e in experiments if e["name"] == experiment][0]
 
     overwrite_local_config("experiment_id", experiment["id"], path=file_path)
-    api_key = get_api_key(project_id)
+    api_key = _api_call("Could not get the project API key", get_api_key, project_id)
     overwrite_local_config("api_key", api_key, path=file_path)
     show_config(file_path)
     print(
@@ -327,6 +358,34 @@ def config():
     )
 
 
+def _cli_provided(ctx, name: str) -> bool:
+    """
+    Whether the option `name` was typed on the command line (or set through its
+    environment variable) rather than left at its Typer default.
+
+    Options left at their default must not be forwarded to the tracker: doing so
+    would silently override the values coming from `.codecarbon.config` and the
+    `CODECARBON_*` environment variables, which the tracker reads itself.
+    """
+    get_source = getattr(ctx, "get_parameter_source", None)
+    if get_source is None:
+        # `monitor` called directly from Python, not through Click: every value
+        # given is explicit.
+        return True
+    source = get_source(name)
+    return source is None or source.name in ("COMMANDLINE", "ENVIRONMENT")
+
+
+def _external_config() -> dict:
+    """The configuration files and CODECARBON_* variables, as a plain dict."""
+    from codecarbon.core.config import get_hierarchical_config
+
+    try:
+        return dict(get_hierarchical_config())
+    except Exception:
+        return {}
+
+
 @codecarbon.command(
     "monitor",
     short_help="Monitor your machine's carbon emissions.",
@@ -362,15 +421,28 @@ def monitor(
 ):
     """Monitor your machine's carbon emissions."""
 
-    # Shared tracker args so monitor and run_and_monitor behave the same
+    external_conf = _external_config()
+
+    # Shared tracker args so monitor and run_and_monitor behave the same.
+    # Only the options actually given are forwarded: the others are left to the
+    # tracker, which resolves them from the configuration file and environment.
+    cli_defaults = (
+        ("measure_power_secs", measure_power_secs),
+        ("api_call_interval", api_call_interval),
+        ("log_level", log_level),
+    )
     tracker_args = {
-        "measure_power_secs": measure_power_secs,
-        "api_call_interval": api_call_interval,
-        "log_level": log_level,
+        name: value for name, value in cli_defaults if _cli_provided(ctx, name)
     }
+    for name, value in cli_defaults:
+        if name not in tracker_args and name not in external_conf:
+            # Nothing configures it: keep the defaults advertised by `--help`
+            # (and an unattended monitor quiet) instead of the tracker's own.
+            tracker_args[name] = value
+
     # Set up the tracker arguments based on mode (offline vs online) and validate required args for each mode
     if offline:
-        if not country_iso_code:
+        if not country_iso_code and not external_conf.get("country_iso_code"):
             print(
                 "ERROR: Country ISO code is required for offline mode. Add it to your configuration or provide it via the command line: `--country-iso-code FRA`",
                 file=sys.stderr,
@@ -379,8 +451,8 @@ def monitor(
 
         tracker_args = {
             **tracker_args,
-            "country_iso_code": country_iso_code,
-            "region": region,
+            **({"country_iso_code": country_iso_code} if country_iso_code else {}),
+            **({"region": region} if region else {}),
         }
     else:
         experiment_id = get_existing_exp_id()

{codecarbon-3.2.9 → codecarbon-3.3.1}/codecarbon/cli/monitor.py

@@ -3,6 +3,7 @@
 import os
 import subprocess
 import sys
+from typing import Optional
 
 import typer
 from rich import print
@@ -12,9 +13,9 @@ from typing_extensions import Annotated
 def run_and_monitor(
     ctx: typer.Context,
     log_level: Annotated[
-        str,
+        Optional[str],
         typer.Option(help="Log level (critical, error, warning, info, debug)"),
-    ] = "error",
+    ] = None,
     offline: bool = False,
     **tracker_args,
 ):
@@ -51,7 +52,11 @@ def run_and_monitor(
     from codecarbon.emissions_tracker import EmissionsTracker, OfflineEmissionsTracker
     from codecarbon.external.logger import set_logger_level
 
-    set_logger_level(log_level)
+    # `log_level` is None when nothing set it: leave it to the tracker, which
+    # resolves it from the configuration file and the environment.
+    if log_level is not None:
+        set_logger_level(log_level)
+        tracker_args["log_level"] = log_level
 
     # Get the command from remaining args (strip nested subcommand / `--` leftovers)
     command = list(getattr(ctx, "args", None) or [])
@@ -67,7 +72,6 @@ def run_and_monitor(
 
     tracker_cls = OfflineEmissionsTracker if offline else EmissionsTracker
     tracker = tracker_cls(
-        log_level=log_level,
         save_to_logger=False,
         tracking_mode="process",
         **tracker_args,