# reference-pydantic

> Reference Pydantic documentation and source for code improvement

- Author: N283T
- Repository: N283T/dotfiles
- Version: 20260120222824
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/N283T/dotfiles
- Web: https://mule.run/skillshub/@@N283T/dotfiles~reference-pydantic:20260120222824

---

---
name: reference-pydantic
description: Reference Pydantic documentation and source for code improvement
allowed-tools: Read, Glob, Grep, Edit, Write, Bash
timeout: 120000
---

# Pydantic Documentation Reference

Reference Pydantic docs and source to improve code quality.

**Repository:** https://github.com/pydantic/pydantic
**Ecosystem:** Python

## Prerequisites

- `curl` and `tar` for downloading
- `SKILL_ROOT` environment variable (set automatically by Claude Code to the skill directory)

## Setup: Download Source

### Step 1: Detect version in project

```bash
# Match 'pydantic' as a word boundary to avoid matching pydantic-settings etc.
VERSION=$(grep -oE '\bpydantic[=<>~!]*[0-9]+\.[0-9]+(\.[0-9]+)?' pyproject.toml requirements*.txt setup.py 2>/dev/null | grep -oE '[0-9]+\.[0-9]+(\.[0-9]+)?' | head -1)
echo "Detected: ${VERSION:-not found, will use 2.12.5}"
```

### Step 2: Download source (if not cached)

```bash
VERSION="${VERSION:-2.12.5}"
CACHE_DIR="${SKILL_ROOT}/assets/pydantic-${VERSION}"

if [[ ! -d "$CACHE_DIR" ]]; then
  echo "Downloading pydantic v${VERSION}..."
  mkdir -p "${SKILL_ROOT}/assets" || { echo "Failed to create assets directory"; exit 1; }

  # Download and extract (GitHub archives extract to pydantic-VERSION/)
  curl -sfL "https://github.com/pydantic/pydantic/archive/refs/tags/v${VERSION}.tar.gz" | \
    tar -xz -C "${SKILL_ROOT}/assets" || { echo "Download/extract failed"; exit 1; }

  # Verify extraction succeeded
  if [[ ! -d "$CACHE_DIR" ]]; then
    echo "Error: Expected directory $CACHE_DIR not found after extraction"
    exit 1
  fi

  echo "Cached: $CACHE_DIR"
else
  echo "Using cached: $CACHE_DIR"
fi

export LIB_SRC="$CACHE_DIR"
```

### Step 3: Build Index (if not exists)

```bash
INDEX_FILE="${SKILL_ROOT}/assets/pydantic-${VERSION}.index.json"

if [[ ! -f "$INDEX_FILE" ]]; then
  echo "Building index for pydantic v${VERSION}..."
  uv run "${SKILL_ROOT}/../make-lib-skill/build_index.py" "$CACHE_DIR" "$VERSION" "$INDEX_FILE"
fi

export LIB_INDEX="$INDEX_FILE"
```

## Query Index

Find relevant files for a topic before diving into source code.

### Find by module/topic name

```bash
# List all indexed modules
jq '.modules | keys[]' "$LIB_INDEX"

# Find paths for a specific module
jq '.modules["pydantic"]' "$LIB_INDEX"

# Search modules by partial name
jq '.modules | to_entries[] | select(.key | contains("fields"))' "$LIB_INDEX"
```

### Find by keyword

```bash
# Search for keyword in index
jq '.keywords["validator"]' "$LIB_INDEX"

# Search keywords containing a term
jq '.keywords | to_entries[] | select(.key | contains("model"))' "$LIB_INDEX"
```

### Find files with specific classes/functions

```bash
# Find files defining a class
jq '.files | to_entries[] | select(.value.classes[]? | contains("BaseModel"))' "$LIB_INDEX"

# Find files with specific function
jq '.files | to_entries[] | select(.value.functions[]? | contains("validate"))' "$LIB_INDEX"
```

## Reference Priority

| Priority | Path | Description |
|----------|------|-------------|
| 1 | `docs/` | Markdown documentation (concepts, examples) |
| 2 | `pydantic/` | Python source code |
| 3 | `tests/` | Test examples showing usage |

## Key Files

### docs/ (Markdown documentation)

| Path | Topic |
|------|-------|
| `docs/concepts/models.md` | Model definition |
| `docs/concepts/fields.md` | Field types and constraints |
| `docs/concepts/validators.md` | Custom validators |
| `docs/concepts/serialization.md` | JSON serialization |
| `docs/concepts/config.md` | Model configuration |
| `docs/api/` | API reference |
| `docs/errors/` | Error handling |

### pydantic/ (Source code)

| File | Topic |
|------|-------|
| `pydantic/main.py` | BaseModel implementation |
| `pydantic/fields.py` | Field definitions |
| `pydantic/functional_validators.py` | Validator decorators |
| `pydantic/types.py` | Built-in types |
| `pydantic/config.py` | ConfigDict |

## Workflow

### 1. Find pydantic usage in project

```bash
grep -r "from pydantic" --include="*.py" .
grep -r "BaseModel" --include="*.py" .
grep -r "Field(" --include="*.py" .
```

### 2. Identify what to improve

Common areas:
- Model definitions
- Field validation
- Custom validators
- Serialization/deserialization
- Settings management
- Error handling

### 3. Read relevant documentation

```bash
# For model basics
Read ${LIB_SRC}/docs/concepts/models.md

# For validation
Read ${LIB_SRC}/docs/concepts/validators.md

# For fields
Read ${LIB_SRC}/docs/concepts/fields.md
```

### 4. Reference source for details

```bash
# Check actual implementation
Read ${LIB_SRC}/pydantic/main.py
Read ${LIB_SRC}/pydantic/fields.py
```

## Output Format

```markdown
## Current Implementation
[Code snippet from project]

## Pydantic Documentation (v${VERSION})
[Relevant info from docs - cite file path]

## Suggested Improvement
[Proposed changes]

## Benefits
- [Benefit 1]
- [Benefit 2]
```

## Usage

```
/reference-pydantic                 # Interactive
/reference-pydantic validation      # Focus on validation
/reference-pydantic serialization   # Focus on serialization
```