Skip to content

Models

Typed Pydantic models that represent the human-managed configuration structure. All models are exported from the top-level oa_configurator package.

StackConfig

Root configuration object. Also the entry point for programmatic construction via StackConfig.for_session().

Bases: BaseModel

Root model for ~/.config/omop/config.toml.

Holds the entire OMOP stack configuration in one object: named database connections, logical resources, per-package tool sections, and environment profiles. Loaded from disk by :func:~oa_configurator.loader.load_stack_config; constructed in memory via :meth:for_session for tests and scripts (no file I/O).

loaded_path property 

loaded_path: Path | None

Path of the TOML file this config was loaded from, if any.

bind_loaded_path 

bind_loaded_path(path: Path) -> None

Record the path of the TOML file this config was loaded from.

database_names 

database_names() -> tuple[str, ...]

Return a sorted tuple of configured database names.

for_session classmethod 

for_session(
    *,
    databases: dict[str, DatabaseConfig] | None = None,
    resources: dict[str, ResourceConfig] | None = None,
    tools: dict[str, ToolConfig] | None = None,
    profiles: dict[str, ProfileOverrideConfig]
    | None = None,
    active_profile: str | None = None,
    resource_aliases: dict[str, str] | None = None,
) -> StackConfig

Build a config in memory without a TOML file.

Intended for tests and scripts. Cross-references are validated at construction time, same as for file-loaded configs.

Notes

Pydantic still coerces a raw dict (e.g. one shaped like a parsed TOML table) into the corresponding model at validation time, so passing plain dicts keeps working at runtime. The parameter types above are the strict, intended shape; prefer constructing ResourceConfig, ToolConfig, and ProfileOverrideConfig instances directly so a renamed field is caught by the type checker instead of only at validation time.

profile_names 

profile_names() -> tuple[str, ...]

Return a sorted tuple of configured profile names.

resource_names 

resource_names() -> tuple[str, ...]

Return a sorted tuple of configured resource names.

tool_names 

tool_names() -> tuple[str, ...]

Return a sorted tuple of configured tool names.

validate_references 

validate_references() -> StackConfig

Ensure all named cross-references point at configured objects.

DatabaseConfig

Bases: BaseModel

Complete specification of one named database: server address, credentials, and target database.

Referenced by :attr:ResourceConfig.database and :attr:ResourceConfig.vocab_database. Each entry under [databases] in config.toml maps to one instance of this model.

Passwords are stored in plaintext for now; secret management support is planned for a future release.

build_url 

build_url() -> str

Build the full connection URL, including the plaintext password.

Returns

str SQLAlchemy-compatible connection URL. For SQLite, returns sqlite:///<database> (or sqlite:///:memory: when database is not set).

safe_url 

safe_url() -> str

Build the connection URL with the password redacted.

Safe for logging and display. Identical to build_url() for SQLite connections, which carry no password.

Returns

str Connection URL with *** substituted for the password field.

to_env_pairs 

to_env_pairs(prefix: str) -> list[str]

Return PREFIX_FIELD=value strings for each non-None field.

Used by :func:~oa_configurator.io.write_env_file to emit env vars for Docker Compose env_file:. Field names are uppercased directly (e.g. host → PREFIX_HOST), so adding a new field here automatically appears in the export without touching io.py. Config-only flags (read_only, test_only) are excluded — they are not database connection parameters.

ResourceConfig

Bases: BaseModel

Maps the OMOP logical roles (CDM, vocab, results) to named databases and schema names.

The unit that consuming packages configure once and reference by name. Most packages only need a single cdm_db resource. Each entry under [resources] in config.toml maps to one instance of this model.

ToolConfig

Bases: BaseModel

Per-package section in config.toml ([tools.<name>]).

default_resource names which resource this package reads from. extra holds the package-specific typed fields declared on the package's :class:~oa_configurator.PackageConfigBase subclass.

ProfileOverrideConfig

Bases: BaseModel

Named environment overlay ([profiles.<name>] in config.toml).

Entries replace base entries with the same name when the profile is active. Anything not mentioned in the profile is inherited from the base config unchanged. Useful for switching between local-dev and production databases without editing the base config.