Skip to content

API

Pyrig plugin that integrates container support into a project.

rig

Mirrored namespace through which this plugin extends pyrig's scaffolding.

Mirrors the pyrig.rig package layout so pyrig's cross-package plugin discovery finds this plugin's configuration and tooling customizations automatically.

configs

Configuration files this plugin contributes to pyrig's discovery scope.

container_file

Containerfile configuration management.

ContainerfileConfigFile

Bases: StringConfigFile

The project's Containerfile, built from a Python slim base image.

Copies in the uv binary, installs runtime dependencies with uv, and runs the project as a non-root user (appuser, UID 1000).

Source code in src/pyrig_containers/rig/configs/container_file.py 
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
class ContainerfileConfigFile(StringConfigFile):
    """The project's `Containerfile`, built from a Python slim base image.

    Copies in the uv binary, installs runtime dependencies with uv, and runs
    the project as a non-root user (`appuser`, UID 1000).
    """

    def extension(self) -> str:
        """Return an empty string; `Containerfile` has no file extension."""
        return ""

    def extension_separator(self) -> str:
        """Return an empty string, overriding the default `.` separator.

        Prevents a trailing dot from being appended when the extension is
        empty, so the filename remains `Containerfile` instead of
        `Containerfile.`.
        """
        return ""

    def content(self) -> str:
        """Build the required `Containerfile` text.

        Returns:
            Dockerfile instructions that copy in the `uv` binary, install
            the project's runtime dependencies, and run the project as the
            non-root `appuser` user.
        """
        latest_python_version = PyprojectConfigFile.I.latest_possible_python_version()
        package_root = PackageManager.I.package_root().as_posix()
        project_name = PackageManager.I.project_name()
        workdir = Path(project_name).as_posix()
        app_username = "appuser"
        entrypoint = json.dumps(list(PackageManager.I.run_args(project_name)))
        readme_path, license_path, pyproject_path, lock_file_path = (
            ReadmeConfigFile.I.path().as_posix(),
            LicenseConfigFile.I.path().as_posix(),
            PyprojectConfigFile.I.path().as_posix(),
            PackageManager.I.lock_file().as_posix(),
        )
        copy_files = f"{readme_path} {license_path} {pyproject_path} {lock_file_path}"
        install_dependencies_no_dev = (
            PackageManager.I.install_dependencies_no_dev_args()
        )
        image_url, image_source_path, image_destination_path = (
            PackageManager.I.container_image()
        )
        return f"""FROM python:{latest_python_version}-slim
WORKDIR /{workdir}
COPY --from={image_url} {image_source_path} {image_destination_path}
COPY {copy_files} ./
RUN useradd --create-home --uid=1000 {app_username}
RUN chown --recursive {app_username}:{app_username} .
USER {app_username}
COPY --chown={app_username}:{app_username} {package_root} {package_root}
RUN {install_dependencies_no_dev}
RUN rm {copy_files}
ENTRYPOINT {entrypoint}
"""

    def parent_path(self) -> Path:
        """Return the project root directory."""
        return Path()

    def stem(self) -> str:
        """Return `"Containerfile"`."""
        return "Containerfile"
content()

Build the required Containerfile text.

Returns:

Type Description
str

Dockerfile instructions that copy in the uv binary, install
str

the project's runtime dependencies, and run the project as the
str

non-root appuser user.
Source code in src/pyrig_containers/rig/configs/container_file.py 
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
    def content(self) -> str:
        """Build the required `Containerfile` text.

        Returns:
            Dockerfile instructions that copy in the `uv` binary, install
            the project's runtime dependencies, and run the project as the
            non-root `appuser` user.
        """
        latest_python_version = PyprojectConfigFile.I.latest_possible_python_version()
        package_root = PackageManager.I.package_root().as_posix()
        project_name = PackageManager.I.project_name()
        workdir = Path(project_name).as_posix()
        app_username = "appuser"
        entrypoint = json.dumps(list(PackageManager.I.run_args(project_name)))
        readme_path, license_path, pyproject_path, lock_file_path = (
            ReadmeConfigFile.I.path().as_posix(),
            LicenseConfigFile.I.path().as_posix(),
            PyprojectConfigFile.I.path().as_posix(),
            PackageManager.I.lock_file().as_posix(),
        )
        copy_files = f"{readme_path} {license_path} {pyproject_path} {lock_file_path}"
        install_dependencies_no_dev = (
            PackageManager.I.install_dependencies_no_dev_args()
        )
        image_url, image_source_path, image_destination_path = (
            PackageManager.I.container_image()
        )
        return f"""FROM python:{latest_python_version}-slim
WORKDIR /{workdir}
COPY --from={image_url} {image_source_path} {image_destination_path}
COPY {copy_files} ./
RUN useradd --create-home --uid=1000 {app_username}
RUN chown --recursive {app_username}:{app_username} .
USER {app_username}
COPY --chown={app_username}:{app_username} {package_root} {package_root}
RUN {install_dependencies_no_dev}
RUN rm {copy_files}
ENTRYPOINT {entrypoint}
"""
extension()

Return an empty string; Containerfile has no file extension.

Source code in src/pyrig_containers/rig/configs/container_file.py 
21
22
23
def extension(self) -> str:
    """Return an empty string; `Containerfile` has no file extension."""
    return ""
extension_separator()

Return an empty string, overriding the default . separator.

Prevents a trailing dot from being appended when the extension is empty, so the filename remains Containerfile instead of Containerfile..

Source code in src/pyrig_containers/rig/configs/container_file.py 
25
26
27
28
29
30
31
32
def extension_separator(self) -> str:
    """Return an empty string, overriding the default `.` separator.

    Prevents a trailing dot from being appended when the extension is
    empty, so the filename remains `Containerfile` instead of
    `Containerfile.`.
    """
    return ""
parent_path()

Return the project root directory.

Source code in src/pyrig_containers/rig/configs/container_file.py 
74
75
76
def parent_path(self) -> Path:
    """Return the project root directory."""
    return Path()
stem()

Return "Containerfile".

Source code in src/pyrig_containers/rig/configs/container_file.py 
78
79
80
def stem(self) -> str:
    """Return `"Containerfile"`."""
    return "Containerfile"

version_control

Version control config overrides this plugin contributes to pyrig.

remote

Container-specific extensions to GitHub remote repository configuration.

workflows

Container-aware overrides for the project's GitHub Actions workflow configs.

deploy

Extension of the deploy workflow that builds and pushes a container image.

Runs after a release and tags the image with both the release version and latest.

DeployWorkflowConfigFile

Bases: DeployWorkflowConfigFile

Deploy workflow that adds a job to build and push a container image to GHCR.

Source code in src/pyrig_containers/rig/configs/version_control/remote/workflows/deploy.py 
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
class DeployWorkflowConfigFile(BaseDeployWorkflowConfigFile):
    """Deploy workflow that adds a job to build and push a container image to GHCR."""

    def jobs(self) -> dict[str, Any]:
        """Add the container image publish job to the base jobs.

        Returns:
            Dict combining the base jobs with the container image job.
        """
        return {
            **super().jobs(),
            **self.job_container_image(),
        }

    def job_container_image(self) -> dict[str, Any]:
        """Build the job that builds and pushes the container image to GHCR.

        Requests `packages: write` permission at the job level, required to
        push to GHCR.

        Returns:
            Dict mapping the derived job ID to its configuration.
        """
        return self.job(
            self.job_container_image,
            permissions={"packages": "write"},
            steps=self.steps_container_image(),
        )

    def steps_container_image(self) -> list[dict[str, Any]]:
        """Build the ordered steps for the publish-container-image job.

        Returns:
            Ordered list of step dicts: core setup, install the container
            engine, log in to the registry, build the image, then push the
            versioned tag and the latest tag.
        """
        return [
            *self.steps_core_setup(),
            self.step_install_container_engine(),
            self.step_login_container_registry(),
            self.step_build_container_image(),
            self.step_push_container_image_version(),
            self.step_push_container_image_latest(),
        ]

    def step_install_container_engine(
        self,
        *,
        step: dict[str, Any] | None = None,
    ) -> dict[str, Any]:
        """Build a step that installs podman on the runner.

        Args:
            step: Additional keys to merge into the step configuration.

        Returns:
            Step using `redhat-actions/podman-install@main`.
        """
        return self.step(
            self.step_install_container_engine,
            uses="redhat-actions/podman-install@main",
            step=step,
        )

    def step_login_container_registry(
        self,
        *,
        step: dict[str, Any] | None = None,
    ) -> dict[str, Any]:
        """Build a step that logs podman in to the container registry.

        Authenticates as the workflow actor, using the automatic
        `GITHUB_TOKEN` secret as the password.

        Args:
            step: Additional keys to merge into the step configuration.

        Returns:
            Step that runs `podman login` against the registry.
        """
        return self.step(
            self.step_login_container_registry,
            run=ContainerEngine.I.login_args(
                registry=ContainerRegistry.I.host(),
                username=self.insert_actor(),
                password=self.insert_github_token(),
            ).multiline(),
            step=step,
        )

    def step_build_container_image(
        self,
        *,
        step: dict[str, Any] | None = None,
    ) -> dict[str, Any]:
        """Build a step that builds the container image.

        Tags the built image with both the versioned tag and the `latest` tag.

        Args:
            step: Additional keys to merge into the step configuration.

        Returns:
            Step that runs `podman build`.
        """
        return self.step(
            self.step_build_container_image,
            run=ContainerEngine.I.build_args(
                tags=(
                    self.container_image_tag_version(),
                    self.container_image_tag_latest(),
                ),
            ).multiline(),
            step=step,
        )

    def step_push_container_image_version(
        self,
        *,
        step: dict[str, Any] | None = None,
    ) -> dict[str, Any]:
        """Build a step that pushes the versioned image tag to the registry.

        Args:
            step: Additional keys to merge into the step configuration.

        Returns:
            Step that runs `podman push` for the versioned tag.
        """
        return self.step(
            self.step_push_container_image_version,
            run=ContainerEngine.I.push_args(
                tag=self.container_image_tag_version(),
            ).multiline(),
            step=step,
        )

    def step_push_container_image_latest(
        self,
        *,
        step: dict[str, Any] | None = None,
    ) -> dict[str, Any]:
        """Build a step that pushes the `latest` image tag to the registry.

        Args:
            step: Additional keys to merge into the step configuration.

        Returns:
            Step that runs `podman push` for the `latest` tag.
        """
        return self.step(
            self.step_push_container_image_latest,
            run=str(ContainerEngine.I.push_args(tag=self.container_image_tag_latest())),
            step=step,
        )

    def container_image_tag_version(self) -> str:
        """Build the project's image reference tagged with the project version.

        The version is a shell substitution expression resolved when the
        workflow runs, not the literal version at generation time.

        Returns:
            Image reference tagged with the bare project version.
        """
        return ContainerRegistry.I.image_tag(self.shell_insert_version())

    def container_image_tag_latest(self) -> str:
        """Build the project's image reference tagged `latest`."""
        return ContainerRegistry.I.image_tag("latest")

    def insert_actor(self) -> str:
        """Return the expression that resolves to the workflow actor.

        Returns:
            GitHub Actions expression for `github.actor`.
        """
        return self.insert_expression("github.actor")
container_image_tag_latest()

Build the project's image reference tagged latest.

Source code in src/pyrig_containers/rig/configs/version_control/remote/workflows/deploy.py 
185
186
187
def container_image_tag_latest(self) -> str:
    """Build the project's image reference tagged `latest`."""
    return ContainerRegistry.I.image_tag("latest")
container_image_tag_version()

Build the project's image reference tagged with the project version.

The version is a shell substitution expression resolved when the workflow runs, not the literal version at generation time.

Returns:

Type Description
str

Image reference tagged with the bare project version.
Source code in src/pyrig_containers/rig/configs/version_control/remote/workflows/deploy.py 
174
175
176
177
178
179
180
181
182
183
def container_image_tag_version(self) -> str:
    """Build the project's image reference tagged with the project version.

    The version is a shell substitution expression resolved when the
    workflow runs, not the literal version at generation time.

    Returns:
        Image reference tagged with the bare project version.
    """
    return ContainerRegistry.I.image_tag(self.shell_insert_version())
insert_actor()

Return the expression that resolves to the workflow actor.

Returns:

Type Description
str

GitHub Actions expression for github.actor.
Source code in src/pyrig_containers/rig/configs/version_control/remote/workflows/deploy.py 
189
190
191
192
193
194
195
def insert_actor(self) -> str:
    """Return the expression that resolves to the workflow actor.

    Returns:
        GitHub Actions expression for `github.actor`.
    """
    return self.insert_expression("github.actor")
job_container_image()

Build the job that builds and pushes the container image to GHCR.

Requests packages: write permission at the job level, required to push to GHCR.

Returns:

Type Description
dict[str, Any]

Dict mapping the derived job ID to its configuration.
Source code in src/pyrig_containers/rig/configs/version_control/remote/workflows/deploy.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
44
def job_container_image(self) -> dict[str, Any]:
    """Build the job that builds and pushes the container image to GHCR.

    Requests `packages: write` permission at the job level, required to
    push to GHCR.

    Returns:
        Dict mapping the derived job ID to its configuration.
    """
    return self.job(
        self.job_container_image,
        permissions={"packages": "write"},
        steps=self.steps_container_image(),
    )
jobs()

Add the container image publish job to the base jobs.

Returns:

Type Description
dict[str, Any]

Dict combining the base jobs with the container image job.
Source code in src/pyrig_containers/rig/configs/version_control/remote/workflows/deploy.py 
20
21
22
23
24
25
26
27
28
29
def jobs(self) -> dict[str, Any]:
    """Add the container image publish job to the base jobs.

    Returns:
        Dict combining the base jobs with the container image job.
    """
    return {
        **super().jobs(),
        **self.job_container_image(),
    }
step_build_container_image(*, step=None)

Build a step that builds the container image.

Tags the built image with both the versioned tag and the latest tag.

Parameters:

Name Type Description Default
step dict[str, Any] | None

Additional keys to merge into the step configuration.

 None

Returns:

Type Description
dict[str, Any]

Step that runs podman build.
Source code in src/pyrig_containers/rig/configs/version_control/remote/workflows/deploy.py 
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
def step_build_container_image(
    self,
    *,
    step: dict[str, Any] | None = None,
) -> dict[str, Any]:
    """Build a step that builds the container image.

    Tags the built image with both the versioned tag and the `latest` tag.

    Args:
        step: Additional keys to merge into the step configuration.

    Returns:
        Step that runs `podman build`.
    """
    return self.step(
        self.step_build_container_image,
        run=ContainerEngine.I.build_args(
            tags=(
                self.container_image_tag_version(),
                self.container_image_tag_latest(),
            ),
        ).multiline(),
        step=step,
    )
step_install_container_engine(*, step=None)

Build a step that installs podman on the runner.

Parameters:

Name Type Description Default
step dict[str, Any] | None

Additional keys to merge into the step configuration.

 None

Returns:

Type Description
dict[str, Any]

Step using redhat-actions/podman-install@main.
Source code in src/pyrig_containers/rig/configs/version_control/remote/workflows/deploy.py 
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
def step_install_container_engine(
    self,
    *,
    step: dict[str, Any] | None = None,
) -> dict[str, Any]:
    """Build a step that installs podman on the runner.

    Args:
        step: Additional keys to merge into the step configuration.

    Returns:
        Step using `redhat-actions/podman-install@main`.
    """
    return self.step(
        self.step_install_container_engine,
        uses="redhat-actions/podman-install@main",
        step=step,
    )
step_login_container_registry(*, step=None)

Build a step that logs podman in to the container registry.

Authenticates as the workflow actor, using the automatic GITHUB_TOKEN secret as the password.

Parameters:

Name Type Description Default
step dict[str, Any] | None

Additional keys to merge into the step configuration.

 None

Returns:

Type Description
dict[str, Any]

Step that runs podman login against the registry.
Source code in src/pyrig_containers/rig/configs/version_control/remote/workflows/deploy.py 
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def step_login_container_registry(
    self,
    *,
    step: dict[str, Any] | None = None,
) -> dict[str, Any]:
    """Build a step that logs podman in to the container registry.

    Authenticates as the workflow actor, using the automatic
    `GITHUB_TOKEN` secret as the password.

    Args:
        step: Additional keys to merge into the step configuration.

    Returns:
        Step that runs `podman login` against the registry.
    """
    return self.step(
        self.step_login_container_registry,
        run=ContainerEngine.I.login_args(
            registry=ContainerRegistry.I.host(),
            username=self.insert_actor(),
            password=self.insert_github_token(),
        ).multiline(),
        step=step,
    )
step_push_container_image_latest(*, step=None)

Build a step that pushes the latest image tag to the registry.

Parameters:

Name Type Description Default
step dict[str, Any] | None

Additional keys to merge into the step configuration.

 None

Returns:

Type Description
dict[str, Any]

Step that runs podman push for the latest tag.
Source code in src/pyrig_containers/rig/configs/version_control/remote/workflows/deploy.py 
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
def step_push_container_image_latest(
    self,
    *,
    step: dict[str, Any] | None = None,
) -> dict[str, Any]:
    """Build a step that pushes the `latest` image tag to the registry.

    Args:
        step: Additional keys to merge into the step configuration.

    Returns:
        Step that runs `podman push` for the `latest` tag.
    """
    return self.step(
        self.step_push_container_image_latest,
        run=str(ContainerEngine.I.push_args(tag=self.container_image_tag_latest())),
        step=step,
    )
step_push_container_image_version(*, step=None)

Build a step that pushes the versioned image tag to the registry.

Parameters:

Name Type Description Default
step dict[str, Any] | None

Additional keys to merge into the step configuration.

 None

Returns:

Type Description
dict[str, Any]

Step that runs podman push for the versioned tag.
Source code in src/pyrig_containers/rig/configs/version_control/remote/workflows/deploy.py 
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
def step_push_container_image_version(
    self,
    *,
    step: dict[str, Any] | None = None,
) -> dict[str, Any]:
    """Build a step that pushes the versioned image tag to the registry.

    Args:
        step: Additional keys to merge into the step configuration.

    Returns:
        Step that runs `podman push` for the versioned tag.
    """
    return self.step(
        self.step_push_container_image_version,
        run=ContainerEngine.I.push_args(
            tag=self.container_image_tag_version(),
        ).multiline(),
        step=step,
    )
steps_container_image()

Build the ordered steps for the publish-container-image job.

Returns:

Type Description
list[dict[str, Any]]

Ordered list of step dicts: core setup, install the container
list[dict[str, Any]]

engine, log in to the registry, build the image, then push the
list[dict[str, Any]]

versioned tag and the latest tag.
Source code in src/pyrig_containers/rig/configs/version_control/remote/workflows/deploy.py 
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
def steps_container_image(self) -> list[dict[str, Any]]:
    """Build the ordered steps for the publish-container-image job.

    Returns:
        Ordered list of step dicts: core setup, install the container
        engine, log in to the registry, build the image, then push the
        versioned tag and the latest tag.
    """
    return [
        *self.steps_core_setup(),
        self.step_install_container_engine(),
        self.step_login_container_registry(),
        self.step_build_container_image(),
        self.step_push_container_image_version(),
        self.step_push_container_image_latest(),
    ]

tools

Container-specific overrides and additions for pyrig's CLI tool wrappers.

containers

Tools for building and publishing container images.

engine

Podman command construction for authenticating, building, and publishing images.

ContainerEngine

Bases: Tool

podman command wrapper.

Constructs podman command arguments for authenticating with a registry and building and pushing container images. Typical usage: call login_args to authenticate, build_args to build and tag the image, then push_args to publish each tag to the registry.

Source code in src/pyrig_containers/rig/tools/containers/engine.py 
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
class ContainerEngine(Tool):
    """`podman` command wrapper.

    Constructs `podman` command arguments for authenticating with a registry
    and building and pushing container images. Typical usage: call
    `login_args` to authenticate, `build_args` to build and tag the image,
    then `push_args` to publish each tag to the registry.
    """

    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 name(self) -> str:
        """Return `"podman"`."""
        return "podman"

    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 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 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)
build_args(*args, tags=(), context='.')

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.

Parameters:

Name Type Description Default
*args str

Additional arguments appended before the context (e.g. --file to point at a specific Containerfile, or --no-cache).

 ()
tags Iterable[str]

Image references to tag the built image with. Defaults to none.

 ()
context str

Build context directory. Defaults to the current directory.

 '.'

Returns:

Type Description
Args

Args for the podman build command.
Source code in src/pyrig_containers/rig/tools/containers/engine.py 
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
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)
dev_dependencies()

Return an empty tuple; podman is a system package, not a Python one.

Source code in src/pyrig_containers/rig/tools/containers/engine.py 
18
19
20
def dev_dependencies(self) -> tuple[str, ...]:
    """Return an empty tuple; `podman` is a system package, not a Python one."""
    return ()
group()

Return Group.TOOLING.

Source code in src/pyrig_containers/rig/tools/containers/engine.py 
22
23
24
def group(self) -> str:
    """Return `Group.TOOLING`."""
    return Group.TOOLING
image_url()

Return the Shields.io badge URL for podman.

Source code in src/pyrig_containers/rig/tools/containers/engine.py 
26
27
28
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"
link_url()

Return the URL of the podman project page.

Source code in src/pyrig_containers/rig/tools/containers/engine.py 
30
31
32
def link_url(self) -> str:
    """Return the URL of the `podman` project page."""
    return "https://podman.io"
login_args(*args, registry, username, password)

Build args to authenticate the container engine with a registry.

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

Parameters:

Name Type Description Default
*args str

Additional arguments appended to the command.

 ()
registry str

Registry host to authenticate against (e.g. ghcr.io).

 required
username str

Account name to log in as.

 required
password str

Token or password for the account.

 required

Returns:

Type Description
Args

Args for the podman login command.
Source code in src/pyrig_containers/rig/tools/containers/engine.py 
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
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,
    )
name()

Return "podman".

Source code in src/pyrig_containers/rig/tools/containers/engine.py 
34
35
36
def name(self) -> str:
    """Return `"podman"`."""
    return "podman"
push_args(*args, tag)

Build args to push a tagged image to its registry.

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

Parameters:

Name Type Description Default
*args str

Additional arguments appended to the command.

 ()
tag str

Fully qualified image reference to push (e.g. ghcr.io/owner/repo:latest).

 required

Returns:

Type Description
Args

Args for the podman push command.
Source code in src/pyrig_containers/rig/tools/containers/engine.py 
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
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)
registry

Container registry identity and badge metadata for publishing images.

ContainerRegistry

Bases: Tool

GitHub Container Registry (GHCR) wrapper.

Provides the registry host, the project's fully qualified image reference within it, and badge metadata for GHCR.

Source code in src/pyrig_containers/rig/tools/containers/registry.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
class ContainerRegistry(Tool):
    """GitHub Container Registry (GHCR) wrapper.

    Provides the registry host, the project's fully qualified image
    reference within it, and badge metadata for GHCR.
    """

    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 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 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_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 host(self) -> str:
        """Return `"ghcr.io"`."""
        return "ghcr.io"
dev_dependencies()

Return an empty tuple; the registry requires no Python package.

Source code in src/pyrig_containers/rig/tools/containers/registry.py 
17
18
19
def dev_dependencies(self) -> tuple[str, ...]:
    """Return an empty tuple; the registry requires no Python package."""
    return ()
group()

Return Group.PROJECT_INFO.

Source code in src/pyrig_containers/rig/tools/containers/registry.py 
21
22
23
def group(self) -> str:
    """Return `Group.PROJECT_INFO`."""
    return Group.PROJECT_INFO
host()

Return "ghcr.io".

Source code in src/pyrig_containers/rig/tools/containers/registry.py 
63
64
65
def host(self) -> str:
    """Return `"ghcr.io"`."""
    return "ghcr.io"
image_name()

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:

Type Description
str

Image name in the form ghcr.io/<owner>/<project>.
Source code in src/pyrig_containers/rig/tools/containers/registry.py 
50
51
52
53
54
55
56
57
58
59
60
61
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}"
image_tag(tag)

Build the project's image reference for the given tag.

Parameters:

Name Type Description Default
tag str

Tag to append to the image name (e.g. latest or 1.2.3).

 required

Returns:

Type Description
str

Image reference in the form ghcr.io/<owner>/<project>:<tag>.
Source code in src/pyrig_containers/rig/tools/containers/registry.py 
39
40
41
42
43
44
45
46
47
48
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}"
image_url()

Return the Shields.io badge URL for GHCR.

Source code in src/pyrig_containers/rig/tools/containers/registry.py 
25
26
27
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"
link_url()

Return the URL of the project's GHCR container package page.

Source code in src/pyrig_containers/rig/tools/containers/registry.py 
29
30
31
32
33
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}"
name()

Return "ghcr".

Source code in src/pyrig_containers/rig/tools/containers/registry.py 
35
36
37
def name(self) -> str:
    """Return `"ghcr"`."""
    return "ghcr"

packages

Container-specific overrides for pyrig's package-manager tool.

manager

Container-specific conventions for the project's package manager.

PackageManager

Bases: PackageManager

uv package manager, extended with a container-image convention.

Adds container_image, which supplies the image and paths needed to embed the uv binary in a container image.

Source code in src/pyrig_containers/rig/tools/packages/manager.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
class PackageManager(BasePackageManager):
    """`uv` package manager, extended with a container-image convention.

    Adds `container_image`, which supplies the image and paths needed to
    embed the `uv` binary in a container image.
    """

    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"
container_image()

Return the image and paths for copying uv into a container image.

Returns:

Type Description
tuple[str, str, str]

Tuple of (image, path_in_source_image, path_in_target_image).
Source code in src/pyrig_containers/rig/tools/packages/manager.py 
13
14
15
16
17
18
19
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"