Application

The Application is the entry point to any Craft Application. Most apps will only need to configure their own AppMetadata.

AppMetadata

final class craft_application.AppMetadata

Metadata about a craft application.

class 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.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

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.

ProjectClass

alias of Project

__init__(name: str, summary: str | None = None, docs_url: str | None = None, artifact_type: ~typing.Annotated[str, typing.Annotated[~_StrType, Predicate(str.isascii)], typing.Annotated[~_StrType, Predicate(str.islower)]] = 'artifact', source_ignore_patterns: list[str] = <factory>, project_variables: list[str] = <factory>, mandatory_adoptable_fields: list[str] = <factory>, ConfigModel: type[~craft_application._config.ConfigModel] = <class 'craft_application._config.ConfigModel'>, ProjectClass: type[~craft_application.models.project.Project] = <class 'craft_application.models.project.Project'>, supports_multi_base: bool = False, always_repack: bool = True, check_supported_base: bool = False, enable_for_grammar: bool = False) → None

artifact_type: Annotated[str, Annotated[_StrType, Predicate(str.isascii)], Annotated[_StrType, Predicate(str.islower)]] = 'artifact'

The name to refer to the output artifact for this app.

This gets used in messages and should be an all lower-case single-word value, like snap or rock. Defaults to artifact.

check_supported_base: bool = False

Whether this application allows building on unsupported bases.

When True, the app can build on a base even if it is end-of-life. Relevant apt repositories will be migrated to old-releases.ubuntu.com. Currently only supports EOL Ubuntu releases.

When False, the repositories are not migrated and base support is not checked.

docs_url: str | None = None

The root URL for the app’s documentation.

enable_for_grammar: bool = False

Whether this application supports the ‘for’ variant of advanced grammar.

mandatory_adoptable_fields: list[str]

Fields that must either be in the YAML file or adopted with craftctl set.

name: str

The name of the application.

project_variables: list[str]

Fields that are adoptable using craftctl set.

summary: str | None = None

A short summary of the application.

property versioned_docs_url: str | None

The docs_url with the proper app version.

Application

class craft_application.Application

Craft Application Builder.

Variables:

• app – Metadata about this application

• services – A ServiceFactory for this application

Parameters:

extra_loggers – Logger names to integrate with craft-cli beyond the defaults.

__init__(app: AppMetadata, services: service_factory.ServiceFactory, *, extra_loggers: Iterable[str] = ()) → None

add_command_group(name: str, commands: Sequence[type[craft_cli.BaseCommand]], *, ordered: bool = False) → None

Add a CommandGroup to the Application.

add_global_argument(argument: GlobalArgument) → None

Add a global argument to the Application.

property app_config: dict[str, Any]

Get the configuration passed to dispatcher.load_command().

This can generally be left as-is. It’s strongly recommended that if you are overriding it, you begin with config = super().app_config and update the dictionary from there.

property cache_dir: Path

Get the directory for caching any data.

property command_groups: list[CommandGroup]

Return command groups.

Merges command groups provided by the application with craft-application’s default commands.

If the application and craft-application provide a command with the same name in the same group, the application’s command is used.

Note that a command with the same name cannot exist in multiple groups.

configure(global_args: dict[str, Any]) → None

Configure the application using any global arguments.

get_arg_or_config(parsed_args: argparse.Namespace, item: str) → Any

Get a configuration option that could be overridden by a command argument.

Parameters:

• parsed_args – The argparse Namespace to check.

• item – the name of the namespace or config item.

Returns:

the requested value.

get_project(*, platform: str | None = None, build_for: str | None = None) → Project

Get the project model.

This only resolves and renders the project the first time it gets run. After that, it merely uses a cached project model.

Parameters:

• platform – the platform name listed in the build plan.

• build_for – the architecture to build this project for.

Returns:

A transformed, loaded project model.

is_managed() → bool

Shortcut to tell whether we’re running in managed mode.

property log_path: Path | None

Get the path to this process’s log file, if any.

property project: Project

Get this application’s Project metadata.

register_plugins(plugins: dict[str, PluginType]) → None

Register plugins for this application.

run() → int

Bootstrap and run the application.

run_managed(platform: str | None, build_for: str | None) → None

Run the application in a managed instance.