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.

build_on: str | None

The architecture on which to build.

This is ignored in destructive mode and is only used for launching a provider. The provider is instructed about the requested architecture. If that architecture cannot run with the current system configuration, it will raise an error.

debug: bool

Whether the application is in debug mode.

experimental_monorepo: bool

Enable monorepo support, mounting the git working tree root as the build root.

When True and the app sets allow_git_build_root, the git root is mounted in the managed instance instead of the project directory, giving the build access to shared code outside the project directory.

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, enable_pro_support: bool = False, allow_git_build_root: bool = False) → None

allow_git_build_root: bool = False

Whether to allow mounting the git working tree root as the build root.

When True and the user enables the experimental_monorepo config option, the git root is mounted as /root/project in the managed instance rather than the project directory. The working directory inside the instance is adjusted to the project’s subdirectory within the git root, giving the build access to code outside the project directory (e.g. shared libraries in a monorepo).

Has no effect when the project directory is not inside a git repository, or when the project directory is the git root itself.

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.

enable_pro_support: bool = False

Whether this application supports Ubuntu Pro services.

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.

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.

run() → int

Bootstrap and run the application.