Metadata-Version: 2.2
Name: carbon_footprint_cal
Version: 1.0.0
Summary: A library for calculating carbon emissions and managing related data.
Home-page: https://github.com/abigail-anil/Carbon-Footprint-Tracker
Author: Abigail Anil
Author-email: abigailanil19@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: boto3
Requires-Dist: requests
Requires-Dist: requests_mock
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: moto; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Requires-Dist: pylint; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Carbon Emissions Library

**Description:**

This library provides tools for calculating and tracking carbon emissions, integrating with the Carbon Interface API for up-to-date emission factors, and utilizing AWS DynamoDB for data storage. It's designed to be used both in general Python environments and seamlessly within AWS Lambda functions.

## Features

* **Carbon Emission Calculation:** Calculates carbon emissions for various activity types (electricity, transportation, food) using the Carbon Interface API.
* **AWS Integration:** Integrates with AWS DynamoDB for persistent data storage.
* **Data Storage:** Stores carbon emission data (user ID, activity type, value, emission) in a DynamoDB table.
* **Data Validation:** Ensures data integrity through validation of required fields and data types.
* **Automatic API Key Handling:** Automatically retrieves the Carbon Interface API key from environment variables, especially useful in AWS Lambda.
* **Modular Design:** Organized into reusable modules for calculations, data storage, and validation.
* **Environment Variable Configuration:** Designed to be configured via environment variables.

## Installation

**If you have uploaded the library to PyPI:**

```bash
pip install carbon_footprint_cal
```

## Usage
This library uses carbon interface API to fetch the emissions factor. An API key (CARBON_INTERFACE_API_KEY)is required to fetch the emission factor which can be set as an environment variable.

### Calculations


```python

from carbon_footprint_cal.emissions.calculations import Calculations
import os

carbon_interface_api_key = os.environ.get("CARBON_INTERFACE_API_KEY")
carbon_calculator = Calculations(carbon_interface_api_key)

# Electricity Calculation
electricity_value = 100  # kWh or mwh
location = "US-CA"  # Example: "country-state"
electricity_emission = carbon_calculator.calculate_electricity_emission(electricity_value, location, unit="kwh") #unit is optional, and defaults to kwh.
print(f"Calculated electricity emission: {electricity_emission} kg CO2e")

# Flight Calculation
passengers = 2
legs = [{"departure_airport": "sfo", "destination_airport": "yyz"}, {"departure_airport": "yyz", "destination_airport": "sfo"}]
flight_emission = carbon_calculator.calculate_flight_emission(passengers, legs)
print(f"Calculated flight emission: {flight_emission} kg CO2e")

# Shipping Calculation
weight_value = 200
weight_unit = "g"
distance_value = 2000
distance_unit = "km"
transport_method = "truck"
shipping_emission = carbon_calculator.calculate_shipping_emission(weight_value, weight_unit, distance_value, distance_unit, transport_method)
print(f"Calculated shipping emission: {shipping_emission} kg CO2e")
```

### AWS Lambda Environment:

If you configure the CARBON_INTERFACE_API_KEY environment variable in your Lambda function's settings, you can simplify the code:

```python

from carbon_footprint_cal.emissions.calculations import Calculations

def lambda_handler(event, context):
    carbon_calculator = Calculations() #The API key is automatically retrieved.
    emission = carbon_calculator.calculate_emission("electricity", 100, location="US")
    return {
        'statusCode': 200,
        'body': f'Emission: {emission}'
    }
```
    
### Data Storage
```python

from carbon_footprint_cal.data_storage import DataStorage
import os
from decimal import Decimal

data_storage = DataStorage(table_name="TestTable") #Ensure to create the table beforehand.

user_id = "user123"
activity_type = "electricity"
input_params = {"location": "US-CA", "value": Decimal("100"), "unit": "kwh"}
carbon_kg = Decimal("50")

data_storage.store_emission_data(user_id, activity_type, input_params, carbon_kg)
user_data = data_storage.get_user_emissions(user_id)
print(user_data)
```

### Data Validation
```python

from carbon_footprint_cal.validation import Validation

validation = Validation()

# Example: Electricity validation
try:
    validation.validate_electricity_params("US-CA", 100, "kwh")
    print("Electricity data is valid")
except ValueError as e:
    print(f"Electricity data is invalid: {e}")

# Example: Flight validation
try:
    legs = [{"departure_airport": "sfo", "destination_airport": "yyz"}]
    validation.validate_flight_params(2, legs)
    print("Flight data is valid")
except ValueError as e:
    print(f"Flight data is invalid: {e}")

# Example: Shipping validation
try:
    validation.validate_shipping_params(200, "g", 2000, "km", "truck")
    print("Shipping data is valid")
except ValueError as e:
    print(f"Shipping data is invalid: {e}")
```
    
### Data Storage

The library uses AWS DynamoDB for persistent storage.

Table Name: The DynamoDB table name is configurable via the DYNAMODB_TABLE_NAME environment variable or defaults to "CarbonFootprint".
Usage: The data_storage module provides methods to store and retrieve data.

### Data Validation
The library includes data validation to ensure data integrity.

Validation Rules: Checks for required fields (e.g., location, departure_airport, destination_airport, etc) and ensures that values are of the correct type (e.g., non-negative numbers).
Refer https://docs.carboninterface.com/ for the rules to pass data to Carbon Interface API.
Error Handling: Returns an error message if validation fails.
Usage: The validation module provides a method to validate data.

## Dependencies
* requests
* boto3
* os
* logging
* requests_mock (for testing)

## Environment Variables
CARBON_INTERFACE_API_KEY: Your Carbon Interface API key.
DYNAMODB_TABLE_NAME: (Optional) The name of the DynamoDB table to use.

## License
This project is licensed under the MIT License. See the LICENSE file for details.
