Skip to content

API Reference

The top-level package for the project.

rig

Package initialization.

configs

Package initialization.

container_file

Containerfile configuration management.

ContainerfileConfigFile

Bases: StringConfigFile

Generates a production-ready Containerfile for the project.

Produces a Containerfile with a Python slim base image, uv as the package manager, a non-root runtime user (appuser, UID 1000), and layer ordering optimized for cache reuse. Compatible with Docker, Podman, and buildah.

Source code in src/pyrig_containers/rig/configs/container_file.py 
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
class ContainerfileConfigFile(StringConfigFile):
    """Generates a production-ready Containerfile for the project.

    Produces a Containerfile with a Python slim base image, uv as the package
    manager, a non-root runtime user (appuser, UID 1000), and layer ordering
    optimized for cache reuse. Compatible with Docker, Podman, and buildah.
    """

    def stem(self) -> str:
        """Return the filename stem 'Containerfile'."""
        return "Containerfile"

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

    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 base class default separator '.'.

        Prevents the base class from appending a dot to the filename, since
        Containerfile uses neither an extension nor a separator.
        """
        return ""

    def lines(self) -> list[str]:
        """Return the Containerfile build instructions.

        Returns:
            List of instruction lines produced by `layers()`.
        """
        return self.layers()

    def layers(self) -> list[str]:
        """Generate the complete sequence of Containerfile build instructions.

        Produces an optimized layer order so that infrequently changing files
        (project metadata and lock file) are copied before the source tree is
        added. This maximizes Docker/Podman build cache reuse when only source
        code changes.

        Returns:
            List of Containerfile instruction strings followed by a trailing
            empty string.

        Note:
            Reads ``requires-python`` from ``pyproject.toml`` and falls back to
            the bundled ``LATEST_PYTHON_VERSION`` resource file when no upper
            bound is specified.
        """
        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_user_name = "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",
            f"WORKDIR /{workdir}",
            f"COPY --from={image_url} {image_source_path} {image_destination_path}",
            f"COPY {copy_files} ./",
            f"RUN useradd -m -u 1000 {app_user_name}",
            f"RUN chown -R {app_user_name}:{app_user_name} .",
            f"USER {app_user_name}",
            f"COPY --chown={app_user_name}:{app_user_name} {package_root} {package_root}",  # noqa: E501
            f"RUN {install_dependencies_no_dev}",
            f"RUN rm {copy_files}",
            f"ENTRYPOINT {entrypoint}",
            "",
        ]
extension()

Return an empty string (Containerfile has no file extension).

Source code in src/pyrig_containers/rig/configs/container_file.py 
29
30
31
def extension(self) -> str:
    """Return an empty string (Containerfile has no file extension)."""
    return ""
extension_separator()

Return an empty string, overriding the base class default separator '.'.

Prevents the base class from appending a dot to the filename, since Containerfile uses neither an extension nor a separator.

Source code in src/pyrig_containers/rig/configs/container_file.py 
33
34
35
36
37
38
39
def extension_separator(self) -> str:
    """Return an empty string, overriding the base class default separator '.'.

    Prevents the base class from appending a dot to the filename, since
    Containerfile uses neither an extension nor a separator.
    """
    return ""
layers()

Generate the complete sequence of Containerfile build instructions.

Produces an optimized layer order so that infrequently changing files (project metadata and lock file) are copied before the source tree is added. This maximizes Docker/Podman build cache reuse when only source code changes.

Returns:

Type Description
list[str]

List of Containerfile instruction strings followed by a trailing
list[str]

empty string.
Note

Reads requires-python from pyproject.toml and falls back to the bundled LATEST_PYTHON_VERSION resource file when no upper bound is specified.

Source code in src/pyrig_containers/rig/configs/container_file.py 
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
def layers(self) -> list[str]:
    """Generate the complete sequence of Containerfile build instructions.

    Produces an optimized layer order so that infrequently changing files
    (project metadata and lock file) are copied before the source tree is
    added. This maximizes Docker/Podman build cache reuse when only source
    code changes.

    Returns:
        List of Containerfile instruction strings followed by a trailing
        empty string.

    Note:
        Reads ``requires-python`` from ``pyproject.toml`` and falls back to
        the bundled ``LATEST_PYTHON_VERSION`` resource file when no upper
        bound is specified.
    """
    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_user_name = "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",
        f"WORKDIR /{workdir}",
        f"COPY --from={image_url} {image_source_path} {image_destination_path}",
        f"COPY {copy_files} ./",
        f"RUN useradd -m -u 1000 {app_user_name}",
        f"RUN chown -R {app_user_name}:{app_user_name} .",
        f"USER {app_user_name}",
        f"COPY --chown={app_user_name}:{app_user_name} {package_root} {package_root}",  # noqa: E501
        f"RUN {install_dependencies_no_dev}",
        f"RUN rm {copy_files}",
        f"ENTRYPOINT {entrypoint}",
        "",
    ]
lines()

Return the Containerfile build instructions.

Returns:

Type Description
list[str]

List of instruction lines produced by layers().
Source code in src/pyrig_containers/rig/configs/container_file.py 
41
42
43
44
45
46
47
def lines(self) -> list[str]:
    """Return the Containerfile build instructions.

    Returns:
        List of instruction lines produced by `layers()`.
    """
    return self.layers()
parent_path()

Return the project root directory.

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

Return the filename stem 'Containerfile'.

Source code in src/pyrig_containers/rig/configs/container_file.py 
21
22
23
def stem(self) -> str:
    """Return the filename stem 'Containerfile'."""
    return "Containerfile"

tools

Package initialization.

container_engine

Container engine wrapper.

Wraps container engine commands and information.

ContainerEngine

Bases: Tool

Container engine wrapper.

Constructs podman command arguments for building and saving container images. Typical usage: call build_args to build the image, then save_args to export it as a tar archive.

Source code in src/pyrig_containers/rig/tools/container_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
class ContainerEngine(Tool):
    """Container engine wrapper.

    Constructs podman command arguments for building and saving container images.
    Typical usage: call ``build_args`` to build the image, then ``save_args``
    to export it as a tar archive.
    """

    def name(self) -> str:
        """Get tool name.

        Returns:
            'podman'
        """
        return "podman"

    def group(self) -> str:
        """Returns the group the tool belongs to."""
        return Group.TOOLING

    def image_url(self) -> str:
        """Return the badge image URL for this tool.

        Returns:
            The URL of the badge image as a string.
        """
        return "https://img.shields.io/badge/Container-Podman-A23CD6?logo=podman&logoColor=grey&colorA=0D1F3F&colorB=A23CD6"

    def link_url(self) -> str:
        """Return the URL that the badge should link to for this tool.

        Returns:
            The URL of the project page as a string.
        """
        return "https://podman.io"

    def dev_dependencies(self) -> tuple[str, ...]:
        """Get tool dependencies.

        Podman is a system package (not a Python dependency), so this
        returns an empty tuple.

        Returns:
            Empty tuple — podman must be installed at the OS level.
        """
        return ()
dev_dependencies()

Get tool dependencies.

Podman is a system package (not a Python dependency), so this returns an empty tuple.

Returns:

Type Description
tuple[str, ...]

Empty tuple — podman must be installed at the OS level.
Source code in src/pyrig_containers/rig/tools/container_engine.py 
45
46
47
48
49
50
51
52
53
54
def dev_dependencies(self) -> tuple[str, ...]:
    """Get tool dependencies.

    Podman is a system package (not a Python dependency), so this
    returns an empty tuple.

    Returns:
        Empty tuple — podman must be installed at the OS level.
    """
    return ()
group()

Returns the group the tool belongs to.

Source code in src/pyrig_containers/rig/tools/container_engine.py 
25
26
27
def group(self) -> str:
    """Returns the group the tool belongs to."""
    return Group.TOOLING
image_url()

Return the badge image URL for this tool.

Returns:

Type Description
str

The URL of the badge image as a string.
Source code in src/pyrig_containers/rig/tools/container_engine.py 
29
30
31
32
33
34
35
def image_url(self) -> str:
    """Return the badge image URL for this tool.

    Returns:
        The URL of the badge image as a string.
    """
    return "https://img.shields.io/badge/Container-Podman-A23CD6?logo=podman&logoColor=grey&colorA=0D1F3F&colorB=A23CD6"

Return the URL that the badge should link to for this tool.

Returns:

Type Description
str

The URL of the project page as a string.
Source code in src/pyrig_containers/rig/tools/container_engine.py 
37
38
39
40
41
42
43
def link_url(self) -> str:
    """Return the URL that the badge should link to for this tool.

    Returns:
        The URL of the project page as a string.
    """
    return "https://podman.io"
name()

Get tool name.

Returns:

Type Description
str

'podman'
Source code in src/pyrig_containers/rig/tools/container_engine.py 
17
18
19
20
21
22
23
def name(self) -> str:
    """Get tool name.

    Returns:
        'podman'
    """
    return "podman"

package_manager

Package manager wrapper.

Wraps PackageManager commands and information.

PackageManager

Bases: PackageManager

You can override methods from the base class to customize behavior.

Source code in src/pyrig_containers/rig/tools/package_manager.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
class PackageManager(BasePackageManager):
    """You can override methods from the base class to customize behavior."""

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

        Used when generating a ``Containerfile`` to add a
        ``COPY --from=<image> <src> <dst>`` directive that installs uv
        into the container image.

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

Return the container image coordinates for copying uv.

Used when generating a Containerfile to add a COPY --from=<image> <src> <dst> directive that installs uv into the container image.

Returns:

Type Description
tuple[str, str, str]

Tuple of (image_name, path_in_source_image, path_in_target_image).
Source code in src/pyrig_containers/rig/tools/package_manager.py 
12
13
14
15
16
17
18
19
20
21
22
def container_image(self) -> tuple[str, str, str]:
    """Return the container image coordinates for copying uv.

    Used when generating a ``Containerfile`` to add a
    ``COPY --from=<image> <src> <dst>`` directive that installs uv
    into the container image.

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