Embedded Module (EM)¶

class EMClient:
    """Client interface for accessing Embedded Manager API interfaces.

    This class exposes a property-based interface for accessing the Embedded Manager API
    model interfaces. Each property returns an interface responsible for interacting
    with a specific Embedded Manager model.

    Args:
        resource_api: Optional resources API provider. When omitted, the models keep their
            lazily built ``ResourceApi`` session. Inject a custom implementation for testing.
            The injected session is bound to every model served by ``/resources``, not only
            the Embedded Manager ones.

    Examples:
        >>> client = EMClient()
        >>> projects = client.em_project.get_list("firmware_id", "fw-1")
    """

    def __init__(self, resource_api: JsonApiProtocol | None = None) -> None:
        if resource_api is None:
            return

        bind_session(ResourcesApiModel, resource_api.api)

    @property
    def em_project(self) -> EmProjectInterface:
        """Returns the interface for interacting with EmProject resources.

        Returns:
            EmProjectInterface: The interface for managing EmProject models.

        Examples:
            >>> client.em_project.get("firmware_id", "fw-1")
        """
        interface: EmProjectInterface = EMInterfaceFactory.get_interface("em_project")
        return interface

    @property
    def em_build(self) -> EmBuildInterface:
        """Returns the interface for interacting with EmBuild resources.

        Returns:
            EmBuildInterface: The interface for managing EmBuild models.

        Examples:
            >>> client.em_build.get("build_ref", "main")
        """
        interface: EmBuildInterface = EMInterfaceFactory.get_interface("em_build")
        return interface

    @property
    def gitlab_connection(self) -> GitlabConnectionInterface:
        """Returns the interface for interacting with GitlabConnection resources.

        Returns:
            GitlabConnectionInterface: The interface for managing GitlabConnection models.

        Examples:
            >>> client.gitlab_connection.get("name", "dave-gitlab")
        """
        interface: GitlabConnectionInterface = EMInterfaceFactory.get_interface("gitlab_connection")
        return interface

    @property
    def storage_bucket(self) -> StorageBucketInterface:
        """Returns the interface for interacting with StorageBucket resources.

        Returns:
            StorageBucketInterface: The interface for managing StorageBucket models.

        Examples:
            >>> client.storage_bucket.get("name", "em-artifacts")
        """
        interface: StorageBucketInterface = EMInterfaceFactory.get_interface("storage_bucket")
        return interface

class EMInterfaceFactory(BaseInterfaceFactory):
    """Factory class for retrieving Embedded Manager API interface instances.

    This class provides access to interface classes responsible for interacting
    with the Embedded Manager API models (projects, builds, GitLab connections and
    storage buckets).

    Attributes:
        _model_map (dict): A mapping of model names to their interface classes.

    Examples:
        >>> interface = EMInterfaceFactory.get_interface("em_project")
        >>> project = interface.new()
    """

    _model_map = {
        "em_project": EmProjectInterface,
        "em_build": EmBuildInterface,
        "gitlab_connection": GitlabConnectionInterface,
        "storage_bucket": StorageBucketInterface,
    }

class EMApiClient(_SelfInitializingClient):
    """Ready-to-use authenticated client for the ToloMEO ``embedded-manager`` REST endpoints."""

    _path = "tolomeo/embedded-manager"

    def refs(self, project_id: str) -> list[EmRef]:
        """List the branches and tags a build of the project can run on."""
        data = self.get(f"projects/{project_id}/refs").json()
        return [EmRef.model_validate(ref) for ref in data.get("refs", [])]

    def config(self, project_id: str, ref: str) -> EmConfigDocument:
        """Fetch the project's em-config document at ``ref``."""
        return EmConfigDocument.model_validate(self.get(f"projects/{project_id}/config", params={"ref": ref}).json())

    def create_build(self, project_id: str, request: CreateBuildRequest) -> EmBuildDto:
        """Start a build: the backend triggers the GitLab pipeline and returns the new build."""
        return EmBuildDto.model_validate(self.post(f"projects/{project_id}/builds", json=request.payload()).json())

    def live_build(self, build_id: str) -> EmBuildDto:
        """Return the build merged with a live GitLab read while it is not finished."""
        return EmBuildDto.model_validate(self.get(f"builds/{build_id}/live").json())