Prerequisites

Before you begin, ensure you have:

• A Git repository
• A working Python environment

Setting Up Poetry

Install Poetry (if not already installed)

Use the following command to install Poetry:

1

curl -sSL https://install.python-poetry.org | python3 -

📘 Reference: Poetry Installation Guide

Initialize Poetry in Your Project

If you’re setting up Poetry in an existing project:

1

poetry init

📘 Reference: Initializing a Pre-Existing Project

Adding Linters

Use the --group dev option to manage development tools as development dependencies.

Option 1: Traditional Approach

Commonly Used Tools

• black: Code formatting
• isort: Import sorting
• flake8: Code style checking

1
2
3

poetry add --group dev "black^24.2.0"
poetry add --group dev "isort^5.13.2"
poetry add --group dev "flake8^7.0.0"

Style Configuration

Create a configuration file:

1

touch setup.cfg

Add the following configuration to setup.cfg:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

[flake8]
max-line-length = 120
extend-ignore = E203
exclude =
    .git,
    __pycache__,
    build,
    dist,
    *.egg-info
per-file-ignores =
    __init__.py: F401

⚠️ Note: flake8 does not support pyproject.toml for configuration.

Option 2: Modern Approach (I Personally Recommend This Way)

Use ruff, a fast all-in-one linter and formatter.

1

poetry add --group dev "ruff^0.11.10"

✅ Widely adopted by many modern open-source Python projects.

Setting Up Pre-commit Hooks (Optional but Recommended)

pre-commit helps enforce code style and quality checks before commits.

Install Pre-commit

1

poetry add --dev pre-commit

Initialize Pre-commit in Your Repo

1

poetry run pre-commit install

Create Configuration File

Create the configuration file at the root of your project:

1

touch .pre-commit-config.yaml

Configuration for Option 1 (Traditional Linters)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: trailing-whitespace
        exclude: ^scripts/.*
      - id: end-of-file-fixer
        exclude: ^scripts/.*
      - id: check-added-large-files
        exclude: ^scripts/.*

  - repo: https://github.com/psf/black
    rev: 24.2.0
    hooks:
      - id: black

  - repo: https://github.com/pycqa/isort
    rev: 5.13.2
    hooks:
      - id: isort

  - repo: https://github.com/pycqa/flake8
    rev: 7.0.0
    hooks:
      - id: flake8

Configuration for Option 2 (ruff)

1
2
3
4
5
6

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.11.10
    hooks:
      - id: ruff
        args: [--fix]

Using a Makefile for Developer Workflow

A Makefile can help streamline common tasks like setting up the development environment, running tests, or starting services.

Create a Makefile

1

touch Makefile

Add a Setup Command

Add the following to your Makefile:

1
2
3

setup-project-dev:
	poetry install
	poetry run pre-commit install

This command will install dependencies and set up the pre-commit hooks.

Conclusion

I personally have the demand to create a project from scratch when I write this article. -> github-repo
The article can also help me to on board a new developer If there is a need one day in the future.
Although it might be over simplified for a big project but it is a correct way to start a Python project.