scaffold-python-package

Scaffold a new Python package following PEP 621, PDM, Black/isort/Flake8, type hints, and Loguru logging.

For detailed Python conventions, refer to the Python rule. For testing patterns, refer to the Testing rule. For Makefile setup, refer to the CI/CD rule.

Directory Structure

<project>/
├── <package_name>/
│   ├── __init__.py
│   └── main.py
├── tests/
│   ├── __init__.py
│   └── test_main.py
├── examples/
│   └── example_usage.py
├── Dockerfile
├── pyproject.toml
└── README.md

Step-by-Step

1. Initialize with PDM

mkdir <project> && cd <project>
pdm init

2. Configure pyproject.toml (PEP 621)

[project]
name = "package-name"
version = "0.1.0"
description = "Brief description of the package"
readme = "README.md"
requires-python = ">=3.10"
license = {text = "MIT"}
authors = [
    {name = "Author Name", email = "[email protected]"},
]
dependencies = []

[project.optional-dependencies]
dev = [
    "black",
    "isort",
    "flake8",
    "pytest",
    "loguru",
]

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

[tool.black]
line-length = 120

[tool.isort]
profile = "black"
line_length = 120

[tool.flake8]
max-line-length = 120

3. Create the package module

# <package_name>/__init__.py
"""Package description."""

__version__ = "0.1.0"

# <package_name>/main.py
from loguru import logger


def main() -> None:
    """Entry point for the package."""
    logger.info("Starting application")

4. Add type hints everywhere

All functions must have type hints on parameters and return types:

def process_data(input_data: list[str], max_items: int = 10) -> dict[str, int]:
    """Process the input data and return counts."""
    result: dict[str, int] = {}
    for item in input_data[:max_items]:
        result[item] = result.get(item, 0) + 1
    return result

5. Set up logging with Loguru

Always use Loguru -- NEVER use the standard logging module or print():