Python Clean Architecture Boilerplate

A robust Python boilerplate implementing clean architecture principles, with integrated tools for development, testing, and deployment.

Table of Contents

• Prerequisites
• Installation
• What's in the box ?
• Clean Architecture
• Development Tools
• Testing
• Docker
• Configuration
• License

Prerequisites

• Python >=3.12 <3.13 (tested with 3.12.5)
• pre-commit
• poetry >=1.2.2 <1.9 (tested with 1.8.3)
• docker (optional)

Installation

1. Clone the repository:

   git clone https://github.com/galezra/python-clean-architecture-boilerplate.git
   cd python-clean-architecture-boilerplate/

2. Install dependencies:

   poetry install

3. Set up pre-commit hooks:

   pre-commit install

---

What's in the box ?

Poetry

Poetry is a tool for dependency management and packaging in Python. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you.

pyproject.toml file (pyproject.toml): orchestrate your project and its dependencies poetry.lock file (poetry.lock): ensure that the package versions are consistent for everyone working on your project

For more configuration options and details, see the configuration docs.

pre-commit

pre-commit is a framework for managing and maintaining multi-language pre-commit hooks.

.pre-commit-config.yaml file (.pre-commit-config.yaml): describes what repositories and hooks are installed

For more configuration options and details, see the configuration docs.

ruff

ruff is an extremely fast Python linter, written in Rust.

Rules are defined in the pyproject.toml.

For more configuration options and details, see the configuration docs.

mypy

mypy is an optional static type checker for Python that aims to combine the benefits of dynamic (or "duck") typing and static typing.

Rules are defined in the pyproject.toml.

For more configuration options and details, see the configuration docs.

bandit

bandit is a tool designed to find common security issues in Python code.

Rules are defined in the pyproject.toml.

For more configuration options and details, see the configuration docs.

docformatter

docformatter is a tool designed to format docstrings to follow PEP 257.

Options are defined in the .pre-commit-config.yaml.

---

Clean Architecture

This boilerplate follows the principles of Clean Architecture, which promotes separation of concerns and independence of frameworks. The project structure is organized into layers:

1. Domain Layer: Contains business logic and entities.
2. Use Case Layer: Implements application-specific business rules.
3. Interface Adapters: Converts data between the use cases and external agencies.
4. Frameworks and Drivers: Contains frameworks and tools like databases, web frameworks, etc.

Benefits of this architecture:

• Testability: Business logic can be tested independently of the UI, database, or any external element.
• Independence of Framework: The architecture doesn't depend on the existence of some library of feature-laden software.
• Independence of UI: The UI can change easily, without changing the rest of the system.
• Independence of Database: You can swap out databases without affecting the business rules.

The src/ directory is structured to reflect these layers, promoting a clear separation of concerns and making the codebase more maintainable and scalable.

---

Development Tools

This boilerplate includes several development tools to ensure code quality and consistency:

• Poetry: Dependency management and packaging
• pre-commit: Multi-language pre-commit hook framework
• ruff: Fast Python linter and formatter
• mypy: Static type checker
• bandit: Security issue finder
• docformatter: Docstring formatter
• pytest: Testing framework

For detailed configurations, refer to pyproject.toml and .pre-commit-config.yaml.

---

Testing

Run tests using pytest:

poetry run pytest tests

For coverage report:

poetry run pytest tests --cov=src

---

Docker

Build the Docker image:

docker build . -t my-python-application:latest

Run the application in Docker:

docker run -p 8000:8000 -it --rm my-python-application:latest

---

Configuration

The application uses YAML configuration files located in the config/ directory. The ENVIRONMENT environment variable determines which configuration file to use:

• config/default.yaml: Default configuration
• config/staging.yaml: Staging environment configuration
• config/production.yaml: Production environment configuration

---

License

This project is licensed under the MIT License. See the LICENSE file for details.