craft-application 6.2.0__tar.gz → 6.2.2__tar.gz

{craft_application-6.2.0 → craft_application-6.2.2}/.pre-commit-config.yaml

@@ -13,7 +13,7 @@ repos:
       - id: fix-byte-order-marker
       - id: mixed-line-ending
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.15.0"
+    rev: "v0.15.4"
     hooks:
       # Run the linter
       - id: ruff

{craft_application-6.2.0/craft_application.egg-info → craft_application-6.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: craft-application
-Version: 6.2.0
+Version: 6.2.2
 Summary: A framework for *craft applications.
 License:                    GNU LESSER GENERAL PUBLIC LICENSE
                                Version 3, 29 June 2007

craft_application-6.2.2/craft_application/_config.py

@@ -0,0 +1,68 @@
+# This file is part of craft-application.
+#
+# Copyright 2024 Canonical Ltd.
+#
+# This program is free software: you can redistribute it and/or modify it
+# under the terms of the GNU Lesser General Public License version 3, as
+# published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranties of MERCHANTABILITY,
+# SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR PURPOSE.
+# See the GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+"""Configuration model for craft applications."""
+
+from __future__ import annotations
+
+import pydantic
+from craft_cli import EmitterMode
+
+
+class ConfigModel(pydantic.BaseModel):
+    """The configuration model for the app.
+
+    This model informs the config service what configuration items are available
+    to the application.
+    """
+
+    verbosity_level: EmitterMode = EmitterMode.BRIEF
+    """The verbosity level for the app."""
+    debug: bool = False
+    """Whether the application is in debug mode."""
+    build_environment: str | None = None
+    """The build environment to use for this app.
+
+    Defaults to unset, can also be set as ``host`` to enable destructive mode.
+    """
+    secrets: str
+
+    platform: str | None = None
+    """The platform for which to build."""
+    build_for: str | None = None
+    """The target architecture for which to build."""
+
+    parallel_build_count: int
+    """The parallel build count to send to Craft Parts.
+
+    Supersedes any value set in ``max_parallel_build_count``.
+    """
+    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.
+    """
+    lxd_remote: str = "local"
+    """The LXD remote to use if using the LXD provider."""
+    launchpad_instance: str = "production"
+    """The Launchpad instance to use for remote builds."""
+
+    idle_mins: pydantic.NonNegativeInt | None = 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.
+    """

{craft_application-6.2.0 → craft_application-6.2.2}/craft_application/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '6.2.0'
-__version_tuple__ = version_tuple = (6, 2, 0)
+__version__ = version = '6.2.2'
+__version_tuple__ = version_tuple = (6, 2, 2)
 
-__commit_id__ = commit_id = 'gf4a4d28'
+__commit_id__ = commit_id = 'g421a445'

{craft_application-6.2.0 → craft_application-6.2.2}/craft_application/application.py

@@ -32,6 +32,7 @@ from typing import TYPE_CHECKING, Annotated, Any, Literal, cast, final
 
 import annotated_types
 import craft_cli
+import craft_platforms
 import craft_providers
 from platformdirs import user_cache_path
 
@@ -573,7 +574,8 @@ class Application:
 
     def _register_default_plugins(self) -> None:
         """Register per application plugins when initializing."""
-        self.register_plugins(self._get_app_plugins())
+        with warnings.catch_warnings():
+            self.register_plugins(self._get_app_plugins())
 
     def _pre_run(self, dispatcher: craft_cli.Dispatcher) -> None:
         """Do any final setup before running the command.
@@ -775,7 +777,30 @@ class Application:
     def _enable_craft_parts_features(self) -> None:
         """Enable any specific craft-parts Feature that the application will need."""
 
+    @final
+    def _set_plugin_group(self) -> None:
+        """Set the plugin group from the lifecycle service.
+
+        If no plugin group is provided or an error occurs while determining
+        the build info, no plugin group is registered.
+        """
+        try:
+            build_plan = self.services.get("build_plan").plan()
+        except (craft_cli.CraftError, craft_platforms.CraftPlatformsError):
+            # We can do this here because when we start the lifecycle
+            # we actually exit the app if there's an error.
+            craft_cli.emit.debug("No plugin group registered due to error.")
+            return
+        group = self.services.get_class("lifecycle").get_plugin_group(build_plan[0])
+
+        # We don't need to import this unless we have a group to set.
+        from craft_parts.plugins import set_plugin_group  # noqa: PLC0415
+
+        if group:
+            set_plugin_group(group)
+
     def _initialize_craft_parts(self) -> None:
         """Perform craft-parts-specific initialization, like features and plugins."""
         self._enable_craft_parts_features()
         self._register_default_plugins()
+        self._set_plugin_group()

{craft_application-6.2.0 → craft_application-6.2.2}/craft_application/services/buildplan.py

@@ -95,7 +95,7 @@ class BuildPlanService(base.AppService):
         """Filter the build plan.
 
         This method filters the given build plan based on the provided filter values.
-        An application may override this if in needs to filter the build plan in
+        An application may override this if it needs to filter the build plan in
         non-default ways. It exists to allow applications to only change the build plan
         filter and should only be used by :meth:`get_build_plan` except in testing.
 

{craft_application-6.2.0 → craft_application-6.2.2}/craft_application/services/config.py

@@ -42,9 +42,10 @@ T = TypeVar("T")
 
 
 class ConfigHandler(abc.ABC):
-    """An abstract class for configuration handlers."""
+    """The abstract class that is the parent of all configuration handlers."""
 
     def __init__(self, app: application.AppMetadata) -> None:
+        """Create the configuration handler with the relevant application metadata."""
         self._app = app
 
     @abc.abstractmethod
@@ -59,7 +60,11 @@ class ConfigHandler(abc.ABC):
 
 @final
 class AppEnvironmentHandler(ConfigHandler):
-    """Configuration handler to get values from app-specific environment variables."""
+    """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``.
+    """
 
     def __init__(self, app: application.AppMetadata) -> None:
         super().__init__(app)
@@ -89,7 +94,12 @@ class CraftEnvironmentHandler(ConfigHandler):
 
 
 class SnapConfigHandler(ConfigHandler):
-    """Configuration handler that gets values from snap."""
+    """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``
+    """
 
     def __init__(self, app: application.AppMetadata) -> None:
         super().__init__(app)

{craft_application-6.2.0 → craft_application-6.2.2}/craft_application/services/package.py

@@ -32,7 +32,7 @@ if TYPE_CHECKING:  # pragma: no cover
 
 
 class PackageService(base.AppService):
-    """Business logic for creating packages."""
+    """The business logic for creating packages."""
 
     def __init__(self, app: AppMetadata, services: ServiceFactory) -> None:
         super().__init__(app, services)
@@ -40,11 +40,14 @@ class PackageService(base.AppService):
 
     @abc.abstractmethod
     def pack(self, prime_dir: pathlib.Path, dest: pathlib.Path) -> list[pathlib.Path]:
-        """Create one or more packages as appropriate.
+        """Create one or more packages.
 
-        :param prime_dir: Directory path to the prime directory.
+        :param prime_dir: Directory path to the default prime directory.
+            **DEPRECATED** in favour of retrieving this information from the
+            :attr:`LifecycleService
+            <craft_application.services.lifecycle.LifecycleService.project_info>`.
         :param dest: Directory into which to write the package(s).
-        :returns: A list of paths to created packages.
+        :returns: A list of paths to the created packages.
         """
 
     # This was implemented as a separate property to allow applications to

{craft_application-6.2.0 → craft_application-6.2.2}/craft_application/services/service_factory.py

@@ -183,7 +183,7 @@ class ServiceFactory:
 
         This works like ``dict.update()``, overwriting already-set values.
 
-        :param service: the name of the service (e.g. "lifecycle")
+        :param service: the name of the service. For example,  "lifecycle".
         :param kwargs: keyword arguments to set.
         """
         self._service_kwargs.setdefault(service, {}).update(kwargs)
@@ -304,11 +304,11 @@ class ServiceFactory:
     def get(self, service: str) -> services.AppService:
         """Get a service by name.
 
-        :param service: the name of the service (e.g. "config")
-        :returns: An instantiated and set up service class.
-
         Also caches the service so as to provide a single service instance per
-        ServiceFactory.
+        ``ServiceFactory``.
+
+        :param service: the name of the service. For example, "config".
+        :returns: An instantiated and setup service class.
         """
         if service in self._services:
             return self._services[service]

{craft_application-6.2.0 → craft_application-6.2.2/craft_application.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: craft-application
-Version: 6.2.0
+Version: 6.2.2
 Summary: A framework for *craft applications.
 License:                    GNU LESSER GENERAL PUBLIC LICENSE
                                Version 3, 29 June 2007

{craft_application-6.2.0 → craft_application-6.2.2}/craft_application.egg-info/SOURCES.txt

@@ -121,6 +121,7 @@ docs/common/craft-application/how-to-guides/build-remotely.rst
 docs/common/craft-application/how-to-guides/reuse-packages-between-builds.rst
 docs/common/craft-application/reference/fetch-service.rst
 docs/common/craft-application/reference/remote-builds.rst
+docs/common/craft-application/reference/strict-platform-names.rst
 docs/explanation/build-plans.rst
 docs/explanation/cryptography.rst
 docs/explanation/index.rst
@@ -143,8 +144,11 @@ docs/reference/models/index.rst
 docs/reference/models/platforms.rst
 docs/reference/models/project.rst
 docs/reference/services/app.rst
+docs/reference/services/buildplan.rst
+docs/reference/services/config.rst
 docs/reference/services/index.rst
 docs/reference/services/lifecycle.rst
+docs/reference/services/package.rst
 docs/reference/services/project.rst
 docs/reuse/links.txt
 docs/tutorials/index.rst

craft_application-6.2.2/docs/common/craft-application/reference/strict-platform-names.rst

@@ -0,0 +1,23 @@
+.. _reference-strict-platform-names:
+
+Naming rules
+------------
+
+A platform's name typically matches its target architecture. However, names can deviate
+from this norm if they satisfy the following rules:
+
+* A platform name must be at least one character in length.
+* A platform name must begin and end with a letter, a number, or a Unicode character
+  classified as "Symbol, other".
+
+  - In addition to those categories, characters other than the beginning and end of a
+    platform name may contain a hyphen (``-``), an at sign (``@``), a full stop (``.``),
+    or a colon (``:``).
+* The platform name ``any`` is reserved and cannot be used.
+
+|Starcraft| uses platform names as part of the file name when packing a |star|. A few valid
+but unusual platform names include:
+
+- ``amd64``
+- ``my-platform``
+- ``🇧🇷❣️``

{craft_application-6.2.0 → craft_application-6.2.2}/docs/conf.py

@@ -51,6 +51,7 @@ exclude_patterns = [
     "common/craft-application/how-to-guides/reuse-packages-between-builds.rst",
     "common/craft-application/reference/remote-builds.rst",
     "common/craft-application/reference/fetch-service.rst",
+    "common/craft-application/reference/strict-platform-names.rst",
     # There's no tutorials right now, so just hide the scaffolding
     "tutorials",
 ]
@@ -89,10 +90,6 @@ html_css_files = [
 # Intersphinx extension
 # https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration
 
-intersphinx_mapping = {
-    "python": ("https://docs.python.org/3", None),
-}
-
 # Type hints configuration
 set_type_checking_flag = True
 typehints_fully_qualified = False
@@ -103,6 +100,7 @@ github_username = "canonical"
 github_repository = "craft-application"
 
 intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
     "craft-cli": (
         "https://canonical-craft-cli.readthedocs-hosted.com/en/latest",
         None,

{craft_application-6.2.0 → craft_application-6.2.2}/docs/reference/application.rst

@@ -12,6 +12,7 @@ need to configure their own :py:class:`AppMetadata`.
 
 .. autoclass:: AppMetadata
     :members:
+    :no-index: ConfigModel
 
 
 ``Application``

{craft_application-6.2.0 → craft_application-6.2.2}/docs/reference/changelog.rst

@@ -15,6 +15,35 @@ Changelog
 
     For a complete list of commits, check out the `1.2.3`_ release on GitHub.
 
+6.2.2 (2026-03-12)
+------------------
+
+Documentation
+=============
+
+- Fix a misspelling.
+
+For a complete list of commits, check out the `6.2.2`_ release on GitHub.
+
+6.2.1 (2026-03-06)
+------------------
+
+Bug fixes
+=========
+
+- The :py:class:`~craft_application.Application` now sets the plugin group on
+  application load.
+
+Documentation
+=============
+
+- Add a :ref:`reference-BuildPlanService` reference document.
+- Add a :ref:`reference-ConfigService` reference document.
+- Add a :ref:`reference-PackageService` reference document.
+- Add a snippet for :ref:`platform naming rules <reference-strict-platform-names>`
+  that can be reused across applications.
+
+For a complete list of commits, check out the `6.2.1`_ release on GitHub.
 
 6.2.0 (2026-02-12)
 ------------------
@@ -1210,3 +1239,5 @@ For a complete list of commits, check out the `2.7.0`_ release on GitHub.
 .. _6.1.0: https://github.com/canonical/craft-application/releases/tag/6.1.0
 .. _6.1.1: https://github.com/canonical/craft-application/releases/tag/6.1.1
 .. _6.2.0: https://github.com/canonical/craft-application/releases/tag/6.2.0
+.. _6.2.1: https://github.com/canonical/craft-application/releases/tag/6.2.1
+.. _6.2.2: https://github.com/canonical/craft-application/releases/tag/6.2.2

{craft_application-6.2.0 → craft_application-6.2.2}/docs/reference/models/platforms.rst

@@ -28,6 +28,11 @@ The following mockup shows all the valid ways to create platform entries:
       build-on: [<arch 1>, <arch 2>]
       build-for: <arch 2>
 
+.. |star| replace:: package
+.. |Starcraft| replace:: Craft Application
+
+.. include:: /common/craft-application/reference/strict-platform-names.rst
+
 .. _platform-schema:
 
 ``Platform`` schema

{craft_application-6.2.0 → craft_application-6.2.2}/docs/reference/models/project.rst

@@ -40,6 +40,11 @@ This key determines the project's build environment.
 .. kitbash-field:: Project platforms
     :override-type: dict[str, Platform]
 
+    If the application has enabled strict platform naming (the default when using the
+    base ``ubuntu@25.10`` or newer), platform names must follow
+    :ref:`a set of rules <reference-strict-platform-names>` that limit what can
+    be used in a platform name.
+
 .. kitbash-field:: Project contact
     :override-type: str | list[str]
 

craft_application-6.2.2/docs/reference/services/buildplan.rst

@@ -0,0 +1,24 @@
+.. meta::
+    :description: API reference for the BuildPlanService. In a craft application, the BuildPlanService creates build plans for a project.
+
+.. py:currentmodule:: craft_application.services.buildplan
+
+.. _reference-BuildPlanService:
+
+``BuildPlanService``
+====================
+
+The ``BuildPlanService`` uses :external+craft-platforms:doc:`index` to create
+:doc:`build plans </explanation/build-plans>`.
+Apps that need to generate custom build plans that Craft Platforms can't handle must
+override :py:meth:`~BuildPlanService._gen_exhaustive_build_plan`.
+
+
+API documentation
+-----------------
+
+.. autoclass:: BuildPlanService
+    :member-order: bysource
+    :members:
+    :private-members: _gen_exhaustive_build_plan,_filter_plan
+    :undoc-members:

craft_application-6.2.2/docs/reference/services/config.rst

@@ -0,0 +1,71 @@
+.. meta::
+    :description: API reference for the ConfigService. In a craft app, the ConfigService provides access to the configuration.
+
+.. py:currentmodule:: craft_application.services.config
+
+.. _reference-ConfigService:
+
+``ConfigService``
+=================
+
+The ``ConfigService`` provides read access to a user's application configuration
+through a series of :class:`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
+:class:`~craft_application._config.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. :py:class:`AppEnvironmentHandler` gets app-specific environment variables.
+2. :py:class:`CraftEnvironmentHandler` gets general ``CRAFT_*`` environment variables.
+3. Extra handlers (if any) provided by the application.
+4. :py:class:`SnapConfigHandler` (if running as a snap) gets a `snap configuration option`_.
+5. :py:class:`DefaultConfigHandler` gets the default value, if there is one.
+
+A handler raises a :external+python:class:`KeyError` if it doesn't have a relevant
+config option set. If no handlers return a value when getting a configuration option, a
+:external+python:class:`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 :attr:`~craft_application.AppMetadata` instance. An app may extend its fields from those
+in the configuration model.
+
+.. autoclass:: craft_application.ConfigModel
+    :members:
+    :exclude-members: model_config
+
+
+API documentation
+-----------------
+
+.. autoclass:: ConfigHandler
+    :members:
+
+.. autoclass:: AppEnvironmentHandler
+    :members:
+
+.. autoclass:: CraftEnvironmentHandler
+    :members:
+
+.. autoclass:: SnapConfigHandler
+    :members:
+
+.. autoclass:: DefaultConfigHandler
+    :members:
+
+.. autoclass:: ConfigService
+    :member-order: bysource
+    :members:
+    :private-members:
+
+.. _`snap configuration option`: https://snapcraft.io/docs/configuration-in-snaps

craft_application-6.2.2/docs/reference/services/index.rst

@@ -0,0 +1,28 @@
+.. meta::
+    :description: API reference for services. In a craft application, each service is responsible for a different category of tasks.
+
+.. _reference-services:
+
+Services
+========
+
+These pages provide reference information for services provided by Craft Application.
+
+Service factory API documentation
+---------------------------------
+
+.. autoclass:: craft_application.services.ServiceFactory
+    :members: register,reset,update_kwargs,get_class,get
+    :member-order: bysource
+    :exclude-members: __new__
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   app
+   buildplan
+   config
+   lifecycle
+   package
+   project

craft_application-6.2.2/docs/reference/services/package.rst

@@ -0,0 +1,21 @@
+.. meta::
+    :description: API reference for the PackageService. In a craft app, the PackageService turns one or more directories into software packages.
+
+.. py:currentmodule:: craft_application.services.package
+
+.. _reference-PackageService:
+
+``PackageService``
+==================
+
+The ``PackageService`` takes the final output of the :external+craft-parts:ref:`prime step <craft_parts_steps>`
+and assembles it into the final package. Because this step is unique to the app,
+the :meth:`~PackageService.pack` and :meth:`~PackageService.metadata` methods are abstract
+and must be implemented by the app.
+
+API documentation
+-----------------
+
+.. autoclass:: PackageService
+    :member-order: bysource
+    :members:

{craft_application-6.2.0 → craft_application-6.2.2}/pyproject.toml

@@ -87,7 +87,7 @@ types = [
 ]
 docs = [
     "canonical-sphinx[full]~=0.5.1",
-    "pydantic-kitbash~=0.1.1",
+    "pydantic-kitbash~=1.0.1",
     "sphinx-autobuild==2024.10.3",
     "sphinx-lint==1.0.2",
     "sphinx-substitution-extensions>=2025.1.2",

{craft_application-6.2.0 → craft_application-6.2.2}/tests/spread/witchcraft/plugin-groups/task.yaml

@@ -16,7 +16,7 @@ execute: |
 
   # Check that the package referencing a plugin not used on this system does not pack.
   cd "invalid-${DISTRO}"
-  witchcraft pack --destructive-mode |& MATCH "Plugin '[a-z]+' in part 'part1' is not registered."
+  witchcraft pack --destructive-mode |& MATCH "plugin not registered: '[a-z]+' \(in field 'parts.part1',"
 
 
 restore: |

{craft_application-6.2.0 → craft_application-6.2.2}/tests/unit/test_application.py

@@ -1027,6 +1027,64 @@ def test_register_plugins_default(mocker, app_metadata, fake_services):
     assert reg.call_count == 0
 
 
+def test_set_plugin_group(mocker, app_metadata, fake_services):
+    """Test that we set the plugin group early."""
+    mock_set = mocker.patch("craft_parts.plugins.set_plugin_group")
+    mock_get_plugin_group = mocker.patch.object(
+        fake_services.get_class("lifecycle"), "get_plugin_group"
+    )
+
+    app = FakeApplication(app_metadata, fake_services)
+    with pytest.raises(SystemExit):
+        app.run()
+
+    mock_set.assert_called_once_with(mock_get_plugin_group.return_value)
+
+
+def test_set_plugin_group_empty(mocker, app_metadata, fake_services):
+    """Test that we set the plugin group early."""
+    mock_set = mocker.patch("craft_parts.plugins.set_plugin_group")
+    mock_get_plugin_group = mocker.patch.object(
+        fake_services.get_class("lifecycle"), "get_plugin_group", return_value=None
+    )
+
+    app = FakeApplication(app_metadata, fake_services)
+    with pytest.raises(SystemExit):
+        app.run()
+
+    mock_get_plugin_group.assert_called_once()
+    mock_set.assert_not_called()
+
+
+@pytest.mark.parametrize(
+    "planning_error",
+    [
+        craft_cli.CraftError("General craft error"),
+        craft_platforms.CraftPlatformsError("Platforms error"),
+        craft_application.errors.CraftValidationError("Validation!"),
+    ],
+)
+def test_set_plugin_group_ignores_errors(
+    mocker, app_metadata, fake_services, planning_error
+):
+    """Test that we set the plugin group early."""
+    mock_set = mocker.patch("craft_parts.plugins.set_plugin_group")
+    mock_get_plugin_group = mocker.patch.object(
+        fake_services.get_class("lifecycle"), "get_plugin_group", return_value=None
+    )
+    mock_planner = mocker.patch.object(
+        fake_services.get("build_plan"), "plan", side_effect=planning_error
+    )
+
+    app = FakeApplication(app_metadata, fake_services)
+    with pytest.raises(SystemExit):
+        app.run()
+
+    mock_planner.assert_called_once()
+    mock_get_plugin_group.assert_not_called()
+    mock_set.assert_not_called()
+
+
 @pytest.fixture
 def grammar_project_mini(tmp_path):
     """A project that builds on amd64 to riscv64 and s390x."""