⚡️ Simple and fast Python template ⚡️

Pre-structure project to start coding right away

Requirements  •  Folder Structure  •  How To Use  •  Commands  •  Dependencies

Resources

This template is inspired by pmareke repository. You can find his template in the link bellow:

Requirements

The project runs with Python 3.12.

The recommended way to install Python is using pyenv if you are on Linux or MacOS. Here is a summary of the steps, but it's recommended to visit the documentation for more details.

Install Python with pyenv

1. Install pyenv:

   curl https://pyenv.run | bash

2. Set you bash profile to load pyenv. In my case I use fish:

   set -Ux PYENV_ROOT $HOME/.pyenv
   fish_add_path $PYENV_ROOT/bin

   Then, add the following line to ~/.config/fish/config.fish:

   echo pyenv init - | source >> ~/.config/fish/config.fish

3. Install the selected Python version (you can see available version with pyenv install --list):

   pyenv install 3.12

4. Go to your project folder and select this Python version for the folder

   pyenv local 3.12

After installing pyenv you only need to install the package manager, in this case I prefer to use pdm. Just need to run the following command on your project folder:

pip install pdm

To install directly all dependencies, run:

make install

Folder Structure

The project is structured following the Clean Architecture principles and Domain Driven Design.

Production Code

The production code goes inside the src folder. Which is divided into two main folders:

• The contexts folder will contain all the bounded contexts of the application:
  • Each bounded context has the main business logic of a specific domain. Inside each bounded context you will find one or more modules that represent a specific part of the domain. Each module is divided into the following subfolders:
    • The domain folder contains the business rules, entities and value objects.
    • The application folder contains use cases and handlers
    • The infra folder contains the implementation of the interfaces defined in the domain for I/O operations like database, buses etc.
      • The shared folder contains code that is shared across multiple modules of the bounded context.
  • The shared folder contains code that is shared across multiple bounded contexts.
• The delivery folder contains the entry points of the application, these would be your API controllers, web frontend, mobile frontend, etc.

Tests

The tests folder follows a similar structure to the production code.

• The contexts folder contains the tests for the main business logic of the application. It follows the same structure as the production code, separating the bounded contexts into different folders and modules. Each module will contain tests that represent the following:
  • The domain folder should contain mother objects and tests for the entities and value objects.
  • The application folder should contain tests for the use cases and handlers.
  • The infra folder should contain tests for the implementation of the interfaces defined in the domain.
• The delivery folder should contain the acceptance or end-to-end tests.

Utilities

Inside scripts folder you can put any script utility like hooks, pre-defined commands etc.

How To Use

In order to use this template and start your project follow these steps:

1. From this template on GitHub click on the "Use this template" button and select "Create a new repository". This will open a new page where you can name your repository and select the visibility.
2. Clone your repository on you local machine

   git clone <your_repo_url>

3. Run the make local-setup command to be able to run the hooks inside hooks folder.

Note

If you want to ignore the hooks folder, you can remove it and just run make install command.

4. Rename the source bounded context as well as tests bounded context
5. Happy coding

Make Commands

The project leverages lots of actions to a Makefile. The following commands are available by default:

• test: runs all the tests
• test-unit: detects changes on domain or application changes and runs the bounding context corresponding tests
• all-test-unit: runs all domain and application tests in all bounded contexts
• test-integration: detects changes on infra and runs the bounding context corresponding tests
• all-test-integration: runs all infra tests in all bounded contexts
• test-acceptance: runs all acceptance tests
• coverage: runs all the tests with coverage
• local-setup: sets up the local environment
• install: installs all dependencies
• update: updates dependencies
• add-dependency: installs a new dependency
• check-typing: runs static type checking with mypy
• check-lint: checks linting with ruff
• lint: lints the code with ruff
• check-format: check formats with ruff
• format: formats the code with ruff
• pre-commit: runs the pre-commit checks (check types, checks linting, checks format and runs all unit tests)
• pre-push: runs integration and acceptance tests
• watch: runs a watch session to run all the tests on file changes

Default Dependencies

The project uses pdm as package manager. When you run the make install or make local-setup command, it will install the following dependencies. You can check the versions in the pyproject.toml file.

Testing

• pytest: testing runner.
• pytest-xdist: pytest plugin to run the tests in parallel.
• expects: an expressive assertion library for Python.
• doublex: a test doubles library for Python.
• doublex-expects: a plugin for doublex that integrates with expects.

Code style

• mypy: a static type checker.
• yapf: a Python formatter.
• ruff: a Python linter and formatter.