Project configuration

Utilities to read and process configuration for a project.

class maykin_common.config.DocumentationParams(help_text: str = '', group: str | None = None, add_to_docs: bool = True, auto_display_default: bool = True)

Dataclass to define the parameters for documentation generation for environment variables loaded via the maykin_common.config.config() helper

add_to_docs: bool: Indicates whether this environment variable should be displayed in the documentation.

auto_display_default: bool: Indicates whether the documentation directives should display the specified default. Can be set to False if you want to manually specify a default.

group: str | None: The name of the group this environment variable belongs to. Defaults to “Required” or “Optional” depending on whether a default is passed.

help_text: str: The description of this environment variable.

maykin_common.config.config(option: str, *, documentation: DocumentationParams | None = None) → str

maykin_common.config.config(option: str, *, default: str, split: Literal[True], cast: Callable[[str], T] | Undefined = undefined, documentation: DocumentationParams | None = None) → Never

maykin_common.config.config(option: str, *, default: Sequence[T], split: Literal[True], cast: Callable[[str], T] | Undefined = undefined, documentation: DocumentationParams | None = None) → list[T]

maykin_common.config.config(option: str, *, default: Undefined = undefined, split: Literal[True], cast: Undefined = undefined, documentation: DocumentationParams | None = None) → list[str]

maykin_common.config.config(option: str, *, default: Undefined = undefined, split: Literal[True], cast: Callable[[str], T], documentation: DocumentationParams | None = None) → list[T]

maykin_common.config.config(option: str, *, default: None, documentation: DocumentationParams | None = None) → str | None

maykin_common.config.config(option: str, *, default: T | Undefined = undefined, documentation: DocumentationParams | None = None) → T

maykin_common.config.config(option: str, *, default: None, cast: Callable, documentation: DocumentationParams | None = None) → Never

maykin_common.config.config(option: str, *, default: str | Undefined = undefined, cast: Callable[[str], T], documentation: DocumentationParams | None = None) → T

Pull a config parameter from the environment.

Read the config variable option. If it’s optional, use the default value.

If not cast parameter is provided, then the cast is derived from the default type when a default is provided. However, when you provide a cast parameter explicitly, you must provide any default as a string as it will be passed to the provided cast callback.

Note that default=None does not mean there’s no default; omitting the default kwarg entirely means there’s no default.

Pass split=True to split the comma-separated input into a list. If a default is provided, it must be a list.

Examples:

>>> SECRET_KEY: str = config("SECRET_KEY")
>>> DB_NAME: str = config("DB_NAME", default="my-awesome-project")
>>> DB_PORT: int = config("DB_PORT", default=5432")
>>> SESSION_COOKIE_DOMAIN: str | None = config(
...     "SESSION_COOKIE_DOMAIN", default=None
... )
>>> ALLOWED_HOSTS: list[str] = config("ALLOWED_HOSTS", split=True, default=[])
>>> CUSTOM = config(
...     "CUSTOM",
...     default="123",
...     cast=lambda v: int(v) if v is not None else None,
... )  # typed as int | None

The documentation parameter is available to generate documentation for environment variables with Sphinx directives provided by this library:

Parameters:: documentation – See maykin_common.config.DocumentationParams