Python Packaging

Python Packaging

Overview

Use this skill when the task is to create, structure, validate, or publish a Python package using the modern PyPA workflow.

This enhanced version preserves the original skill intent while upgrading it into an operator-facing packaging workflow centered on:

• pyproject.toml-first configuration
• standardized project metadata
• backend-neutral build guidance
• src/ layout decisions
• wheel and source distribution validation
• safer publishing practices for PyPI

Prefer this skill for distributable libraries, reusable internal packages, and Python CLI tools that should be installed through standard packaging workflows.

Do not use it as a substitute for framework-specific deployment guidance, OS packaging, containerization-only workflows, or environment-specific release approvals.

For deeper execution support, use:

• references/runtime-practices.md for standards and decision tables
• examples/implementation-example.md for concrete package layouts and pyproject.toml examples
• scripts/validate-runtime.py for preflight validation of packaging metadata and artifacts

When to Use

Activate this skill when the user needs to:

• create a Python library for distribution
• package a Python CLI tool with console entry points
• migrate from legacy setup.py-first packaging toward pyproject.toml
• build and inspect wheels and source distributions
• publish to PyPI or TestPyPI
• troubleshoot packaging failures such as missing files, bad metadata, or editable install mismatches
• separate runtime dependencies from optional or development-only dependencies

Do not activate it when the task is mainly about:

• virtual environment management alone
• application deployment without packaging
• Docker image construction
• Conda packaging or Linux distro package maintenance
• framework-specific release automation with no Python packaging decisions involved

Operating Table

Workflow

1. Clarify package intent

   • Determine whether the target is a library, a library plus CLI, or an internal package.
   • Confirm Python version support, target index, and release expectations.
   • Ask whether the user needs public PyPI, TestPyPI, or private index publication.

2. Choose packaging structure deliberately

   • For distributable libraries, prefer src/ layout.
   • For very small internal apps, flat layout may be acceptable, but call out the risk of imports succeeding locally while failing after installation.
   • Decide whether the package needs only runtime dependencies, optional extras, or separate development groups.

3. Author pyproject.toml first

   • Define [build-system] with the selected backend requirements.
   • Put standardized metadata in [project] where possible.
   • Keep backend-specific configuration in tool-specific sections only when needed.
   • Avoid introducing legacy setup.py configuration unless the task is explicitly legacy maintenance.

4. Create the package layout

   • Ensure importable package directories are present.
   • Include __init__.py where appropriate for regular packages.
   • Place tests outside the package tree unless there is a deliberate reason not to.
   • If packaging a CLI, declare console entry points instead of relying on ad hoc wrapper scripts.

5. Install and test in development mode

   • Create a clean virtual environment.
   • Install editable dependencies if the backend supports editable installs.
   • Run the project test suite and basic import checks.
   • Confirm that development success is not caused by importing directly from the repository root.

6. Build distributable artifacts

   • Run:
     • python -m pip install --upgrade build
     • python -m build
   • Expect dist/ to contain at least a wheel and often an sdist.
   • If only one artifact type is produced, verify that this is intentional.

7. Validate artifacts before publishing

   • Run twine check dist/*.
   • Optionally install the built wheel into a fresh environment and run a smoke test.
   • Use python scripts/validate-runtime.py --twine-check for a local preflight report.
   • Confirm package data, README rendering, entry points, and metadata fields.

8. Publish safely

   • Prefer TestPyPI or another non-production validation path before a first public release.
   • For CI/CD publication, prefer PyPI Trusted Publishers when available.
   • Treat long-lived API tokens as a fallback, not the preferred baseline.
   • If release integrity is a mature concern, consider attestations as an advanced enhancement.

9. Hand off with concrete verification

   • Report the backend used, project layout, build commands, artifact results, and publishing path.
   • Include any warnings from scripts/validate-runtime.py and the fix applied or deferred.

Examples

Open examples/implementation-example.md when the task needs copy-check-compare examples.

Use those examples for:

• a minimal distributable library using src/ layout
• a library plus CLI package with a console entry point
• expected dist/ outputs after build
• validation steps before TestPyPI or PyPI publication

Troubleshooting