Skip to main content

Introduction

What is pyetm?​

pyetm is a package written in Python that allows ETM users to interact with the ETM via the API. The package is designed to be a modular tool that advanced users can incorporate into their workflows.

You can clone the pyetm from our Github. The package is also available via pip like any other python package - install it and use it in your project!

pip install pyetm

To run the tools a Python installation is required, however many of the actions require very little programming experience, and we've given examples of the workflows in the examples folder. #TODO link examples section

With pyetm you can:

Getting started​

Make sure you have Python 3 installed. Then, install all required libraries by opening a terminal/command-prompt window in the pyetm folder (or navigate to this folder in the terminal using cd "path/to/scenario-tools-folder"). All following examples of running the tool expect you to be in this folder.

Poetry​

Follow the official instructions:

For Mac with brew​

Make sure pipx is installed, otherwise use:

brew install pipx

Then:

pipx install poetry

Other systems​

curl -sSL https://install.python-poetry.org | python3 -

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 either with a config.env file or environment variables. You can simply set an environment and the base URL will be inferred for you.

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

  2. Edit config.env:

    # 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://user:pass@proxy.example.com:8080
    # PROXY_SERVERS_HTTPS=http://user:pass@secureproxy.example.com:8080

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

Place config.env in the project root (pyetm/ folder).

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​

If you prefer, set these environment variables directly:

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