Metadata-Version: 2.4
Name: ecotrace
Version: 0.3.2
Summary: EcoTrace: A powerful Python library to measure CPU/GPU energy consumption and estimate carbon emissions with detailed PDF reporting and continuous sampling.
Author-email: Emre Ozkal <emreozkal03@gmail.com>
Project-URL: Homepage, https://github.com/Zwony/ecotrace
Project-URL: Repository, https://github.com/Zwony/ecotrace
Keywords: carbon-footprint,energy-efficiency,green-computing,sustainability,metrics,cpu-monitoring,gpu-monitoring
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: psutil
Requires-Dist: py-cpuinfo
Requires-Dist: fpdf
Requires-Dist: matplotlib
Requires-Dist: nvidia-ml-py
Requires-Dist: wmi; sys_platform == "win32"
Dynamic: license-file

# 🌱 EcoTrace

> **Measure your code's carbon footprint. Write cleaner code. Protect the planet.**

EcoTrace is a lightweight yet powerful Python library that analyzes the CPU and GPU load of your functions and calculates how much CO₂ they emit.

![EcoTrace Demo](demo.gif)

[![PyPI version](https://badge.fury.io/py/ecotrace.svg)](https://badge.fury.io/py/ecotrace)
[![Python 3.7+](https://img.shields.io/badge/python-3.7+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Downloads](https://pepy.tech/badge/ecotrace)](https://pepy.tech/project/ecotrace)
[![Downloads/Month](https://pepy.tech/badge/ecotrace/month)](https://pepy.tech/project/ecotrace)
[![GitHub stars](https://img.shields.io/github/stars/Zwony/ecotrace?style=social)](https://github.com/Zwony/ecotrace/stargazers)

---

## 🚀 Installation

```bash
pip install ecotrace
```

---

## ⚡ Quick Start

```python
from ecotrace import EcoTrace

eco = EcoTrace(region_code="US")

@eco.track
def process_data():
    return sum(i * i for i in range(10**6))

process_data()
# [EcoTrace] Function   : process_data
# [EcoTrace] Duration   : 0.0452 sec
# [EcoTrace] Avg CPU    : 23.4%
# [EcoTrace] CO2 Emitted: 0.00001823 gCO2
```

---

## 🧩 Features

### ✅ CPU Tracking — `@eco.track`

Track any function with a single decorator:

```python
@eco.track
def train_model():
    # model training...
    pass
```

Async functions are supported out of the box:

```python
@eco.track
async def fetch_data():
    await asyncio.sleep(1)
    # API call...
```

### ✅ GPU Tracking — `@eco.track_gpu`

Supports NVIDIA, AMD, and Intel GPUs. Select a specific GPU with `gpu_index`:

```python
# Default — first GPU
eco = EcoTrace(region_code="US")

# Select a specific GPU
eco = EcoTrace(region_code="US", gpu_index=1)

@eco.track_gpu
def gpu_compute():
    # GPU-intensive work...
    pass
```

### ✅ Async Measurement — `eco.measure_async()`

For more accurate, continuous sampling of async functions:

```python
async def my_async_task():
    await asyncio.sleep(1)
    return "Done"

result = await eco.measure_async(my_async_task)
print(f"CO2: {result['carbon']}g, Result: {result['result']}")
```

### ✅ Comparison Analysis — `eco.compare()`

Compare two implementations side-by-side:

```python
def fast_version():
    return sum(i for i in range(10**5))

def slow_version():
    return sum(i for i in range(10**6))

result = eco.compare(fast_version, slow_version)
```

### ✅ PDF Report with Charts — `eco.generate_pdf_report()`

Export all measurements as a detailed PDF report including CPU usage charts:

```python
# Pass cpu_samples from measure_async to include the chart
eco.generate_pdf_report("report.pdf", comparison=result, cpu_samples=result.get('cpu_samples'))
```

Report includes:
- System info (CPU, GPU, TDP, region)
- Full function measurement history
- **NEW: CPU Usage Over Time charts**
- Comparison analysis table
- Total cumulative CO₂ emissions

### ✅ Carbon Limit Warning

Get a warning when you exceed a defined threshold:

```python
eco = EcoTrace(region_code="US", carbon_limit=0.001)
# ⚠️ WARNING: Carbon limit exceeded! (0.00124 > 0.001 gCO2)
```

---

## 🌍 Supported Regions

| Code | Country        | Carbon Intensity |
|------|----------------|-----------------|
| TR   | Turkey         | 475 gCO₂/kWh    |
| DE   | Germany        | 385 gCO₂/kWh    |
| FR   | France         | 55 gCO₂/kWh     |
| US   | United States  | 367 gCO₂/kWh    |
| GB   | United Kingdom | 253 gCO₂/kWh    |

---

## 🖥️ Supported CPUs

EcoTrace automatically detects TDP values using the [Boavizta](https://github.com/Boavizta/cpu-spec) database with 1800+ CPUs:

- Intel Core i3 / i5 / i7 / i9 (all generations)
- AMD Ryzen 3 / 5 / 7 / 9
- Apple M1 / M2 / M3
- AMD Threadripper, EPYC
- Intel Xeon

---

## 📦 Dependencies

```
psutil
py-cpuinfo
fpdf
matplotlib
nvidia-ml-py
wmi; sys_platform == 'win32'
```

---

## 📊 Sample PDF Output

```
EcoTrace Analysis Report
─────────────────────────────────────
CPU      : Intel Core i7-13700H
TDP      : 45.0W
Region   : US (367 gCO₂/kWh)
─────────────────────────────────────
Function       Duration(s)  CPU%   Carbon(gCO2)
process_data   0.0452       23.4   0.00001823
fetch_data     1.0021       2.1    0.00037486
─────────────────────────────────────
TOTAL CUMULATIVE EMISSIONS: 0.00039309 gCO2
```

---

## 🤝 Contributing

Pull requests and issues are welcome!

---

## 💬 Community & Support

Join the EcoTrace community to contribute, ask questions, and connect with other developers.

[![Join Discord](https://img.shields.io/discord/1483105790993633411?label=Join%20Discord&logo=discord&style=for-the-badge)](https://discord.gg/hs58XXb3Uq)

- 🐛 Report bugs
- 💡 Suggest new features
- 💻 Share your hardware TDP data to grow the database
- 🛠️ Get installation and usage support

## 👤 Author

**Emre Özkal** — [emreozkal03@gmail.com](mailto:emreozkal03@gmail.com)

---

## 📄 License

MIT License — use it however you like.
