scope3track 1.0.0__tar.gz

scope3track-1.0.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: scope3track
+Version: 1.0.0
+Summary: Carbon and Scope 3 emissions tracking for SMBs — GHG Protocol compliant calculations, supplier tracking, CSRD-ready reporting
+Home-page: https://github.com/scope3track-py/scope3track
+Author: 
+Keywords: scope 3 emissions,carbon tracking python,GHG protocol,CSRD compliance,carbon footprint calculator,scope3 reporting,sustainability reporting,carbon accounting SMB,emission factor calculation,supply chain emissions tracking
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# scope3track
+
+**Carbon and Scope 3 emissions tracking for SMBs and enterprise supply chains** — GHG Protocol-compliant calculations, supplier-level tracking, CSRD-ready reporting.
+
+Enterprise carbon tools cost $30K–$150K/year. `scope3track` brings the same capability to Python developers for free.
+
+[![PyPI version](https://badge.fury.io/py/scope3track.svg)](https://pypi.org/project/scope3track/)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/)
+
+## The Problem
+
+EU CSRD enforcement + enterprise Scope 3 requirements are now cascading to SMB suppliers. Companies are required to report their full value-chain emissions. Enterprise tools cost $30K–$150K/year — nothing exists at the $99–$499/mo SMB price point.
+
+## Installation
+
+```bash
+pip install scope3track
+```
+
+## Quick Start
+
+```python
+from scope3track import EmissionCalculator, EmissionScope, Scope3Category
+from datetime import datetime
+
+calc = EmissionCalculator()
+
+# Calculate Scope 3 Category 4: upstream transport
+transport_entry = calc.calculate(
+    entry_id="ENT-001",
+    scope=EmissionScope.SCOPE3,
+    category=Scope3Category.UPSTREAM_TRANSPORT,
+    source="Freight — Shanghai to LA",
+    activity_amount=5000,    # kg of freight
+    activity_unit="kg",
+    factor_key="km_road_freight_hgv",
+    period_start=datetime(2025, 1, 1),
+    period_end=datetime(2025, 3, 31),
+    supplier_id="SUPPLIER-CN-01",
+)
+
+print(f"{transport_entry.emissions_kg_co2e:.2f} kg CO2e")
+```
+
+## Build a Full Report
+
+```python
+entries = [
+    calc.calculate("e1", EmissionScope.SCOPE1, "Natural gas heating", 10000, "kwh", "kwh_natural_gas", period_start=..., period_end=...),
+    calc.calculate("e2", EmissionScope.SCOPE2, "Office electricity", 50000, "kwh", "kwh_electricity_us", period_start=..., period_end=...),
+    calc.calculate("e3", EmissionScope.SCOPE3, "Employee commuting", 200000, "km", "km_passenger_car", category=Scope3Category.EMPLOYEE_COMMUTING, period_start=..., period_end=...),
+]
+
+report = calc.build_report(
+    company_id="ACME-INC",
+    reporting_year=2025,
+    entries=entries,
+)
+
+print(report.summary())
+# {'company_id': 'ACME-INC', 'scope1_t_co2e': 2.02, 'scope2_t_co2e': 19.3, 'scope3_t_co2e': 34.2, 'total_t_co2e': 55.52, ...}
+```
+
+## Built-in Emission Factors
+
+`scope3track` ships with GHG Protocol default factors for:
+
+- **Energy**: electricity (US/EU grid), natural gas
+- **Transport**: road freight, air freight, sea freight, passenger car, business flights
+- **Materials**: steel, aluminium, plastic, paper, concrete
+- **Waste**: landfill, recycled, composted
+
+Register custom factors:
+
+```python
+from scope3track import default_registry
+
+default_registry.register("kwh_solar_ppa", 0.012)
+```
+
+## Scope 3 Categories Supported
+
+All 15 GHG Protocol Scope 3 categories (upstream + downstream):
+
+`purchased_goods_services`, `capital_goods`, `fuel_and_energy_activities`, `upstream_transportation_distribution`, `waste_generated_in_operations`, `business_travel`, `employee_commuting`, `upstream_leased_assets`, `downstream_transportation_distribution`, `processing_of_sold_products`, `use_of_sold_products`, `end_of_life_treatment`, `downstream_leased_assets`, `franchises`, `investments`
+
+## Advanced Features
+
+### Pipeline
+
+```python
+from scope3track import EmissionPipeline
+
+pipeline = (
+    EmissionPipeline()
+    .filter(lambda e: e.scope == EmissionScope.SCOPE3, name="scope3_only")
+    .map(lambda entries: sorted(entries, key=lambda e: -e.emissions_kg_co2e), name="sort_by_impact")
+    .with_retry(count=2)
+)
+
+scope3_sorted = pipeline.run(entries)
+```
+
+### Caching
+
+```python
+from scope3track import EmissionCache
+
+cache = EmissionCache(max_size=1000, ttl_seconds=3600)
+
+@cache.memoize
+def get_supplier_emissions(supplier_id):
+    ...
+
+cache.save("emissions_cache.pkl")
+cache.load("emissions_cache.pkl")
+print(cache.stats())
+```
+
+### Export Reports
+
+```python
+from scope3track import EmissionReportExporter
+
+print(EmissionReportExporter.to_json(report))
+print(EmissionReportExporter.to_csv(report))
+print(EmissionReportExporter.to_markdown(report))
+```
+
+### Drift Detection
+
+```python
+from scope3track import EmissionDriftDetector
+
+detector = EmissionDriftDetector(threshold=0.15)
+for period_total in quarterly_totals:
+    detector.record(period_total)
+
+if detector.is_drifted():
+    print(f"Emission drift detected: {detector.drift_ratio():.1%}")
+```
+
+### Diff Between Periods
+
+```python
+from scope3track import diff_entries
+
+diff = diff_entries(q1_entries, q2_entries)
+print(diff.summary())  # {'added': 2, 'removed': 0, 'modified': 3}
+print(diff.to_json())
+```
+
+### Async Batch
+
+```python
+from scope3track import abatch_calculate, CancellationToken
+
+token = CancellationToken()
+entries = await abatch_calculate(raw_data, calc_fn, max_concurrency=8, token=token)
+```
+
+### Streaming NDJSON
+
+```python
+from scope3track import entries_to_ndjson
+
+for line in entries_to_ndjson(entries):
+    output_stream.write(line)
+```
+
+## Frameworks Supported
+
+- GHG Protocol Corporate Standard
+- EU CSRD / ESRS E1
+- ISO 14064-1
+
+## License
+
+MIT

scope3track-1.0.0/README.md

@@ -0,0 +1,179 @@
+# scope3track
+
+**Carbon and Scope 3 emissions tracking for SMBs and enterprise supply chains** — GHG Protocol-compliant calculations, supplier-level tracking, CSRD-ready reporting.
+
+Enterprise carbon tools cost $30K–$150K/year. `scope3track` brings the same capability to Python developers for free.
+
+[![PyPI version](https://badge.fury.io/py/scope3track.svg)](https://pypi.org/project/scope3track/)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/)
+
+## The Problem
+
+EU CSRD enforcement + enterprise Scope 3 requirements are now cascading to SMB suppliers. Companies are required to report their full value-chain emissions. Enterprise tools cost $30K–$150K/year — nothing exists at the $99–$499/mo SMB price point.
+
+## Installation
+
+```bash
+pip install scope3track
+```
+
+## Quick Start
+
+```python
+from scope3track import EmissionCalculator, EmissionScope, Scope3Category
+from datetime import datetime
+
+calc = EmissionCalculator()
+
+# Calculate Scope 3 Category 4: upstream transport
+transport_entry = calc.calculate(
+    entry_id="ENT-001",
+    scope=EmissionScope.SCOPE3,
+    category=Scope3Category.UPSTREAM_TRANSPORT,
+    source="Freight — Shanghai to LA",
+    activity_amount=5000,    # kg of freight
+    activity_unit="kg",
+    factor_key="km_road_freight_hgv",
+    period_start=datetime(2025, 1, 1),
+    period_end=datetime(2025, 3, 31),
+    supplier_id="SUPPLIER-CN-01",
+)
+
+print(f"{transport_entry.emissions_kg_co2e:.2f} kg CO2e")
+```
+
+## Build a Full Report
+
+```python
+entries = [
+    calc.calculate("e1", EmissionScope.SCOPE1, "Natural gas heating", 10000, "kwh", "kwh_natural_gas", period_start=..., period_end=...),
+    calc.calculate("e2", EmissionScope.SCOPE2, "Office electricity", 50000, "kwh", "kwh_electricity_us", period_start=..., period_end=...),
+    calc.calculate("e3", EmissionScope.SCOPE3, "Employee commuting", 200000, "km", "km_passenger_car", category=Scope3Category.EMPLOYEE_COMMUTING, period_start=..., period_end=...),
+]
+
+report = calc.build_report(
+    company_id="ACME-INC",
+    reporting_year=2025,
+    entries=entries,
+)
+
+print(report.summary())
+# {'company_id': 'ACME-INC', 'scope1_t_co2e': 2.02, 'scope2_t_co2e': 19.3, 'scope3_t_co2e': 34.2, 'total_t_co2e': 55.52, ...}
+```
+
+## Built-in Emission Factors
+
+`scope3track` ships with GHG Protocol default factors for:
+
+- **Energy**: electricity (US/EU grid), natural gas
+- **Transport**: road freight, air freight, sea freight, passenger car, business flights
+- **Materials**: steel, aluminium, plastic, paper, concrete
+- **Waste**: landfill, recycled, composted
+
+Register custom factors:
+
+```python
+from scope3track import default_registry
+
+default_registry.register("kwh_solar_ppa", 0.012)
+```
+
+## Scope 3 Categories Supported
+
+All 15 GHG Protocol Scope 3 categories (upstream + downstream):
+
+`purchased_goods_services`, `capital_goods`, `fuel_and_energy_activities`, `upstream_transportation_distribution`, `waste_generated_in_operations`, `business_travel`, `employee_commuting`, `upstream_leased_assets`, `downstream_transportation_distribution`, `processing_of_sold_products`, `use_of_sold_products`, `end_of_life_treatment`, `downstream_leased_assets`, `franchises`, `investments`
+
+## Advanced Features
+
+### Pipeline
+
+```python
+from scope3track import EmissionPipeline
+
+pipeline = (
+    EmissionPipeline()
+    .filter(lambda e: e.scope == EmissionScope.SCOPE3, name="scope3_only")
+    .map(lambda entries: sorted(entries, key=lambda e: -e.emissions_kg_co2e), name="sort_by_impact")
+    .with_retry(count=2)
+)
+
+scope3_sorted = pipeline.run(entries)
+```
+
+### Caching
+
+```python
+from scope3track import EmissionCache
+
+cache = EmissionCache(max_size=1000, ttl_seconds=3600)
+
+@cache.memoize
+def get_supplier_emissions(supplier_id):
+    ...
+
+cache.save("emissions_cache.pkl")
+cache.load("emissions_cache.pkl")
+print(cache.stats())
+```
+
+### Export Reports
+
+```python
+from scope3track import EmissionReportExporter
+
+print(EmissionReportExporter.to_json(report))
+print(EmissionReportExporter.to_csv(report))
+print(EmissionReportExporter.to_markdown(report))
+```
+
+### Drift Detection
+
+```python
+from scope3track import EmissionDriftDetector
+
+detector = EmissionDriftDetector(threshold=0.15)
+for period_total in quarterly_totals:
+    detector.record(period_total)
+
+if detector.is_drifted():
+    print(f"Emission drift detected: {detector.drift_ratio():.1%}")
+```
+
+### Diff Between Periods
+
+```python
+from scope3track import diff_entries
+
+diff = diff_entries(q1_entries, q2_entries)
+print(diff.summary())  # {'added': 2, 'removed': 0, 'modified': 3}
+print(diff.to_json())
+```
+
+### Async Batch
+
+```python
+from scope3track import abatch_calculate, CancellationToken
+
+token = CancellationToken()
+entries = await abatch_calculate(raw_data, calc_fn, max_concurrency=8, token=token)
+```
+
+### Streaming NDJSON
+
+```python
+from scope3track import entries_to_ndjson
+
+for line in entries_to_ndjson(entries):
+    output_stream.write(line)
+```
+
+## Frameworks Supported
+
+- GHG Protocol Corporate Standard
+- EU CSRD / ESRS E1
+- ISO 14064-1
+
+## License
+
+MIT

scope3track-1.0.0/scope3track/__init__.py

@@ -0,0 +1,76 @@
+"""scope3track — Carbon and Scope 3 emissions tracking for SMBs and enterprise supply chains."""
+from scope3track.models import (
+    EmissionEntry,
+    EmissionReport,
+    EmissionScope,
+    EmissionUnit,
+    Scope3Category,
+    SupplierEmissions,
+)
+from scope3track.calculator import (
+    EmissionCalculator,
+    EmissionFactorRegistry,
+    default_registry,
+)
+from scope3track.exceptions import (
+    CalculationError,
+    ReportError,
+    Scope3TrackError,
+    ValidationError,
+)
+from scope3track.advanced import (
+    AuditLog,
+    CancellationToken,
+    EmissionCache,
+    EmissionDiff,
+    EmissionDriftDetector,
+    EmissionPipeline,
+    EmissionProfiler,
+    EmissionReportExporter,
+    EmissionRule,
+    EmissionValidator,
+    PIIScrubber,
+    RateLimiter,
+    abatch_calculate,
+    batch_calculate,
+    diff_entries,
+    entries_to_ndjson,
+    stream_entries,
+)
+
+__version__ = "1.0.0"
+__all__ = [
+    # Core
+    "EmissionCalculator",
+    "EmissionFactorRegistry",
+    "default_registry",
+    "EmissionEntry",
+    "EmissionReport",
+    "EmissionScope",
+    "EmissionUnit",
+    "Scope3Category",
+    "SupplierEmissions",
+    # Exceptions
+    "Scope3TrackError",
+    "CalculationError",
+    "ValidationError",
+    "ReportError",
+    # Advanced
+    "EmissionCache",
+    "EmissionPipeline",
+    "EmissionValidator",
+    "EmissionRule",
+    "RateLimiter",
+    "CancellationToken",
+    "batch_calculate",
+    "abatch_calculate",
+    "EmissionProfiler",
+    "EmissionDriftDetector",
+    "EmissionReportExporter",
+    "stream_entries",
+    "entries_to_ndjson",
+    "EmissionDiff",
+    "diff_entries",
+    "AuditLog",
+    "PIIScrubber",
+]