DOCSEARCHbyAlgolia
Submit Docs

python-blueprint

repository·main·Indexed 20 days ago

https://github.com/johnthagen/python-blueprint

A professional Python project blueprint demonstrating modern best practices for package management, testing, linting, type checking, and documentation generation. It utilizes uv for dependency management, Nox for task orchestration, pytest for unit testing, Ruff for linting and formatting, mypy for static type checking, and MkDocs with mkdocstrings for documentation. The blueprint implements a recommended src layout and includes an example package named fact (v1.0.0).

Tokens
2.1K
Snippets
16
Records
17
Agent score
71%

What's inside python-blueprint

  1. Run automated code quality checks with Nox

    main

    Automated quality checks (testing, linting, type checking, and documentation) are orchestrated by Nox. Nox uses noxfile.py to manage virtual environments and run specific task sessions. nox is automatically installed into your environment when you run uv sync.

    # Run all default Nox sessions
uv run nox

  2. Use the recommended `src` layout for Python projects

    main

    To avoid issues with pytest and nox where the project root shadows installed packages in isolated virtual environments, this blueprint recommends using a src directory. This ensures that tests run against the installed distribution rather than the local source code in the project root.

    Recommended structure:

    fact
├── src
│   └── fact
│       ├── __init__.py
│       ├── cli.py
│       └── lib.py
├── tests
│   ├── __init__.py
│   └── test_fact.py
├── noxfile.py
└── pyproject.toml

  4. Perform static type checking with mypy

    main

    Static type checking is performed using mypy. To ensure your package is recognized by type checkers (like mypy, PyCharm, or VS Code) as containing type annotations, you must include a py.typed file in the root of your installed package (e.g., src/fact/py.typed).

    # Run type checking via Nox
uv run nox -s type_check

  5. Build and publish Python distributions

    main

    The project is structured as a redistributable Python package. You can build both source distributions (sdist) and wheels using uv build. To publish the built packages to PyPI, use uv publish.

    Note: To enable publishing, ensure you remove the "Private :: Do Not Upload" Trove classifier from your configuration.

    # Package the project as sdist and wheel
uv build

# Publish distributions to PyPI
uv publish

  6. Install and manage Python versions with uv

    main

    This project uses uv for package management and virtual environment isolation.

    To use this blueprint, first install uv globally on your system. You can then manage Python versions directly through uv.

    # Install a specific Python version
uv python install 3.13

# Upgrade all uv-managed Python versions to latest patch releases
uv python upgrade

  7. Install the `fact` package

    main

    The fact package is managed using uv. First, install the uv package manager, then use uv sync to install the package and its dependencies.

    Install uv on macOS and Linux:

    curl -LsSf https://astral.sh/uv/install.sh | sh

    Install uv on Windows:

    powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

    Install fact dependencies:

    uv sync
    uv sync

  8. Lint and format code with Ruff

    main

    Code style compliance (PEP 8) and automated formatting are handled by [Ruff]. Configuration is stored in the [tool.ruff] section of pyproject.toml.

    # Lint code
uv run nox -s lint

# Automatically fix fixable lint errors
uv run nox -s lint_fix

# Automatically format code and sort imports
uv run nox -s fmt

  9. Generate and serve user documentation with MkDocs

    main

    The project uses Material for MkDocs to generate static user guides. Documentation can be built for offline viewing, served locally with auto-reloading, or checked for broken URLs.

    # Build the user guide
uv run nox -s docs

# Validate external URLs in the documentation
uv run nox -s docs_check_urls

# Build the guide for offline viewing
uv run nox -s docs_offline

# Build and serve the guide locally with auto-reloading
uv run nox -s docs_serve

  10. Run unit tests with pytest

    main

    Unit testing is performed using pytest. Tests are located in the tests folder, which is treated as a Python package to ensure unique namespacing. Code coverage is provided via pytest-cov.

    When running the test Nox session, an HTML coverage report is generated in the htmlcov folder. You can view it by opening htmlcov/index.html in a browser.

    # Run the test session via Nox
uv run nox -s test

# Pass specific arguments to pytest through Nox
uv run nox -s test -- -k invalid_factorial

  11. Manage dependencies with uv

    main

    Dependencies are defined in pyproject.toml and locked in uv.lock to ensure reproducible environments. Use uv sync to create an isolated virtual environment with all required dependencies, or uv lock --upgrade to update all dependencies to their latest versions.

    # Install all dependencies into an isolated virtual environment
uv sync

# Upgrade all dependencies to their latest versions
uv lock --upgrade

  12. Generate API documentation using mkdocstrings

    main

    API documentation is generated using the mkdocstrings plugin, which renders Google-style docstrings into the MkDocs project.

    Example of a compatible Google-style docstring:

    """Computes the factorial through a recursive algorithm.

Args:
    n: A positive input value.

Raises:
    InvalidFactorialError: If n is less than 0.

Returns:
    Computed factorial.
"""