API Reference¶

Quick-reference tables for every public class, method, and enumeration in the sites-toolkit library.

Imports cheat sheet¶

from sites.sdk import SitesClient
from sites.sdk.sites import Site, Authenticator
from sites.sdk.sites.site_content import SiteContentManagement
from sites.sdk.sites.utils import FileType, SiteType, SiteAccessPermission, ProxyType, ContextRoot, ArchiveFormat
from sites.sdk.common import ApiCallException, ChecksumMismatchError
from sites.sdk.common.http.utils import parse_repr_digest
from sites.sdk.common.configuration import configuration

`Authenticator`¶

Module: sites.sdk.sites.Authenticator

Factory methods¶

Method	Parameters	Returns	Description
`from_credentials(username, password)`	`username: str`, `password: str`	`Authenticator`	Authenticate with ECMWF OpenID Connect
`from_token(token)`	`token: str`	`Authenticator`	Authenticate with a site-specific bearer token
`from_credentials_base64(credentials)`	`credentials: str`	`Authenticator`	Restore from a base64-encoded `username.password` string
`from_environment_variables()`	—	`Authenticator`	Read `SITES_AUTHENTICATOR_USERNAME` and `SITES_AUTHENTICATOR_PASSWORD` from the environment

Instance methods¶

Method	Parameters	Returns	Description
`get_token()`	—	`str`	The raw JWT or bearer token
`get_authorization_header()`	—	`dict`	`{'Authorization': 'Bearer <token>'}`
`get_credentials_base64()`	—	`str`	Base64-encoded `username.password` for storage

`SitesClient`¶

Module: sites.sdk.SitesClient

Constructor: SitesClient(authenticator=None, config=configuration)

Hub-level operations¶

Method	Parameters	Returns	Description
`whoami()`	—	`dict`	Authenticated user's profile and group memberships
`list(owner, name, space, site_type, query, enabled_only)`	all optional	`dict`	List sites with optional filters
`list_walk(owner, name, space, site_type, enabled_only)`	all optional	`Iterator`	Lazy generator over filtered sites
`create_site(site)`	`site: Site`	`dict`	Create a site; refreshes `site` from server
`update_site(space, name, site)`	`space: str`, `name: str`, `site: Site`	`dict`	Update a site; refreshes `site` from server
`delete_site(site)`	`site: Site`	`dict`	Permanently delete a site
`toggle_site(site)`	`site: Site`	`dict`	Enable or disable a site
`health()`	—	`dict`	Aggregated platform health status
`sites_health()`	—	`dict`	Sites service health status
`content(site, authenticator)`	`site: Site`, `authenticator` optional	`SiteContentManagement`	Get a content manager for a site

`Site`¶

Module: sites.sdk.sites.Site

Factory methods¶

Method	Parameters	Returns	Description
`from_space_and_name(space, name)`	`space: str`, `name: str`	`Site`	Create a site reference from space + name
`from_template(template)`	`template: str`	`Site`	Create a site from a named template
`from_dict(dic)`	`dic: dict`	`Site`	Reconstruct a site from a dictionary
~~`from_owner_and_name(owner, name)`~~	`owner: str`, `name: str`	`Site`	Deprecated — use `from_space_and_name`

Instance methods¶

Method	Parameters	Returns	Description
`load_from_server(authenticator)`	`authenticator` optional	`None`	Reload all properties from the API
`get_content_manager(authenticator)`	`authenticator` optional	`SiteContentManagement`	Get a content manager for this site
`to_dict()`	—	`dict`	Serialize all public properties to a dictionary
`to_str()`	—	`str`	Pretty-print the site
`get_path()`	—	`str`	Returns `'space/name'`
`get_base_url()`	—	`str`	Returns the platform base URL
`get_config()`	—	`Configuration`	Returns the configuration object

Properties¶

See the Site Management — properties table for the full list.

`SiteContentManagement`¶

Module: sites.sdk.sites.site_content.SiteContentManagement

Constructor: SiteContentManagement(site, authenticator=None)

File operations¶

Method	Key parameters	Returns	Description
`list(remote_path, match_pattern, file_type, recursive, limit, continuation_token)`	—	`dict`	List files; defaults to API version from config
`list_v1(remote_path, match_pattern, file_type, recursive)`	—	`dict`	List using API v1
`list_v2(remote_path, match_pattern, file_type, recursive, limit, continuation_token)`	—	`dict`	List using API v2 with pagination
`list_walk(remote_path, match_pattern, file_type, recursive, limit)`	—	`Iterator`	Lazy, paginated file iterator
`download(remote_path, match_pattern, verify, archive)`	`verify: bool` (default `False`), `archive: ArchiveFormat` (optional)	`bytes` or `dict`	Download a file or file listing; optionally verify SHA-256 integrity. Pass `archive` (`zip`, `tar`, `tgz`) to download a compressed archive
`download_with_checksum(remote_path, match_pattern, verify)`	`verify: bool` (default `False`)	`dict`	Deprecated: use `download(..., verify=True)`; will be removed in the next release
`checksum(remote_path)`	`remote_path: str` required	`dict`	Retrieve SHA-256 checksum and file metadata via HEAD (no body download)
`upload(local_path, match_pattern, remote_path, recursive, ignore_errors, if_exists_rename_to, if_exists_backup, upload_zero_byte_files)`	`local_path: str` required	`list[dict]`	Upload file(s) to the site. Always returns a list with one result dict per uploaded file — even for a single file. A `checksum` key is included when the server returns a digest
`delete(remote_path, match_pattern, recursive)`	—	`dict`	Delete file(s) or directories. Returns `207 Multi-Status` dict with `deleted`/`failed` arrays on partial failure
`health()`	—	`dict`	Site health status
`get_version()`	—	`dict`	Site API version (e.g. `{'version': '2.0.0'}`)
`clone(to_site, authenticator, cleanup_after, ignore_errors, local_path)`	—	`None`	Clone all content to another site
`publish()`	—	`dict`	Trigger the publishing workflow

Token operations¶

Method	Key parameters	Returns	Description
`generate_token(identifier, duration, permission)`	all required	`dict`	Generate a branca bearer token
`decode_token(token)`	`token: str`	`dict`	Inspect a token without revoking it
`revoke_token(token, token_hash)`	one of the two required	`dict`	Revoke a token by string or hash
`token_history(identifier, permission, expiring_within, include_expired)`	all optional	`dict`	List token usage history
`delete_token_history(token_hash)`	`token_hash: str`	`dict`	Remove a single history entry
`backup_token_history()`	—	`dict`	Create a server-side backup of history
`restore_token_history()`	—	`dict`	Restore history from latest backup

Signed URL operations¶

Method	Key parameters	Returns	Description
`generate_signed_url(target_url, duration, permission)`	all required	`dict`	Create a time-limited, signed link
`verify_signed_url(url)`	`url: str`	`dict`	Verify a signed URL's validity

Symlink operations¶

Method	Key parameters	Returns	Description
`create_symlink(path, target_path, force)`	`path` and `target_path` required	`dict`	Create a symlink inside the site
`get_symlink(path)`	`path: str` required	`dict`	Get symlink info (target path)
`delete_symlink(path, force)`	`path: str` required	`dict`	Delete a symlink; `force` defaults to `False`

Enumerations¶

`FileType`¶

from sites.sdk.sites.utils import FileType

FileType.FILE    # 'f' — regular files
FileType.DIR     # 'd' — directories

`SiteType`¶

from sites.sdk.sites.utils import SiteType

SiteType.Public    # 'public'  — no authentication required
SiteType.Private   # 'private' — authentication + ACL required (default)

`SiteAccessPermission`¶

from sites.sdk.sites.utils import SiteAccessPermission

SiteAccessPermission.Read       # 'r'  — read-only
SiteAccessPermission.ReadWrite  # 'rw' — read and write

`ProxyType`¶

from sites.sdk.sites.utils import ProxyType

ProxyType.ProxyPass   # 'proxy'   — standard HTTP proxy (Apache ProxyPass)
ProxyType.FastCGI     # 'fastcgi' — FastCGI proxy

`ContextRoot`¶

from sites.sdk.sites.utils import ContextRoot

ContextRoot.RootContext   # 'root_context' — app served from '/'
ContextRoot.SiteContext   # 'site_context' — app served from '/space/name/'

`ArchiveFormat`¶

from sites.sdk.sites.utils import ArchiveFormat

ArchiveFormat.ZIP   # 'zip' — ZIP archive
ArchiveFormat.TAR   # 'tar' — uncompressed TAR archive
ArchiveFormat.TGZ   # 'tgz' — gzip-compressed TAR archive

Environment variables¶

Variable	Default	Description
`SITES_BASE_URL`	`https://sites.ecmwf.int`	Platform base URL
`API_VERSION`	`2`	REST API version for file operations
`RETRIES`	`5`	HTTP retry count on failure
`LARGE_FILE_SIZE`	`107374182` (≈ 100 MB)	Byte threshold for automatic v2 upload routing
`SITES_AUTHENTICATOR_USERNAME`	(not set)	Username for `from_environment_variables()`
`SITES_AUTHENTICATOR_PASSWORD`	(not set)	Password for `from_environment_variables()`

Exceptions¶

Exception	When raised
`ApiCallException`	An API request returned an error status. The exception message contains the error detail.
`ChecksumMismatchError`	The SHA-256 digest computed locally after download does not match the server-reported `Repr-Digest`. Subclass of `ApiCallException`.
`FileNotFoundError`	A local file or path passed to `upload()` does not exist, or a remote file was not found (404).
`RuntimeError`	Invalid method arguments (e.g., neither `token` nor `token_hash` provided to `revoke_token`).

API Reference¶

Imports cheat sheet¶

Authenticator¶

Factory methods¶

Instance methods¶

SitesClient¶

Hub-level operations¶

Site¶

Factory methods¶

Instance methods¶

Properties¶

SiteContentManagement¶

File operations¶

Token operations¶

Signed URL operations¶

Symlink operations¶

Enumerations¶

FileType¶

SiteType¶

SiteAccessPermission¶

ProxyType¶

ContextRoot¶

ArchiveFormat¶

Environment variables¶

Exceptions¶

`Authenticator`¶

`SitesClient`¶

`Site`¶

`SiteContentManagement`¶

`FileType`¶

`SiteType`¶

`SiteAccessPermission`¶

`ProxyType`¶

`ContextRoot`¶

`ArchiveFormat`¶