python-dataclass-converter

Turn hand-written data-holding classes, loose dicts, positional tuples and raw JSON payloads into precise, typed data containers. The default target is @dataclass for internal objects; pydantic v2 is chosen at trust boundaries that need validation, TypedDict when the data must stay a plain dict, NamedTuple for small immutable records that are unpacked, attrs or msgspec when converters or decode speed matter. Every conversion must preserve behaviour (constructor signature, equality, hashing, repr secrecy) or state exactly what changed.

#Trigger Conditions

Activate this skill when the user:

• Asks to "convert this class to a dataclass", "remove the init boilerplate", "make this a dataclass / pydantic model / TypedDict"
• Pastes a JSON sample or API response (OpenAI, Anthropic, a vector DB, a webhook) and wants typed classes for it
• Passes dicts or tuples around (msg["role"], row[2]) and wants named, typed fields
• Hits ValueError: mutable default <class 'list'> for field ... is not allowed, TypeError: non-default argument 'x' follows default argument, FrozenInstanceError, TypeError: unhashable type, or The truth value of an array with more than one element is ambiguous from a dataclass __eq__
• Asks about field(), __post_init__, InitVar, KW_ONLY, slots=True, frozen=True, replace(), asdict()
• Designs config objects, LLM request/response types, chat messages, RAG chunks, eval records

#Workflow

1. INVENTORY  -> list the classes/dicts/JSON to convert; run scripts/to_dataclass.py class|json
2. CLASSIFY   -> pick the container per object (decision table below): boundary vs internal
3. CONVERT    -> fields + defaults + options; move logic to __post_init__; drop redundant dunders
4. PRESERVE   -> check constructor signature, eq/hash identity semantics, repr secrets, ordering
5. SERIALIZE  -> decide to/from JSON path (asdict, from_dict, pydantic, msgspec)
6. VERIFY     -> construct, compare, hash, round-trip JSON; run tests and type checker

#Choosing the Container

Rule of thumb: validate at the edge (pydantic), compute in the core (dataclasses). Convert once at the boundary, then pass dataclasses around. Full matrix: choosing-a-data-container.md.

#Conversion Rules

#1. Fields come from __init__ parameters, in order

# Before
class RetrievedChunk:
    def __init__(self, chunk_id: str, text: str, score: float = 0.0, metadata: dict | None = None):
        self.chunk_id = chunk_id
        self.text = text
        self.score = score
        self.metadata = metadata if metadata is not None else {}

# After
from dataclasses import dataclass, field

@dataclass
class RetrievedChunk:
    chunk_id: str
    text: str
    score: float = 0.0
    metadata: dict = field(default_factory=dict)

• Keep parameter order: positional call sites (RetrievedChunk("c1", "text")) must keep working.
• Keep annotations; infer from defaults when missing; use Any and flag it rather than guess.
• x: T = None without Optional -> write Optional[T] / T | None (3.10+).
• The None sentinel + or [] idiom becomes default_factory. Behaviour change to mention: passing None explicitly now stores None.

#2. Mutable defaults always use default_factory

The decorator rejects unhashable defaults (list, dict, set, and since 3.11 any instance whose class sets __hash__ = None) with ValueError. Defaults that are other mutable objects (a Tokenizer() instance) are silently shared: use a factory.

#3. Logic goes into __post_init__; construction-only params become InitVar

import os
from dataclasses import InitVar, dataclass, field

@dataclass
class LLMClient:
    model: str
    api_key_env: InitVar[str] = "OPENAI_API_KEY"
    timeout: float = 30.0
    api_key: str = field(init=False, repr=False)       # never printed in logs

    def __post_init__(self, api_key_env: str) -> None:
        if self.timeout <= 0:
            raise ValueError("timeout must be positive")
        self.api_key = os.environ.get(api_key_env, "")

• Validation (if ...: raise), normalisation (self.model = self.model.strip()) and derived attributes all move to __post_init__; parameter names become self.<name>.
• A parameter that is used but never stored becomes InitVar[T]; it is passed to __post_init__ in field order and is excluded from fields(), asdict() and repr.
• Derived attributes are field(init=False); give them a default if they are only set conditionally, otherwise repr() raises AttributeError.
• Subclasses must call super().__post_init__(...) themselves.

#4. Frozen classes write through object.__setattr__

@dataclass(frozen=True, slots=True)
class PromptTemplate:
    template: str
    variables: tuple[str, ...] = ()

    def __post_init__(self) -> None:
        if not self.variables:
            import string
            names = tuple(n for _, n, _, _ in string.Formatter().parse(self.template) if n)
            object.__setattr__(self, "variables", names)

Methods that mutated self must return a new instance: dataclasses.replace(cfg, temperature=0.0) (or copy.replace 3.13+). Store tuples / frozenset / MappingProxyType in frozen classes; a frozen class holding a list is only shallowly immutable and unhashable.

#5. Drop dunders the decorator generates, but keep semantics

#6. Arrays and tensors never take part in eq/hash

import numpy as np
from dataclasses import dataclass, field

@dataclass
class Embedded:
    doc_id: str
    vector: np.ndarray = field(compare=False, repr=False)

    def same_vector(self, other: "Embedded", atol: float = 1e-6) -> bool:
        return self.vector.shape == other.vector.shape and bool(np.allclose(self.vector, other.vector, atol=atol))

Generated __eq__ compares field values like tuples; array == array returns an array and bool(array) raises ValueError: The truth value of an array ... is ambiguous (it "works" only when both sides are the same object). The same applies to torch.Tensor, pandas objects and anything whose == is element-wise.

#7. Inheritance and default ordering

@dataclass
class BaseRequest:
    model: str
    temperature: float = 0.7

@dataclass(kw_only=True)            # 3.10+: avoids "non-default argument follows default argument"
class ChatRequest(BaseRequest):
    messages: list["Message"]
    stream: bool = False

Fields are collected base-first. A subclass field without a default after a base field with a default raises TypeError unless it is keyword-only (kw_only=True, field(kw_only=True) or after _: KW_ONLY). On 3.9, give the subclass field a default or use composition. Frozen and non-frozen dataclasses cannot inherit from each other.

#Option Cheat-Sheet

field() parameters: default, default_factory, init, repr, hash, compare, metadata, kw_only (3.10), doc (3.14). Full semantics, hash table and error catalogue: dataclass-reference.md.

#asdict / astuple / replace Pitfalls

• asdict() recurses into dataclasses, lists, tuples and dicts and copy.deepcopys everything else: a field holding a 100 MB np.ndarray is copied; a field holding a client, lock or open file raises TypeError: cannot pickle .... Use fields() + getattr for a shallow dict, or mark the field and skip it.
• asdict() keeps Enum, datetime, Path, Decimal objects as-is: json.dumps then fails. Pass default= or write a to_json_dict().
• replace() calls __init__ again: __post_init__ re-runs, init=False fields are recomputed (not copied), InitVars without defaults must be passed.
• fields() excludes ClassVar and InitVar pseudo-fields.

Serialization patterns (json, nested, enums, datetimes, numpy) and validation strategies: serialization-and-validation.md.

#AI-Engineering Patterns (summary)

from dataclasses import dataclass, field
from enum import Enum
from typing import Any, Literal, Optional

class Role(str, Enum):
    SYSTEM = "system"
    USER = "user"
    ASSISTANT = "assistant"
    TOOL = "tool"

@dataclass(frozen=True, slots=True)
class ToolCall:
    id: str
    name: str
    arguments: str          # raw JSON string from the model; parse+validate at the edge

@dataclass(slots=True)
class Message:
    role: Role
    content: Optional[str] = None
    tool_calls: list[ToolCall] = field(default_factory=list)
    tool_call_id: Optional[str] = None

    def to_api(self) -> dict[str, Any]:
        d: dict[str, Any] = {"role": self.role.value, "content": self.content}
        if self.tool_calls:
            d["tool_calls"] = [{"id": t.id, "type": "function",
                                "function": {"name": t.name, "arguments": t.arguments}} for t in self.tool_calls]
        if self.tool_call_id:
            d["tool_call_id"] = self.tool_call_id
        return d

@dataclass(frozen=True)
class GenerationConfig:
    model: str
    temperature: float = 0.0
    max_tokens: int = 1024
    stop: tuple[str, ...] = ()
    response_format: Literal["text", "json_object"] = "text"

• Configs: frozen dataclass, built once from YAML/env (validated with pydantic or a from_env classmethod), hashed into cache keys and run names.
• Requests/responses: dataclass with to_api() / from_api(); pydantic when parsing model output that may be malformed.
• Chunks/documents: embedding field with compare=False, repr=False; identity by chunk_id.
• Eval records: order=True or sorted(key=...); asdict() straight into a DataFrame / JSONL.

Full patterns (training/inference configs, streaming deltas, Anthropic content blocks, vector store records, eval harness rows): ai-engineering-models.md.

#Anti-Patterns to Fix

#Output Format

When converting, provide:

1. Container choice per object with one-line reason (boundary vs internal, mutability, hashing).
2. Converted code: imports, decorator options, fields, __post_init__, kept methods.
3. Behaviour changes: constructor signature, equality/hash semantics, repr output, explicit-None handling, version requirements (3.10 for kw_only/slots/KW_ONLY).
4. Serialization path if the object crosses a JSON/API boundary (from_dict, model_validate, asdict).
5. Verification snippet: construct, compare, hash, replace, JSON round-trip.

#Scripts

scripts/to_dataclass.py is static analysis only (it parses, never imports or runs the code):

# Convert boilerplate classes in a module; prints imports, notes with rule ids and @dataclass code
python scripts/to_dataclass.py class models.py
python scripts/to_dataclass.py class models.py --frozen --slots --kw-only
python scripts/to_dataclass.py class models.py --json --strict    # exit 1 if anything is convertible
cat models.py | python scripts/to_dataclass.py class -

# Generate nested typed classes from a JSON sample (object or list of objects)
python scripts/to_dataclass.py json response.json --name ChatCompletion                  # dataclasses + from_dict()
python scripts/to_dataclass.py json response.json --name ChatCompletion --style pydantic # BaseModel + Field(alias=)
python scripts/to_dataclass.py json events.json --name Event --style typeddict --json

Class mode findings: DC001 mutable default, DC002 None-sentinel default, DC003/DC004 redundant __repr__/__eq__, DC005 __hash__ -> frozen/unsafe_hash, DC006 ordering -> order=True, DC007 inferred/missing annotation, DC008 logic moved to __post_init__, DC009 slots, DC010 ClassVar, DC011 keyword-only, DC012 positional-only, DC013 InitVar, DC014 internal state field, DC015 mutation under frozen, DC016 identity-eq/hash change, DC017 array field excluded from eq, DC018 shared call default, DC019 implicit Optional. Skips: S01 already declarative, S02 no __init__, S03 *args/**kwargs, S04 super().__init__, S05 attribute renamed, S06 parameter reassigned after storing, S07 special base (Exception, Enum, BaseModel...), S08 metaclass/__new__, S09 return/yield in __init__, S10 nothing stored. JSON mode merges types across list items, marks missing/null keys Optional, snake_cases keys (aliases kept in metadata["json_key"] or Field(alias=)) and flags ISO-8601 strings. Exit codes: 0 ok, 1 with --strict when convertible classes exist, 2 on read/parse/usage errors. Always review the output: it cannot see call sites.

#Additional Resources