python-packaging

# ── Build backend ──────────────────────────────────────
[build-system]
requires      = ["hatchling"]
build-backend = "hatchling.build"

# ── Metadata PEP 621 ────────────────────────────────────
[project]
name            = "my-package"          # kebab-case, unique on PyPI
version         = "1.0.0"              # or dynamic (see below)
description     = "Short description"
readme          = "README.md"
license         = { file = "LICENSE" }
authors         = [{ name = "Name", email = "you@example.com" }]
requires-python = ">=3.10"
classifiers = [
  "Development Status :: 5 - Production/Stable",
  "Intended Audience :: Developers",
  "License :: OSI Approved :: MIT License",
  "Programming Language :: Python :: 3.10",
  "Programming Language :: Python :: 3.11",
  "Programming Language :: Python :: 3.12",
  "Typing :: Typed",
]
keywords      = ["keyword1", "keyword2"]
dependencies  = [
  "requests>=2.28",
  "pydantic>=2.0",
]

[project.urls]
Homepage      = "https://github.com/user/my-package"
Documentation = "https://my-package.readthedocs.io"
Repository    = "https://github.com/user/my-package"
Issues        = "https://github.com/user/my-package/issues"
Changelog     = "https://github.com/user/my-package/blob/main/CHANGELOG.md"

# ── Optional dependencies (extras) ─────────────────────
[project.optional-dependencies]
dev = [
  "pytest>=7.4",
  "pytest-cov>=4.1",
  "black>=23.0",
  "ruff>=0.1",
  "mypy>=1.5",
]
docs = [
  "mkdocs>=1.5",
  "mkdocs-material>=9.4",
]

# ── CLI entry points ────────────────────────────────────
[project.scripts]
my-tool = "my_package.cli:main"

# ── Hatchling: build targets ────────────────────────────
[tool.hatch.build.targets.wheel]
packages = ["src/my_package"]

# ── Other tool config ───────────────────────────────────
[tool.ruff]
line-length    = 88
target-version = "py310"

[tool.mypy]
python_version       = "3.10"
strict               = true
ignore_missing_imports = true

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts   = "-ra -q"

my-package/
├── pyproject.toml          ← the only config file
├── README.md
├── LICENSE
├── CHANGELOG.md
├── .gitignore
├── src/
│   └── my_package/         ← underscore, not kebab-case
│       ├── __init__.py
│       ├── _version.py     ← optional: version string only
│       ├── py.typed        ← optional: typed package marker (PEP 561)
│       ├── core.py
│       ├── cli.py          ← if you have a CLI
│       └── data/           ← data files (JSON, templates, etc.)
│           └── config.json
└── tests/
    ├── conftest.py
    ├── test_core.py
    └── test_cli.py

# Version read from metadata (no need to hardcode in two places)
from importlib.metadata import version, PackageNotFoundError

try:
    __version__ = version("my-package")
except PackageNotFoundError:
    __version__ = "unknown"

# Public API
from .core import MyClass, main_function
from .utils import helper

__all__ = ["__version__", "MyClass", "main_function", "helper"]

# Install hatch once
pip install hatch

# Bump version (automatically updates file + version)
hatch version patch    # 1.2.3 → 1.2.4
hatch version minor    # 1.2.3 → 1.3.0
hatch version major    # 1.2.3 → 2.0.0
hatch version 2.0.0    # set directly to a specific version

# Or with bump-my-version (more flexible)
pip install bump-my-version
bump-my-version bump patch
bump-my-version bump --new-version "2.0.0rc1"

dependencies = [
  "requests",                         # ❌ any version — avoid
  "requests>=2.28",                   # ✓ minimum version — most common
  "requests>=2.28,<3.0",             # ✓ range — for libs that break often
  "requests~=2.28",                   # ✓ compatible: >=2.28, <3.0
  "requests==2.28.2",                # ✓ exact pin — OK for apps, avoid in libraries
  
  # Platform-specific dependencies
  "pywin32>=300; sys_platform == 'win32'",
  "pyobjc-framework-Cocoa>=9.0; sys_platform == 'darwin'",
  
  # Python version backports
  "tomllib; python_version < '3.11'",
]

# Install build tools
pip install build twine
# Or faster with uv:
uv tool install build && uv tool install twine

# Build sdist + wheel at once
python -m build

# Output in dist/:
# dist/my_package-1.2.3-py3-none-any.whl   ← wheel
# dist/my_package-1.2.3.tar.gz              ← sdist

# Verify before uploading
twine check dist/*

# Install locally for testing
pip install dist/my_package-1.2.3-py3-none-any.whl

# Dev mode (editable) — source changes take effect immediately
pip install -e .
pip install -e ".[dev,docs]"    # with extras

# Console scripts — CLI commands
[project.scripts]
my-tool       = "my_package.cli:main"
my-tool-admin = "my_package.cli:admin"

# GUI scripts — no console window on Windows
[project.gui-scripts]
my-gui = "my_package.gui:main"

# Plugin system — extendable by other packages
[project.entry-points."my_package.plugins"]
csv-exporter  = "my_csv_plugin:CsvExporter"
json-exporter = "my_json_plugin.core:JsonExporter"

import click

@click.group()
@click.version_option()
def cli() -> None:
    """Your tool description."""
    pass

@cli.command()
@click.argument("input", type=click.Path(exists=True))
@click.option("-o", "--output", default="output.txt", help="Output file")
@click.option("-v", "--verbose", is_flag=True)
def process(input: str, output: str, verbose: bool) -> None:
    """Process an input file."""
    if verbose:
        click.echo(f"Processing {input} → {output}")

def main() -> None:
    cli()  # entry point calls this

name: Publish to PyPI
on:
  push:
    tags: ["v*"]

jobs:
  publish:
    runs-on: ubuntu-latest
    environment: pypi
    permissions:
      id-token: write       # required for OIDC — no token needed!

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Build
        run: |
          pip install build
          python -m build

      - name: Verify version matches tag
        run: |
          PKG_VER=$(python -c "import my_package; print(my_package.__version__)")
          TAG_VER="${GITHUB_REF#refs/tags/v}"
          [ "$PKG_VER" = "$TAG_VER" ] || { echo "Version mismatch"; exit 1; }

      - name: Publish to PyPI
        uses: pypa/gh-action-pypi-publish@release/v1
        # no password / token required!

# Upload to Nexus
TWINE_REPOSITORY_URL=https://nexus.company.com/repository/pypi-internal/ \
TWINE_USERNAME=myuser \
TWINE_PASSWORD=mypassword \
twine upload dist/*

# Install from private registry
pip install my-package \
  --index-url https://nexus.company.com/repository/pypi-all/simple/ \
  --trusted-host nexus.company.com

# Dual: private registry + PyPI fallback in pip.conf
# ~/.config/pip/pip.conf
[global]
index-url = https://nexus.company.com/repository/pypi-all/simple/
extra-index-url = https://pypi.org/simple/