lang-python

name	lang-python
description	This skill should be used when the user asks to "write Python code", "debug a Python script", "set up a Python project", "explain Python concepts", or mentions Python-specific libraries like FastAPI, Django, or Pandas.
credit	modu-ai/moai-adk

<skill_doc> <trigger_keywords>

Trigger Keywords

Activate this skill when the user mentions any of:

File Extensions: .py, pyproject.toml, requirements.txt, pytest.ini, setup.py

Python Core: Python, python3, pip, poetry, uv, asyncio, async/await, type hints, dataclass, Protocol, TypeVar, ParamSpec, match/case, pattern matching

Web Frameworks: FastAPI, Django, Flask, Starlette, ASGI, WSGI, Depends, APIRouter, @app.get, @app.post

Validation: Pydantic, BaseModel, model_validate, ConfigDict, Field, validator, model_validator

ORM/Database: SQLAlchemy, AsyncSession, create_async_engine, Alembic, migrations, ORM, query builder

Testing: pytest, pytest-asyncio, @pytest.fixture, @pytest.mark.parametrize, mock, conftest.py, coverage

Data Science: numpy, pandas, polars, DataFrame, ndarray, data pipeline, ETL

Package Management: uv (preferred), poetry, pip install, virtual environment, venv </trigger_keywords>

⛔ Forbidden Patterns

1. NO Mutable Default Arguments: Never use def foo(x=[]). Use None as default and initialize inside the function.
2. NO Sync I/O in Async Functions: Blocking operations (like requests.get or time.sleep) inside async def kill performance. Use httpx or asyncio.sleep.
3. NO Wildcard Imports: Avoid from module import *. Explicit imports prevent namespace pollution and make code readable.
4. NO Bare Excepts: Never use except:. Always catch specific exceptions (e.g., except ValueError:).
5. NO Pip/Poetry (unless forced): ALWAYS prefer uv for package management. It is significantly faster and more reliable. Only use pip or poetry if explicitly requested or if uv is unavailable.

🤖 Agent Tool Strategy

1. Discovery: Check for justfile first. If it exists, use just -l. Read pyproject.toml or requirements.txt.
2. Package Management: ALWAYS use uv for all package operations (uv add, uv pip install, uv venv). Only fallback to pip/poetry if uv fails.
3. Virtual Environment: uv venv creates environments instantly. Use it.
4. Code Analysis: Use search_files to find definitions. Avoid grep if possible.
5. Testing: Use pytest for running tests. Prefer pytest over unittest.
6. Linting/Formatting: Respect ruff.toml or pyproject.toml [tool.ruff] settings.

Quick Reference (30 seconds)

Python 3.13+ Development Specialist - FastAPI, Django, async patterns, pytest, and modern Python features.

Auto-Triggers: .py files, pyproject.toml, requirements.txt, pytest.ini, FastAPI/Django discussions

Core Capabilities:

• Python 3.13 Features: JIT compiler (PEP 744), GIL-free mode (PEP 703), pattern matching
• Web Frameworks: FastAPI 0.115+, Django 5.2 LTS
• Data Validation: Pydantic v2.9 with model_validate patterns
• ORM: SQLAlchemy 2.0 async patterns
• Testing: pytest with fixtures, async testing, parametrize
• Package Management: poetry, uv, pip with pyproject.toml
• Type Hints: Protocol, TypeVar, ParamSpec, modern typing patterns
• Async: asyncio, async generators, task groups
• Data Science: numpy, pandas, polars basics

Quick Patterns

FastAPI Endpoint:

from fastapi import FastAPI, Depends
from pydantic import BaseModel

app = FastAPI()

class UserCreate(BaseModel):
    name: str
    email: str

@app.post("/users/")
async def create_user(user: UserCreate) -> User:
    return await UserService.create(user)

Pydantic v2.9 Validation:

from pydantic import BaseModel, ConfigDict

class User(BaseModel):
    model_config = ConfigDict(from_attributes=True, str_strip_whitespace=True)

    id: int
    name: str
    email: str

user = User.model_validate(orm_obj)  # from ORM object
user = User.model_validate_json(json_data)  # from JSON

pytest Async Test:

import pytest

@pytest.mark.asyncio
async def test_create_user(async_client):
    response = await async_client.post("/users/", json={"name": "Test"})
    assert response.status_code == 201

---

Implementation Guide (5 minutes)

See patterns.md for the detailed implementation guide covering:

• Python 3.13 New Features (JIT, GIL-Free)
• FastAPI 0.115+ Patterns (Async DI, Class Dependencies)
• Django 5.2 LTS Features
• Pydantic v2.9 Deep Patterns
• SQLAlchemy 2.0 Async Patterns
• pytest Advanced Patterns
• Type Hints Modern Patterns
• Package Management (Poetry, uv)

---

Advanced Implementation (10+ minutes)

For comprehensive coverage including:

• Production deployment patterns (Docker, Kubernetes)
• Advanced async patterns (task groups, semaphores)
• Data science integration (numpy, pandas, polars)
• Performance optimization techniques
• Security best practices (OWASP patterns)
• CI/CD integration patterns

See:

• patterns.md - Implementation patterns (FastAPI, Pydantic, SQLAlchemy)
• reference.md - Complete reference documentation
• examples.md - Production-ready code examples

---

Context7 Library Mappings

/docs/astral.sh/uv
/tiangolo/fastapi - FastAPI async web framework
/django/django - Django web framework
/pydantic/pydantic - Data validation with type annotations
/sqlalchemy/sqlalchemy - SQL toolkit and ORM
/pytest-dev/pytest - Testing framework
/numpy/numpy - Numerical computing
/pandas-dev/pandas - Data analysis library
/pola-rs/polars - Fast DataFrame library

---

Troubleshooting

Common Issues:

Python Version Check:

python --version  # Should be 3.13+
python -c "import sys; print(sys.version_info)"

Async Session Detached Error:

• Solution: Set expire_on_commit=False in session config
• Or: Use await session.refresh(obj) after commit

pytest asyncio Mode Warning:

# pyproject.toml
[tool.pytest.ini_options]
asyncio_mode = "auto"
asyncio_default_fixture_loop_scope = "function"

Pydantic v2 Migration:

• parse_obj() is now model_validate()
• parse_raw() is now model_validate_json()
• from_orm() requires from_attributes=True in ConfigDict </skill_doc>