python-architect

Python Architect

Expert-level Python software architecture with modern tooling and best practices.

🎯 Philosophy

• Simplicity over complexity: Simple solutions are easier to maintain
• Tests as documentation: Well-written tests explain intent
• Type safety: Use type hints to catch bugs early
• Automation: Automate checks, formatting, and releases

🛠️ Tech Stack

Tool	Purpose	Replacement For
uv	Package management & virtual envs	pip, poetry, pipenv
ruff	Linting & formatting	flake8, black, isort, pydocstyle
pytest	Testing	unittest
mypy	Type checking	-
pre-commit	Git hooks	-
GitHub Actions	CI/CD	-

📁 Project Structure

my-project/
├── src/
│   └── my_project/           # Source code
│       ├── __init__.py
│       ├── core/             # Domain logic
│       ├── services/         # Business logic
│       ├── repositories/     # Data access
│       └── api/              # Web interface
├── tests/
│   ├── unit/                 # Unit tests
│   ├── integration/          # Integration tests
│   └── conftest.py          # pytest fixtures
├── docs/                     # Documentation
├── scripts/                  # Utility scripts
├── .github/
│   └── workflows/           # CI/CD
├── pyproject.toml           # Project config (uv, ruff, pytest, mypy)
├── README.md
├── LICENSE
└── .pre-commit-config.yaml

🚀 Quick Start

# Create new project
python scripts/init_python_project.py my-project

# Setup existing project
python scripts/setup_modern_python.py

# Run all checks
python scripts/check_project.py

📋 Best Practices

1. Project Initialization with uv

# Create project
uv init my-project
cd my-project

# Add dependencies
uv add requests pydantic
uv add --dev pytest ruff mypy

# Sync environment
uv sync

2. pyproject.toml Configuration

[project]
name = "my-project"
version = "0.1.0"
description = "A modern Python project"
requires-python = ">=3.11"
dependencies = [
    "pydantic>=2.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "pytest-cov",
    "ruff>=0.1.0",
    "mypy>=1.0",
    "pre-commit",
]

[tool.ruff]
target-version = "py311"
line-length = 88
select = [
    "E",   # pycodestyle errors
    "F",   # Pyflakes
    "I",   # isort
    "N",   # pep8-naming
    "W",   # pycodestyle warnings
    "UP",  # pyupgrade
    "B",   # flake8-bugbear
    "C4",  # flake8-comprehensions
    "SIM", # flake8-simplify
]
ignore = ["E501"]  # Line too long (handled by formatter)

[tool.ruff.format]
quote-style = "double"
indent-style = "space"

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]
python_classes = ["Test*"]
python_functions = ["test_*"]
addopts = "-v --tb=short --strict-markers"
markers = [
    "unit: Unit tests",
    "integration: Integration tests",
    "slow: Slow tests",
]

[tool.mypy]
python_version = "3.11"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true
strict = true