Python dataclass vs Pydantic model — when to use each

<p>I'm building a Python service and not sure whether to use Python dataclasses, Pydantic models, or attrs for different data structures. I need to understand the tradeoffs for API schemas, internal data transfer objects, and configuration.</p>

<p>Use each type for its strengths:</p> <div class="highlight"><pre><span></span><code><span class="c1"># Pydantic BaseModel — for API requests/responses and config</span> <span class="c1"># Pros: validation, serialization, OpenAPI schema generation</span> <span class="c1"># Cons: slower to create, heavier than dataclasses</span> <span class="kn">from</span><span class="w"> </span><span class="nn">pydantic</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseModel</span> <span class="k">class</span><span class="w"> </span><span class="nc">TraceCreate</span><span class="p">(</span><span class="n">BaseModel</span><span class="p">):</span> <span class="c1"># API request body</span> <span class="n">title</span><span class="p">:</span> <span class="nb">str</span> <span class="n">context_text</span><span class="p">:</span> <span class="nb">str</span> <span class="n">tags</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="p">[]</span> <span class="c1"># Python dataclass — for internal data transfer objects</span> <span class="c1"># Pros: fast, simple, stdlib (no deps), good for pure data carriers</span> <span class="c1"># Cons: no validation, no serialization helpers</span> <span class="kn">from</span><span class="w"> </span><span class="nn">dataclasses</span><span class="w"> </span><span class="kn">import</span> <span class="n">dataclass</span><span class="p">,</span> <span class="n">field</span> <span class="nd">@dataclass</span> <span class="k">class</span><span class="w"> </span><span class="nc">EmbeddingResult</span><span class="p">:</span> <span class="c1"># Internal DTO between worker layers</span> <span class="n">trace_id</span><span class="p">:</span> <span class="nb">str</span> <span class="n">embedding</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="nb">float</span><span class="p">]</span> <span class="n">model</span><span class="p">:</span> <span class="nb">str</span> <span class="n">tokens_used</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span> <span class="c1"># TypedDict — for dict-compatible type hints (JSON-like structures)</span> <span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">TypedDict</span> <span class="k">class</span><span class="w"> </span><span class="nc">SearchFilters</span><span class="p">(</span><span class="n">TypedDict</span><span class="p">,</span> <span class="n">total</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span> <span class="c1"># Optional keys</span> <span class="n">status</span><span class="p">:</span> <span class="nb">str</span> <span class="n">tag</span><span class="p">:</span> <span class="nb">str</span> <span class="n">min_trust</span><span class="p">:</span> <span class="nb">float</span> <span class="c1"># Named tuples — for simple immutable records</span> <span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">NamedTuple</span> <span class="k">class</span><span class="w"> </span><span class="nc">PaginationMeta</span><span class="p">(</span><span class="n">NamedTuple</span><span class="p">):</span> <span class="n">page</span><span class="p">:</span> <span class="nb">int</span> <span class="n">page_size</span><span class="p">:</span> <span class="nb">int</span> <span class="n">total</span><span class="p">:</span> <span class="nb">int</span> </code></pre></div> <p>Decision guide: - API boundary (in/out): <strong>Pydantic</strong> — validation + schema generation - Configuration: <strong>Pydantic Settings</strong> — env var support - Internal DTOs: <strong>dataclass</strong> — fast, simple, no overhead - Dict-like JSON structures: <strong>TypedDict</strong> — type hints without instantiation - Small immutable tuples: <strong>NamedTuple</strong> — readable, hashable</p>