Authentication & Configuration#

saia_python.load_api_key(path: str | Path | None = None) → str[source]#

Discover and return the SAIA API key.

Resolution order:

  1. path argument — explicit file path (.saia_api or .env format)

  2. SAIA_API_KEY environment variable

  3. .saia_api in the current working directory

  4. .saia_api in the home directory

  5. .env in the current working directory (looks for SAIA_API_KEY=...)

  6. .env in the home directory

Parameters:

path – Optional explicit path to a .saia_api or .env file.

Returns:

The API key string.

Raises:
saia_python.load_arcana_ids() → dict[str, str][source]#

Discover ARCANA IDs from .env, config.toml, and environment variables.

All sources are merged. The "default" key is set by the highest-priority source that provides a single ARCANA ID:

  1. SAIA_ARCANA_ID in .env or environment variable

  2. [saia.arcana] default in config.toml

  3. First element of [saia.arcana] ids in config.toml

  4. First SAIA_ARCANA_ID_XX key (by file/env order, not sorted)

Additional IDs from config.toml arrays and numbered env vars are included under their respective labels.

Returns:

  • "default" — the default arcana ID (if any source provides one)

  • "0", "1", … — from [saia.arcana] ids array

  • Numbered suffixes (e.g. "01") — from SAIA_ARCANA_ID_01 env vars

Returns an empty dict if no ARCANA IDs are found.

Return type:

A dict mapping label to arcana ID string

saia_python.load_config() → dict[source]#

Load the full config.toml as a dict.

Searches the current working directory, then the home directory.

Returns:

The parsed TOML dict, or an empty dict if not found.

saia_python.load_username() → str | None[source]#

Discover the SAIA username from environment, .env, or config.toml.

Resolution order:

  1. SAIA_USERNAME environment variable

  2. SAIA_USERNAME in .env

  3. [saia] username in config.toml

Returns:

The username string, or None if not configured.

saia_python.resolve_base_url(explicit: str | None = None) → str[source]#

Resolve the SAIA API base URL.

Resolution order: explicit parameter > [saia] base_url in config.toml > the hardcoded DEFAULT_BASE_URL.

Parameters:

explicit – An explicit URL. If provided, returned as-is (trailing slash stripped).

Returns:

The resolved base URL string.