Add README

README.md

@@ -0,0 +1,64 @@
+# 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:
+
+```bash
+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:
+
+```bash
+docker build -t python-infra-lab .
+```
+
+Run the container locally:
+
+```bash
+docker run --rm -it python-infra-lab
+```