Python PyPI Project Setup Pattern

This skill helps you set up a Python project for PyPI publishing following modern best practices with pyproject.toml, src layout, and standardized build/publish scripts.

When to Use This Skill

Use this skill when:

• Starting a new Python package for PyPI distribution
• Setting up a private Python library distributed via GitHub
• You want to use modern pyproject.toml-based configuration
• You need a standardized src/ layout with explicit package discovery
• You want automated build and publish scripts (PyPI path)

What This Skill Creates

1. pyproject.toml - Modern Python project configuration
2. src/{package_name}/ - Source layout with package structure
3. .gitignore - Comprehensive Python gitignore
4. requirements.txt - Development dependencies (includes build/twine for PyPI only)
5. build-publish.sh - Automated build and publish script (PyPI only)
6. LICENSE - License file (Proprietary, MIT, or O'Saasy)
7. README.md - Basic project documentation
8. tests/ - Test directory with a starter smoke test (pytest is scoped to it via pyproject.toml)

Step 1: Gather Project Information

IMPORTANT: Before creating files, ask the user these questions:

1. "What is your project name?" (e.g., "pg-podcast-toolkit", "mypackage")
   • Use this to derive:
     • PyPI package name: {project-name} (with hyphens, e.g., pg-podcast-toolkit)
     • Python package name: {package_name} (with underscores, e.g., pg_podcast_toolkit)
     • Module directory: src/{package_name}/
2. "What is the project description?" (brief one-line description for PyPI)
3. "What is your name?" (for author field)
4. "What is your email?" (for author field — only ask this if the answer to question 6 is GitHub private. PyPI metadata and public GitHub repos are publicly browsable, so embedding the author email there exposes it to scrapers. For those, omit the email entirely; capture name only.)
5. "What is your GitHub username?" (for project URLs)
6. "How will this package be distributed?" (one of three; this drives both the tooling AND whether the author email is embedded)
   • PyPI — Public package registry. Includes build/twine tooling and a publish script. Email omitted from authors and README (PyPI metadata is public).
   • GitHub public — Public repo, installed via git+https:// URL. No PyPI artifacts. Email omitted from authors and README (repo is publicly browsable).
   • GitHub private — Private repo, installed via git+https://${CR_PAT}@... URL. No PyPI artifacts. Email included (only readers with repo access see it).
7. "What license do you want to use?" (options: Proprietary, MIT, O'Saasy)
   • Proprietary: All rights reserved, no open source distribution
   • MIT: Permissive open source, allows commercial use
   • O'Saasy: Modified MIT that reserves commercial SaaS rights for the copyright holder (see https://osaasy.dev/)
8. "What Python version should be the minimum requirement?" (default: 3.13)
9. "What are your initial dependencies?" (optional - comma-separated list, can be empty)
   • Check these against the Python minimum before writing pyproject.toml (see "Check dependency Python requirements" below).
10. "What keywords describe your project?" (optional - for PyPI searchability)

Check dependency Python requirements

The minimum from question 8 must be at least as high as what every initial dependency requires, or the library won't install. Also check that the Python that will create the venv meets the minimum (python3 --version).

For each dependency, find its requires-python:

• On PyPI: curl -fsS https://pypi.org/pypi/{dependency}/json | jq -r .info.requires_python. This shows the latest release, so if the dependency is pinned to an older version, check that version instead: https://pypi.org/pypi/{dependency}/{version}/json.
• From a Git repo: read requires-python in that repo's pyproject.toml.

If a dependency needs a newer Python than the chosen minimum, tell the user which one and what it requires, then ask whether to raise the minimum before continuing. If you can't determine a dependency's requirement, say so rather than assuming it is compatible.

Step 2: Create Directory Structure

Create these directories if they don't exist:

{project_root}/
├── src/
│   └── {package_name}/
├── tests/
└── (other files at root)

Step 3: Create pyproject.toml

Create pyproject.toml with the following structure, substituting project-specific values:

[project]
name = "{project-name}"
version = "0.0.1"
authors = [
  { name="{author_name}", email="{author_email}" },   # GitHub PRIVATE only — see note below
]
description = "{project_description}"
keywords = [{keywords_list}]
readme = "README.md"
requires-python = ">={python_version}"
license = {text = "{license_text}"}
classifiers = [
    "Programming Language :: Python :: 3",
    "{license_classifier}",
    "Operating System :: OS Independent",
]
# CRITICAL — private git deps MUST use TOKEN-FREE URLs here. Never embed
# {env:CR_PAT} in this list: hatchling expands it at wheel build time and
# bakes the live PAT into the wheel's .dist-info/METADATA Requires-Dist,
# leaking a valid credential into every published image. Auth belongs at
# install time (see the Installation section below + uv-supply-chain-hardening).
dependencies = [
  {dependencies_list}
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.metadata]
# Required if ANY dependency is a direct URL reference (e.g., a private
# GitHub repo via `pkg @ git+https://...`). Without this, hatchling refuses
# to build the package: `ValueError: Dependency #N cannot be a direct
# reference unless field tool.hatch.metadata.allow-direct-references is
# set to true`. Harmless when no direct-ref deps are present, so it's
# enabled unconditionally in this template.
allow-direct-references = true

[tool.hatch.build.targets.wheel]
packages = ["src/{package_name}"]

[tool.pytest.ini_options]
# REQUIRED. The venv lives at the project root (bin/, lib/, include/), so an
# unconstrained `pytest` collects the venv's own site-packages tests (e.g.
# mypy's vendored mypyc tests) and dies on third-party collection errors
# before running a single project test. Restrict collection to our tests.
testpaths = ["tests"]

[project.urls]
Homepage = "https://github.com/{github_username}/{project-name}"
Issues = "https://github.com/{github_username}/{project-name}/issues"

CRITICAL Substitutions:

• {project-name} → project name with hyphens (e.g., pg-podcast-toolkit)
• {package_name} → package name with underscores (e.g., pg_podcast_toolkit)
• {author_name} → author's name
• {author_email} → author's email — only when distribution is GitHub private. For PyPI and GitHub public, drop the , email="..." half and write the entry as { name="{author_name}" } (PEP 621 allows the email field to be omitted; it must not be left blank or set to a placeholder, just omit the key).
• {project_description} → one-line description
• {keywords_list} → comma-separated quoted keywords (e.g., "podcasting", "rss", "parser") or empty
• {python_version} → minimum Python version (e.g., 3.13)
• {license_name} → license name for the README (e.g., MIT, O'Saasy, Proprietary - All Rights Reserved)
• {license_text} → license text for pyproject.toml, exactly as listed under "License Text Handling" below
• {license_classifier} → Full classifier string:
  • MIT: License :: OSI Approved :: MIT License
  • O'Saasy: License :: Other/Proprietary License
  • Proprietary: License :: Other/Proprietary License
• {dependencies_list} → comma-separated quoted dependencies (e.g., 'requests', 'beautifulsoup4') or empty
• {github_username} → GitHub username

License Classifiers Mapping:

• Proprietary → Other/Proprietary License
• MIT → MIT License
• O'Saasy → Other/Proprietary License (modified MIT with SaaS restrictions)

License Text Handling:

• Proprietary: {license_text} is Proprietary - All Rights Reserved
• MIT: {license_text} is MIT License
• O'Saasy: {license_text} is O'Saasy License, and create LICENSE file from https://osaasy.dev/

Step 4: Create Comprehensive .gitignore

CRITICAL ordering — the virtual environment MUST be created before this .gitignore is written. Since Python 3.13, python3 -m venv <path> writes a .gitignore containing just * into the venv root. This skill's convention puts the venv at the project root (python3 -m venv . — see Step 6's build-publish.sh and the README's Development / Setup section), so if .gitignore is written first and python3 -m venv . runs after, the project's .gitignore gets clobbered with *. git init && git add . then silently ignores every file in the package.

Correct order:

1. python3 -m venv . (create the venv at the project root; produces a throwaway .gitignore with * inside)
2. Write the .gitignore below — this overwrites the venv-generated one with the comprehensive pattern set, which itself already ignores the venv directory contents.

Create .gitignore with comprehensive Python patterns:

# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class

# C extensions
*.so

# Distribution / packaging
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
# No trailing slash: Linux venvs can make lib64 a symlink to lib.
lib64
# uv writes this transient lock into the venv root (= project root here).
/.lock
parts/
sdist/
var/
wheels/
pip-wheel-metadata/
share/
*.egg-info/
.installed.cfg
*.egg
MANIFEST

# PyInstaller
*.manifest
*.spec

# Unit test / coverage reports
htmlcov/
.tox/
.nox/
.coverage
.coverage.*
.cache
nosetests.xml
coverage.xml
*.cover
*.py,cover
.hypothesis/
.pytest_cache/

# Translations
*.mo
*.pot

# Django stuff:
*.log
local_settings.py
db.sqlite3
db.sqlite3-journal

# Flask stuff:
instance/
.webassets-cache

# Scrapy stuff:
.scrapy

# Sphinx documentation
docs/_build/

# PyBuilder
target/

# Jupyter Notebook
.ipynb_checkpoints

# IPython
profile_default/
ipython_config.py

# pyenv
.python-version

# pipenv
Pipfile.lock

# PEP 582
__pypackages__/

# Celery stuff
celerybeat-schedule
celerybeat.pid

# SageMath parsed files
*.sage.py

# Environments
.env
.venv
env/
venv/
ENV/
env.bak/
venv.bak/
bin/
include/
pyvenv.cfg

# Spyder project settings
.spyderproject
.spyproject

# Rope project settings
.ropeproject

# mkdocs documentation
/site

# mypy
.mypy_cache/
.dmypy.json
dmypy.json

# Pyre type checker
.pyre/

# IDEs
.vscode/
.idea/
*.swp
*.swo
*~
.DS_Store

Step 5: Create requirements.txt

Create requirements.txt with development dependencies. A library's runtime dependencies live in pyproject.toml's dependencies list, so requirements.txt here holds only the dev/build toolchain — the same filename python-project-scaffold uses, installed with pip install --upgrade -r requirements.txt.

Use python3 -m venv . (not python) to create the venv: no venv is active yet, and bare python does not exist on stock macOS.

If distribution is PyPI:

build
twine
pytest
black
mypy

If distribution is GitHub:

pytest
black
mypy

These are the tools needed to develop (and for PyPI, build/publish) the package. Add other dev tools as needed (isort, pytest-cov, etc.).

Step 6: Create build-publish.sh (PyPI only)

If distribution is GitHub, skip this step entirely.

If distribution is PyPI, create build-publish.sh with venv activation and build/publish commands:

#!/bin/bash
# Build and publish package to PyPI
# Activates virtual environment before running

# Activate virtual environment
source bin/activate

# Clean previous builds
rm -rf dist/*

# Build package
python -m build

# Upload to PyPI
python -m twine upload dist/*

Note: This script follows the convention that the virtual environment is in bin/ at the project root.

Step 7: Create Package Structure

Create the basic package structure:

1. src/{package_name}/__init__.py - Package initialization file:

   """
   {project_description}
   """
   
   __version__ = "0.0.1"

2. If this is a library package, you can add:

   # Export main classes/functions here for easier imports
   # from .module import ClassName, function_name
   # __all__ = ['ClassName', 'function_name']

3. tests/test_package.py - Starter smoke test, so pytest has something to collect (an empty tests/ exits with code 5, "no tests ran"):

   import {package_name}
   
   
   def test_package_imports() -> None:
       assert {package_name}.__version__

Step 8: Create LICENSE File

Create the appropriate LICENSE file based on the user's license choice:

For MIT License:

MIT License

Copyright (c) {year} {author_name}

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

For O'Saasy License:

Download the license text from https://osaasy.dev/ and replace <Year> and <Copyright Holder> with appropriate values:

O'Saasy License

Copyright (c) {year} {author_name}

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to use, copy,
modify, merge, publish, distribute, sublicense, and/or sell copies of the Software,
and to permit persons to whom the Software is furnished to do so, subject to
the following conditions:

1. The above copyright notice and this permission notice shall be included in
   all copies or substantial portions of the Software.

2. The licensee may not use the Software to directly compete with the original
   Licensor by offering it to third parties as a hosted, managed, or
   Software-as-a-Service (SaaS) product or cloud service.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

For Proprietary License:

Proprietary License

Copyright (c) {year} {author_name}. All rights reserved.

This software and associated documentation files (the "Software") are proprietary
and confidential. Unauthorized copying, modification, distribution, or use of
this Software, via any medium, is strictly prohibited.

The Software is provided for use only by authorized licensees under the terms
of a separate written agreement with the copyright holder.

Step 9: Create README.md

Create README.md with basic project documentation. The Installation and Development sections vary by distribution type.

If distribution is PyPI:

# {project-name}

{project_description}

## Installation

```bash
pip install {project-name}

Usage

import {package_name}

# Add usage examples here

Development

Setup

Note (Python 3.13+): python3 -m venv . writes a .gitignore with * into the venv root, which is the project root under this convention — so re-creating the venv here overwrites this project's .gitignore. On first setup that's fine (the repo's real .gitignore hasn't been created yet). If you re-create the venv later, restore the tracked file immediately: git checkout .gitignore.

# Create virtual environment
python3 -m venv .

# Activate virtual environment
source bin/activate  # On Windows: Scripts\activate

# Install dependencies
pip install --upgrade -r requirements.txt
pip install -e .

# Run tests
pytest

Building and Publishing

# Make sure you have PyPI credentials configured
# Build and publish to PyPI
./build-publish.sh

License

{license_name}

Author

{author_name}

> The Author line above is `{author_name}` only — PyPI READMEs render publicly on
> pypi.org, so the email is intentionally omitted. (Same rule as the `pyproject.toml`
> `authors` block in Step 3.)

**If distribution is GitHub:**

```markdown
# {project-name}

{project_description}

## Installation

### Public repo
```bash
pip install git+https://github.com/{github_username}/{project-name}.git

Private repo (requires CR_PAT environment variable)

pip install git+https://${CR_PAT}@github.com/{github_username}/{project-name}.git

As a dependency in pyproject.toml

dependencies = [
    # TOKEN-FREE URL — never embed {env:CR_PAT} here. hatchling expands it at
    # wheel build time and bakes the live PAT into .dist-info/METADATA
    # Requires-Dist, leaking a credential into every published image.
    # Auth is supplied at install time (see below).
    "{project-name} @ git+https://github.com/{github_username}/{project-name}.git",
]

Auth for private repos declared this way is supplied at INSTALL time — either by a ${CR_PAT} line in the consuming app's requirements.txt (safe there; requirements files are never packaged), or by git url.insteadOf config:

export GIT_CONFIG_COUNT=1 \
  GIT_CONFIG_KEY_0="url.https://${CR_PAT}@github.com/.insteadOf" \
  GIT_CONFIG_VALUE_0="https://github.com/"

The uv-supply-chain-hardening skill wires this end-to-end for a Docker build.

As a dependency in requirements.txt

Token inline is safe here — requirements files are never packaged into wheels:

{project-name} @ git+https://${CR_PAT}@github.com/{github_username}/{project-name}.git

Usage

import {package_name}

# Add usage examples here

Development

Setup

Note (Python 3.13+): python3 -m venv . writes a .gitignore with * into the venv root, which is the project root under this convention — so re-creating the venv here overwrites this project's .gitignore. On first setup that's fine (the repo's real .gitignore hasn't been created yet). If you re-create the venv later, restore the tracked file immediately: git checkout .gitignore.

# Create virtual environment
python3 -m venv .

# Activate virtual environment
source bin/activate  # On Windows: Scripts\activate

# Install dependencies
pip install --upgrade -r requirements.txt
pip install -e .

# Run tests
pytest

Private git deps: install-time auth. If pyproject.toml declares any private git dep via a token-free URL (per the pattern above), pip install -e . will fail auth on a fresh clone with no credentials in scope. Export the git insteadOf config in the shell first so pip's git clone picks up your PAT:

export GIT_CONFIG_COUNT=1 \
  GIT_CONFIG_KEY_0="url.https://${CR_PAT}@github.com/.insteadOf" \
  GIT_CONFIG_VALUE_0="https://github.com/"

Add this to ~/.zshrc / ~/.bashrc alongside export CR_PAT=... so every shell has it. Persist it globally with git config --global if you prefer.

License

{license_name}

Author

{author_name} ({author_email})

> **Author line rule for the GitHub template above:**
> - **GitHub private** → keep as shown: `{author_name} ({author_email})`.
> - **GitHub public** → drop the email parens; write `{author_name}` only. Public
>   GitHub READMEs are scraped, and the email was never collected in this branch
>   anyway (see Step 1, question 4).

## Step 10: Make Script Executable (PyPI only)

**If distribution is GitHub, skip this step.**

**If distribution is PyPI**, run:
```bash
chmod +x build-publish.sh

Step 11: Create Initial Git Repository (if needed)

If not already a git repository:

git init
git status --short

Do not commit without asking. Show the user what git status --short lists and ask whether to make the initial commit. Only if they approve:

git add .
git commit -m "Initial project structure"

Step 12: Document Next Steps

Inform the user of the next steps.

If distribution is PyPI:

1. Install development dependencies:

   source bin/activate
   pip install --upgrade -r requirements.txt

2. Install package in development mode:

   pip install -e .

3. Write your code in src/{package_name}/
4. Update version in pyproject.toml before publishing
5. Configure PyPI credentials (one-time setup):

   # Create ~/.pypirc with your PyPI token

6. Build and publish:

   ./build-publish.sh

If distribution is GitHub:

1. Install development dependencies:

   source bin/activate
   pip install --upgrade -r requirements.txt

2. Install package in development mode:

   pip install -e .

3. Write your code in src/{package_name}/
4. Update version in pyproject.toml before each release
5. Referencing this library from other projects:
   • In pyproject.toml — always TOKEN-FREE, public or private. {env:CR_PAT} inside a pyproject.toml gets baked into the wheel's Requires-Dist metadata at build time (hatchling expansion), leaking a live PAT into every image built from that consuming package. Auth is supplied at install time:

     dependencies = [
         "{project-name} @ git+https://github.com/{github_username}/{project-name}.git",
     ]

   • In requirements.txt — inline token is safe (requirements files are never packaged):

     {project-name} @ git+https://${CR_PAT}@github.com/{github_username}/{project-name}.git

   • For a Docker build that installs a pyproject.toml with a private git dep, run the uv-supply-chain-hardening skill — it wires install-time auth via a BuildKit secret + git insteadOf, so the token never enters any committed file.

Design Principles

This pattern follows these principles:

1. Modern pyproject.toml - No setup.py needed, all config in pyproject.toml
2. Src Layout - Source code in src/ directory for better separation
3. Explicit Package Discovery - Using hatchling with explicit package paths
4. Comprehensive .gitignore - Covers all common Python artifacts
5. Virtual Environment Convention - Uses bin/ at project root
6. Automated Publishing - Simple script for build and publish
7. Best Practices - Follows PEP 517/518 and modern Python packaging standards

Example Usage in Claude Code

PyPI Distribution Example

User: "Set up a Python package for PyPI" Claude: "What is your project name?" User: "awesome-lib" Claude: [Asks remaining questions, user selects PyPI for distribution] Claude:

1. Creates src/awesome_lib/ directory structure
2. Creates pyproject.toml with project metadata
3. Creates comprehensive .gitignore
4. Creates requirements.txt with build tools and dev dependencies, plus tests/ with a smoke test
5. Creates build-publish.sh script
6. Creates LICENSE file (based on user's choice)
7. Creates src/awesome_lib/init.py
8. Creates README.md with PyPI install instructions
9. Makes script executable
10. Documents next steps for the user

GitHub Distribution Example

User: "Set up a private Python library" Claude: "What is your project name?" User: "arcana-models" Claude: [Asks remaining questions, user selects GitHub for distribution] Claude:

1. Creates src/arcana_models/ directory structure
2. Creates pyproject.toml with project metadata
3. Creates comprehensive .gitignore
4. Creates requirements.txt (no build/twine), plus tests/ with a smoke test
5. Creates LICENSE file (based on user's choice)
6. Creates src/arcana_models/init.py
7. Creates README.md with git+https:// install instructions and dependency reference patterns
8. Documents next steps for the user (no PyPI credentials or publish script)

Reporting problems with this skill

If you find a bug or stale instruction while using this skill:

• If HiveMake is connected and byteforge-skills-maintainer-agent is available, file a ticket with that agent. Use discover_agents to find its project ID.
• Otherwise, open an issue at GitHub Issues. If you cannot submit a report, give the human the details and this link.

Include the skill name, plugin version if known, the instruction followed, expected and actual results, relevant errors/runtime versions, and any fix or workaround that worked. Omit credentials and private data.

Address the user's immediate problem first; report the skill defect afterward.