pyetm 2.0.0b5

Python-ETM Connector

---

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 ETM documentation page.

---

Installation

You can install pyetm directly from PyPI:

pip install pyetm

Or clone from our GitHub repository if you want the latest development version:

git clone https://github.com/quintel/pyetm.git
cd pyetm

---

Running Jupyter Notebooks (Beginner Friendly)

If you only want to open and run our Jupyter notebooks in VS Code without developing the package, follow the beginner guide here: Running notebooks.

---

Development Setup (Using Poetry)

We recommend using Poetry to manage dependencies and virtual environments. Poetry ensures all dependencies are installed in an isolated environment, keeping your system clean.

Python

Make sure you have Python 3.12 or later installed:

• Windows: Download from python.org
• macOS: Install via Homebrew

  brew install python@3.12
  

• Linux: Use your package manager or install from source.

Check your version:

python3 --version

---

Poetry

Follow the official instructions:

For Mac with brew

brew install poetry

For other systems

Make sure pipx is installed, otherwise use:

brew install pipx

Then:

pipx install poetry

Finally

After installation, ensure Poetry is available:

poetry --version

Install Dependencies

Navigate to the pyetm folder and install all dependencies:

poetry install

This will:

• Create a virtual environment
• Install runtime dependencies If you want development dependencies (testing, linting, etc.) then append the "--with dev" flag to the install command.

How to use the environment:

You can either:

• Run commands inside Poetry's environment:

  poetry run pytest
  poetry run pyetm
  

• Or activate the shell:

  eval $(poetry env activate)
  

  Then run you can commands normally (e.g.):

  pytest
  

Configuring Your Settings

You can configure your API token and base URL using environment variables or a .env file. You can simply set an environment and the base URL will be inferred for you.

Option 1: .env File (Recommended)

1. Copy the example file (.env.example) and rename it to .env:

   cp .env.example .env
   

2. Edit .env with your settings:

   # Your ETM API token (required)
   ETM_API_TOKEN=your.token.here
   
   # Environment (default: pro)
   ENVIRONMENT=pro
   
   # Optional: Override base URL directly
   # BASE_URL=https://engine.energytransitionmodel.com/api/v3
   
   # Optional: Proxy settings
   # PROXY_SERVERS_HTTP=http://proxy.example.com:8080
   # PROXY_SERVERS_HTTPS=http://secureproxy.example.com:8080
   
   # CSV settings (optional)
   CSV_SEPARATOR=,
   DECIMAL_SEPARATOR=.
   

For development: Place .env in the repository root (pyetm/ folder).

For installed package: Place .env in your project's working directory (where you run your Python scripts).

Environment Options:

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

Option 2: Environment Variables

Set these environment variables directly in your shell:

ETM_API_TOKEN=<your token>
ENVIRONMENT=<pro|beta|local|YYYY-MM>
# or provide a direct override instead of ENVIRONMENT
BASE_URL=<api url>

Note: Environment variables take precedence over values in .env files.

---

Temporary File Storage

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

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

Files are organized by scenario ID to enable efficient caching across requests.

---

Running Examples

The example notebooks in the examples/ directory are designed for development and require the repository to be cloned. They use repository-relative paths and sample input files that are not included when installing via pip.

To run the examples:

1. Clone the repository:

   git clone https://github.com/quintel/pyetm.git
   cd pyetm
   

2. Install with development dependencies:

   poetry install --with dev
   

3. Configure your settings (see "Configuring Your Settings" above)
4. Open the notebooks in Jupyter or VS Code

---

Notes

• Windows:
  • Use py instead of python3 if python3 is not recognized.
  • In PowerShell, set environment variables with:

    $env:ETM_API_TOKEN="your-token"
    

• macOS/Linux:
  • Use python3 in commands.
  • Set environment variables with:

    export ETM_API_TOKEN="your-token"
    export ENVIRONMENT=beta
    

Contributing

See our Contributing Guide for details.