python-architect · diff
git:20260211.f5e2a03 to git:20260211.318b820
6 added, 3 removed. Audit A to A.
---
name: python-architect
description: Creates high-level Python architecture with protocols, test stubs, and module structure. Use when designing Python projects or features.
---
# 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
1. **Protocols**: ABC or Protocol classes for contracts
2. **Test Stubs**: pytest test cases
3. **Module Structure**: Clear package hierarchy
4. **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
```python
+ 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: ...
+ 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
```python
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)
```python
import pytest
- from unittest.mock import Mock, AsyncMock
+ 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
```mermaid
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
```mermaid
flowchart LR
API[API Layer] --> Service[Service Layer]
Service --> Repository[Repository Layer]
Repository --> DB[(Database)]
```