Setting up OpenSTEF for development#

This guide will help you set up a development environment for OpenSTEF 4.0, which uses a modern Python development stack with uv and a monorepo workspace structure.

Prerequisites#

Python version#

OpenSTEF 4.0 requires Python 3.12 or higher. You can check your Python version with:

python --version

Installing uv#

OpenSTEF 4.0 uses uv as the primary dependency manager and Python project manager. uv is a fast, Rust-based Python package manager that handles both dependency resolution and virtual environments.

Install uv using the recommended method for your platform:

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

pipx install uv

pip install uv

For more installation options, see the uv installation guide.

Cloning the repository#

Clone the OpenSTEF repository and navigate to the project directory:

git clone https://github.com/OpenSTEF/openstef.git
cd openstef

Setting up the development environment#

OpenSTEF 4.0 uses a workspace structure with multiple packages:

  • openstef-models: Core forecasting models, feature engineering, and data processing

  • openstef-beam: Backtesting, evaluation, analysis and metrics

  • openstef-core: Core utilities, dataset types, shared types and base models used by other packages

  • docs: Documentation source

  • openstef-compatibility: Compatibility layer for OpenSTEF 3.x (coming soon)

  • openstef-foundational-models: Deep learning and foundational models (coming soon)

Install the development dependencies using uv:

uv sync --all-groups --all-extras

This will:

  1. Create a virtual environment (if one doesn’t exist)

  2. Install all workspace packages in development mode

  3. Install all development dependencies including testing, linting, and documentation tools

  4. Install all optional extras for development

Understanding the workspace structure#

OpenSTEF 4.0 uses a monorepo workspace structure defined in pyproject.toml:

[tool.uv.workspace]
members = [
        "packages/openstef-models",
        "packages/openstef-beam",
        "packages/openstef-core",
  "docs",
]

This means:

  • All packages are developed together in a single repository

  • Dependencies between packages are automatically resolved

  • You can work on multiple packages simultaneously

  • Changes in one package are immediately available to other packages

Verifying your installation#

Test that your environment is set up correctly:

# Check that uv is working
uv --version

# Check that you can run the task runner
uv run poe --help

# Run a quick test to verify everything works
uv run poe all --check

If everything is working correctly, the last command should run all linting, formatting, type checking, and tests without errors.

Next steps#

Now that you have a working development environment, you can:

  1. Read the Development workflow guide to understand how to contribute

  2. Explore the Documentation Guide guide if you want to contribute to documentation

  3. Look at the good first issues to find something to work on

Development tools overview#

Note that also OpenSTEF 4.0 uses several modern development tools:

All these tools are configured and ready to use through the poe task runner. See poe --help for available commands.

Building documentation#

To build the documentation locally:

# Build the documentation
poe docs

# Build and serve with live reload (recommended for editing)
poe docs --serve

# Clean previous builds
poe docs-clean

The built documentation will be available at docs/build/html/index.html.

Note

Building documentation requires additional dependencies that are included in the development environment. Make sure you’ve run uv sync --all-groups --all-extras first.