Packaging & Distribution

# Build system configuration (required)
[build-system]
requires = ["setuptools>=68", "wheel"]
build-backend = "setuptools.build_meta"

# Project metadata (required)
[project]
name = "my-awesome-package"
version = "0.1.0"
description = "A fantastic Python package that does amazing things"
readme = "README.md"
requires-python = ">=3.10"
license = {text = "MIT"}
authors = [
    {name = "Your Name", email = "you@example.com"},
]
maintainers = [
    {name = "Maintainer Name", email = "maintainer@example.com"},
]
keywords = ["api", "data", "automation"]
classifiers = [
    "Development Status :: 4 - Beta",
    "Intended Audience :: Developers",
    "License :: OSI Approved :: MIT License",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
]

# Dependencies
dependencies = [
    "requests>=2.31.0,<3.0",
    "pydantic>=2.0",
    "click>=8.0",
]

# Optional dependencies (extras)
[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "pytest-cov>=4.0",
    "black>=23.0",
    "ruff>=0.1.0",
    "mypy>=1.0",
]
docs = [
    "mkdocs>=1.5",
    "mkdocs-material>=9.0",
]
all = ["my-awesome-package[dev,docs]"]

# URLs
[project.urls]
Homepage = "https://github.com/username/my-awesome-package"
Documentation = "https://my-awesome-package.readthedocs.io"
Repository = "https://github.com/username/my-awesome-package"
Changelog = "https://github.com/username/my-awesome-package/blob/main/CHANGELOG.md"
"Bug Tracker" = "https://github.com/username/my-awesome-package/issues"

# CLI scripts
[project.scripts]
myapp = "my_package.cli:main"
myapp-admin = "my_package.cli:admin_main"

# Entry points (for plugins)
[project.entry-points."my_package.plugins"]
plugin_a = "my_package.plugins:PluginA"

# Tool configurations
[tool.setuptools]
packages = ["my_package"]

[tool.setuptools.package-dir]
"" = "src"

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]
python_classes = ["Test*"]
python_functions = ["test_*"]
addopts = "-v --cov=my_package --cov-report=html"

[tool.black]
line-length = 100
target-version = ["py310", "py311", "py312"]

[tool.ruff]
line-length = 100
select = ["E", "F", "I"]
ignore = ["E501"]

[tool.mypy]
python_version = "3.10"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true

# Version progression examples

1.0.0  →  1.0.1  # Bug fix: Fixed login error
1.0.1  →  1.1.0  # New feature: Added export to PDF
1.1.0  →  1.1.1  # Bug fix: Fixed PDF formatting
1.1.1  →  2.0.0  # Breaking: Changed API authentication method

# Pre-release versions
1.0.0-alpha.1    # Alpha release
1.0.0-beta.2     # Beta release
1.0.0-rc.1       # Release candidate

# Development versions
1.0.0.dev1       # Development version

dependencies = [
    # Minimum version (flexible)
    "requests>=2.31.0",

    # Version range (recommended for libraries)
    "pydantic>=2.0,<3.0",

    # Compatible release (recommended)
    "flask~=3.0.0",  # Allows 3.0.x but not 3.1.0

    # Exact version (avoid unless necessary)
    "numpy==1.24.3",

    # Multiple constraints
    "django>=4.2,<5.0,!=4.2.5",  # Exclude specific version

    # Optional dependencies with extras
    "sqlalchemy[asyncio]>=2.0",

    # Environment markers
    'pywin32>=300; platform_system == "Windows"',
    'uvloop>=0.17; sys_platform != "win32"',
]

[project.optional-dependencies]
# Development tools
dev = [
    "pytest>=7.0",
    "black>=23.0",
    "mypy>=1.0",
]

# Documentation
docs = [
    "mkdocs>=1.5",
    "mkdocs-material>=9.0",
]

# Database support
postgres = ["psycopg2-binary>=2.9"]
mysql = ["pymysql>=1.0"]

# All extras
all = ["mypackage[dev,docs,postgres,mysql]"]

# Install with extras:
# pip install mypackage[dev]
# pip install mypackage[postgres,docs]
# pip install mypackage[all]

# Editable install (development mode)
pip install -e .

# With extras
pip install -e ".[dev]"

# Why editable install?
# - Changes to source code are immediately available
# - No need to reinstall after each change
# - Perfect for active development

# Install build tool
pip install build

# Build source distribution and wheel
python -m build

# Output:
# dist/
# ├── my_package-0.1.0.tar.gz        # Source distribution
# └── my_package-0.1.0-py3-none-any.whl  # Wheel (faster install)

# Install from wheel
pip install dist/my_package-0.1.0-py3-none-any.whl

# Install from source distribution
pip install dist/my_package-0.1.0.tar.gz

# pyproject.toml
[project.scripts]
myapp = "my_package.cli:main"
myapp-admin = "my_package.cli:admin"

# src/my_package/cli.py
import click

@click.command()
@click.option('--name', default='World', help='Name to greet')
@click.option('--count', default=1, help='Number of greetings')
def main(name, count):
    """Simple CLI tool"""
    for _ in range(count):
        click.echo(f"Hello {name}!")

@click.command()
def admin():
    """Admin commands"""
    click.echo("Admin mode activated")

if __name__ == '__main__':
    main()

# After installation:
# $ myapp --name Alice --count 3
# Hello Alice!
# Hello Alice!
# Hello Alice!
#
# $ myapp-admin
# Admin mode activated

# 1. Create accounts
# - Test PyPI: https://test.pypi.org/account/register/
# - Real PyPI: https://pypi.org/account/register/

# 2. Install publishing tools
pip install build twine

# 3. Build your package
python -m build

# 4. Upload to Test PyPI first
twine upload --repository testpypi dist/*

# 5. Test installation from Test PyPI
pip install --index-url https://test.pypi.org/simple/ my-package

# 6. If everything works, upload to real PyPI
twine upload dist/*

# 7. Install from PyPI
pip install my-package

# Create ~/.pypirc file
[distutils]
index-servers =
    pypi
    testpypi

[pypi]
username = __token__
password = pypi-AgEIcHlwaS5vcmc...  # Your API token

[testpypi]
username = __token__
password = pypi-AgENdGVzdC5weXBp...  # Your Test PyPI token

# Now you can upload without entering credentials
twine upload dist/*

# .github/workflows/publish.yml
name: Publish to PyPI

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4

    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.11'

    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install build twine

    - name: Build package
      run: python -m build

    - name: Publish to PyPI
      env:
        TWINE_USERNAME: __token__
        TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
      run: twine upload dist/*