`ProjectService`¶

The ProjectService is a service for handling access to the project.

Project loading¶

The Project service handles loading, validating and rendering the project file to a Project model. The most common use case is to render the project as though running on the host’s architecture, for the targeted platform. However, it can also render a project as though it is running on any architecture and building for any platform or architecture.

The rendering process follows these steps:

Configure the ProjectService¶

The first step is for the Application to configure the project service. It:

Set the project directory location. This is done by passing a directory on instantiation.
Set any platform and build_for hints. This is done using the configure() method.

Find the project file¶

Once a project directory is declared, ProjectService.resolve_project_file_path() finds the path to the actual project file. By default, this is simply <app name>.yaml in the project directory. However, applications may override this if they need to search for the project file at other locations.

Parse the project file YAML¶

Once the project file is found, it is parsed as a YAML file. The file has additional requirements beyond being a valid YAML document:

It must contain only a single document.
Its top level must be a map whose keys are strings.

Validate grammar¶

In this step, any user-added grammar is validated using Craft Grammar. No grammar is processed yet.

Perform application-specific transforms¶

At this step, any application-specific transformations of the document are applied by the ProjectService._app_preprocess_project() method. By default, nothing happens here.

The project dict at this state is available using the ProjectService._preprocess() protected method. _preprocess() calls _app_preprocess_project() as the last step of processing before returning the pre-processed project dict.

Expand the environment¶

Next, craft_parts.expand_environment() is called to replace global parts variables with their expected values.

Process parts grammar¶

At this point, grammar is processed for each part. This includes parts added during the application-specific transforms step, meaning that transforms may add grammar-aware syntax if needed.

Validate the Pydantic model¶

A Pydantic model of the project is loaded, validating more thoroughly.

Check mandatory adoptable fields¶

The final step in loading the project is checking mandatory adoptable fields. If the adopt-info key is not set on the project, any mandatory fields that are presented as optional because of their adoptability are checked to ensure they are set.

API documentation¶

class craft_application.services.project.ProjectService(app: AppMetadata, services: ServiceFactory, *, project_dir: pathlib.Path)¶

A service for handling access to the project.

static _app_preprocess_project(project: dict[str, Any], *, build_on: str, build_for: str, platform: str) → None¶

Run any application-specific pre-processing on the project, in-place.

This includes any application-specific transformations on a project’s raw data structure before it gets rendered as a pydantic model. Some examples of processing to do here include:

Applying extensions
Adding “hidden” app-specific parts
Processing grammar for keys other than parts

_app_render_legacy_platforms() → dict[str, PlatformDict]¶

Application-specific rendering function if no platforms are declared.

This method is intended to be overridden by an application-specific service if the root project has no platforms key. In this case, it should return a dictionary structured the same way as the platforms key in a project for use in that project. This dictionary is less strict than what is expected in the project file’s platforms key. For example, the build-for key for each platform MAY contain multiple targets.

final _preprocess(*, build_for: str, build_on: str, platform: str) → dict[str, Any]¶

Preprocess the project for the given build-on, build-for and platform.

This method provides a project dict that has gone through any app-specific pre-processing and has had its grammar validated, has not had environment expansion or parts grammar applied.

This method is for internal use only, such as for getting partitions.

Parameters:

build_for – The target architecture of the build.
platform – The name of the target platform.
build_on – The host architecture the build happens on.

Returns:

A dict containing a pre-processed project.

final configure(*, platform: str | None, build_for: str | None) → None¶

Configure the prime project to render.

This method configures the settings of our prime project rendering - that is, the one that will be used for the project that is cached.

final get() → models.Project¶

Get the rendered project.

Returns:: The project model.
Raises:: RuntimeError if the project has not been configured.

get_partitions_for(*, platform: str, build_for: str, build_on: DebianArchitecture) → list[str] | None¶

Get the partitions for a destination of this project.

The default implementation gets partitions for an application that does not have partitions. Applications that will enable partitions must override this method.

final get_platforms() → dict[str, PlatformDict]¶

Get the platforms definition for the project.

The platforms definition must always be immediately able to be rendered from the raw YAML. This means that platforms cannot contain grammar, they cannot be defined by extensions, etc.

final get_raw() → dict[str, Any]¶: Get the raw project data structure.

property is_configured: bool¶: Whether the project has already been rendered.

property partitions: list[str] | None¶: The partitions for the prime project.

final render_for(*, build_for: str, build_on: str, platform: str) → models.Project¶

Render the project for a specific combination of archs/platforms..

This method does not guarantee that the project will be buildable with the given parameters or that the parameters even correspond to something a build plan would generate.

Parameters:

build_for – The target architecture of the build.
platform – The name of the target platform.
build_on – The host architecture the build happens on.

Returns:

A Project model containing the project rendered as above.

resolve_project_file_path() → Path¶

Get the path to the project file from the root project directory.

The default behaviour is to find the project file directly in the directory based on the app name or raise an exception. However, an application may override this if necessary. For example, Snapcraft needs to override this to check other possible directories.

Parameters:: project_dir – The base project directory to search.
Returns:: The path to the extant project file
Raises:: ProjectFileMissingError if the project file could not be found.

update_project_environment(info: ProjectInfo) → None¶: Update a ProjectInfo’s global environment.