pypi-publisher_skill

This skill guides you through publishing Python packages to PyPI, including testing, versioning, authentication, and automated workflows to ensure reliable

Python

6

GitHub Stars

1

Bundled Files

2 months ago

Catalog Refreshed

4 months ago

First Indexed

Readme & install

Copy the install command, review bundled files from the catalogue, and read any extended description pulled from the listing source.

Installation

Preview and clipboard use veilstrat where the catalogue uses aiagentskills.

npx veilstrat add skill trotsky1997/my-claude-agent-skills --skill pypi-publisher

SKILL.md6.8 KB

Overview

This skill is a practical, end-to-end guide for publishing Python packages to PyPI. It covers pre-publish checks, building and validating distributions, secure authentication with API tokens, common error troubleshooting, and automation for repeatable releases. Use it to streamline safe, consistent package releases to Test PyPI and production.

How this skill works

The guide inspects common release steps: running tests, verifying and synchronizing version numbers, cleaning build artifacts, building source and wheel distributions, and validating packages with twine. It explains authentication via API tokens, how to handle frequent upload errors, and how to automate the workflow with scripts that stop on failures and surface clear messages.

When to use it

Publishing a brand-new package to Test PyPI or production PyPI
Releasing a new version of an existing package
Setting up or debugging automated CI/CD publishing workflows
Troubleshooting PyPI upload errors like "file already exists" or credential issues
Verifying package metadata, structure, and post-publish installation behavior

Best practices

Always run the full test suite before any publish and fail the pipeline on test errors
Keep version numbers consistent across pyproject.toml, package __init__.py, and any hardcoded strings
Use Test PyPI first for trial uploads and API tokens rather than account passwords
Clean old build artifacts (dist/, build/, *.egg-info) before building to avoid stale files
Automate the sequence: tests → build → twine check → upload, and check exit codes at each step

Example use cases

Local release checklist: run pytest, update version in pyproject.toml and __init__.py, build, twine check, upload to Test PyPI
CI pipeline: a script that runs tests, builds with python -m build, validates with twine check, and uploads using TWINE_USERNAME/TWINE_PASSWORD env vars
Fixing "File already exists": increment semantic version, rebuild distributions, and re-upload
Using API token in PowerShell or Bash to perform non-interactive uploads to production PyPI
Post-publish verification: pip install package==X.Y.Z and run basic import/CLI smoke tests

FAQ

Increment the semantic version in pyproject.toml and package __init__.py, rebuild, and upload the new artifacts.

How should I authenticate non-interactively in CI?

Create a PyPI API token and set TWINE_USERNAME=__token__ and TWINE_PASSWORD to the token in CI secrets, then run uvx twine upload --non-interactive.

How do I catch package metadata problems before upload?

Run uvx twine check dist/* and fix warnings in pyproject.toml or package structure, then rebuild and recheck.