Ushka

API reference

ushka.core.config

Application configuration: defaults < ushka.toml < .env < environment.

Config is a process-wide singleton. Values are exposed as SECTION_KEY attributes ([app] debug becomes config.APP_DEBUG) and through config.get("app_debug").

Layers, lowest to highest priority:

  1. Built-in defaults (DEFAULTS below).
  2. ushka.toml in the application directory. It is only read: Ushka never rewrites your file.
  3. A .env file next to it (KEY=value lines), for secrets you keep out of version control.
  4. Real environment variables.

Layers 3 and 4 use the name USHKA_<SECTION>_<KEY>, e.g. USHKA_APP_DEBUG=true or USHKA_APP_SECRET_KEY=.... Values are converted to the type of the default (true/false/1/0/yes/no/on/off for booleans). Two common names are understood too: DATABASE_URL (set by most hosting platforms) and the older USHKA_DB_URL.

def parse_dotenv(text: str) -> dict[str, str]

Parses .env content: KEY=value lines, # comments, optional quotes.

export KEY=value is accepted. Variable expansion is not supported.

class Config

Process-wide application configuration (singleton).

Parameters

workdirPath | str

The application directory, where ushka.toml and .env live. Defaults to the current working directory, resolved when the first instance is created.

set_workdir(self, workdir: Path | str) -> Config

Re-roots the configuration at workdir (where ushka.toml/.env live).

The application calls this with its own directory, so a CLI that created the singleton earlier from another current directory does not decide where the app's files are.

load_from_file(self, config_path: Path | None = None) -> Config

Reads ushka.toml and .env and applies the environment.

A missing ushka.toml is fine: defaults are used. The file is never created or modified.

Returns

Config

The instance, for chaining.

get(self, key: str, default: Any = None, required: bool = False) -> Any

Returns the value of SECTION_KEY (case-insensitive).

Raises

KeyError

If the key is missing and required is true.

source_of(self, key: str) -> str

Where the value of key came from: default, ushka.toml, .env...