codecarbon 3.2.6__tar.gz → 3.2.8__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (130) hide show
  1. codecarbon-3.2.8/PKG-INFO +233 -0
  2. codecarbon-3.2.8/README.md +186 -0
  3. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/__init__.py +7 -1
  4. codecarbon-3.2.8/codecarbon/_version.py +1 -0
  5. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/cli/auth.py +13 -6
  6. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/cli/main.py +2 -2
  7. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/cli/monitor.py +4 -3
  8. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/core/api_client.py +4 -0
  9. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/core/cpu.py +8 -7
  10. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/core/emissions.py +40 -16
  11. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/core/gpu_amd.py +1 -1
  12. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/core/powermetrics.py +1 -1
  13. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/core/schemas.py +4 -0
  14. codecarbon-3.2.8/codecarbon/core/telemetry_client.py +61 -0
  15. codecarbon-3.2.8/codecarbon/core/telemetry_schemas.py +156 -0
  16. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/data/hardware/cpu_power.csv +1 -0
  17. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/emissions_tracker.py +304 -160
  18. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/external/ram.py +1 -1
  19. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/output.py +1 -1
  20. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/output_methods/base_output.py +27 -0
  21. codecarbon-3.2.8/codecarbon.egg-info/PKG-INFO +233 -0
  22. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon.egg-info/SOURCES.txt +4 -0
  23. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon.egg-info/requires.txt +2 -4
  24. {codecarbon-3.2.6 → codecarbon-3.2.8}/pyproject.toml +11 -8
  25. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_api_call.py +9 -0
  26. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_config.py +102 -1
  27. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_cpu.py +34 -3
  28. codecarbon-3.2.8/tests/test_docs_examples.py +53 -0
  29. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_emissions.py +98 -0
  30. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_emissions_tracker.py +145 -0
  31. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_gpu_amd.py +73 -0
  32. codecarbon-3.2.8/tests/test_telemetry_client.py +104 -0
  33. codecarbon-3.2.6/PKG-INFO +0 -267
  34. codecarbon-3.2.6/README.md +0 -219
  35. codecarbon-3.2.6/codecarbon/_version.py +0 -1
  36. codecarbon-3.2.6/codecarbon.egg-info/PKG-INFO +0 -267
  37. {codecarbon-3.2.6 → codecarbon-3.2.8}/LICENSE +0 -0
  38. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/cli/__init__.py +0 -0
  39. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/cli/cli_utils.py +0 -0
  40. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/core/__init__.py +0 -0
  41. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/core/cloud.py +0 -0
  42. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/core/config.py +0 -0
  43. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/core/electricitymaps_api.py +0 -0
  44. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/core/gpu.py +0 -0
  45. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/core/gpu_device.py +0 -0
  46. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/core/gpu_nvidia.py +0 -0
  47. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/core/measure.py +0 -0
  48. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/core/rapl.py +0 -0
  49. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/core/resource_tracker.py +0 -0
  50. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/core/units.py +0 -0
  51. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/core/util.py +0 -0
  52. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/data/canada_provinces.geojson +0 -0
  53. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/data/cloud/impact.csv +0 -0
  54. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/data/hardware/cpu_dataset_builder/amd_cpu_scrapper.py +0 -0
  55. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/data/hardware/cpu_dataset_builder/intel_cpu_scrapper.py +0 -0
  56. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/data/hardware/cpu_dataset_builder/merge_scrapped_cpu_power.py +0 -0
  57. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/data/private_infra/2016/usa_emissions.json +0 -0
  58. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/data/private_infra/2023/canada_energy_mix.json +0 -0
  59. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/data/private_infra/carbon_intensity_per_source.json +0 -0
  60. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/data/private_infra/global_energy_mix.json +0 -0
  61. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/data/private_infra/nordic_emissions.json +0 -0
  62. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/external/__init__.py +0 -0
  63. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/external/geography.py +0 -0
  64. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/external/hardware.py +0 -0
  65. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/external/logger.py +0 -0
  66. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/external/scheduler.py +0 -0
  67. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/external/task.py +0 -0
  68. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/input.py +0 -0
  69. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/lock.py +0 -0
  70. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/output_methods/__init__.py +0 -0
  71. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/output_methods/boamps/__init__.py +0 -0
  72. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/output_methods/boamps/mapper.py +0 -0
  73. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/output_methods/boamps/models.py +0 -0
  74. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/output_methods/boamps/output.py +0 -0
  75. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/output_methods/emissions_data.py +0 -0
  76. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/output_methods/file.py +0 -0
  77. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/output_methods/http.py +0 -0
  78. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/output_methods/logger.py +0 -0
  79. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/output_methods/metrics/__init__.py +0 -0
  80. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/output_methods/metrics/logfire.py +0 -0
  81. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/output_methods/metrics/metric_docs.py +0 -0
  82. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/output_methods/metrics/prometheus.py +0 -0
  83. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/py.typed +0 -0
  84. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/viz/__init__.py +0 -0
  85. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/viz/assets/__init__.py +0 -0
  86. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/viz/assets/car_icon.png +0 -0
  87. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/viz/assets/house_icon.png +0 -0
  88. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/viz/assets/tv_icon.png +0 -0
  89. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/viz/carbonboard.py +0 -0
  90. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/viz/carbonboard_on_api.py +0 -0
  91. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/viz/components.py +0 -0
  92. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/viz/data.py +0 -0
  93. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon/viz/units.py +0 -0
  94. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon.egg-info/dependency_links.txt +0 -0
  95. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon.egg-info/entry_points.txt +0 -0
  96. {codecarbon-3.2.6 → codecarbon-3.2.8}/codecarbon.egg-info/top_level.txt +0 -0
  97. {codecarbon-3.2.6 → codecarbon-3.2.8}/setup.cfg +0 -0
  98. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_boamps_output.py +0 -0
  99. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_cloud.py +0 -0
  100. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_core_util.py +0 -0
  101. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_cpu_load.py +0 -0
  102. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_custom_handler.py +0 -0
  103. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_electricitymaps_api.py +0 -0
  104. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_electricitymaps_backward_compatibility.py +0 -0
  105. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_electricitymaps_config_backward_compatibility.py +0 -0
  106. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_emissions_tracker_constant.py +0 -0
  107. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_emissions_tracker_flush.py +0 -0
  108. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_energy.py +0 -0
  109. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_geography.py +0 -0
  110. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_gpu.py +0 -0
  111. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_gpu_nvidia.py +0 -0
  112. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_input.py +0 -0
  113. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_lock.py +0 -0
  114. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_logger.py +0 -0
  115. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_logging_output.py +0 -0
  116. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_offline_emissions_tracker.py +0 -0
  117. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_package_integrity.py +0 -0
  118. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_powermetrics.py +0 -0
  119. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_ram.py +0 -0
  120. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_rapl_mmio_scanning.py +0 -0
  121. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_rapl_parameters.py +0 -0
  122. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_rapl_permissions.py +0 -0
  123. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_resource_tracker.py +0 -0
  124. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_tracking_inference.py +0 -0
  125. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_unsupported_gpu.py +0 -0
  126. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_utilization_tracking.py +0 -0
  127. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_viz_data.py +0 -0
  128. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/test_viz_units.py +0 -0
  129. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/testdata.py +0 -0
  130. {codecarbon-3.2.6 → codecarbon-3.2.8}/tests/testutils.py +0 -0
@@ -0,0 +1,233 @@
1
+ Metadata-Version: 2.4
2
+ Name: codecarbon
3
+ Version: 3.2.8
4
+ Author: Mila, DataForGood, BCG GAMMA, Comet.ml, Haverford College
5
+ License-Expression: MIT
6
+ Project-URL: Homepage, https://codecarbon.io/
7
+ Project-URL: Repository, https://github.com/mlco2/codecarbon
8
+ Project-URL: Dashboard, http://dashboard.codecarbon.io/
9
+ Project-URL: Documentation, https://docs.codecarbon.io/
10
+ Project-URL: Issues, https://github.com/mlco2/codecarbon/issues
11
+ Project-URL: Changelog, https://github.com/mlco2/codecarbon/releases
12
+ Classifier: Natural Language :: English
13
+ Classifier: Programming Language :: Python :: 3.10
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: Programming Language :: Python :: 3.14
18
+ Requires-Python: >=3.10
19
+ Description-Content-Type: text/markdown
20
+ License-File: LICENSE
21
+ Requires-Dist: arrow
22
+ Requires-Dist: authlib>=1.2.1
23
+ Requires-Dist: joserfc>=1.0.0
24
+ Requires-Dist: click
25
+ Requires-Dist: pandas>=2.3.3; python_version >= "3.14"
26
+ Requires-Dist: pandas; python_version < "3.14"
27
+ Requires-Dist: prometheus_client
28
+ Requires-Dist: psutil>=6.0.0
29
+ Requires-Dist: py-cpuinfo
30
+ Requires-Dist: pydantic<3.0.0,>=2.0.0
31
+ Requires-Dist: nvidia-ml-py
32
+ Requires-Dist: rapidfuzz
33
+ Requires-Dist: requests
34
+ Requires-Dist: questionary
35
+ Requires-Dist: rich
36
+ Requires-Dist: typer
37
+ Requires-Dist: pycountry
38
+ Provides-Extra: carbonboard
39
+ Requires-Dist: dash; extra == "carbonboard"
40
+ Requires-Dist: dash_bootstrap_components>1.0.0; extra == "carbonboard"
41
+ Requires-Dist: fire; extra == "carbonboard"
42
+ Provides-Extra: viz-legacy
43
+ Requires-Dist: dash; extra == "viz-legacy"
44
+ Requires-Dist: dash_bootstrap_components>1.0.0; extra == "viz-legacy"
45
+ Requires-Dist: fire; extra == "viz-legacy"
46
+ Dynamic: license-file
47
+
48
+ ![banner](docs/images/banner.png)
49
+
50
+ # Track & reduce CO₂ emissions from your local computing
51
+
52
+ Estimate and track carbon emissions from your computer, quantify and analyze their impact.
53
+
54
+ [![](https://img.shields.io/pypi/v/codecarbon?color=024758)](https://pypi.org/project/codecarbon/) [![DOI](https://zenodo.org/badge/263364731.svg)](https://zenodo.org/badge/latestdoi/263364731) [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/mlco2/codecarbon/badge)](https://scorecard.dev/viewer/?uri=github.com/mlco2/codecarbon) [![codecov](https://codecov.io/gh/mlco2/codecarbon/graph/badge.svg)](https://codecov.io/gh/mlco2/codecarbon) [![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/GS9js2XkJR)
55
+
56
+ - **A lightweight, easy to use Python library** – Simple API to track emissions
57
+ - **Open source, free & community driven** – Built by and for the community
58
+ - **Effective visual outputs** – Put emissions in context with real-world equivalents
59
+
60
+ > **Tracking GenAI API calls?** CodeCarbon measures emissions from **local computing** (your hardware). To track emissions from remote GenAI API calls (OpenAI, Anthropic, Mistral, etc.), use [**EcoLogits**](https://ecologits.ai/). Both tools are complementary.
61
+
62
+ > **Join the community!** Have questions, want to share your work, or contribute? Join us on [**Discord**](https://discord.gg/GS9js2XkJR) – we're here to help and excited to hear from you!
63
+
64
+ ## Installation
65
+
66
+ ```bash
67
+ pip install codecarbon
68
+ ```
69
+
70
+ If you use Conda:
71
+
72
+ ```bash
73
+ conda activate your_env
74
+ pip install codecarbon
75
+ ```
76
+
77
+ More installation options: [installation docs](https://docs.codecarbon.io/latest/how-to/installation/).
78
+
79
+ ## Quickstart (Python)
80
+
81
+ ```python
82
+ from codecarbon import EmissionsTracker
83
+
84
+ tracker = EmissionsTracker()
85
+ tracker.start()
86
+
87
+ # Your code here
88
+
89
+ emissions = tracker.stop()
90
+ print(f"Emissions: {emissions} kg CO₂")
91
+ ```
92
+
93
+ [**Learn more** →](https://docs.codecarbon.io/latest/tutorials/first-tracking/)
94
+
95
+ ## Quickstart (CLI)
96
+
97
+ Track a command without changing your code:
98
+
99
+ ```bash
100
+ codecarbon monitor --no-api -- python train.py
101
+ ```
102
+
103
+ Detect your hardware:
104
+
105
+ ```bash
106
+ codecarbon detect
107
+ ```
108
+
109
+ Full CLI guide: [CLI tutorial](https://docs.codecarbon.io/latest/tutorials/cli/).
110
+
111
+ ## Configuration
112
+
113
+ You can configure CodeCarbon using:
114
+
115
+ - `~/.codecarbon.config` (global)
116
+ - `./.codecarbon.config` (project-local)
117
+ - `CODECARBON_*` environment variables
118
+ - Python arguments (`EmissionsTracker(...)`)
119
+
120
+ Configuration precedence and examples: [configuration guide](https://docs.codecarbon.io/latest/how-to/configuration/).
121
+
122
+ ## How it works
123
+
124
+ We created a Python package that estimates your hardware electricity power consumption (GPU + CPU + RAM) and we apply to it the carbon intensity of the region where the computing is done.
125
+
126
+ CodeCarbon focuses on the main compute components it can measure or estimate directly: CPU, GPU, and RAM. It does not separately model disk I/O, network transfers, displays, cooling, or other peripherals because those sources are usually much smaller for local code-level experiments and are not exposed through the same low-overhead measurement interfaces.
127
+
128
+ ![calculation Summary](docs/images/calculation.png)
129
+
130
+ We explain more about this calculation in the [**Methodology**](https://docs.codecarbon.io/latest/explanation/methodology/) section of the documentation.
131
+
132
+ ## Visualize
133
+
134
+ You can visualize your experiment emissions on the [dashboard](https://dashboard.codecarbon.io/) or locally with [carbonboard](https://docs.codecarbon.io/latest/how-to/visualize/).
135
+
136
+ ![dashboard](docs/images/dashboard.png)
137
+
138
+ ## Quick links
139
+
140
+ | Section | Description |
141
+ |---------|-------------|
142
+ | [Quickstart](https://docs.codecarbon.io/latest/tutorials/first-tracking/) | Get started in 5 minutes |
143
+ | [Installation](https://docs.codecarbon.io/latest/how-to/installation/) | Install CodeCarbon |
144
+ | [CLI Tutorial](https://docs.codecarbon.io/latest/tutorials/cli/) | Track emissions from the command line |
145
+ | [Python API Tutorial](https://docs.codecarbon.io/latest/tutorials/python-api/) | Track emissions in Python code |
146
+ | [Comparing Model Efficiency](https://docs.codecarbon.io/latest/tutorials/comparing-model-efficiency/) | Measure carbon efficiency across ML models |
147
+ | [API Reference](https://docs.codecarbon.io/latest/reference/api/) | Full parameter documentation |
148
+ | [Framework examples (scikit-learn)](https://docs.codecarbon.io/latest/how-to/scikit-learn/) | Task-oriented ML framework examples |
149
+ | [Methodology](https://docs.codecarbon.io/latest/explanation/methodology/) | How emissions are calculated |
150
+ | [EcoLogits](https://ecologits.ai/) | Track emissions from GenAI API calls |
151
+ | [Discord Community](https://discord.gg/GS9js2XkJR) | Chat with us and the community |
152
+
153
+ ## Links
154
+
155
+ - [Main website](https://codecarbon.io) to learn why we do this.
156
+ - [Dashboard](https://dashboard.codecarbon.io/) to see your emissions.
157
+ - [Documentation](https://docs.codecarbon.io/) to learn how to use the package and our methodology.
158
+ - [EcoLogits](https://ecologits.ai/) to track emissions from GenAI API calls (OpenAI, Anthropic, etc.).
159
+ - [GitHub](https://github.com/mlco2/codecarbon) to look at the source code and contribute.
160
+ - [Discord](https://discord.gg/GS9js2XkJR) to chat with us.
161
+
162
+ ## Contributing
163
+
164
+ We are hoping that the open-source community will help us edit the code and make it better!
165
+
166
+ You are welcome to open issues, even suggest solutions and better still contribute the fix/improvement! We can guide you if you're not sure where to start but want to help us out.
167
+
168
+ Check out our [contribution guidelines](https://github.com/mlco2/codecarbon/blob/master/CONTRIBUTING.md).
169
+
170
+ Feel free to chat with us on [Discord](https://discord.gg/GS9js2XkJR).
171
+
172
+ ## Citation
173
+
174
+ If you find CodeCarbon useful for your research, you can find a citation under a variety of formats on [Zenodo](https://zenodo.org/records/11171501).
175
+
176
+ <details>
177
+ <summary>BibTeX</summary>
178
+
179
+ ```tex
180
+ @software{benoit_courty_2024_11171501,
181
+ author = {Benoit Courty and
182
+ Victor Schmidt and
183
+ Sasha Luccioni and
184
+ Goyal-Kamal and
185
+ MarionCoutarel and
186
+ Boris Feld and
187
+ Jérémy Lecourt and
188
+ LiamConnell and
189
+ Amine Saboni and
190
+ Inimaz and
191
+ supatomic and
192
+ Mathilde Léval and
193
+ Luis Blanche and
194
+ Alexis Cruveiller and
195
+ ouminasara and
196
+ Franklin Zhao and
197
+ Aditya Joshi and
198
+ Alexis Bogroff and
199
+ Hugues de Lavoreille and
200
+ Niko Laskaris and
201
+ Edoardo Abati and
202
+ Douglas Blank and
203
+ Ziyao Wang and
204
+ Armin Catovic and
205
+ Marc Alencon and
206
+ Michał Stęchły and
207
+ Christian Bauer and
208
+ Lucas Otávio N. de Araújo and
209
+ JPW and
210
+ MinervaBooks},
211
+ title = {mlco2/codecarbon: v2.4.1},
212
+ month = may,
213
+ year = 2024,
214
+ publisher = {Zenodo},
215
+ version = {v2.4.1},
216
+ doi = {10.5281/zenodo.11171501},
217
+ url = {https://doi.org/10.5281/zenodo.11171501}
218
+ }
219
+ ```
220
+
221
+ </details>
222
+
223
+ ## Contact
224
+
225
+ Feel free to chat with us on [Discord](https://discord.gg/GS9js2XkJR).
226
+
227
+ Codecarbon was formerly developed by volunteers from [**Mila**](http://mila.quebec) and the [**DataForGoodFR**](https://twitter.com/dataforgood_fr) community alongside donated professional time of engineers at [**Comet.ml**](https://comet.ml) and [**BCG GAMMA**](https://www.bcg.com/en-nl/beyond-consulting/bcg-gamma/default).
228
+
229
+ 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.
230
+
231
+ ### Star History
232
+
233
+ [![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)
@@ -0,0 +1,186 @@
1
+ ![banner](docs/images/banner.png)
2
+
3
+ # Track & reduce CO₂ emissions from your local computing
4
+
5
+ Estimate and track carbon emissions from your computer, quantify and analyze their impact.
6
+
7
+ [![](https://img.shields.io/pypi/v/codecarbon?color=024758)](https://pypi.org/project/codecarbon/) [![DOI](https://zenodo.org/badge/263364731.svg)](https://zenodo.org/badge/latestdoi/263364731) [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/mlco2/codecarbon/badge)](https://scorecard.dev/viewer/?uri=github.com/mlco2/codecarbon) [![codecov](https://codecov.io/gh/mlco2/codecarbon/graph/badge.svg)](https://codecov.io/gh/mlco2/codecarbon) [![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/GS9js2XkJR)
8
+
9
+ - **A lightweight, easy to use Python library** – Simple API to track emissions
10
+ - **Open source, free & community driven** – Built by and for the community
11
+ - **Effective visual outputs** – Put emissions in context with real-world equivalents
12
+
13
+ > **Tracking GenAI API calls?** CodeCarbon measures emissions from **local computing** (your hardware). To track emissions from remote GenAI API calls (OpenAI, Anthropic, Mistral, etc.), use [**EcoLogits**](https://ecologits.ai/). Both tools are complementary.
14
+
15
+ > **Join the community!** Have questions, want to share your work, or contribute? Join us on [**Discord**](https://discord.gg/GS9js2XkJR) – we're here to help and excited to hear from you!
16
+
17
+ ## Installation
18
+
19
+ ```bash
20
+ pip install codecarbon
21
+ ```
22
+
23
+ If you use Conda:
24
+
25
+ ```bash
26
+ conda activate your_env
27
+ pip install codecarbon
28
+ ```
29
+
30
+ More installation options: [installation docs](https://docs.codecarbon.io/latest/how-to/installation/).
31
+
32
+ ## Quickstart (Python)
33
+
34
+ ```python
35
+ from codecarbon import EmissionsTracker
36
+
37
+ tracker = EmissionsTracker()
38
+ tracker.start()
39
+
40
+ # Your code here
41
+
42
+ emissions = tracker.stop()
43
+ print(f"Emissions: {emissions} kg CO₂")
44
+ ```
45
+
46
+ [**Learn more** →](https://docs.codecarbon.io/latest/tutorials/first-tracking/)
47
+
48
+ ## Quickstart (CLI)
49
+
50
+ Track a command without changing your code:
51
+
52
+ ```bash
53
+ codecarbon monitor --no-api -- python train.py
54
+ ```
55
+
56
+ Detect your hardware:
57
+
58
+ ```bash
59
+ codecarbon detect
60
+ ```
61
+
62
+ Full CLI guide: [CLI tutorial](https://docs.codecarbon.io/latest/tutorials/cli/).
63
+
64
+ ## Configuration
65
+
66
+ You can configure CodeCarbon using:
67
+
68
+ - `~/.codecarbon.config` (global)
69
+ - `./.codecarbon.config` (project-local)
70
+ - `CODECARBON_*` environment variables
71
+ - Python arguments (`EmissionsTracker(...)`)
72
+
73
+ Configuration precedence and examples: [configuration guide](https://docs.codecarbon.io/latest/how-to/configuration/).
74
+
75
+ ## How it works
76
+
77
+ We created a Python package that estimates your hardware electricity power consumption (GPU + CPU + RAM) and we apply to it the carbon intensity of the region where the computing is done.
78
+
79
+ CodeCarbon focuses on the main compute components it can measure or estimate directly: CPU, GPU, and RAM. It does not separately model disk I/O, network transfers, displays, cooling, or other peripherals because those sources are usually much smaller for local code-level experiments and are not exposed through the same low-overhead measurement interfaces.
80
+
81
+ ![calculation Summary](docs/images/calculation.png)
82
+
83
+ We explain more about this calculation in the [**Methodology**](https://docs.codecarbon.io/latest/explanation/methodology/) section of the documentation.
84
+
85
+ ## Visualize
86
+
87
+ You can visualize your experiment emissions on the [dashboard](https://dashboard.codecarbon.io/) or locally with [carbonboard](https://docs.codecarbon.io/latest/how-to/visualize/).
88
+
89
+ ![dashboard](docs/images/dashboard.png)
90
+
91
+ ## Quick links
92
+
93
+ | Section | Description |
94
+ |---------|-------------|
95
+ | [Quickstart](https://docs.codecarbon.io/latest/tutorials/first-tracking/) | Get started in 5 minutes |
96
+ | [Installation](https://docs.codecarbon.io/latest/how-to/installation/) | Install CodeCarbon |
97
+ | [CLI Tutorial](https://docs.codecarbon.io/latest/tutorials/cli/) | Track emissions from the command line |
98
+ | [Python API Tutorial](https://docs.codecarbon.io/latest/tutorials/python-api/) | Track emissions in Python code |
99
+ | [Comparing Model Efficiency](https://docs.codecarbon.io/latest/tutorials/comparing-model-efficiency/) | Measure carbon efficiency across ML models |
100
+ | [API Reference](https://docs.codecarbon.io/latest/reference/api/) | Full parameter documentation |
101
+ | [Framework examples (scikit-learn)](https://docs.codecarbon.io/latest/how-to/scikit-learn/) | Task-oriented ML framework examples |
102
+ | [Methodology](https://docs.codecarbon.io/latest/explanation/methodology/) | How emissions are calculated |
103
+ | [EcoLogits](https://ecologits.ai/) | Track emissions from GenAI API calls |
104
+ | [Discord Community](https://discord.gg/GS9js2XkJR) | Chat with us and the community |
105
+
106
+ ## Links
107
+
108
+ - [Main website](https://codecarbon.io) to learn why we do this.
109
+ - [Dashboard](https://dashboard.codecarbon.io/) to see your emissions.
110
+ - [Documentation](https://docs.codecarbon.io/) to learn how to use the package and our methodology.
111
+ - [EcoLogits](https://ecologits.ai/) to track emissions from GenAI API calls (OpenAI, Anthropic, etc.).
112
+ - [GitHub](https://github.com/mlco2/codecarbon) to look at the source code and contribute.
113
+ - [Discord](https://discord.gg/GS9js2XkJR) to chat with us.
114
+
115
+ ## Contributing
116
+
117
+ We are hoping that the open-source community will help us edit the code and make it better!
118
+
119
+ You are welcome to open issues, even suggest solutions and better still contribute the fix/improvement! We can guide you if you're not sure where to start but want to help us out.
120
+
121
+ Check out our [contribution guidelines](https://github.com/mlco2/codecarbon/blob/master/CONTRIBUTING.md).
122
+
123
+ Feel free to chat with us on [Discord](https://discord.gg/GS9js2XkJR).
124
+
125
+ ## Citation
126
+
127
+ If you find CodeCarbon useful for your research, you can find a citation under a variety of formats on [Zenodo](https://zenodo.org/records/11171501).
128
+
129
+ <details>
130
+ <summary>BibTeX</summary>
131
+
132
+ ```tex
133
+ @software{benoit_courty_2024_11171501,
134
+ author = {Benoit Courty and
135
+ Victor Schmidt and
136
+ Sasha Luccioni and
137
+ Goyal-Kamal and
138
+ MarionCoutarel and
139
+ Boris Feld and
140
+ Jérémy Lecourt and
141
+ LiamConnell and
142
+ Amine Saboni and
143
+ Inimaz and
144
+ supatomic and
145
+ Mathilde Léval and
146
+ Luis Blanche and
147
+ Alexis Cruveiller and
148
+ ouminasara and
149
+ Franklin Zhao and
150
+ Aditya Joshi and
151
+ Alexis Bogroff and
152
+ Hugues de Lavoreille and
153
+ Niko Laskaris and
154
+ Edoardo Abati and
155
+ Douglas Blank and
156
+ Ziyao Wang and
157
+ Armin Catovic and
158
+ Marc Alencon and
159
+ Michał Stęchły and
160
+ Christian Bauer and
161
+ Lucas Otávio N. de Araújo and
162
+ JPW and
163
+ MinervaBooks},
164
+ title = {mlco2/codecarbon: v2.4.1},
165
+ month = may,
166
+ year = 2024,
167
+ publisher = {Zenodo},
168
+ version = {v2.4.1},
169
+ doi = {10.5281/zenodo.11171501},
170
+ url = {https://doi.org/10.5281/zenodo.11171501}
171
+ }
172
+ ```
173
+
174
+ </details>
175
+
176
+ ## Contact
177
+
178
+ Feel free to chat with us on [Discord](https://discord.gg/GS9js2XkJR).
179
+
180
+ Codecarbon was formerly developed by volunteers from [**Mila**](http://mila.quebec) and the [**DataForGoodFR**](https://twitter.com/dataforgood_fr) community alongside donated professional time of engineers at [**Comet.ml**](https://comet.ml) and [**BCG GAMMA**](https://www.bcg.com/en-nl/beyond-consulting/bcg-gamma/default).
181
+
182
+ 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.
183
+
184
+ ### Star History
185
+
186
+ [![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)
@@ -8,6 +8,12 @@ from .emissions_tracker import (
8
8
  OfflineEmissionsTracker,
9
9
  track_emissions,
10
10
  )
11
+ from .output import OutputMethod
11
12
 
12
- __all__ = ["EmissionsTracker", "OfflineEmissionsTracker", "track_emissions"]
13
+ __all__ = [
14
+ "EmissionsTracker",
15
+ "OfflineEmissionsTracker",
16
+ "OutputMethod",
17
+ "track_emissions",
18
+ ]
13
19
  __app_name__ = "codecarbon"
@@ -0,0 +1 @@
1
+ __version__ = "3.2.8"
@@ -6,6 +6,7 @@ PKCE), credential storage, JWKS validation, and transparent refresh.
6
6
  """
7
7
 
8
8
  import json
9
+ import logging
9
10
  import os
10
11
  import webbrowser
11
12
  from http.server import BaseHTTPRequestHandler, HTTPServer
@@ -15,9 +16,9 @@ from urllib.parse import parse_qs, urlparse
15
16
  import requests
16
17
  from authlib.common.security import generate_token
17
18
  from authlib.integrations.requests_client import OAuth2Session
18
- from authlib.jose import JsonWebKey
19
- from authlib.jose import jwt as jose_jwt
20
19
  from authlib.oauth2.rfc7636 import create_s256_code_challenge
20
+ from joserfc import jwt as jose_jwt
21
+ from joserfc.jwk import KeySet
21
22
 
22
23
  AUTH_CLIENT_ID = os.environ.get(
23
24
  "AUTH_CLIENT_ID",
@@ -31,6 +32,7 @@ AUTH_SERVER_WELL_KNOWN = os.environ.get(
31
32
  _REDIRECT_PORT = 8090
32
33
  _REDIRECT_URI = f"http://localhost:{_REDIRECT_PORT}/callback"
33
34
  _CREDENTIALS_FILE = Path("./credentials.json")
35
+ logger = logging.getLogger(__name__)
34
36
 
35
37
 
36
38
  # ── OAuth callback server ───────────────────────────────────────────
@@ -108,11 +110,16 @@ def _validate_access_token(access_token: str) -> bool:
108
110
  discovery = _discover_endpoints()
109
111
  jwks_resp = requests.get(discovery["jwks_uri"])
110
112
  jwks_resp.raise_for_status()
111
- keyset = JsonWebKey.import_key_set(jwks_resp.json())
112
- claims = jose_jwt.decode(access_token, keyset)
113
- claims.validate()
113
+ keyset = KeySet.import_key_set(jwks_resp.json())
114
+ token = jose_jwt.decode(access_token, keyset)
115
+ jose_jwt.JWTClaimsRegistry().validate(token.claims)
114
116
  return True
115
- except requests.RequestException:
117
+ except requests.RequestException as exc:
118
+ logger.warning(
119
+ "Skipping local access token validation because the auth server is "
120
+ "unreachable; the API will validate the token. Error: %s",
121
+ exc,
122
+ )
116
123
  return True # Can't reach auth server — let the API handle it
117
124
  except Exception:
118
125
  return False
@@ -310,7 +310,7 @@ def config():
310
310
  overwrite_local_config("api_key", api_key, path=file_path)
311
311
  show_config(file_path)
312
312
  print(
313
- "Consult [link=https://docs.codecarbon.io/latest/getting-started/usage/#configuration]configuration documentation[/link] for more configuration options"
313
+ "Consult [link=https://docs.codecarbon.io/latest/how-to/configuration/]configuration documentation[/link] for more configuration options"
314
314
  )
315
315
 
316
316
 
@@ -377,7 +377,7 @@ def monitor(
377
377
 
378
378
  # If extra args are provided (e.g. `codecarbon monitor -- my_script.py`), delegate to `run_and_monitor`
379
379
  if getattr(ctx, "args", None):
380
- return run_and_monitor(ctx, **tracker_args)
380
+ return run_and_monitor(ctx, offline=offline, **tracker_args)
381
381
 
382
382
  # Instantiate the tracker
383
383
  if offline:
@@ -8,7 +8,7 @@ import typer
8
8
  from rich import print
9
9
  from typing_extensions import Annotated
10
10
 
11
- from codecarbon.emissions_tracker import EmissionsTracker
11
+ from codecarbon.emissions_tracker import EmissionsTracker, OfflineEmissionsTracker
12
12
 
13
13
 
14
14
  def run_and_monitor(
@@ -17,6 +17,7 @@ def run_and_monitor(
17
17
  str,
18
18
  typer.Option(help="Log level (critical, error, warning, info, debug)"),
19
19
  ] = "error",
20
+ offline: bool = False,
20
21
  **tracker_args,
21
22
  ):
22
23
  """
@@ -63,8 +64,8 @@ def run_and_monitor(
63
64
  )
64
65
  raise typer.Exit(1)
65
66
 
66
- # Initialize tracker with specified logging level and shared args
67
- tracker = EmissionsTracker(
67
+ tracker_cls = OfflineEmissionsTracker if offline else EmissionsTracker
68
+ tracker = tracker_cls(
68
69
  log_level=log_level,
69
70
  save_to_logger=False,
70
71
  tracking_mode="process",
@@ -227,6 +227,10 @@ class ApiClient: # (AsyncClient)
227
227
  gpu_energy=carbon_emission["gpu_energy"],
228
228
  ram_energy=carbon_emission["ram_energy"],
229
229
  energy_consumed=carbon_emission["energy_consumed"],
230
+ cpu_utilization_percent=carbon_emission.get("cpu_utilization_percent"),
231
+ gpu_utilization_percent=carbon_emission.get("gpu_utilization_percent"),
232
+ ram_utilization_percent=carbon_emission.get("ram_utilization_percent"),
233
+ wue=carbon_emission.get("wue", 0),
230
234
  )
231
235
  try:
232
236
  payload = dataclasses.asdict(emission)
@@ -217,19 +217,19 @@ def is_psutil_available():
217
217
  return True
218
218
  else:
219
219
  logger.debug(
220
- f"is_psutil_available(): psutil.cpu_times().nice is too small: {nice}"
220
+ f"is_psutil_available(): psutil.cpu_times().nice is too small: {nice}; "
221
+ "using fallback check."
221
222
  )
222
- return False
223
223
 
224
224
  else:
225
- # Fallback: check if psutil works by calling cpu_percent
226
225
  logger.debug(
227
226
  "is_psutil_available(): no 'nice' attribute, using fallback check."
228
227
  )
229
228
 
230
- # check CPU utilization usable
231
- psutil.cpu_percent(interval=0.0, percpu=False)
232
- return True
229
+ # Fallback: check if psutil CPU utilization is usable. This covers
230
+ # platforms like Windows and macOS where cpu_times().nice is absent or 0.
231
+ psutil.cpu_percent(interval=0.0, percpu=False)
232
+ return True
233
233
 
234
234
  except Exception as e:
235
235
  logger.debug(
@@ -828,7 +828,8 @@ class IntelRAPL:
828
828
  """
829
829
  cpu_details = {}
830
830
  try:
831
- list(map(lambda rapl_file: rapl_file.delta(duration), self._rapl_files))
831
+ for rapl_file in self._rapl_files:
832
+ rapl_file.delta(duration)
832
833
 
833
834
  for rapl_file in self._rapl_files:
834
835
  logger.debug(rapl_file)