playbooks

home / skills / joncrangle / .dotfiles / lang-python

lang-python skill

/dot_config/opencode/skills/lang-python

This skill helps you write, debug, and set up Python projects with modern tooling and frameworks like FastAPI, Django, and pandas.

npx playbooks add skill joncrangle/.dotfiles --skill lang-python

Review the files below or copy the command above to add this skill to your agents.

Files (4)
SKILL.md
6.2 KB
---
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:
```python
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:
```python
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:
```python
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](references/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](references/patterns.md) - Implementation patterns (FastAPI, Pydantic, SQLAlchemy)
- [reference.md](references/reference.md) - Complete reference documentation
- [examples.md](examples/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:
```bash
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:
```toml
# 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>

Overview

This skill helps with writing, debugging, and structuring Python projects using modern tools and idioms. It focuses on async-first web frameworks (FastAPI, Starlette), Pydantic validation, SQLAlchemy async patterns, pytest async testing, and contemporary type-hinting. It prefers fast, reproducible package management and venv workflows to speed iteration and reduce errors.

How this skill works

The agent inspects project files like pyproject.toml, requirements.txt, and source .py files to infer frameworks, dependencies, and test layouts. It uses a discovery-first approach: check justfile, then read project metadata, then operate with uv for package and venv management. For code suggestions it enforces safe patterns (no mutable defaults, no wildcard imports, no bare excepts) and avoids sync I/O inside async functions.

When to use it

  • When you ask to write or refactor Python code or endpoints (FastAPI, Django, Flask).
  • When debugging Python scripts, async behaviors, or test failures (pytest, pytest-asyncio).
  • When setting up a project: virtual env, dependency management, pyproject.toml, or CI steps.
  • When migrating to Pydantic v2 or modern typing (Protocol, TypeVar, ParamSpec).
  • When you need database async patterns with SQLAlchemy, Alembic migrations, or ORM mapping.
  • When working with data libraries (pandas, numpy, polars) or building ETL pipelines.

Best practices

  • Never use mutable default arguments; use None and initialize inside functions.
  • Avoid blocking sync I/O within async functions; prefer httpx and asyncio primitives.
  • Use explicit imports; avoid from module import *.
  • Catch specific exceptions only; never use bare except:.
  • Prefer uv for package management and uv venv for environments; fall back to pip/poetry only if explicitly requested or uv fails.
  • Respect lint/format settings found in ruff.toml or pyproject.toml [tool.ruff].

Example use cases

  • Generate FastAPI endpoints with Pydantic v2 models and async DB access using SQLAlchemy 2.0 async sessions.
  • Create pytest async tests and fixtures for an ASGI app, including async_client examples.
  • Migrate models to Pydantic v2 using model_config and model_validate patterns.
  • Set up project env: detect pyproject.toml, run uv venv, and add dependencies with uv add.
  • Debug detached session issues: set expire_on_commit=False or await session.refresh(obj) after commit.

FAQ

What package manager do you recommend?

Use uv for all package and venv operations; only use pip or poetry if explicitly requested or if uv is unavailable.

How should I handle blocking libraries in async code?

Replace blocking calls with async equivalents (httpx for HTTP, asyncio.sleep) or run blocking work in thread/process pools.

How do I validate ORM objects with Pydantic v2?

Enable from_attributes=True in model_config (ConfigDict) and call model_validate(orm_obj) to create models from ORM instances.