Package Hosting: PyPI
Introduction
PyPI (Python Package Index) is the official package repository for Python software. This guide provides comprehensive instructions for packaging, distributing, and maintaining Python projects on PyPI using modern development practices. The documentation covers the complete workflow from project configuration to automated publishing, including security best practices for package distribution.
Key Features
Hatch-based Build System: Optimized configuration for PyPI-compatible packages
Automated Publishing: GitHub Actions workflow for seamless PyPI releases
Dual Repository Support: Simultaneous publishing to PyPI and TestPyPI
Version Management: Dynamic version control synced with PyPI releases
Security: Token-based authentication with proper secret management
Compatibility: Broad Python version support (3.8 through 3.13)
Installation
To install the package from PyPI:
pip install fusepystarter
For development installation:
pip install -i https://test.pypi.org/simple/ fusepystarter
Configuration
PyPI Project Setup
Configure your package in pyproject.toml
:
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[project]
name = "fusepystarter"
description = "A modern Python project forge with pre-configured tooling and CI/CD."
dynamic = ["version"]
authors = [{ name = "Sunil Ghimire", email = "sunil.ghimire@fusemachines.com" }]
readme = "README.rst"
requires-python = ">=3.12"
dependencies = ["dynaconf>=3.2.11", "fire>=0.7.0"]
Build Configuration
[tool.hatch.build.targets.sdist]
exclude = ["/.github", "/docs", "/tests"]
[tool.hatch.build.targets.wheel]
packages = ["src"]
[tool.hatch.version]
path = "src/__init__.py"
[tool.hatch]
installer = "uv"
Token Setup
Create or log in to your PyPI account
Navigate to Account Settings
Select Add API token
Configure token with appropriate scope
Store the token securely
Security Note: Treat API tokens as sensitive credentials. They provide full publishing access to your PyPI account.
Usage
Publishing Workflow
Add PyPI tokens to GitHub Secrets: -
PYPI_TOKEN
for production -TEST_PYPI_TOKEN
for testing environmentUse the automated GitHub Actions workflow:
name: PyPI Release
on:
push:
tags:
- "v*.*.*"
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pypa/hatch@install
- run: hatch build --clean
- run: hatch publish
env:
HATCH_INDEX_USER: __token__
HATCH_INDEX_AUTH: ${{ secrets.PYPI_TOKEN }}
Tagging Releases
Create versioned releases with Git tags:
git tag v1.0.0
git push origin v1.0.0
Manual Publishing
For manual publishing:
hatch build
hatch publish --repo test # For TestPyPI
hatch publish # For PyPI
Additional Resources
Next Steps
Once you’ve tested your package workflows, the next step is to report issues or suggest improvements using our GitHub issue template. This helps us track and address problems systematically.