pyetm 2.0.2

This package provides a set of tools for interaction with the Energy Transition Model's API. Learn more about the Energy Transition Model here.

The package is designed to be a modular tool that advanced users can incorporate into their scenario workflows. More documentation is available via the docs.

Installation

Note: If you are not familiar working with python packages, please refer to the quick start guide first.

Install pyetm from PyPI:

pip install pyetm

Requirements: Python 3.12 or later

Check your Python version:

python3 --version

If you need to install Python:

• Windows: Download from python.org
• macOS: Install via Homebrew: brew install python@3.12
• Linux: Use your package manager (e.g., apt install python3)

Quick Start

1. Create a Virtual Environment

We recommend using a virtual environment to keep your project dependencies isolated:

# Create a new virtual environment
python3 -m venv .venv

# Activate it
# On macOS/Linux:
source .venv/bin/activate

# On Windows (PowerShell):
.venv\Scripts\Activate.ps1

# On Windows (Command Prompt):
.venv\Scripts\activate.bat

More details on how python virtual environments work can be found here

2. Install pyetm

With your virtual environment activated:

pip install pyetm

Note: New versions of pyetm are consistently released. Check here for the latest release

An example of how to install a specific release:

pip install pyetm==2.0.0

3. Initialize Your Project

Run the interactive setup command:

pyetm init

This will:

• Ask which environment you want to use (production, beta, or local)
• Create a .env configuration file
• Copy an input template Excel file to excel/input.xlsx

After initialization, you'll need to manually add your API token to the .env file:

1. Open .env in your text editor
2. Find the commented # ETM_API_TOKEN= line
3. Uncomment it by removing the #
4. Paste your full token after the = sign (get your token here)
5. Save the file

Note: API tokens are very long (1000+ characters). Make sure you paste the entire token.

Command options:

• --environment: Target environment (pro, beta, or local)
• --force: Overwrite existing files without prompting

Example:

pyetm init --environment pro

4. Run Scenarios from Excel

The easiest way to work with scenarios is using Excel files:

# Edit excel/input.xlsx with your scenario data, then run:
pyetm run excel/input.xlsx

This will load your scenarios, update them on ETM, and export results to excel/input_results.xlsx.

Command options:

• --output PATH or -o PATH: Custom output file location
• --log-level: Logging verbosity

Example:

# Custom output location
pyetm run excel/input.xlsx --output results/my_results.xlsx

# Read-only mode (fetch data without updating)
pyetm run excel/input.xlsx --no-update

For more detailed 'pyetm run' workflow instructions, see the Quick Start Guide in the docs.

Configuration

The pyetm init command creates a .env file with your settings. You can also configure manually:

Environment Variables

Create a .env file in your project directory:

# Your ETM API token (optional for public scenarios)
ETM_API_TOKEN=etm_your_token_here

# Environment (default: pro)
# Options: pro, beta, local, or stable tags like 2025-01
ENVIRONMENT=pro

# Error handling (default: default)
# Options: safe, default, dangerous
PYETM_ERROR_MODE=default

# CSV export settings (optional)
CSV_SEPARATOR=,
DECIMAL_SEPARATOR=.

Note on API Token:

• Without a token: You can create and work with public scenarios (read and write operations)
• With a token: Required to access your saved scenarios, list your scenarios, and work with private scenarios
• Get your token here

Environment Options:

• pro (default): Production environment
• beta: Staging environment
• local: Local development environment
• YYYY-MM: Stable tagged environment (e.g., 2025-01)

Error Handling Modes:

• default (recommended): Errors raise in single operations, warnings collected in bulk operations
• safe: All warnings raise exceptions (use in CI/production for maximum safety)
• dangerous: No warnings raise (use only for exploratory data analysis)

Advanced Configuration

You can override the base URL directly if needed:

BASE_URL=https://engine.energytransitionmodel.com/api/v3

SSL/TLS Configuration

For corporate environments or custom certificate setups:

Example for corporate CA:

SSL_CERT_PATH=/path/to/corporate-ca-bundle.pem
TRUST_ENV=true
HTTP_PROXY=http://proxy.company.com:8080

For examples and tutorials, visit our documentation.

Temporary File Storage

The package stores temporary files (cached curves and custom data) in your system's temp directory:

• macOS/Linux: /tmp/pyetm/
• Windows: %TEMP%\pyetm\

Contributing

Interested in contributing to pyetm development? See our Contributing Guide for details on:

• Setting up the development environment with Poetry
• Running tests
• Code style guidelines
• Submitting pull requests

Getting Help

• Documentation: docs.energytransitionmodel.com
• Issues: GitHub Issues
• Repository: github.com/quintel/pyetm