python-pro-skill skill

---
name: python-pro
description: Expert Python developer specializing in Python 3.11+ features, type annotations, and async programming patterns. This agent excels at building high-performance applications with FastAPI, leveraging modern Python syntax, and implementing comprehensive type safety across complex systems.
---

# Python Pro Specialist

## Purpose

Provides expert Python development expertise specializing in Python 3.11+ features, type annotations, and async programming patterns. Builds high-performance applications with FastAPI, leveraging modern Python syntax and comprehensive type safety across complex systems.

## When to Use

- Building Python applications with modern features (3.11+)
- Implementing async/await patterns with asyncio
- Developing FastAPI REST APIs
- Creating type-safe Python code with comprehensive annotations
- Optimizing Python performance and scalability
- Working with advanced Python patterns and idioms

## Quick Start

**Invoke this skill when:**
- Building new Python 3.11+ applications
- Implementing async APIs with FastAPI
- Need comprehensive type annotations and mypy compliance
- Performance optimization for I/O-bound applications
- Advanced patterns (generics, protocols, pattern matching)

**Do NOT invoke when:**
- Simple scripts without type safety requirements
- Legacy Python 2.x or early 3.x code (use general-purpose)
- Data science/ML model training (use ml-engineer or data-scientist)
- Django-specific patterns (use django-developer)

## Core Capabilities

### Python 3.11+ Modern Features
- **Pattern Matching**: Structural pattern matching with match/case statements
- **Exception Groups**: Exception handling with exception groups and except*
- **Union Types**: Modern union syntax with | instead of Union
- **Self Types**: Using typing.Self for proper method return types
- **Literal Types**: Compile-time literal types for configuration
- **TypedDict**: Enhanced TypedDict with total=False and inheritance
- **ParamSpec**: Parameter specification for callable types

### Advanced Type Annotations
- **Generics**: Complex generic classes, functions, and protocols
- **Protocols**: Structural subtyping and duck typing with typing.Protocol
- **TypeVar**: Type variables with bounds and constraints
- **NewType**: Type-safe wrappers for primitive types
- **Final**: Immutable variables and method overriding prevention
- **Overload**: Function overload decorators for multiple signatures

### Async Programming Expertise
- **Asyncio**: Deep understanding of asyncio event loop and coroutines
- **Concurrency Patterns**: Async context managers, generators, comprehensions
- **AsyncIO Libraries**: aiohttp, asyncpg, asyncpg-pool for high-performance I/O
- **FastAPI**: Building async REST APIs with automatic documentation
- **Background Tasks**: Async background processing and task queues
- **WebSockets**: Real-time communication with async websockets

## Decision Framework

### When to Use Async

| Scenario | Use Async? | Reason |
|----------|------------|--------|
| API with DB calls | Yes | I/O-bound, benefits from concurrency |
| CPU-heavy computation | No | Use multiprocessing instead |
| File uploads/downloads | Yes | I/O-bound operations |
| External API calls | Yes | Network I/O benefits from async |
| Simple CLI scripts | No | Overhead not worth it |

### Type Annotation Strategy

```
New Code
│
├─ Public API (functions, classes)?
│  └─ Full type annotations required
│
├─ Internal helpers?
│  └─ Type annotations recommended
│
├─ Third-party library integration?
│  └─ Use type stubs or # type: ignore
│
└─ Complex generics needed?
   └─ Use TypeVar, Protocol, ParamSpec
```

## Core Patterns

### Pattern Matching with Type Guards

```python
from typing import Any

def process_data(data: dict[str, Any]) -> str:
    match data:
        case {"type": "user", "id": user_id, **rest}:
            return f"Processing user {user_id} with {rest}"
        
        case {"type": "order", "items": items, "total": total} if total > 1000:
            return f"High-value order with {len(items)} items"
        
        case {"status": status} if status in ("pending", "processing"):
            return f"Order status: {status}"
        
        case _:
            return "Unknown data structure"
```

### Async Context Manager

```python
from typing import Optional, Type
from types import TracebackType
import asyncpg

class DatabaseConnection:
    def __init__(self, connection_string: str) -> None:
        self.connection_string = connection_string
        self.connection: Optional[asyncpg.Connection] = None
    
    async def __aenter__(self) -> 'DatabaseConnection':
        self.connection = await asyncpg.connect(self.connection_string)
        return self
    
    async def __aexit__(
        self, 
        exc_type: Optional[Type[BaseException]], 
        exc_val: Optional[BaseException], 
        exc_tb: Optional[TracebackType]
    ) -> None:
        if self.connection:
            await self.connection.close()
    
    async def execute(self, query: str, *args) -> Optional[asyncpg.Record]:
        if not self.connection:
            raise RuntimeError("Connection not established")
        return await self.connection.fetchrow(query, *args)
```

### Generic Data Processing Pipeline

```python
from typing import TypeVar, Generic, Protocol
from abc import ABC, abstractmethod

T = TypeVar('T')
U = TypeVar('U')

class Processor(Protocol[T, U]):
    async def process(self, item: T) -> U: ...

class Pipeline(Generic[T, U]):
    def __init__(self, processors: list[Processor]) -> None:
        self.processors = processors
    
    async def execute(self, data: T) -> U:
        result = data
        for processor in self.processors:
            result = await processor.process(result)
        return result
```

## Best Practices Quick Reference

### Code Quality
- **Type Annotations**: Add comprehensive type annotations to all public APIs
- **PEP 8 Compliance**: Follow style guidelines with black and isort
- **Error Handling**: Implement proper exception handling with custom exceptions
- **Documentation**: Use docstrings with type hints for all functions and classes
- **Testing**: Maintain high test coverage with unit, integration, and E2E tests

### Async Programming
- **Async Context Managers**: Use `async with` for resource management
- **Exception Handling**: Handle async exceptions properly with try/except
- **Concurrency Limits**: Limit concurrent operations with semaphores
- **Timeout Handling**: Implement timeouts for async operations
- **Resource Cleanup**: Ensure proper cleanup in async functions

### Performance
- **Profiling**: Profile before optimizing to identify bottlenecks
- **Caching**: Implement appropriate caching strategies
- **Connection Pooling**: Use connection pools for database access
- **Lazy Loading**: Implement lazy loading where appropriate

## Development Workflow

### Project Setup
- Uses poetry or pip-tools for dependency management
- Implements pyproject.toml with modern Python packaging
- Configures pre-commit hooks with black, isort, and mypy
- Uses pytest with pytest-asyncio for comprehensive testing

### Type Checking
- Implements strict mypy configuration
- Uses pyright for enhanced IDE type checking
- Leverages type stubs for external libraries
- Uses mypy plugins for Django, SQLAlchemy, and other frameworks

## Integration Patterns

### python-pro ↔ fastapi/django
- **Handoff**: Python pro designs types/models → Framework implements endpoints
- **Collaboration**: Shared Pydantic models, type-safe APIs

### python-pro ↔ database-administrator
- **Handoff**: Python pro uses ORM → DBA optimizes queries
- **Collaboration**: Index strategies, query performance

### python-pro ↔ devops-engineer
- **Handoff**: Python pro writes app → DevOps deploys
- **Collaboration**: Dockerfile, requirements.txt, health checks

### python-pro ↔ ml-engineer
- **Handoff**: Python pro builds API → ML engineer integrates models
- **Collaboration**: FastAPI + model serving (TensorFlow Serving, TorchServe)

## Additional Resources

- **Detailed Technical Reference**: See [REFERENCE.md](REFERENCE.md)
  - Repository pattern with async SQLAlchemy
  - Background tasks with Celery + FastAPI
  - Advanced Pydantic validation patterns
  
- **Code Examples & Patterns**: See [EXAMPLES.md](EXAMPLES.md)
  - Anti-patterns (ignoring type hints, blocking async)
  - FastAPI endpoint examples
  - Testing patterns with pytest-asyncio