craft-application 0.1.0__py3-none-any.whl

build/lib/build/lib/build/lib/build/lib/craft_application/__init__.py

@@ -0,0 +1,51 @@
+# This file is part of craft-application.
+#
+# Copyright 2023 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/>.
+"""Framework for *craft applications."""
+
+from craft_application.application import Application, AppFeatures, AppMetadata
+from craft_application import models
+from craft_application.services import (
+    AppService,
+    ProjectService,
+    LifecycleService,
+    PackageService,
+    ProviderService,
+    ServiceFactory,
+)
+
+try:
+    from ._version import __version__
+except ImportError:  # pragma: no cover
+    from importlib.metadata import version, PackageNotFoundError
+
+    try:
+        __version__ = version("craft-archives")
+    except PackageNotFoundError:
+        __version__ = "dev"
+
+__all__ = [
+    "__version__",
+    "Application",
+    "AppFeatures",
+    "AppMetadata",
+    "AppService",
+    "models",
+    "ProjectService",
+    "LifecycleService",
+    "PackageService",
+    "ProviderService",
+    "ServiceFactory",
+]

build/lib/build/lib/build/lib/build/lib/craft_application/_version.py

@@ -0,0 +1,16 @@
+# file generated by setuptools_scm
+# don't change, don't track in version control
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple, Union
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)

build/lib/build/lib/build/lib/build/lib/craft_application/application.py

@@ -0,0 +1,477 @@
+# This file is part of craft_application.
+#
+# Copyright 2023 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/>.
+"""Main application classes for a craft-application."""
+from __future__ import annotations
+
+import functools
+import importlib
+import logging
+import os
+import pathlib
+import signal
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from importlib import metadata
+from typing import TYPE_CHECKING, Any, cast, final
+
+import craft_cli
+import craft_parts
+import craft_providers
+from xdg.BaseDirectory import save_cache_path  # type: ignore[import]
+
+from craft_application import commands, models, secrets, util
+from craft_application.models import BuildInfo
+
+if TYPE_CHECKING:
+    from craft_application.services import service_factory
+
+GLOBAL_VERSION = craft_cli.GlobalArgument(
+    "version", "flag", "-V", "--version", "Show the application version and exit"
+)
+
+
+@dataclass(frozen=True)
+class AppFeatures:
+    """Specific features that can be enabled/disabled per-application."""
+
+    build_secrets: bool = False
+    """Support for build-time secrets."""
+
+
+@final
+@dataclass(frozen=True)
+class AppMetadata:
+    """Metadata about a *craft application."""
+
+    name: str
+    summary: str | None = None
+    version: str = field(init=False)
+    source_ignore_patterns: list[str] = field(default_factory=lambda: [])
+    managed_instance_project_path = pathlib.PurePosixPath("/root/project")
+    features: AppFeatures = AppFeatures()
+
+    ProjectClass: type[models.Project] = models.Project
+
+    def __post_init__(self) -> None:
+        setter = super().__setattr__
+
+        # Try to determine the app version.
+        try:
+            # First, via the __version__ attribute on the app's main package.
+            version = importlib.import_module(self.name).__version__
+        except (AttributeError, ModuleNotFoundError):
+            try:
+                # If that fails, try via the installed metadata.
+                version = metadata.version(self.name)
+            except metadata.PackageNotFoundError:
+                # If that fails too, default to "dev".
+                version = "dev"
+
+        setter("version", version)
+        if self.summary is None:
+            md = metadata.metadata(self.name)
+            setter("summary", md["summary"])
+
+
+class Application:
+    """Craft Application Builder.
+
+    :ivar app: Metadata about this application
+    :ivar services: A ServiceFactory for this application
+    """
+
+    def __init__(
+        self,
+        app: AppMetadata,
+        services: service_factory.ServiceFactory,
+    ) -> None:
+        self.app = app
+        self.services = services
+        self._command_groups: list[craft_cli.CommandGroup] = []
+        self._global_arguments: list[craft_cli.GlobalArgument] = [GLOBAL_VERSION]
+
+        # When build_secrets are enabled, this contains the secret info to pass to
+        # managed instances.
+        self._secrets: secrets.BuildSecrets | None = None
+
+        if self.is_managed():
+            self._work_dir = pathlib.Path("/root")
+        else:
+            self._work_dir = pathlib.Path.cwd()
+
+    @property
+    def command_groups(self) -> list[craft_cli.CommandGroup]:
+        """Return command groups."""
+        lifecycle_commands = commands.get_lifecycle_command_group()
+        other_commands = commands.get_other_command_group()
+
+        merged: dict[str, list[type[craft_cli.BaseCommand]]] = {}
+        all_groups = [lifecycle_commands, other_commands, *self._command_groups]
+
+        # Merge the default command groups with those provided by the application,
+        # so that we don't get multiple groups with the same name.
+        for group in all_groups:
+            merged.setdefault(group.name, []).extend(group.commands)
+
+        return [
+            craft_cli.CommandGroup(name, commands_)
+            for name, commands_ in merged.items()
+        ]
+
+    @property
+    def log_path(self) -> pathlib.Path | None:
+        """Get the path to this process's log file, if any."""
+        if self.is_managed():
+            return util.get_managed_logpath(self.app)
+        return None
+
+    def add_global_argument(self, argument: craft_cli.GlobalArgument) -> None:
+        """Add a global argument to the Application."""
+        self._global_arguments.append(argument)
+
+    def add_command_group(
+        self, name: str, commands: list[type[craft_cli.BaseCommand]]
+    ) -> None:
+        """Add a CommandGroup to the Application."""
+        self._command_groups.append(craft_cli.CommandGroup(name, commands))
+
+    @property
+    def cache_dir(self) -> str:
+        """Get the directory for caching any data."""
+        # Mypy doesn't know what type save_cache_path returns, but pyright figures
+        # it out correctly. We can remove this ignore comment once the typeshed has
+        # xdg types: https://github.com/python/typeshed/pull/10163
+        return save_cache_path(self.app.name)  # type: ignore[no-any-return]
+
+    def _configure_services(
+        self,
+        platform: str | None,  # noqa: ARG002 (Unused method argument)
+        build_for: str | None,
+    ) -> None:
+        """Configure additional keyword arguments for any service classes.
+
+        Any child classes that override this must either call this directly or must
+        provide a valid ``project`` to ``self.services``.
+        """
+        self.services.set_kwargs(
+            "lifecycle",
+            cache_dir=self.cache_dir,
+            work_dir=self._work_dir,
+            build_for=build_for,
+        )
+        self.services.set_kwargs(
+            "provider",
+            work_dir=self._work_dir,
+        )
+
+    @functools.cached_property
+    def project(self) -> models.Project:
+        """Get this application's Project metadata."""
+        # Current working directory contains the project file
+        project_file = pathlib.Path(f"{self.app.name}.yaml").resolve()
+        craft_cli.emit.debug(f"Loading project file '{project_file!s}'")
+
+        with project_file.open() as file:
+            yaml_data = util.safe_yaml_load(file)
+
+        yaml_data = self._transform_project_yaml(yaml_data)
+
+        return self.app.ProjectClass.from_yaml_data(yaml_data, project_file)
+
+    def is_managed(self) -> bool:
+        """Shortcut to tell whether we're running in managed mode."""
+        return self.services.ProviderClass.is_managed()
+
+    def run_managed(self, platform: str | None, build_for: str | None) -> None:
+        """Run the application in a managed instance."""
+        extra_args: dict[str, Any] = {}
+
+        build_plan = self.project.get_build_plan()
+        build_plan = _filter_plan(build_plan, platform, build_for)
+
+        for build_info in build_plan:
+            env = {"CRAFT_PLATFORM": build_info.platform}
+
+            if self.app.features.build_secrets:
+                # If using build secrets, put them in the environment of the managed
+                # instance.
+                secret_values = cast(secrets.BuildSecrets, self._secrets)
+                env.update(secret_values.environment)
+
+            extra_args["env"] = env
+
+            craft_cli.emit.debug(
+                f"Running {self.app.name}:{build_info.platform} in {build_info.build_for} instance..."
+            )
+            instance_path = pathlib.PosixPath("/root/project")
+
+            with self.services.provider.instance(
+                build_info, work_dir=self._work_dir
+            ) as instance:
+                try:
+                    # Pyright doesn't fully understand craft_providers's CompletedProcess.
+                    instance.execute_run(  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]
+                        [self.app.name, *sys.argv[1:]],
+                        cwd=instance_path,
+                        check=True,
+                        **extra_args,
+                    )
+                except subprocess.CalledProcessError as exc:
+                    raise craft_providers.ProviderError(
+                        f"Failed to execute {self.app.name} in instance."
+                    ) from exc
+
+    def configure(self, global_args: dict[str, Any]) -> None:
+        """Configure the application using any global arguments."""
+
+    def _get_dispatcher(self) -> craft_cli.Dispatcher:
+        """Configure this application. Should be called by the run method.
+
+        Side-effect: This method may exit the process.
+
+        :returns: A ready-to-run Dispatcher object
+        """
+        # Set the logging level to DEBUG for all craft-libraries. This is OK even if
+        # the specific application doesn't use a specific library, the call does not
+        # import the package.
+        craft_libs = ["craft_archives", "craft_parts", "craft_providers", "craft_store"]
+        for craft_lib in craft_libs:
+            logger = logging.getLogger(craft_lib)
+            logger.setLevel(logging.DEBUG)
+
+        craft_cli.emit.init(
+            mode=craft_cli.EmitterMode.BRIEF,
+            appname=self.app.name,
+            greeting=f"Starting {self.app.name}",
+            log_filepath=self.log_path,
+            streaming_brief=True,
+        )
+
+        dispatcher = craft_cli.Dispatcher(
+            self.app.name,
+            self.command_groups,
+            summary=str(self.app.summary),
+            extra_global_args=self._global_arguments,
+        )
+
+        try:
+            craft_cli.emit.trace("pre-parsing arguments...")
+            # Workaround for the fact that craft_cli requires a command.
+            # https://github.com/canonical/craft-cli/issues/141
+            if "--version" in sys.argv or "-V" in sys.argv:
+                try:
+                    global_args = dispatcher.pre_parse_args(["pull", *sys.argv[1:]])
+                except craft_cli.ArgumentParsingError:
+                    global_args = dispatcher.pre_parse_args(sys.argv[1:])
+            else:
+                global_args = dispatcher.pre_parse_args(sys.argv[1:])
+
+            if global_args.get("version"):
+                craft_cli.emit.ended_ok()
+                print(f"{self.app.name} {self.app.version}")
+                sys.exit(0)
+        except craft_cli.ProvideHelpException as err:
+            print(err, file=sys.stderr)  # to stderr, as argparse normally does
+            craft_cli.emit.ended_ok()
+            sys.exit(0)
+        except craft_cli.ArgumentParsingError as err:
+            print(err, file=sys.stderr)  # to stderr, as argparse normally does
+            craft_cli.emit.ended_ok()
+            sys.exit(64)  # Command line usage error from sysexits.h
+        except KeyboardInterrupt as err:
+            self._emit_error(craft_cli.CraftError("Interrupted."), cause=err)
+            sys.exit(128 + signal.SIGINT)
+        except Exception as err:  # noqa: BLE001
+            self._emit_error(
+                craft_cli.CraftError(
+                    f"Internal error while loading {self.app.name}: {err!r}"
+                )
+            )
+            if os.getenv("CRAFT_DEBUG") == "1":
+                raise
+            sys.exit(70)  # EX_SOFTWARE from sysexits.h
+
+        craft_cli.emit.trace("Preparing application...")
+        self.configure(global_args)
+
+        return dispatcher
+
+    def run(self) -> int:  # noqa: PLR0912 (too many branches due to error handling)
+        """Bootstrap and run the application."""
+        dispatcher = self._get_dispatcher()
+        craft_cli.emit.trace("Preparing application...")
+
+        return_code = 1  # General error
+        try:
+            command = cast(
+                commands.AppCommand,
+                dispatcher.load_command(
+                    {
+                        "app": self.app,
+                        "services": self.services,
+                    }
+                ),
+            )
+            platform = getattr(dispatcher.parsed_args(), "platform", None)
+            build_for = getattr(dispatcher.parsed_args(), "build_for", None)
+            self._configure_services(platform, build_for)
+
+            if not command.run_managed(dispatcher.parsed_args()):
+                # command runs in the outer instance
+                craft_cli.emit.debug(f"Running {self.app.name} {command.name} on host")
+                if command.always_load_project:
+                    self.services.project = self.project
+                return_code = dispatcher.run() or 0
+            elif not self.is_managed():
+                # command runs in inner instance, but this is the outer instance
+                self.services.project = self.project
+                self.run_managed(platform, build_for)
+                return_code = 0
+            else:
+                # command runs in inner instance
+                self.services.project = self.project
+                return_code = dispatcher.run() or 0
+        except craft_cli.ArgumentParsingError as err:
+            print(err, file=sys.stderr)  # to stderr, as argparse normally does
+            craft_cli.emit.ended_ok()
+            return_code = 64  # Command line usage error from sysexits.h
+        except KeyboardInterrupt as err:
+            self._emit_error(craft_cli.CraftError("Interrupted."), cause=err)
+            return_code = 128 + signal.SIGINT
+        except craft_cli.CraftError as err:
+            self._emit_error(err)
+        except craft_parts.PartsError as err:
+            self._emit_error(
+                craft_cli.CraftError(
+                    err.brief, details=err.details, resolution=err.resolution
+                )
+            )
+            return_code = 1
+        except craft_providers.ProviderError as err:
+            self._emit_error(
+                craft_cli.CraftError(
+                    err.brief, details=err.details, resolution=err.resolution
+                )
+            )
+            return_code = 1
+        except Exception as err:  # noqa: BLE001 pylint: disable=broad-except
+            self._emit_error(
+                craft_cli.CraftError(f"{self.app.name} internal error: {err!r}")
+            )
+            if os.getenv("CRAFT_DEBUG") == "1":
+                raise
+            return_code = 70  # EX_SOFTWARE from sysexits.h
+        else:
+            craft_cli.emit.ended_ok()
+
+        return return_code
+
+    def _emit_error(
+        self, error: craft_cli.CraftError, *, cause: BaseException | None = None
+    ) -> None:
+        """Emit the error in a centralized way so we can alter it consistently."""
+        # set the cause, if any
+        if cause is not None:
+            error.__cause__ = cause
+
+        # Do not report the internal logpath if running inside an instance
+        if self.is_managed():
+            error.logpath_report = False
+
+        craft_cli.emit.error(error)
+
+    def _transform_project_yaml(self, yaml_data: dict[str, Any]) -> dict[str, Any]:
+        """Update the project's yaml data with runtime properties.
+
+        Performs task such as environment expansion. Note that this transforms
+        ``yaml_data`` in-place.
+        """
+        # Perform variable expansion.
+        self._expand_environment(yaml_data)
+
+        # Handle build secrets.
+        if self.app.features.build_secrets:
+            self._render_secrets(yaml_data)
+
+        # Perform extra, application-specific transformations.
+        return self._extra_yaml_transform(yaml_data)
+
+    def _expand_environment(self, yaml_data: dict[str, Any]) -> None:
+        """Perform expansion of project environment variables."""
+        project_vars = self._project_vars(yaml_data)
+
+        info = craft_parts.ProjectInfo(
+            application_name=self.app.name,  # not used in environment expansion
+            cache_dir=pathlib.Path(),  # not used in environment expansion
+            project_name=yaml_data.get("name", ""),
+            project_dirs=craft_parts.ProjectDirs(work_dir=self._work_dir),
+            project_vars=project_vars,
+        )
+
+        self._set_global_environment(info)
+
+        craft_parts.expand_environment(yaml_data, info=info)
+
+    def _project_vars(self, yaml_data: dict[str, Any]) -> dict[str, str]:
+        """Return a dict with project-specific variables, for a craft_part.ProjectInfo."""
+        return {"version": cast(str, yaml_data["version"])}
+
+    def _set_global_environment(self, info: craft_parts.ProjectInfo) -> None:
+        """Populate the ProjectInfo's global environment."""
+        info.global_environment.update(
+            {
+                "CRAFT_PROJECT_VERSION": info.get_project_var("version", raw_read=True),
+            }
+        )
+
+    def _render_secrets(self, yaml_data: dict[str, Any]) -> None:
+        """Render build-secrets, in-place."""
+        secret_values = secrets.render_secrets(
+            yaml_data, managed_mode=self.is_managed()
+        )
+
+        num_secrets = len(secret_values.secret_strings)
+        craft_cli.emit.debug(f"Project has {num_secrets} build-secret(s).")
+
+        craft_cli.emit.set_secrets(list(secret_values.secret_strings))
+
+        self._secrets = secret_values
+
+    def _extra_yaml_transform(self, yaml_data: dict[str, Any]) -> dict[str, Any]:
+        """Perform additional transformations on a project's yaml data.
+
+        Note: subclasses should return a new dict and keep the parameter unmodified.
+        """
+        return yaml_data
+
+
+def _filter_plan(
+    build_plan: list[BuildInfo], platform: str | None, build_for: str | None
+) -> list[BuildInfo]:
+    """Filter out builds not matching build-on and build-for."""
+    host_arch = util.get_host_architecture()
+
+    plan: list[BuildInfo] = []
+    for build_info in build_plan:
+        platform_matches = not platform or build_info.platform == platform
+        build_on_matches = build_info.build_on == host_arch
+        build_for_matches = not build_for or build_info.build_for == build_for
+
+        if platform_matches and build_on_matches and build_for_matches:
+            plan.append(build_info)
+
+    return plan

build/lib/build/lib/build/lib/build/lib/craft_application/commands/__init__.py

@@ -0,0 +1,28 @@
+#  This file is part of craft-application.
+#
+#  Copyright 2023 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/>.
+"""Command classes for a craft application."""
+
+from craft_application.commands.base import AppCommand
+from craft_application.commands import lifecycle
+from craft_application.commands.lifecycle import get_lifecycle_command_group
+from craft_application.commands.other import get_other_command_group
+
+__all__ = [
+    "AppCommand",
+    "lifecycle",
+    "get_lifecycle_command_group",
+    "get_other_command_group",
+]

build/lib/build/lib/build/lib/build/lib/craft_application/commands/base.py

@@ -0,0 +1,76 @@
+#  This file is part of craft-application.
+#
+#  Copyright 2023 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/>.
+"""Base command for craft-application commands."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from craft_cli import BaseCommand, emit
+
+if TYPE_CHECKING:  # pragma: no cover
+    import argparse
+
+    from craft_application import application
+    from craft_application.services import service_factory
+
+
+class AppCommand(BaseCommand):
+    """Command for use with craft-application."""
+
+    always_load_project: bool = False
+    """The project is also loaded in non-managed mode."""
+
+    def __init__(self, config: dict[str, Any] | None) -> None:
+        if config is None:
+            # This should only be the case when the command is not going to be run.
+            # For example, when requesting help on the command.
+            emit.trace("Not completing command configuration")
+            return
+
+        super().__init__(config)
+
+        self._app: application.AppMetadata = config["app"]
+        self._services: service_factory.ServiceFactory = config["services"]
+
+    def run_managed(
+        self,
+        parsed_args: argparse.Namespace,  # noqa: ARG002 (the unused argument is for subclasses)
+    ) -> bool:
+        """Whether this command should run in managed mode.
+
+        By default returns `False`. Subclasses can override this method to change this,
+        including by inspecting the arguments in `parsed_args`.
+        """
+        return False
+
+    def get_managed_cmd(
+        self,
+        parsed_args: argparse.Namespace,  # - Used by subclasses
+    ) -> list[str]:
+        """Get the command to run in managed mode.
+
+        :param parsed_args: The parsed arguments used.
+        :returns: A list of strings ready to be passed into a craft-providers executor.
+        :raises: RuntimeError if this command is not supposed to run managed.
+
+        Commands that have additional parameters to pass in managed mode should
+        override this method to include those parameters.
+        """
+        if not self.run_managed(parsed_args):
+            raise RuntimeError("Unmanaged commands should not be run in managed mode.")
+        cmd_name = self._app.name
+        verbosity = emit.get_mode().name.lower()
+        return [cmd_name, f"--verbosity={verbosity}", self.name]