Configuration¶

VARS is deployed differently at each institution — different hosts, different secrets, some without Raziel at all. vars_client.config decouples "where do I find each service" from any one deployment via the ConfigProvider interface:

class ConfigProvider(ABC):
    async def get_endpoints(self) -> dict[str, ServiceEndpoint]: ...

ServiceEndpoint is a small frozen dataclass: name, url, secret (None when a service needs no secret, e.g. Skimmer). All three built-in providers below return the same shape, so they're interchangeable anywhere a ConfigProvider is expected — including VARSClient.

RazielConfigProvider¶

Discovers endpoints at runtime from a running Raziel instance:

from vars_client.config import RazielConfigProvider

config = RazielConfigProvider("https://raziel.example.org", "user", "password")
endpoints = await config.get_endpoints()

Pass internal=True to get Raziel's internal (docker-network) URLs instead of external ones. username/password are optional — omit both for anonymous, read-only discovery (endpoints come back without secrets):

config = RazielConfigProvider("https://raziel.example.org")

StaticConfigProvider¶

Fixed endpoints, for institutions not running Raziel:

from vars_client.config import StaticConfigProvider

config = StaticConfigProvider.from_dict({
    "annosaurus": {"url": "https://annosaurus.example.org", "secret": "..."},
    "beholder": {"url": "https://beholder.example.org", "secret": "..."},
    "skimmer": {"url": "https://skimmer.example.org"},
})

or from a YAML file with the same shape:

# vars-config.yaml
annosaurus:
  url: https://annosaurus.example.org
  secret: ...
beholder:
  url: https://beholder.example.org
  secret: ...
skimmer:
  url: https://skimmer.example.org

config = StaticConfigProvider.from_yaml("vars-config.yaml")

EnvConfigProvider¶

Reads VARS_<SERVICE>_URL / VARS_<SERVICE>_SECRET environment variables — handy for CI or simple single-host deployments. Services with no *_URL set are silently omitted rather than erroring:

export VARS_ANNOSAURUS_URL=https://annosaurus.example.org
export VARS_ANNOSAURUS_SECRET=...

from vars_client.config import EnvConfigProvider

config = EnvConfigProvider()

The recognized service names are raziel, annosaurus, vampire_squid, oni, panoptes, beholder; pass services=(...) to override (e.g. to add skimmer, which isn't in the default set since it has no OpenAPI-backed client).

Writing your own¶

Any object with an async get_endpoints() -> dict[str, ServiceEndpoint] satisfies the interface — implement ConfigProvider directly if none of the built-ins fit (e.g. reading from a secrets manager).