Skip to content

Configure a bundle

Every bundle works with its default values. To change a value, the application adds a configuration file for that bundle. The file holds a function with the @configure decorator. The function returns the configuration object of the bundle. The configuration of an application is Python code, so a type checker reads it.

This guide configures the console bundle of the shop application.

Before you start

  • You have an application with the name shop. If not, create an application.
  • The bundle that you want to configure is active. uv run shop debug:bundles lists every active bundle.
  • You know the configuration type of the bundle. The README of the package names the type under Use in an application.

Procedure

  1. Open a terminal in the directory of the application.
  2. If the directory src/shop/config/packages/ is absent, create it.
  3. If the file src/shop/config/packages/__init__.py is absent, create it with this content:
"""One configuration file for each bundle."""

from __future__ import annotations

__all__: list[str] = []

The kernel scans an importable package only. Without this file the kernel finds no configuration file. 4. Read the configuration of the bundle as it is now:

uv run shop debug:config console

The output names each step of the resolution and the value after the last step:

console
-------

default
ConsoleConfig(name=None, version=None, description=None, catch_exceptions=True)
  1. Create the file src/shop/config/packages/console.py with a function that returns the configuration type of the bundle:
"""The console: the name and the version that the help header shows."""

from __future__ import annotations

from xtr_console.bundle import ConsoleConfig
from xtr_dependency_injection import configure

__all__ = ["console"]


@configure
def console() -> ConsoleConfig:
    """The name and the version of the application."""
    return ConsoleConfig(name="shop", version="1.0.0")
  1. Run a command of the application:
uv run shop list

The first line of the output is now shop 1.0.0.

Note

A function without a parameter is a base provider. Its value replaces the default value of the bundle. One bundle permits one base provider in the application.

Change one field and keep the others

A function with one parameter is a transform provider. The kernel gives it the value of the step before, and the function returns a new value. Use dataclasses.replace to change one field of a frozen dataclass.

  1. Add a second function to src/shop/config/packages/console.py:
from dataclasses import replace


@configure
def console_description(config: ConsoleConfig) -> ConsoleConfig:
    """The line under the name in the help header."""
    return replace(config, description="The console of the shop")
  1. Add the name of the function to __all__:
__all__ = ["console", "console_description"]
  1. Run uv run shop list. The third line of the output is the description.

Configure one environment only

The kernel builds for one environment. It reads the name of the environment from the APP_ENV variable, and dev is the default. The @when and @when_not decorators limit a provider to the environments that you name.

  1. Add a provider with the @when decorator under @configure:
from xtr_dependency_injection import configure, when


@configure
@when("prod")
def console_prod(config: ConsoleConfig) -> ConsoleConfig:
    """In `prod`, let an exception leave the command."""
    return replace(config, catch_exceptions=False)
  1. Add console_prod to __all__.
  2. Read the configuration of the dev environment:
uv run shop debug:config console

The steps of the output have no console_prod. 4. Read the configuration of the prod environment:

APP_ENV=prod uv run shop debug:config console

The last step of the output is now transform ...:console_prod.

Note

The allowed_envs argument of the kernel lists the environments that the application permits. The kernel refuses every other name.

Put the configuration of one environment in a directory

A directory in src/shop/config/packages/ with the name of an environment is an environment directory. The kernel imports its files only for that environment. It imports them after the other configuration files, so their providers replace the providers of the other files. Use an environment directory for a bundle that is active in dev only. A production installation does not have the package of that bundle. The kernel does not import the directory in production.

  1. Create the directory src/shop/config/packages/dev/.
  2. Create the file src/shop/config/packages/dev/__init__.py with this content:
"""The configuration of the dev environment."""

from __future__ import annotations

__all__: list[str] = []
  1. Create the file src/shop/config/packages/dev/maker.py:
"""The makers write classes that are not final."""

from __future__ import annotations

from xtr_dependency_injection import configure
from xtr_maker.bundle import MakerConfig

__all__ = ["maker"]


@configure
def maker() -> MakerConfig:
    """Write classes without the `@final` decorator."""
    return MakerConfig(final_classes=False)
  1. Read the configuration of the dev environment:
uv run shop debug:config maker

The output shows the step base shop.config.packages.dev.maker:maker.

Note

The name of each environment directory must be in allowed_envs. If the name is not in allowed_envs, the kernel stops with UnknownEnvironmentFolderError.

Read a value from an environment variable

env() returns a placeholder, not a value. The container reads the variable when it builds a service that needs the value. Therefore the container compiles on a machine that has no value for the variable.

  1. Use env() as the value of a field:
from xtr_dependency_injection import configure, env


@configure
def console_from_env(config: ConsoleConfig) -> ConsoleConfig:
    """The description comes from `SHOP_DESCRIPTION`."""
    return replace(
        config,
        description=env("SHOP_DESCRIPTION", default="The console of the shop"),
    )
  1. Add the variable to the .env file of the application:
SHOP_DESCRIPTION=The console of the shop, in development
  1. Run uv run shop debug:config console. The value of the field is env(SHOP_DESCRIPTION), not the text of the variable.

The second argument of env() converts the text of the variable:

Written The field receives
env("SMTP_HOST") the text of the variable
env("SMTP_PORT", int) an integer, or an error for other text
env("MAIL_DEBUG", bool) true for 1, true, yes, on or a number that is not zero
env("SMTP_PORT", int, default=25) 25 when the variable has no value
env("json:file:OPTIONS_FILE") the JSON content of the file that the variable names

Warning

Keep a password, a key or another secret in .env.local, not in .env. Git tracks .env, and .gitignore excludes .env.local.

Check the configuration

  1. Read the configuration of every bundle:
uv run shop debug:config
  1. Read the configuration of one bundle:
uv run shop debug:config console

The line under the name of the bundle shows the steps of the resolution. The kernel resolves the value in this sequence:

Step Source
1 the default value of the configuration type
2 the base provider of the application, and the one in the environment directory before the other one
3 a field that another bundle forwards with AliasOf
4 the changes of other bundles, in the sequence of the bundles
5 the transform providers of the application, with the providers of the environment directory last
  1. If debug:config reports no provider of yours, read step 3 of the procedure again. A directory without __init__.py holds no module that the kernel finds.

Next step