Skip to content

1. Python Project Template Documentation

1.1 Overview

The Python Project Template offers a standardized, maintainable foundation for Python projects, with integrated tooling for:

  • Code quality enforcement
  • Static analysis and security auditing
  • Automated testing
  • Documentation generation
  • Development automation via Make and GitHub Actions

This template is intended to streamline development processes, promote consistency across projects, and encourage best practices.

1.2 Project Structure and Core Components

1.2.1 Makefile

The Makefile defines reusable commands to facilitate routine operations such as installation, cleaning, linting, testing, and documentation. These tasks can be executed using make <target>.

1.2.1.1 make install

Installs and upgrades the project’s dependencies using uv, based on the pyproject.toml file. This includes both development and documentation tools, organized by dependency groups.

1.2.1.2 make clean

Cleans the workspace by removing generated cache and temporary files, including:

  • Python bytecode (.pyc, .pyo)
  • Cache directories: __pycache__, .pytest_cache, .mypy_cache

This ensures a clean state for test and lint runs.

1.2.1.3 make lint

Formats and analyzes code using Ruff:

  • Automatically applies code formatting.
  • Performs static lint checks on both source and test directories to ensure adherence to defined coding standards.

1.2.1.4 make code_check

Performs in-depth code analysis and security checks:

  • Mypy: Validates static type annotations.
  • Complexipy: Analyzes code complexity to identify overly complicated logic structures.
  • Bandit: Detects common security issues in Python code.

This step is essential for maintaining robust, secure, and maintainable codebases.

1.2.1.5 make tests

Executes the project's unit tests using Pytest. If no tests or test files are detected, the command exits gracefully without failure.

1.2.1.6 make doc

Serves the documentation locally using MkDocs. This allows for live previews of your documentation before deployment.

1.2.1.7 make pipeline

Runs a full quality pipeline comprising:

  • Environment cleanup
  • Code linting and formatting
  • Static analysis and security scans
  • Test execution

This target is suitable for continuous integration environments and pre-release validations.

1.2.1.8 make all

Performs a complete workflow:

  • Installs dependencies
  • Executes the full quality pipeline
  • Builds and serves the documentation

Recommended for initial setup and full-cycle verifications.

1.3 pyproject.toml

The pyproject.toml file defines the project's metadata, dependency groups, and tool configurations in accordance with modern Python standards.

1.3.1 [project]

Specifies metadata such as:

  • Project name, version, and description
  • Python version compatibility
  • Required runtime dependencies (if any)

This section aligns with PEP 621 standards for project metadata.

1.3.2 [dependency-groups]

Organizes development dependencies into logical groups:

  • pipeline: Tools used for static analysis, linting, security checks, complexity analysis, and testing:

  • pytest, pytest-order, ruff, mypy, bandit, complexipy

  • documentation: Tools used to build and extend project documentation with MkDocs and various plugins:

  • mkdocs-material, mkdocstrings, mkdocs-jupyter, etc.

These groups allow selective installation via uv, improving modularity and dependency management.

1.3.3 [tool.ruff]

Defines configuration for Ruff, the linter and code formatter:

  • Line and indentation style
  • Linting rules to enforce (e.g., error detection, unused imports, code simplifications)
  • Excluded directories (e.g., venv, dist, .pytest_cache, .ipynb_checkpoints)
  • Formatting settings for docstrings and imports

1.3.4 [tool.mypy]

Configures Mypy, the static type checker:

  • Enables checks on untyped function definitions
  • Ignores unresolved imports (helpful for missing stubs)
  • Excludes irrelevant directories such as build environments

These settings help detect type-related issues early in the development process.

1.4 Development Workflow

A typical development and validation workflow using this template may include the following steps:

  1. Setup
make install
  1. Clean Environment
make clean
  1. Code Linting and Analysis
make lint
make code_check
  1. Run Tests
make tests
  1. Generate and Preview Documentation
make doc
  1. Full Workflow Execution
make all

These commands can be used locally or integrated into CI/CD pipelines for automated validation.