Skip to content

API Reference

The top-level package for the project.

rig

Package initialization.

configs

Package initialization.

pyproject

Configuration management for pyproject.toml.

Provides the PyprojectConfigFile class, which generates and validates the project's pyproject.toml according to PEP 518, 621, and 660. Covers project metadata, runtime and development dependencies, build system configuration, and tool settings.

PyprojectConfigFile

Bases: PyprojectConfigFile

Pyproject config that adds PyPI trove classifiers and keywords.

Source code in src/pyrig_pypi/rig/configs/pyproject.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
class PyprojectConfigFile(BasePyprojectConfigFile):
    """Pyproject config that adds PyPI trove classifiers and keywords."""

    def _configs(self) -> ConfigDict:
        """Extend the base config with PyPI classifiers and keywords.

        Adds the ``project.classifiers`` and ``project.keywords`` fields to the
        base pyproject.toml configuration.

        Returns:
            The base configuration dict with the ``project`` table augmented.
        """
        configs = super()._configs()
        project: ConfigDict = configs["project"]
        project["classifiers"] = self.make_classifiers()
        project["keywords"] = self.make_keywords()
        return configs

    def make_classifiers(self) -> list[str]:
        """Build the PyPI trove classifiers for the project.

        Generates a ``Programming Language :: Python :: X.Y`` classifier for every
        Python minor version in the project's supported range (derived from
        ``requires-python``), plus the fixed classifiers
        ``Programming Language :: Python``, ``Programming Language :: Python :: 3``,
        ``Programming Language :: Python :: 3 :: Only``,
        ``Operating System :: OS Independent`` and ``Typing :: Typed``.

        Returns:
            List of trove classifier strings, ready for the ``project.classifiers``
            field in pyproject.toml.
        """
        return [
            "Programming Language :: Python",
            "Programming Language :: Python :: 3",
            "Programming Language :: Python :: 3 :: Only",
            *(
                f"Programming Language :: Python :: {v.major}.{v.minor}"
                for v in self.supported_python_versions()
            ),
            "Operating System :: OS Independent",
            "Typing :: Typed",
        ]

    def make_keywords(self) -> list[str]:
        """Get the PyPI keywords for this project.

        Adds the ``pyrig`` ecosystem keyword. It is universally accurate
        because any package published through this plugin is a pyrig project,
        and it aids discoverability of the pyrig ecosystem in PyPI search.

        Returns:
            ``["pyrig"]``
        """
        return [Pyrigger.I.name()]
_configs()

Extend the base config with PyPI classifiers and keywords.

Adds the project.classifiers and project.keywords fields to the base pyproject.toml configuration.

Returns:

Type Description
ConfigDict

The base configuration dict with the project table augmented.
Source code in src/pyrig_pypi/rig/configs/pyproject.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
def _configs(self) -> ConfigDict:
    """Extend the base config with PyPI classifiers and keywords.

    Adds the ``project.classifiers`` and ``project.keywords`` fields to the
    base pyproject.toml configuration.

    Returns:
        The base configuration dict with the ``project`` table augmented.
    """
    configs = super()._configs()
    project: ConfigDict = configs["project"]
    project["classifiers"] = self.make_classifiers()
    project["keywords"] = self.make_keywords()
    return configs
make_classifiers()

Build the PyPI trove classifiers for the project.

Generates a Programming Language :: Python :: X.Y classifier for every Python minor version in the project's supported range (derived from requires-python), plus the fixed classifiers Programming Language :: Python, Programming Language :: Python :: 3, Programming Language :: Python :: 3 :: Only, Operating System :: OS Independent and Typing :: Typed.

Returns:

Type Description
list[str]

List of trove classifier strings, ready for the project.classifiers
list[str]

field in pyproject.toml.
Source code in src/pyrig_pypi/rig/configs/pyproject.py 
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
def make_classifiers(self) -> list[str]:
    """Build the PyPI trove classifiers for the project.

    Generates a ``Programming Language :: Python :: X.Y`` classifier for every
    Python minor version in the project's supported range (derived from
    ``requires-python``), plus the fixed classifiers
    ``Programming Language :: Python``, ``Programming Language :: Python :: 3``,
    ``Programming Language :: Python :: 3 :: Only``,
    ``Operating System :: OS Independent`` and ``Typing :: Typed``.

    Returns:
        List of trove classifier strings, ready for the ``project.classifiers``
        field in pyproject.toml.
    """
    return [
        "Programming Language :: Python",
        "Programming Language :: Python :: 3",
        "Programming Language :: Python :: 3 :: Only",
        *(
            f"Programming Language :: Python :: {v.major}.{v.minor}"
            for v in self.supported_python_versions()
        ),
        "Operating System :: OS Independent",
        "Typing :: Typed",
    ]
make_keywords()

Get the PyPI keywords for this project.

Adds the pyrig ecosystem keyword. It is universally accurate because any package published through this plugin is a pyrig project, and it aids discoverability of the pyrig ecosystem in PyPI search.

Returns:

Type Description
list[str]

["pyrig"]
Source code in src/pyrig_pypi/rig/configs/pyproject.py 
57
58
59
60
61
62
63
64
65
66
67
def make_keywords(self) -> list[str]:
    """Get the PyPI keywords for this project.

    Adds the ``pyrig`` ecosystem keyword. It is universally accurate
    because any package published through this plugin is a pyrig project,
    and it aids discoverability of the pyrig ecosystem in PyPI search.

    Returns:
        ``["pyrig"]``
    """
    return [Pyrigger.I.name()]

remote_version_control

Package initialization.

workflows

Package initialization.

deploy

GitHub Actions workflow for deploying.

Provides the DeployWorkflowConfigFile class, which generates the .github/workflows/deploy.yml workflow file. This workflow is the final step in the automated CI/CD pipeline and runs after a successful release.

DeployWorkflowConfigFile

Bases: DeployWorkflowConfigFile

Deploy workflow that adds a build-and-publish-to-PyPI job after release.

Source code in src/pyrig_pypi/rig/configs/remote_version_control/workflows/deploy.py 
 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
class DeployWorkflowConfigFile(BaseDeployWorkflowConfigFile):
    """Deploy workflow that adds a build-and-publish-to-PyPI job after release."""

    def jobs(self) -> ConfigDict:
        """Get the jobs for the deploy workflow.

        Combines the base jobs with the package publish job.
        """
        return {
            **super().jobs(),
            **self.job_package(),
        }

    def job_package(self) -> ConfigDict:
        """Build the job that packages and publishes the project to PyPI.

        The job runs only when the triggering workflow run succeeded. Steps
        are provided by :meth:`steps_package`.

        Returns:
            Dict mapping the derived job ID to its configuration.
        """
        return self.job(
            job_func=self.job_package,
            steps=self.steps_package(),
            if_condition=self.if_workflow_run_is_success(),
        )

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

        Combines core setup with a distribution build and a PyPI publish step.
        The publish step authenticates with the ``PYPI_TOKEN`` repository secret.

        Returns:
            Ordered list of step dicts: core setup, build wheel and source
            distributions, publish to PyPI.
        """
        return [
            *self.steps_core_setup(),
            self.step_build_package(),
            self.step_publish_package(),
        ]

    def step_build_package(
        self,
        *,
        step: dict[str, Any] | None = None,
    ) -> dict[str, Any]:
        """Build a step that packages the project for distribution.

        Runs ``uv build`` to produce wheel and source distributions in the
        ``dist/`` directory.

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

        Returns:
            Step that runs ``uv build``.
        """
        return self.step(
            step_func=self.step_build_package,
            run=str(PackageManager.I.build_args()),
            step=step,
        )

    def step_publish_package(
        self,
        *,
        step: dict[str, Any] | None = None,
    ) -> dict[str, Any]:
        """Build a step that publishes the distributions to PyPI.

        Runs ``uv publish`` authenticated with the ``PYPI_TOKEN`` repository
        secret, injected as the ``${{ secrets.PYPI_TOKEN }}`` expression.

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

        Returns:
            Step that publishes to PyPI using ``PYPI_TOKEN``.
        """
        return self.step(
            step_func=self.step_publish_package,
            run=str(PackageManager.I.publish_args(token=self.insert_pypi_token())),
            step=step,
        )

    def insert_pypi_token(self) -> str:
        """Get the ``${{ secrets.PYPI_TOKEN }}`` expression.

        Returns:
            GitHub Actions expression for the ``PYPI_TOKEN`` secret.
        """
        return self.insert_var(self.pypi_token_var())

    def pypi_token_var(self) -> str:
        """Get the raw secrets expression for ``PYPI_TOKEN``.

        Returns:
            ``"secrets.PYPI_TOKEN"``
        """
        return self.secrets_var(PackageIndex.I.access_token_key())
insert_pypi_token()

Get the ${{ secrets.PYPI_TOKEN }} expression.

Returns:

Type Description
str

GitHub Actions expression for the PYPI_TOKEN secret.
Source code in src/pyrig_pypi/rig/configs/remote_version_control/workflows/deploy.py 
107
108
109
110
111
112
113
def insert_pypi_token(self) -> str:
    """Get the ``${{ secrets.PYPI_TOKEN }}`` expression.

    Returns:
        GitHub Actions expression for the ``PYPI_TOKEN`` secret.
    """
    return self.insert_var(self.pypi_token_var())
job_package()

Build the job that packages and publishes the project to PyPI.

The job runs only when the triggering workflow run succeeded. Steps are provided by :meth:steps_package.

Returns:

Type Description
ConfigDict

Dict mapping the derived job ID to its configuration.
Source code in src/pyrig_pypi/rig/configs/remote_version_control/workflows/deploy.py 
32
33
34
35
36
37
38
39
40
41
42
43
44
45
def job_package(self) -> ConfigDict:
    """Build the job that packages and publishes the project to PyPI.

    The job runs only when the triggering workflow run succeeded. Steps
    are provided by :meth:`steps_package`.

    Returns:
        Dict mapping the derived job ID to its configuration.
    """
    return self.job(
        job_func=self.job_package,
        steps=self.steps_package(),
        if_condition=self.if_workflow_run_is_success(),
    )
jobs()

Get the jobs for the deploy workflow.

Combines the base jobs with the package publish job.

Source code in src/pyrig_pypi/rig/configs/remote_version_control/workflows/deploy.py 
22
23
24
25
26
27
28
29
30
def jobs(self) -> ConfigDict:
    """Get the jobs for the deploy workflow.

    Combines the base jobs with the package publish job.
    """
    return {
        **super().jobs(),
        **self.job_package(),
    }
pypi_token_var()

Get the raw secrets expression for PYPI_TOKEN.

Returns:

Type Description
str

"secrets.PYPI_TOKEN"
Source code in src/pyrig_pypi/rig/configs/remote_version_control/workflows/deploy.py 
115
116
117
118
119
120
121
def pypi_token_var(self) -> str:
    """Get the raw secrets expression for ``PYPI_TOKEN``.

    Returns:
        ``"secrets.PYPI_TOKEN"``
    """
    return self.secrets_var(PackageIndex.I.access_token_key())
step_build_package(*, step=None)

Build a step that packages the project for distribution.

Runs uv build to produce wheel and source distributions in the dist/ directory.

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 uv build.
Source code in src/pyrig_pypi/rig/configs/remote_version_control/workflows/deploy.py 
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
def step_build_package(
    self,
    *,
    step: dict[str, Any] | None = None,
) -> dict[str, Any]:
    """Build a step that packages the project for distribution.

    Runs ``uv build`` to produce wheel and source distributions in the
    ``dist/`` directory.

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

    Returns:
        Step that runs ``uv build``.
    """
    return self.step(
        step_func=self.step_build_package,
        run=str(PackageManager.I.build_args()),
        step=step,
    )
step_publish_package(*, step=None)

Build a step that publishes the distributions to PyPI.

Runs uv publish authenticated with the PYPI_TOKEN repository secret, injected as the ${{ secrets.PYPI_TOKEN }} expression.

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 publishes to PyPI using PYPI_TOKEN.
Source code in src/pyrig_pypi/rig/configs/remote_version_control/workflows/deploy.py 
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
def step_publish_package(
    self,
    *,
    step: dict[str, Any] | None = None,
) -> dict[str, Any]:
    """Build a step that publishes the distributions to PyPI.

    Runs ``uv publish`` authenticated with the ``PYPI_TOKEN`` repository
    secret, injected as the ``${{ secrets.PYPI_TOKEN }}`` expression.

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

    Returns:
        Step that publishes to PyPI using ``PYPI_TOKEN``.
    """
    return self.step(
        step_func=self.step_publish_package,
        run=str(PackageManager.I.publish_args(token=self.insert_pypi_token())),
        step=step,
    )
steps_package()

Build the ordered steps for the publish-package job.

Combines core setup with a distribution build and a PyPI publish step. The publish step authenticates with the PYPI_TOKEN repository secret.

Returns:

Type Description
list[dict[str, Any]]

Ordered list of step dicts: core setup, build wheel and source
list[dict[str, Any]]

distributions, publish to PyPI.
Source code in src/pyrig_pypi/rig/configs/remote_version_control/workflows/deploy.py 
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
def steps_package(self) -> list[dict[str, Any]]:
    """Build the ordered steps for the publish-package job.

    Combines core setup with a distribution build and a PyPI publish step.
    The publish step authenticates with the ``PYPI_TOKEN`` repository secret.

    Returns:
        Ordered list of step dicts: core setup, build wheel and source
        distributions, publish to PyPI.
    """
    return [
        *self.steps_core_setup(),
        self.step_build_package(),
        self.step_publish_package(),
    ]

tools

Package initialization.

package_index

Package index tool wrapper.

Wraps commands and information of the package index tool.

PackageIndex

Bases: Tool

PyPI package index wrapper.

Constructs the PyPI project URL and shields.io version badge for the current project. The package name is read from PackageManager.I.project_name().

Source code in src/pyrig_pypi/rig/tools/package_index.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
class PackageIndex(Tool):
    """PyPI package index wrapper.

    Constructs the PyPI project URL and shields.io version badge for the
    current project. The package name is read from ``PackageManager.I.project_name()``.
    """

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

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

    def image_url(self) -> str:
        """Get the PyPI version badge URL."""
        repo = PackageManager.I.project_name()
        return f"https://img.shields.io/pypi/v/{repo}?logo=pypi&logoColor=white"

    def link_url(self) -> str:
        """Get the PyPI project page URL."""
        repo = PackageManager.I.project_name()
        return f"https://pypi.org/project/{repo}"

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

        Returns an empty tuple because PyPI itself requires no extra
        development dependency; publishing is handled by the package
        manager (e.g. uv) via ``pyproject.toml``.

        Returns:
            Empty tuple.
        """
        return ()

    def access_token_key(self) -> str:
        """Get the environment variable key for the PyPI access token.

        Used in CI/CD pipelines to authenticate when publishing packages
        to PyPI.

        Returns:
            ``'PYPI_TOKEN'``
        """
        return "PYPI_TOKEN"
access_token_key()

Get the environment variable key for the PyPI access token.

Used in CI/CD pipelines to authenticate when publishing packages to PyPI.

Returns:

Type Description
str

'PYPI_TOKEN'
Source code in src/pyrig_pypi/rig/tools/package_index.py 
47
48
49
50
51
52
53
54
55
56
def access_token_key(self) -> str:
    """Get the environment variable key for the PyPI access token.

    Used in CI/CD pipelines to authenticate when publishing packages
    to PyPI.

    Returns:
        ``'PYPI_TOKEN'``
    """
    return "PYPI_TOKEN"
dev_dependencies()

Get development dependencies for this tool.

Returns an empty tuple because PyPI itself requires no extra development dependency; publishing is handled by the package manager (e.g. uv) via pyproject.toml.

Returns:

Type Description
tuple[str, ...]

Empty tuple.
Source code in src/pyrig_pypi/rig/tools/package_index.py 
35
36
37
38
39
40
41
42
43
44
45
def dev_dependencies(self) -> tuple[str, ...]:
    """Get development dependencies for this tool.

    Returns an empty tuple because PyPI itself requires no extra
    development dependency; publishing is handled by the package
    manager (e.g. uv) via ``pyproject.toml``.

    Returns:
        Empty tuple.
    """
    return ()
group()

Returns the group the tool belongs to.

Source code in src/pyrig_pypi/rig/tools/package_index.py 
21
22
23
def group(self) -> str:
    """Returns the group the tool belongs to."""
    return Group.PROJECT_INFO
image_url()

Get the PyPI version badge URL.

Source code in src/pyrig_pypi/rig/tools/package_index.py 
25
26
27
28
def image_url(self) -> str:
    """Get the PyPI version badge URL."""
    repo = PackageManager.I.project_name()
    return f"https://img.shields.io/pypi/v/{repo}?logo=pypi&logoColor=white"

Get the PyPI project page URL.

Source code in src/pyrig_pypi/rig/tools/package_index.py 
30
31
32
33
def link_url(self) -> str:
    """Get the PyPI project page URL."""
    repo = PackageManager.I.project_name()
    return f"https://pypi.org/project/{repo}"
name()

Get tool name.

Source code in src/pyrig_pypi/rig/tools/package_index.py 
17
18
19
def name(self) -> str:
    """Get tool name."""
    return "pypi"

package_manager

Package manager wrapper.

Wraps PackageManager commands and information.

PackageManager

Bases: PackageManager

Package manager that adds PyPI publish arguments to the uv commands.

Source code in src/pyrig_pypi/rig/tools/package_manager.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
class PackageManager(BasePackageManager):
    """Package manager that adds PyPI publish arguments to the uv commands."""

    def publish_args(self, *args: str, token: str) -> Args:
        """Construct ``Args`` for publishing the package to PyPI.

        Args:
            *args: Additional arguments for the publish command.
            token: PyPI authentication token (keyword-only).

        Returns:
            Args for ``uv publish --token <token> <args...>``.
        """
        return self.args("publish", "--token", token, *args)
publish_args(*args, token)

Construct Args for publishing the package to PyPI.

Parameters:

Name Type Description Default
*args str

Additional arguments for the publish command.

 ()
token str

PyPI authentication token (keyword-only).

 required

Returns:

Type Description
Args

Args for uv publish --token <token> <args...>.
Source code in src/pyrig_pypi/rig/tools/package_manager.py 
13
14
15
16
17
18
19
20
21
22
23
def publish_args(self, *args: str, token: str) -> Args:
    """Construct ``Args`` for publishing the package to PyPI.

    Args:
        *args: Additional arguments for the publish command.
        token: PyPI authentication token (keyword-only).

    Returns:
        Args for ``uv publish --token <token> <args...>``.
    """
    return self.args("publish", "--token", token, *args)

programming_language

Programming language tool wrapper.

Wraps ProgrammingLanguage commands and information.

ProgrammingLanguage

Bases: ProgrammingLanguage

Programming language tool that badges the project with PyPI pyversions.

Source code in src/pyrig_pypi/rig/tools/programming_language.py 
12
13
14
15
16
17
18
19
class ProgrammingLanguage(BaseProgrammingLanguage):
    """Programming language tool that badges the project with PyPI pyversions."""

    def image_url(self) -> str:
        """Override to use pyversion badge instead of a static logo."""
        return (
            f"https://img.shields.io/pypi/pyversions/{PackageManager.I.project_name()}"
        )
image_url()

Override to use pyversion badge instead of a static logo.

Source code in src/pyrig_pypi/rig/tools/programming_language.py 
15
16
17
18
19
def image_url(self) -> str:
    """Override to use pyversion badge instead of a static logo."""
    return (
        f"https://img.shields.io/pypi/pyversions/{PackageManager.I.project_name()}"
    )