API¶

def build_args(
    self,
    *args: str,
    tags: Iterable[str] = (),
    context: str = ".",
) -> Args:
    """Build args to build and tag an image from the build context.

    Constructs `podman build --tag=<tag>... <context>`, repeating
    `--tag` for each provided tag and inserting `*args` before the
    context. No `--file` is passed, so podman discovers the
    `Containerfile` in the build context automatically.

    Args:
        *args: Additional arguments appended before the context (e.g.
            `--file` to point at a specific Containerfile, or
            `--no-cache`).
        tags: Image references to tag the built image with. Defaults to none.
        context: Build context directory. Defaults to the current directory.

    Returns:
        Args for the `podman build` command.
    """
    tag_args = (f"--tag={tag}" for tag in tags)
    return self.args("build", *tag_args, *args, context)

def dev_dependencies(self) -> tuple[str, ...]:
    """Return an empty tuple; `podman` is a system package, not a Python one."""
    return ()

def group(self) -> str:
    """Return `Group.TOOLING`."""
    return Group.TOOLING

def image_url(self) -> str:
    """Return the Shields.io badge URL for `podman`."""
    return f"https://img.shields.io/badge/Container-{self.shield_name().capitalize()}-A23CD6?logo=podman&logoColor=grey&colorA=0D1F3F&colorB=A23CD6"

def link_url(self) -> str:
    """Return the URL of the `podman` project page."""
    return "https://podman.io"

def login_args(
    self,
    *args: str,
    registry: str,
    username: str,
    password: str,
) -> Args:
    """Build args to authenticate the container engine with a registry.

    Constructs `podman login <registry> --username=<username>
    --password=<password>`, appending `*args` at the end.

    Args:
        *args: Additional arguments appended to the command.
        registry: Registry host to authenticate against (e.g. `ghcr.io`).
        username: Account name to log in as.
        password: Token or password for the account.

    Returns:
        Args for the `podman login` command.
    """
    return self.args(
        "login",
        registry,
        f"--username={username}",
        f"--password={password}",
        *args,
    )

def name(self) -> str:
    """Return `"podman"`."""
    return "podman"

def push_args(self, *args: str, tag: str) -> Args:
    """Build args to push a tagged image to its registry.

    Constructs `podman push <tag>`, appending `*args` at the end.

    Args:
        *args: Additional arguments appended to the command.
        tag: Fully qualified image reference to push (e.g.
            `ghcr.io/owner/repo:latest`).

    Returns:
        Args for the `podman push` command.
    """
    return self.args("push", tag, *args)

def dev_dependencies(self) -> tuple[str, ...]:
    """Return an empty tuple; the registry requires no Python package."""
    return ()

def group(self) -> str:
    """Return `Group.PROJECT_INFO`."""
    return Group.PROJECT_INFO

def host(self) -> str:
    """Return `"ghcr.io"`."""
    return "ghcr.io"

def image_name(self) -> str:
    """Build the project's fully qualified image name without a tag.

    Combines the registry host with the lowercased repository owner and
    project name, as GHCR requires image names to be lowercase.

    Returns:
        Image name in the form `ghcr.io/<owner>/<project>`.
    """
    owner = VersionController.I.repo_owner().lower()
    project = PackageManager.I.project_name().lower()
    return f"{self.host()}/{owner}/{project}"

def image_tag(self, tag: str) -> str:
    """Build the project's image reference for the given tag.

    Args:
        tag: Tag to append to the image name (e.g. `latest` or `1.2.3`).

    Returns:
        Image reference in the form `ghcr.io/<owner>/<project>:<tag>`.
    """
    return f"{self.image_name()}:{tag}"

def image_url(self) -> str:
    """Return the Shields.io badge URL for GHCR."""
    return "https://img.shields.io/badge/GHCR-Container_Image-black?logo=github&logoColor=white"

def link_url(self) -> str:
    """Return the URL of the project's GHCR container package page."""
    repo_url = RemoteVersionController.I.repo_url()
    package = PackageManager.I.project_name()
    return f"{repo_url}/pkgs/container/{package}"

def name(self) -> str:
    """Return `"ghcr"`."""
    return "ghcr"

def container_image(self) -> tuple[str, str, str]:
    """Return the image and paths for copying uv into a container image.

    Returns:
        Tuple of `(image, path_in_source_image, path_in_target_image)`.
    """
    return "ghcr.io/astral-sh/uv:latest", "/uv", "/usr/local/bin/uv"