python-infra-lab

A minimal, production-grade Python infrastructure template utilizing the src/ layout and PEP 621 configurations. This repository serves as a robust foundation for building scalable, maintainable Python applications and libraries without unnecessary bloat.

Features

• Standardized Project Structure: Enforces the src/ layout to isolate package code, ensuring testing is performed against the installed package rather than source files.
• Modern Packaging: Uses pyproject.toml (PEP 621) with the hatchling build backend for dependency parsing, metadata, and tool configuration.
• Comprehensive Tooling: Integrated support for formatting, linting, and testing via ruff, pytest, pytest-cov, and pre-commit.
• Automated CI Pipeline: Matrix testing defined in GitHub Actions ensuring compatibility across multiple Python versions.
• Production-Ready Dockerization: Minimal image footprint utilizing python:3.11-slim, non-root execution, and optimized caching.
• Developer Workflows: Centralized orchestration using make commands.

Setup

A Makefile is provided to orchestrate environment initialization and installation.

Ensure a Python virtual environment is active, then execute:

make install

This command installs the package in editable mode (pip install -e ".[dev]") alongside all development dependencies, and configures pre-commit hooks.

Developer Tooling

The project incorporates several tools to enforce code quality and consistency. Tool configurations are centralized within pyproject.toml.

• Formatting & Linting: Handled exclusively by ruff, providing rapid static analysis and automatic code formatting.
• Pre-commit Hooks: Configured via .pre-commit-config.yaml to run ruff and enforce codebase integrity prior to commits.
• Testing: pytest is configured to run tests located in the tests/ directory. Coverage reports are generated using pytest-cov, with enforcement rules specified in the project configuration.

Makefile Usage

The following targets are available for developer workflows:

• make install: Installs dependencies and sets up pre-commit hooks.
• make test: Executes the test suite with coverage reporting.
• make lint: Runs static analysis checks via ruff.
• make format: Automatically resolves formatting and fixable linting violations.
• make clean: Removes caches, compiled bytecode, and test artifacts.

Continuous Integration

The repository leverages GitHub Actions (.github/workflows/ci.yml) to enforce CI requirements on pull requests and pushes to the main branch.

The test strategy includes a matrix execution spanning Python 3.9, 3.10, 3.11, and 3.12. The pipeline verifies proper editable installation, asserts code compliance via ruff, and mandates successful execution of the test suite via pytest.

Docker Integration

A production-ready Dockerfile is included, implementing security and size optimizations such as environment variable tuning, caching bypasses, and continuous non-root execution contexts (appuser).

Build the image:

docker build -t python-infra-lab .

Run the container locally:

docker run --rm -it python-infra-lab