Skip to content

Home

CI CD ProjectTester

ByteOrderMarkerFormatter CICDLinter CICDSecurityChecker CaseConflictChecker DependencyChecker EndOfFileFormatter EndOfLineFormatter JSONFormatter JSONLinter LargeFileChecker MarkdownLinter MergeConflictChecker ModuleTestNamingChecker PythonLinter SecretsChecker SecurityChecker ShellFormatter ShellLinter SpellChecker TOMLLinter TrailingWhitespaceFormatter TypeChecker YAMLLinter

PackageManager Pyrigger RemoteVersionController VersionControlHookManager VersionController

DocsBuilder PackageIndex ProgrammingLanguage License

A pyrig plugin for publishing Python packages to PyPI.

Overview

Drop-in pyrig plugin that wires PyPI into your project:

  • Adds a build-and-publish-to-PyPI job to the deploy workflow that runs after a successful release.
  • Replaces the static Python badge with one sourced from PyPI's pyversions endpoint, and adds a badge for the package's current version on PyPI.

No pyrig configuration to write by hand — installing the package as a development dependency and regenerating your pyrig configs as usual is enough for the plugin's overrides to be picked up automatically. Publishing itself needs a one-time trusted publisher setup on PyPI before the first release.

Installation

uv add pyrig-pypi --dev
uv run pyrig sync

Setup

One-time setup before the first publish. Do not create a PyPI API token.

  1. Sign in at pypi.org.
  2. Open the publisher form, depending on whether the project already exists on PyPI:
    • New project — open Your account, select Publishing in the account sidebar, and add a pending publisher under the GitHub section.
    • Existing project — open Your projects, select Manage for the project, select Publishing in the project's sidebar, and add a publisher under the GitHub section.
  3. Fill in the publisher form:
    • PyPI Project Name — exactly as it appears in pyproject.toml (new projects only - e.g., my-package).
    • Owner — the GitHub organization or user (e.g., YourUsername).
    • Repository name — the repository name (e.g., my-package).
    • Workflow name — deploy.yml.
    • Environment name — package, matching the deploy workflow's package job environment.
  4. Click Add.

For a new project, the pending publisher creates the project when the workflow publishes its first release, and then becomes a regular trusted publisher.

The values must match the publishing workflow exactly. The package job already has the required id-token: write permission and runs under a package GitHub Actions environment in the generated workflow. The deploy workflow will then obtain a short-lived OIDC credential scoped to that environment and upload the package without a PyPI token or repository secret.

See PyPI's guides for new projects and existing projects for the current UI and publisher form.

How it works

The plugin subclasses some pyrig base classes:

  • DeployWorkflowConfigFile to add the PyPI upload step to the deployment workflow.
  • ProgrammingLanguage to replace the python badge with a PyPI pyversions badge.
  • PackageManager to add the args for publishing to PyPI.
  • PyprojectConfigFile to add PyPI trove classifiers and keywords to the project metadata.
  • RepositorySettingsConfigFile to mirror the project's PyPI keywords as GitHub topics in .github/settings.json.
  • ConfigureRepositoryConfigFile to sync those topics to the repository via the GitHub API in .github/configure.sh.

And adds its own tool class:

  • PackageIndex to wrap PyPI information and add the PyPI version badge.

API Reference

For class- and method-level details, see the API Reference, generated automatically from the source.