Skip to content

Getting Started

This guide walks you through installing the Sites Python Client, configuring it for your environment, and running your first script to confirm everything is working.

Prerequisites

Installation

pip install sites-toolkit -i https://get.ecmwf.int/repository/pypi-all/simple

From source

Clone the repository and build it yourself:

git clone https://git.ecmwf.int/scm/infra/sites-python-client.git
cd sites-python-client

pip install -r dev-requirements.txt
python -m build
pip install dist/sites_toolkit-*.whl

Verify the installation

import sites
print(sites.__version__)

Configuration

The library can be configured through environment variables. You do not need to set any of them to get started — the defaults work against the live ECMWF Sites platform. Change them if you work against a staging environment or need to tune behaviour.

Variable Default What it does
SITES_BASE_URL https://sites.ecmwf.int Base URL of the Sites platform. Override this to point at a staging or internal instance.
API_VERSION 2 REST API version used for file operations.
RETRIES 5 How many times the client retries a failed HTTP request before raising an error.
LARGE_FILE_SIZE 107374182 (≈ 100 MB) Files at or above this byte size are automatically routed through the API v2 upload path.
SITES_AUTHENTICATOR_USERNAME (not set) Username for Authenticator.from_environment_variables(). Plain text or base64-encoded.
SITES_AUTHENTICATOR_PASSWORD (not set) Password for Authenticator.from_environment_variables(). Plain text or base64-encoded.

Example — pointing at a staging server:

export SITES_BASE_URL="https://sites-stage.ecmwf.int"

Your first script

The script below authenticates with the platform, confirms your identity, and lists all sites you have access to:

from sites.sdk import SitesClient
from sites.sdk.sites import Authenticator

# Step 1: authenticate with your ECMWF credentials
authenticator = Authenticator.from_credentials(
    username='your_username',
    password='your_password'
)

# Step 2: create a client connected to the platform
client = SitesClient(authenticator=authenticator)

# Step 3: verify authentication — prints your username, role, and group memberships
user_info = client.whoami()
print("Logged in as:", user_info['data']['username'])
print("Role:", user_info['data']['role'])

# Step 4: list all your sites
all_sites = client.list()
for s in all_sites.get('data', []):
    print(s['custom_space'], '/', s['site_name'])

Expected output (abbreviated):

Logged in as: myuser
Role: User
docs / my-project-docs
myuser / test-site

What's next?