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:bundleslists 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¶
- Open a terminal in the directory of the application.
- If the directory
src/shop/config/packages/is absent, create it. - If the file
src/shop/config/packages/__init__.pyis 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:
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)
- Create the file
src/shop/config/packages/console.pywith 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")
- Run a command of the application:
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.
- 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")
- Add the name of the function to
__all__:
- 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.
- Add a provider with the
@whendecorator 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)
- Add
console_prodto__all__. - Read the configuration of the
devenvironment:
The steps of the output have no console_prod.
4. Read the configuration of the prod environment:
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.
- Create the directory
src/shop/config/packages/dev/. - Create the file
src/shop/config/packages/dev/__init__.pywith this content:
"""The configuration of the dev environment."""
from __future__ import annotations
__all__: list[str] = []
- 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)
- Read the configuration of the
devenvironment:
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.
- 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"),
)
- Add the variable to the
.envfile of the application:
- Run
uv run shop debug:config console. The value of the field isenv(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¶
- Read the configuration of every bundle:
- Read the configuration of one bundle:
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 |
- If
debug:configreports no provider of yours, read step 3 of the procedure again. A directory without__init__.pyholds no module that the kernel finds.
Next step¶
- Add a console command shows how to write a command.
- The application layout describes the other files of an application.
- Add a package shows how a recipe writes a configuration file for you.
- The README of xtr-dependency-injection describes parameters, placeholders and the resolution of a configuration.
- The API reference
documents
configure,whenandenv.