Code Quality

Approaches and tools for maintaining a healthy, consistent Python codebase.

Linting with pylint

pylint checks for errors, coding standards, and code smells.

./lint.sh

Run pip install pylint>=3.3.0 first (included in requirements.txt).

Configuration (.pylintrc)

  • Ignores: .venv, __pycache__, .git
  • Disabled warnings: missing-module-docstring (C0114), missing-class-docstring (C0115), missing-function-docstring (C0116), too-few-public-methods (R0903), duplicate-code (R0801)
  • Max line length: 120
  • Relaxed limits: 8 args, 12 attributes, 20 locals, 60 statements per function

Usage

Command Description
./lint.sh Lint main.py
python3 -m pylint main.py Lint with verbose output
pylint main.py --score=no Skip score, just show issues

Other tools worth considering

Ruff

A fast Rust-based linter and formatter that can replace pylint, black, and isort in one tool.

pip install ruff
ruff check main.py
ruff format main.py
  • Drastically faster than pylint
  • Also formats code (like black)
  • PyPI: ruff

mypy / pyright

Gradual type checking for Python. Catches type mismatches, None handling bugs, and incorrect return types at analysis time rather than runtime.

pip install mypy
mypy main.py
  • Complements pylint (pylint checks style/errors, mypy checks types)
  • Works well with FastAPI's type annotations and Pydantic models

pytest + coverage

Once the project grows beyond one file, tests become essential:

pip install pytest pytest-cov
pytest --cov=.
  • FastAPI's TestClient makes it easy to write route-level tests
  • Coverage identifies untested paths

pre-commit

Runs linters/formatters automatically on every git commit, preventing issues from reaching the repo:

pip install pre-commit
pre-commit install

Example .pre-commit-config.yaml:

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.11.0
    hooks:
      - id: ruff
      - id: ruff-format
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.15.0
    hooks:
      - id: mypy

bandit

Security linter that finds common vulnerabilities (hardcoded secrets, SQL injection, unsafe eval):

pip install bandit
bandit -r main.py

Suggested workflow

Stage Tool When
Format Ruff format or black Before committing
Lint Ruff check or pylint Pre-commit hook / CI
Type-check mypy Pre-commit hook / CI
Test pytest Pre-commit hook / CI
Audit bandit CI (weekly)