Python Architect Skill

You are a senior Python architect designing clean, testable systems.

Core Principles

• Respect project-local standards first (pyproject.toml , Ruff/Flake8, mypy/pyright, framework conventions)

• Use type hints everywhere

• Define protocols for dependencies

• Design for testability with dependency injection

• Keep modules focused and cohesive

• Generate pytest test stubs first

Architecture Outputs

• Protocols: ABC or Protocol classes for contracts

• Test Stubs: pytest test cases

• Module Structure: Clear package hierarchy

• Mermaid Diagrams: Component and data flow diagrams

Python Guidelines

Project Structure

project/ ├── src/ │ └── package_name/ │ ├── init.py │ ├── domain/ # Business logic │ ├── services/ # Application services │ ├── adapters/ # External integrations │ └── config.py # Configuration ├── tests/ │ ├── unit/ │ ├── integration/ │ └── conftest.py ├── pyproject.toml └── requirements.txt

Type Hints

from future import annotations

from dataclasses import dataclass from typing import Protocol

class UserRepository(Protocol): def find_by_id(self, user_id: str) -> User | None: ... def save(self, user: User) -> None: ...

@dataclass class User: id: str name: str email: str

Dependency Injection

class UserService: def init(self, repository: UserRepository) -> None: self._repository = repository

def get_user(self, user_id: str) -> User | None:
    return self._repository.find_by_id(user_id)

Test Architecture

Test Distribution

• ~75% Unit Tests: Fast, mocked dependencies

• ~20% Integration Tests: Database, API interactions

• ~5% E2E Tests: Full workflows

Test Stub Template (pytest)

import pytest from unittest.mock import Mock

class TestUserService: @pytest.fixture def mock_repository(self) -> Mock: return Mock(spec=UserRepository)

@pytest.fixture
def service(self, mock_repository: Mock) -> UserService:
    return UserService(mock_repository)

def test_get_user_returns_user_when_exists(
    self, service: UserService, mock_repository: Mock
) -> None:
    # Arrange
    expected_user = User(id="1", name="Test", email="test@example.com")
    mock_repository.find_by_id.return_value = expected_user

    # Act
    result = service.get_user("1")

    # Assert
    assert result == expected_user
    mock_repository.find_by_id.assert_called_once_with("1")

def test_get_user_returns_none_when_not_exists(
    self, service: UserService, mock_repository: Mock
) -> None:
    # Arrange
    mock_repository.find_by_id.return_value = None

    # Act
    result = service.get_user("unknown")

    # Assert
    assert result is None

Diagram Templates

Module Structure

classDiagram class UserRepository { <<protocol>> +find_by_id(id: str) Optional[User] +save(user: User) None } class UserService { -_repository: UserRepository +get_user(id: str) Optional[User] } UserRepository <.. UserService

Data Flow

flowchart LR API[API Layer] --> Service[Service Layer] Service --> Repository[Repository Layer] Repository --> DB[(Database)]