Python Full-Stack Expert

Overview

This skill provides expert-level Python development guidance across the full technology stack: from
Web API development with FastAPI/Django/Flask to async programming, data scraping, testing, performance
optimization, containerized deployment, and AI/LLM integration. It equips the assistant to produce
high-quality, runnable, maintainable, and practical Python code while explaining the engineering
trade-offs and best practices behind each decision.

When to Use This Skill

Activate this skill when the user's request involves any of the following:

• General Python: writing, reviewing, or debugging Python code; architecture design; code quality
• Web Backend: building REST/GraphQL APIs with FastAPI/Django/Flask; project scaffolding; middleware; auth
• Async & Concurrency: asyncio, threading, multiprocessing; I/O-bound or CPU-bound task design
• Data & Scraping: HTTP scraping, HTML parsing, anti-bot strategies, ETL pipelines, data cleaning
• Testing & Quality: pytest, coverage, mocking, CI/CD, ruff, mypy, pre-commit hooks
• Performance: profiling with cProfile/py-spy, memory optimization, GIL mitigation, caching
• Deployment: Docker, Kubernetes, Gunicorn+Uvicorn, Nginx reverse proxy, CI/CD pipelines
• AI/LLM: LLM API integration, SSE streaming, RAG architecture, embedding/vector store, function calling

Coding Standards

All Python code produced through this skill adheres to the following standards:

• Python 3.12+ target; use modern syntax (match/case, type unions X | None, from __future__ import annotations where helpful)
• Type hints on all function signatures; use mypy --strict compliance as the goal
• Async-first for I/O-bound operations; avoid blocking the event loop
• Pydantic v2 for data validation and settings management
• Dependency injection for testable, replaceable components
• Structured error handling: domain exceptions with clear error messages, not bare except Exception: pass
• Docstrings on public functions/classes (Google or NumPy style)
• Line length: 100 characters; formatted with ruff format
• Import order: stdlib → third-party → local (enforced by ruff with I rule)

Task Workflows

1. Building a Web API (FastAPI)

When the user requests a Web API or backend service:

1. Assess requirements: data models, auth needs, real-time features (SSE/WebSocket)
2. If starting from scratch, suggest copying the scaffold from assets/fastapi_scaffold/ — it includes
   main.py, config.py, database.py, dependencies.py, middleware.py, and example routers
3. For architecture patterns, middleware, and DB session management, read references/web_backend.md
4. For SSE streaming (LLM chat endpoints), reference the streaming pattern in references/web_backend.md
   and the full SSE+LLM implementation in references/ai_ml_integration.md
5. For framework comparison (FastAPI vs Django vs Flask), consult the decision table in references/web_backend.md

2. Async & Concurrency Solutions

When the user needs async programming, concurrency, or parallelism:

1. Determine the bottleneck type: I/O-bound → asyncio; CPU-bound → multiprocessing; mixed → ThreadPool
2. For specific patterns (semaphore, producer-consumer, async context managers), read references/async_concurrency.md
3. Watch for common pitfalls: blocking calls in async code, missing cancellation handling, thread safety
4. The "Common Pitfalls" section in references/async_concurrency.md covers the top 4 traps and their fixes

3. Web Scraping & Data Pipelines

When the user needs to scrape websites or build data processing pipelines:

1. Check if an official API exists before resorting to scraping
2. For HTTP client patterns, HTML parsing, anti-bot strategies, read references/data_scraping.md
3. For ETL pipeline architecture (extract-transform-load with checkpoints), reference the DataPipeline
   class template in assets/script_templates/data_pipeline.py
4. Always apply compliance: respect robots.txt, control request rate, avoid personal data collection

4. Testing & Code Quality

When the user asks about testing, CI/CD, or code quality:

1. For pytest patterns (fixtures, parametrization, async testing, mocking), read references/testing_quality.md
2. For dependency injection overrides in FastAPI tests, see the "Dependency Injection Override" section
3. For coverage configuration and test layering strategy, see the "Coverage Configuration" and "Test Layering" sections
4. For tool chain setup (ruff, mypy, pre-commit, GitHub Actions), see the "Code Quality Toolchain" and "CI/CD Pipeline" sections

5. Performance Analysis & Optimization

When the user reports slow Python code or asks for optimization:

1. Always measure first — never optimize by intuition
2. Run the performance analysis script: python scripts/analyze_performance.py <target.py> --lines --memory --imports
3. For profiling tools comparison (cProfile, line_profiler, memory_profiler, py-spy), read references/performance_optimization.md
4. For common optimization patterns (list comprehension, string joining, set lookup, N+1 queries, caching),
   see the "Common Performance Bottlenecks" section
5. Follow the "Optimization Decision Framework" in the reference to prioritize improvements

6. Deployment & DevOps

When the user needs to containerize or deploy a Python application:

1. For Dockerfile (multi-stage build), docker-compose, Kubernetes manifests, read references/deployment_devops.md
2. For production server configuration (Gunicorn+Uvicorn, Nginx), see the "Production Environment Configuration" section
3. For CI/CD pipeline (GitHub Actions: test → build → push → deploy), see the "CI/CD Complete Pipeline" section
4. For the production checklist (18 items), see the "Production Best Practices Checklist" at the end of the reference

7. AI/LLM Integration

When the user needs to integrate LLM APIs, build RAG systems, or implement streaming chat:

1. For LLM API client patterns (sync and streaming), read references/ai_ml_integration.md
2. For SSE streaming implementation (FastAPI backend + Fetch frontend), see the "FastAPI SSE Streaming" section
3. For RAG architecture (vector store, embedding, document chunking), see the "RAG Architecture" section
4. For function calling / tool use patterns, see the "Function Calling / Tool Use" section
5. For production considerations (rate limiting, cost control, error handling), see the "Production Notes" section

8. Project Scaffolding

When the user needs to start a new Python project:

1. Run the scaffold generator: python scripts/project_scaffold.py <name> --framework fastapi
2. Supported frameworks: fastapi, django, cli, library
3. Generated structure includes: app skeleton, tests, pyproject.toml, Dockerfile, docker-compose.yml,
   .gitignore, .env.example, README.md

Resource Index

references/ (load into context as needed)

assets/ (use in output, do not load into context)

scripts/ (execute directly)

Engineering Principles

When producing code through this skill, apply these principles consistently:

1. Correctness first, optimization second — write clear, correct code; profile before optimizing
2. Type safety — use type hints everywhere; run mypy in strict mode
3. Async by default — for I/O-bound work, prefer async over threading
4. Dependency injection — inject dependencies, don't hardcode them; enables testing
5. Fail fast and loudly — raise specific exceptions early; silent failures are bugs
6. Composition over inheritance — favor small, composable functions and mixins
7. Configuration externalization — environment variables, not hardcoded values
8. Test what matters — test business logic, not framework internals; coverage is a guide, not a goal
9. Security by default — validate all inputs, sanitize outputs, use parameterized queries
10. Document trade-offs — when choosing approach A over B, explain why in comments or docs