moai-adk 0.8.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-lang-python/SKILL.md

@@ -1,431 +1,231 @@
 ---
-
-name: moai-lang-python
-version: 2.0.0
-created: 2025-10-22
-updated: 2025-10-22
-status: active
-description: Python 3.13+ best practices with pytest 8.4.2, mypy 1.8.0, ruff 0.13.1, and uv 0.9.3. Use when writing or reviewing Python code in project workflows.
-keywords: [python, testing, pytest, mypy, ruff, uv, async, fastapi, pydantic]
+name: "moai-lang-python"
+description: "Python 3.13+ development specialist covering FastAPI, Django, async patterns, data science, testing with pytest, and modern Python features. Use when developing Python APIs, web applications, data pipelines, or writing tests."
+version: 1.1.0
+category: "language"
+modularized: false
+user-invocable: false
+tags:
+  ["language", "python", "fastapi", "django", "pytest", "async", "data-science"]
+updated: 2026-01-11
+status: "active"
 allowed-tools:
   - Read
+  - Grep
+  - Glob
   - Bash
+  - mcp__context7__resolve-library-id
+  - mcp__context7__get-library-docs
 ---
 
-# Python 3.13 Expert Skill
+## Quick Reference (30 seconds)
 
-## Skill Metadata
+Python 3.13+ Development Specialist - FastAPI, Django, async patterns, pytest, and modern Python features.
 
-| Field | Value |
-| ----- | ----- |
-| **Skill Name** | moai-lang-python |
-| **Version** | 2.0.0 (2025-10-22) |
-| **Python Support** | 3.13.1 (latest), 3.12.7 (LTS), 3.11.10 (maintenance) |
-| **Allowed tools** | Read (read_file), Bash (terminal) |
-| **Auto-load** | On demand when language keywords detected |
-| **Trigger cues** | `.py` files, Python frameworks, TDD discussions, async patterns |
-| **Tier** | Language / 23 (comprehensive coverage) |
+Auto-Triggers: Python files with .py extension, pyproject.toml, requirements.txt, pytest.ini, FastAPI or Django discussions
 
----
+Core Capabilities:
 
-## What It Does
+- Python 3.13 Features: JIT compiler via PEP 744, GIL-free mode via PEP 703, pattern matching with match and case statements
+- Web Frameworks: FastAPI 0.115 and later, 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 decorators
+- Package Management: poetry, uv, pip with pyproject.toml
+- Type Hints: Protocol, TypeVar, ParamSpec, and modern typing patterns
+- Async: asyncio, async generators, and task groups
+- Data Science: numpy, pandas, and polars basics
 
-Provides **Python 3.13+ expertise** for modern TDD development, including:
+### Quick Patterns
 
-- ✅ **Testing Framework**: pytest 8.4.2 (fixtures, asyncio, parametrization)
-- ✅ **Code Quality**: ruff 0.13.1 (unified linter + formatter, replaces black/pylint)
-- ✅ **Type Safety**: mypy 1.8.0 + Pydantic 2.7.0 (static + runtime validation)
-- ✅ **Package Management**: uv 0.9.3 (10x faster than pip)
-- ✅ **Python 3.13 Features**: PEP 695 (type params), PEP 701 (f-strings), PEP 698 (@override)
-- ✅ **Async/Await**: asyncio.TaskGroup, context variables, concurrent patterns
-- ✅ **Security**: Secrets module, secure hashing, SQLAlchemy 2.0.28
+FastAPI Endpoint Pattern:
 
----
+Import FastAPI and Depends from fastapi, and BaseModel from pydantic. Create a FastAPI application instance. Define a UserCreate model class inheriting from BaseModel with name and email string fields. Create an async post endpoint at the users path that accepts a UserCreate parameter and returns a User by calling UserService.create with await.
 
-## When to Use
+Pydantic v2.9 Validation Pattern:
 
-**Automatic triggers**:
-- Python code discussions, `.py` files, framework guidance
-- "Writing Python tests", "How to use pytest", "Python type hints"
-- Python SPEC implementation (`/alfred:2-run`)
-- Async pattern requests
+Import BaseModel and ConfigDict from pydantic. Define a User class inheriting from BaseModel. Set model_config using ConfigDict with from_attributes set to True and str_strip_whitespace set to True. Add id as integer, name as string, and email as string fields. Use model_validate to create from ORM objects and model_validate_json to create from JSON data.
 
-**Manual invocation**:
-- Review Python code for TRUST 5 compliance
-- Design Python microservices (FastAPI 0.115.0 recommended)
-- Upgrade from Python 3.12 to 3.13
-- Refactor async code to use TaskGroup
+pytest Async Test Pattern:
+
+Import pytest and mark the test function with pytest.mark.asyncio decorator. Create an async test function that takes async_client as a fixture parameter. Send a post request to the users endpoint with a JSON body containing a name field. Assert that the response status_code equals 201.
 
 ---
 
-## How It Works (Best Practices)
-
-### 1. TDD Framework (pytest 8.4.2)
-
-```python
-# Test discovery & fixtures
-import pytest
-from src.calculator import add
-
-def test_add_positive_numbers():
-    """Verify addition of positive integers."""
-    assert add(2, 3) == 5
-
-@pytest.mark.asyncio
-async def test_async_operation():
-    """Test async functions with pytest-asyncio."""
-    result = await async_fetch_data()
-    assert result is not None
-```
-
-**Key Points**:
-- ✅ Use pytest 8.4.2+ (not unittest)
-- ✅ One assertion per test (clarity)
-- ✅ Fixtures for setup/teardown
-- ✅ `pytest.mark.asyncio` for async tests
-- ✅ `pytest-mock` for mocking (not mock.patch)
-- ✅ Coverage ≥85% enforced by quality gate
-
-**CLI Commands**:
-```bash
-pytest                              # Run all tests
-pytest -v                           # Verbose output
-pytest --cov=src --cov-report=term # Coverage report (≥85% required)
-pytest -k "pattern"                 # Run matching tests
-pytest -m asyncio                   # Run async tests only
-```
-
-### 2. Code Quality (ruff 0.13.1 — NEW STANDARD)
-
-**⚠️ BREAKING CHANGE**: Ruff 0.13.1 replaces black + pylint + isort. Update workflows:
-
-```yaml
-# OLD (deprecated)
-- black .                           # Format
-- pylint src/                       # Lint
-- isort .                           # Import sort
-
-# NEW (ruff 0.13.1)
-- ruff check . --fix                # Lint + fix
-- ruff format .                     # Format (replaces black)
-```
-
-**Configuration** (`pyproject.toml`):
-```toml
-[tool.ruff]
-line-length = 100
-target-version = "py313"
-
-[tool.ruff.lint]
-select = ["E", "F", "W"]  # Errors, formatting, warnings
-extend-select = ["I"]     # Import sorting (replaces isort)
-```
-
-**CLI Commands**:
-```bash
-ruff check .                        # Lint all files
-ruff format .                       # Format with auto-fix
-ruff check --show-fixes .           # Show what would be fixed
-ruff check --select E501 .          # Check specific rule (line length)
-```
-
-### 3. Type Safety (mypy 1.8.0 + Pydantic 2.7.0)
-
-**Static Type Checking** (mypy):
-
-```python
-from typing import override
+## Implementation Guide (5 minutes)
 
-class Parent:
-    def method(self, x: int) -> str: ...
-
-class Child(Parent):
-    @override  # NEW in Python 3.13 — mypy validates this
-    def method(self, x: int) -> str:
-        return str(x)
-```
-
-**Runtime Validation** (Pydantic 2.7.0):
+### Python 3.13 New Features
 
-```python
-from pydantic import BaseModel, Field
+JIT Compiler via PEP 744:
 
-class User(BaseModel):
-    id: int = Field(gt=0)           # Must be > 0
-    name: str = Field(min_length=1)
-    email: str                      # Auto-validated as email
-```
+- Experimental feature disabled by default
+- Enable using the PYTHON_JIT environment variable set to 1
+- Build option available as enable-experimental-jit flag
+- Provides performance improvements for CPU-bound code
+- Uses copy-and-patch JIT that translates specialized bytecode to machine code
 
-**CLI Commands**:
-```bash
-mypy .                              # Run type checker
-mypy --strict .                     # Strict mode (recommended)
-mypy --show-column-numbers .        # Precise error locations
-```
-
-### 4. Package Management (uv 0.9.3)
-
-**Why uv?**: 10x faster than pip, integrated with ruff + pytest
-
-```bash
-# Create virtual environment
-uv venv                             # Create .venv/
-source .venv/bin/activate           # Activate
-
-# Install dependencies
-uv add pytest ruff mypy             # Add to pyproject.toml
-uv add --dev pytest-asyncio         # Add as dev dependency
-uv sync                             # Install all (from lock file)
+GIL-Free Mode via PEP 703:
 
-# Publish
-uv publish                          # Push to PyPI
-```
+- Experimental free-threaded build available as python3.13t
+- Allows true parallel thread execution
+- Available in official Windows and macOS installers
+- Best suited for CPU-intensive multi-threaded applications
+- Not recommended for production use yet
 
-**pyproject.toml** (uv config):
-```toml
-[project]
-name = "my-project"
-version = "2.0.0"
-requires-python = ">=3.13"
+Pattern Matching with match and case:
 
-[project.optional-dependencies]
-dev = ["pytest>=8.4.2", "ruff>=0.13.1", "mypy>=1.8.0"]
+Create a process_response function that takes a response dictionary and returns a string. Use match statement on response. For case with status ok and data field, return success message with the data. For case with status error and message field, return error message. For case with status matching pending or processing using a guard condition, return in progress message. For default case using underscore, return unknown response.
 
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-```
+### FastAPI 0.115+ Patterns
 
-### 5. Async Patterns (Python 3.13)
+Async Dependency Injection:
 
-**TaskGroup** (cleaner than `asyncio.gather`):
+Import FastAPI, Depends from fastapi, AsyncSession from sqlalchemy.ext.asyncio, and asynccontextmanager from contextlib. Create a lifespan async context manager decorated with asynccontextmanager that takes the FastAPI app. In the lifespan, call await init_db for startup, yield, then call await cleanup for shutdown. Create the FastAPI app with the lifespan parameter. Define an async get_db function returning AsyncGenerator of AsyncSession that uses async with on async_session and yields the session. Create a get endpoint for users with user_id path parameter, using Depends with get_db to inject the database session. Call await get_user_by_id and return UserResponse.model_validate with the user.
 
-```python
-import asyncio
+Class-Based Dependencies:
 
-async def main():
-    async with asyncio.TaskGroup() as tg:
-        task1 = tg.create_task(fetch_user(1))
-        task2 = tg.create_task(fetch_posts(1))
-        # Tasks run concurrently
-        # Exceptions propagate automatically (no need for gather)
+Create a Paginator class with an init method accepting page defaulting to 1 and size defaulting to 20. Set self.page to max of 1 and page, self.size to min of 100 and max of 1 and size, and self.offset to page minus 1 multiplied by size. Create a list_items endpoint using Depends on Paginator to inject pagination and return items using get_page with offset and size.
 
-asyncio.run(main())
-```
+### Django 5.2 LTS Features
 
-**Context Variables** (thread-safe in async):
+Composite Primary Keys:
 
-```python
-from contextvars import ContextVar
+Create an OrderItem model with ForeignKey to Order with CASCADE deletion, ForeignKey to Product with CASCADE deletion, and an IntegerField for quantity. In the Meta class, set pk to models.CompositePrimaryKey with order and product fields.
 
-request_id = ContextVar('request_id', default=None)
+URL Reverse with Query Parameters:
 
-async def handle_request(req_id):
-    token = request_id.set(req_id)
-    # All spawned tasks inherit this context var
-    await process_async()
-```
+Import reverse from django.urls. Call reverse with the search view name, query dictionary containing q set to django and page set to 1, and fragment set to results. The result is the search path with query string and fragment.
 
-### 6. Security Best Practices
+Automatic Model Imports in Shell:
 
-**Secrets Module** (token generation):
-```python
-import secrets
+Run python manage.py shell and models from all installed apps are automatically imported without explicit import statements.
 
-api_key = secrets.token_urlsafe(32)  # Safe random tokens
-nonce = secrets.token_bytes(16)       # Cryptographic nonce
-```
+### Pydantic v2.9 Deep Patterns
 
-**Secure Hashing** (sha256, not md5):
-```python
-import hashlib
+Reusable Validators with Annotated:
 
-# ✅ SECURE
-hash_obj = hashlib.sha256(b"password")
+Import Annotated from typing and AfterValidator and BaseModel from pydantic. Define a validate_positive function that takes an integer v and returns an integer. If v is less than or equal to 0, raise ValueError with must be positive message. Otherwise return v. Create PositiveInt as Annotated with int and AfterValidator using validate_positive. Use PositiveInt in model fields for price and quantity.
 
-# ❌ INSECURE (removed in Python 3.13)
-hash_obj = hashlib.md5(b"password")   # ValueError!
-```
+Model Validator for Cross-Field Validation:
 
----
+Import BaseModel and model_validator from pydantic, and Self from typing. Create a DateRange model with start_date and end_date as date fields. Add a model_validator decorator with mode set to after. In the validate_dates method returning Self, check if end_date is before start_date and raise ValueError if so, otherwise return self.
 
-## Python 3.13 New Features
+ConfigDict Best Practices:
 
-### PEP 695 — Type Parameter Syntax
+Create a BaseSchema model with model_config set to ConfigDict. Set from_attributes to True for ORM object support, populate_by_name to True to allow aliases, extra to forbid to fail on unknown fields, and str_strip_whitespace to True to clean strings.
 
-```python
-# OLD (3.12)
-from typing import TypeVar, Generic
-T = TypeVar('T')
-class Stack(Generic[T]):
-    def push(self, item: T) -> None: ...
+### SQLAlchemy 2.0 Async Patterns
 
-# NEW (3.13)
-class Stack[T]:
-    def push(self, item: T) -> None: ...
-```
+Engine and Session Setup:
 
-### PEP 701 — Improved F-Strings
+Import create_async_engine, async_sessionmaker, and AsyncSession from sqlalchemy.ext.asyncio. Create engine using create_async_engine with the postgresql+asyncpg connection string, pool_pre_ping set to True, and echo set to True. Create async_session using async_sessionmaker with the engine, class_ set to AsyncSession, and expire_on_commit set to False to prevent detached instance errors.
 
-```python
-# NEW: Nested f-strings, arbitrary expressions
-user = {"name": "Alice", "age": 30}
-print(f"User: {user['name']}, Age: {user['age']}")  # Works!
+Repository Pattern:
 
-# Nested f-strings
-x = 10
-print(f"Result: {f'{x:>10}'}")  # Works in 3.13!
-```
+Create a UserRepository class with an init method taking an AsyncSession. Define an async get_by_id method that executes a select query with a where clause for user_id, returning scalar_one_or_none result. Define an async create method that creates a User from UserCreate model_dump, adds to session, commits, refreshes, and returns the user.
 
-### PEP 698 — Override Decorator
+Streaming Large Results:
 
-```python
-from typing import override
+Create an async stream_users function that takes an AsyncSession. Call await db.stream with the select User query. Use async for to iterate over result.scalars and yield each user.
 
-class Parent:
-    def method(self) -> None: ...
+### pytest Advanced Patterns
 
-class Child(Parent):
-    @override  # mypy checks this is actually overriding
-    def method(self) -> None: ...
-```
+Async Fixtures with pytest-asyncio:
 
----
+Import pytest, pytest_asyncio, and AsyncClient from httpx. Decorate fixtures with pytest_asyncio.fixture. Create an async_client fixture that uses async with on AsyncClient with app and base_url, yielding the client. Create a db_session fixture that uses async with on async_session and session.begin, yielding session and calling await session.rollback.
 
-## Example Workflow
-
-**Setup** (uv + Python 3.13):
-```bash
-uv venv --python 3.13               # Create venv with Python 3.13
-source .venv/bin/activate
-uv add pytest ruff mypy fastapi pydantic
-```
-
-**TDD Loop** (pytest):
-```bash
-pytest                              # RED: Watch tests fail
-# [implement code]
-pytest                              # GREEN: Watch tests pass
-ruff check --fix .                  # REFACTOR: Fix code quality
-```
-
-**Quality Gate** (before commit):
-```bash
-pytest --cov=src --cov-report=term # Coverage ≥85%?
-ruff check .                        # Lint pass?
-mypy --strict .                     # Type check pass?
-```
+Parametrized Tests:
 
----
+Use pytest.mark.parametrize decorator with input_data and expected_status parameter names. Provide test cases as tuples with dictionaries and expected status codes. Add ids for valid, empty_name, and missing_name cases. The test function takes async_client, input_data, and expected_status, posts to users endpoint, and asserts status_code matches expected.
 
-## Tool Version Matrix (2025-10-22)
+Fixture Factories:
 
-| Tool | Version | Purpose | Status |
-|------|---------|---------|--------|
-| **Python** | 3.13.1 | Runtime | ✅ Latest |
-| **pytest** | 8.4.2 | Testing | ✅ Current |
-| **ruff** | 0.13.1 | Lint/Format | ✅ New standard |
-| **mypy** | 1.8.0 | Type checking | ✅ Current |
-| **uv** | 0.9.3 | Package manager | ✅ Recommended |
-| **FastAPI** | 0.115.0 | Web framework | ✅ Latest |
-| **Pydantic** | 2.7.0 | Validation | ✅ Latest |
-| **SQLAlchemy** | 2.0.28 | ORM | ✅ Latest |
+Create a user_factory fixture that returns an async function. The inner function takes db as AsyncSession and keyword arguments. Set defaults dictionary with name and email. Create User with defaults merged with kwargs using the pipe operator, add to db, commit, and return user.
 
----
+### Type Hints Modern Patterns
 
-## Inputs
+Protocol for Structural Typing:
 
-- Python source directories (e.g., `src/`, `app/`)
-- Configuration files (`pyproject.toml`, `pytest.ini`)
-- Test suites and sample data
-- Existing CI/CD workflows
+Import Protocol and runtime_checkable from typing. Apply runtime_checkable decorator. Define a Repository Protocol with generic type T. Add abstract async get method taking int id returning T or None, async create method taking dict data returning T, and async delete method taking int id returning bool.
 
-## Outputs
+ParamSpec for Decorators:
 
-- Test/lint execution plan for Python 3.13
-- Code review checklist (TRUST 5 principles)
-- Migration guide (3.12 → 3.13)
-- Performance optimization recommendations
+Import ParamSpec, TypeVar, and Callable from typing, and wraps from functools. Define P as ParamSpec and R as TypeVar. Create a retry decorator function taking times defaulting to 3 that returns a callable wrapper. The inner decorator wraps the function and the wrapper iterates for the specified times, trying to await the function and re-raising on the last attempt.
 
-## Failure Modes
+### Package Management
 
-- ❌ Python 3.13 not installed → Recommend `uv venv --python 3.13`
-- ❌ Dependencies missing → Run `uv sync`
-- ❌ Tests fail → Use `debug-helper` agent for triage
+pyproject.toml with Poetry:
 
----
+In the tool.poetry section, set name, version, and python version constraint. Under dependencies, add fastapi, pydantic, and sqlalchemy with asyncio extra. Under dev dependencies, add pytest, pytest-asyncio, and ruff. Configure ruff with line-length and target-version. Set pytest asyncio_mode to auto in ini_options.
 
-## Inputs
+uv Fast Package Manager:
 
-- Language-specific source directories (e.g. `src/`, `app/`).
-- Language-specific build/test configuration files (e.g. `pyproject.toml`).
-- Relevant test suites and sample data.
+Install uv using curl with the install script from astral.sh. Create virtual environment with uv venv. Install dependencies with uv pip install from requirements.txt. Add dependencies with uv add command.
 
-## Outputs
+---
 
-- Test/lint execution plan tailored to Python 3.13+.
-- TRUST 5 review checkpoints (coverage, linting, types, security, tags).
-- Migration path from older Python versions.
+## Advanced Implementation (10+ minutes)
 
-## Failure Modes
+For comprehensive coverage including:
 
-- When Python 3.13 runtime is not installed.
-- When project dependencies are not in pyproject.toml.
-- When test coverage falls below 85%.
+- Production deployment patterns for Docker and Kubernetes
+- Advanced async patterns including task groups and semaphores
+- Data science integration with numpy, pandas, and polars
+- Performance optimization techniques
+- Security best practices following OWASP patterns
+- CI/CD integration patterns
 
-## Dependencies
+See:
 
-- Access to the project file is required using the Read/Bash tools.
-- Integration with `moai-foundation-langs` for language detection.
-- Integration with `moai-foundation-trust` for quality gate enforcement.
+- reference.md for complete reference documentation
+- examples.md for production-ready code examples
 
 ---
 
-## References (Latest Documentation)
+## Context7 Library Mappings
 
-- **Python 3.13**: https://docs.python.org/3.13/ (accessed 2025-10-22)
-- **pytest 8.4.2**: https://docs.pytest.org/en/stable/ (accessed 2025-10-22)
-- **ruff 0.13.1**: https://docs.astral.sh/ruff/ (accessed 2025-10-22)
-- **mypy 1.8.0**: https://mypy.readthedocs.io/ (accessed 2025-10-22)
-- **uv 0.9.3**: https://docs.astral.sh/uv/ (accessed 2025-10-22)
-- **FastAPI 0.115.0**: https://fastapi.tiangolo.com/ (accessed 2025-10-22)
-- **Pydantic 2.7.0**: https://docs.pydantic.dev/ (accessed 2025-10-22)
+- tiangolo/fastapi for FastAPI async web framework
+- django/django for Django web framework
+- pydantic/pydantic for data validation with type annotations
+- sqlalchemy/sqlalchemy for SQL toolkit and ORM
+- pytest-dev/pytest for testing framework
+- numpy/numpy for numerical computing
+- pandas-dev/pandas for data analysis library
+- pola-rs/polars for fast DataFrame library
 
 ---
 
-## Changelog
+## Works Well With
 
-- **v2.0.0** (2025-10-22): Major update with Python 3.13 support, ruff 0.13.1 standard, uv 0.9.3 package manager, async/await TaskGroup patterns, security best practices, PEP 695/701/698 features
-- **v1.0.0** (2025-03-29): Initial Skill with pytest, mypy, ruff, black, uv coverage
+- moai-domain-backend for REST API and microservices architecture
+- moai-domain-database for SQL patterns and ORM optimization
+- moai-workflow-testing for TDD and testing strategies
+- moai-essentials-debug for AI-powered debugging
+- moai-foundation-quality for TRUST 5 quality principles
 
 ---
 
-## Works Well With
+## Troubleshooting
+
+Common Issues:
+
+Python Version Check:
+
+Run python with version flag to verify 3.13 or later. Use python with -c flag to print sys.version_info for detailed version information.
+
+Async Session Detached Error:
+
+Set expire_on_commit to False in session configuration. Alternatively, use await session.refresh with the object after commit.
+
+pytest asyncio Mode Warning:
+
+In pyproject.toml under tool.pytest.ini_options, set asyncio_mode to auto and asyncio_default_fixture_loop_scope to function.
+
+Pydantic v2 Migration:
 
-- `moai-foundation-trust` (coverage verification, quality gates)
-- `moai-alfred-code-reviewer` (Python-specific code review)
-- `moai-alfred-debugger-pro` (Python debugging with pdb, pudb)
-- `moai-lang-sql` (SQLAlchemy integration)
-- `moai-domain-backend` (FastAPI microservices)
+The parse_obj method is now model_validate. The parse_raw method is now model_validate_json. The from_orm functionality requires from_attributes set to True in ConfigDict.
 
 ---
 
-## Best Practices
-
-✅ **DO**:
-- Use ruff 0.13.1 as linter + formatter (not black + pylint)
-- Specify exact Python version: `requires-python = "^3.13"`
-- Use pytest 8.4.2 for all tests
-- Enable type checking: mypy --strict
-- Run quality gate before each commit
-- Use uv for package management (10x faster)
-- Add docstrings to public APIs
-- Use f-strings (PEP 701 supports nested expressions)
-
-❌ **DON'T**:
-- Use black + pylint (deprecated, use ruff instead)
-- Use md5 hashing (removed in Python 3.13)
-- Mix pytest with unittest
-- Ignore coverage requirements (<85% fails)
-- Use old type hint syntax (use PEP 695 `class Foo[T]:`)
-- Use `asyncio.gather` without error handling (use TaskGroup instead)
+Last Updated: 2026-01-11
+Status: Active (v1.1.0)