ConfigService

The ConfigService provides read access to a user’s application configuration through a series of ConfigHandler objects. The default config handlers provide access to both per-application configuration and configuration for all crafts. An application can provide additional config handlers for custom use cases.

The configuration items available to the configuration service are defined in the ConfigModel, which an application can extend.

Handler Order

The application’s configuration is retrieved from the handlers in the order in which they were registered to the config cervice. By default this order is:

1. AppEnvironmentHandler gets app-specific environment variables.

2. CraftEnvironmentHandler gets general CRAFT_* environment variables.

3. Extra handlers (if any) provided by the application.

4. SnapConfigHandler (if running as a snap) gets a snap configuration option.

5. DefaultConfigHandler gets the default value, if there is one.

A handler raises a KeyError if it doesn’t have a relevant config option set. If no handlers return a value when getting a configuration option, a KeyError is raised to signify that no configuration could be found.

Configuration model

Each application has a configuration model, by default craft_application.ConfigModel, which is provided to the application by the ConfigModel attribute of the app’s AppMetadata instance. An app may extend its fields from those in the configuration model.

class craft_application.ConfigModel

The configuration model for the app.

This model informs the config service what configuration items are available to the application.

build_environment: str | None

The build environment to use for this app.

Defaults to unset, can also be set as host to enable destructive mode.

build_for: str | None

The target architecture for which to build.

debug: bool

Whether the application is in debug mode.

idle_mins: pydantic.NonNegativeInt | None

How long the container used by lifecycle steps remains active after the app exits.

If unset, this defaults to exiting synchronously before the app exits.

launchpad_instance: str

The Launchpad instance to use for remote builds.

lxd_remote: str

The LXD remote to use if using the LXD provider.

max_parallel_build_count: int

The maximum parallel build count to send to Craft Parts.

If this value is set but parallel_build_count is not, the smaller of max_parallel_build_count or the number of processor cores available to the app process is used. If unset, the number of processor cores available is used.

parallel_build_count: int

The parallel build count to send to Craft Parts.

Supersedes any value set in max_parallel_build_count.

platform: str | None

The platform for which to build.

verbosity_level: EmitterMode

The verbosity level for the app.

API documentation

class craft_application.services.config.ConfigHandler

The abstract class that is the parent of all configuration handlers.

__init__(app: AppMetadata) → None

Create the configuration handler with the relevant application metadata.

abstract get_raw(item: str) → Any

Get the string value for a configuration item.

Parameters:

item – the name of the configuration item.

Returns:

The raw value of the item.

Raises:

KeyError if the item cannot be found.

final class craft_application.services.config.AppEnvironmentHandler

Configuration handler to get values from app-specific environment variables.

Environment variables used for this are prefixed with a fully upper-case form of the application name. For example, TESTCRAFT_DEBUG.

__init__(app: AppMetadata) → None

Create the configuration handler with the relevant application metadata.

get_raw(item: str) → str

Get the string value for a configuration item.

Parameters:

item – the name of the configuration item.

Returns:

The raw value of the item.

Raises:

KeyError if the item cannot be found.

final class craft_application.services.config.CraftEnvironmentHandler

Configuration handler to get values from CRAFT environment variables.

__init__(app: AppMetadata) → None

Create the configuration handler with the relevant application metadata.

get_raw(item: str) → str

Get the string value for a configuration item.

Parameters:

item – the name of the configuration item.

Returns:

The raw value of the item.

Raises:

KeyError if the item cannot be found.

class craft_application.services.config.SnapConfigHandler

Configuration handler that gets values from snapd.

Snap configuration values are set with kebab case, so the verbosity_level configuration value can be set to verbose using the command snap set <snap-name> verbosity-level=verbose

__init__(app: AppMetadata) → None

Create the configuration handler with the relevant application metadata.

get_raw(item: str) → Any

Get the string value for a configuration item.

Parameters:

item – the name of the configuration item.

Returns:

The raw value of the item.

Raises:

KeyError if the item cannot be found.

final class craft_application.services.config.DefaultConfigHandler

Configuration handler for getting default values.

__init__(app: AppMetadata) → None

Create the configuration handler with the relevant application metadata.

get_raw(item: str) → Any

Get the string value for a configuration item.

Parameters:

item – the name of the configuration item.

Returns:

The raw value of the item.

Raises:

KeyError if the item cannot be found.

class craft_application.services.config.ConfigService

Application-wide configuration access.

__init__(app: application.AppMetadata, services: ServiceFactory, *, extra_handlers: Iterable[type[ConfigHandler]] = ()) → None

setup() → None

Service-specific setup to perform.

Child classes should always call super().setup().

get(item: str) → Any

Get the given configuration item.

_convert_type(value: str, field_type: type[T]) → T

Convert the value to the appropriate type.

get_all() → dict[str, Any]

Get a dictionary of the complete configuration per the ConfigModel.

Configuration items that are unset but have no default value are not included in the resulting mapping.