Skip to content

xtr_dotenv.bundle

The xtr-dependency-injection bundle for xtr-dotenv.

DotenvBundle

Bases: Bundle[DotenvConfig]

Wire the dotenv commands into the container when a console is around.

load_extension

load_extension(config: DotenvConfig, services: ServiceConfigurator, builder: ContainerBuilder) -> None

Load the command module only when a console bundle is active.

Loading a command module late is the pattern the messenger bundle uses too: it keeps the console dependency out of the runtime graph for applications that do not run one, and does no I/O at build.

DotenvConfig dataclass

DotenvConfig(path: str = '%kernel.project_dir%/.env', env_key: str = 'APP_ENV', debug_key: str = 'APP_DEBUG', default_env: str = 'dev', test_envs: tuple[str, ...] = ('test',), prod_envs: tuple[str, ...] = ('prod',), debug_envs: tuple[str, ...] = ('dev', 'local', 'test'))

The one description of the dotenv cascade: entry points and commands both read it.

The bundle itself does no I/O: an application boots the environment from this object — DOTENV.boot(PROJECT_DIR) at its entry point, before the kernel is built — and the dotenv:dump and debug:dotenv commands read the same object from the container. What the cascade is lives here, and nowhere else.

Attributes:

  • path (str) –

    The base .env path. %kernel.project_dir% is resolved against the project directory by :meth:base_path, and every other parameter reference by the kernel; a relative path is taken from the project directory.

  • env_key (str) –

    The variable naming the active environment.

  • debug_key (str) –

    The variable naming debug mode.

  • default_env (str) –

    The environment the cascade settles on when the environment key names none.

  • test_envs (tuple[str, ...]) –

    Environments where the .local overlay is skipped.

  • prod_envs (tuple[str, ...]) –

    Environments declared production — what :meth:~xtr_dotenv.dotenv.Dotenv.boot_env's undeclared-environment warning and the debug:dotenv report read.

  • debug_envs (tuple[str, ...]) –

    Environments where boot_env leaves debug on by default; everywhere else it stays off.

Raises:

  • InvalidArgumentError –

    When any of path, env_key, debug_key, default_env, test_envs, prod_envs or debug_envs is empty.

base_path

base_path(project_dir: Path) -> Path

Return :attr:path resolved against project_dir.

%kernel.project_dir% — the one parameter reference a caller can resolve without a container — is substituted here, so an entry point can boot the cascade before the kernel exists; a config the kernel handed on is already resolved and passes through unchanged. Any other %...% reference is refused: only the container can resolve it, and a caller without one would read a path that does not exist.

Raises:

  • InvalidArgumentError –

    When the path still names a parameter after the project directory is substituted.

loader

loader(*, environ: MutableMapping[str, str] | None = None) -> Dotenv

Return the :class:~xtr_dotenv.dotenv.Dotenv this description builds.

The one place the keys and the environment sets become a loader: an entry point and the commands run the very same cascade.

boot

boot(project_dir: Path, *, environ: MutableMapping[str, str] | None = None) -> Dotenv

Load the cascade this description names into environ, and set debug.

The entry-point call — DOTENV.boot(PROJECT_DIR) runs before the kernel is built, so the base path is resolved against project_dir here, where no container exists to resolve it.