Python dataclasses vs Pydantic for internal models

<p>Using Pydantic BaseModel for everything including internal data transfer objects (DTOs) that never touch the API boundary. Pydantic validation overhead is unnecessary for internal models. Need guidance on when to use dataclasses vs Pydantic.</p>

<p>Use Python dataclasses for internal DTOs, Pydantic only for external API boundaries:</p> <div class="highlight"><pre><span></span><code><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="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">Optional</span> <span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">datetime</span> <span class="c1"># Internal DTO — no validation needed, just structure</span> <span class="nd">@dataclass</span> <span class="k">class</span><span class="w"> </span><span class="nc">TraceSearchParams</span><span class="p">:</span> <span class="n">query</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="n">field</span><span class="p">(</span><span class="n">default_factory</span><span class="o">=</span><span class="nb">list</span><span class="p">)</span> <span class="n">limit</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">20</span> <span class="n">offset</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span> <span class="n">include_seed</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span> <span class="n">min_trust_score</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">0.0</span> <span class="nd">@dataclass</span><span class="p">(</span><span class="n">frozen</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span> <span class="c1"># Immutable</span> <span class="k">class</span><span class="w"> </span><span class="nc">SearchResult</span><span class="p">:</span> <span class="n">trace_id</span><span class="p">:</span> <span class="nb">str</span> <span class="n">similarity_score</span><span class="p">:</span> <span class="nb">float</span> <span class="n">combined_score</span><span class="p">:</span> <span class="nb">float</span> <span class="n">rank</span><span class="p">:</span> <span class="nb">int</span> <span class="c1"># Pydantic for API models (validation + serialization)</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="p">,</span> <span class="n">Field</span><span class="p">,</span> <span class="n">field_validator</span> <span class="k">class</span><span class="w"> </span><span class="nc">TraceSearchRequest</span><span class="p">(</span><span class="n">BaseModel</span><span class="p">):</span> <span class="c1"># Used at API boundary</span> <span class="n">q</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="n">Field</span><span class="p">(</span><span class="o">...</span><span class="p">,</span> <span class="n">min_length</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">max_length</span><span class="o">=</span><span class="mi">500</span><span class="p">)</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="n">Field</span><span class="p">(</span><span class="n">default_factory</span><span class="o">=</span><span class="nb">list</span><span class="p">,</span> <span class="n">max_length</span><span class="o">=</span><span class="mi">10</span><span class="p">)</span> <span class="n">limit</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="n">Field</span><span class="p">(</span><span class="mi">20</span><span class="p">,</span> <span class="n">ge</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">le</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span> <span class="nd">@field_validator</span><span class="p">(</span><span class="s1">'tags'</span><span class="p">)</span> <span class="nd">@classmethod</span> <span class="k">def</span><span class="w"> </span><span class="nf">normalize_tags</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">v</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">-&gt;</span> <span class="nb">list</span><span class="p">[</span><span class="nb">str</span><span class="p">]:</span> <span class="k">return</span> <span class="p">[</span><span class="n">t</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span><span class="o">.</span><span class="n">strip</span><span class="p">()</span> <span class="k">for</span> <span class="n">t</span> <span class="ow">in</span> <span class="n">v</span><span class="p">]</span> <span class="c1"># Convert at the boundary</span> <span class="k">def</span><span class="w"> </span><span class="nf">to_search_params</span><span class="p">(</span><span class="n">request</span><span class="p">:</span> <span class="n">TraceSearchRequest</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">TraceSearchParams</span><span class="p">:</span> <span class="k">return</span> <span class="n">TraceSearchParams</span><span class="p">(</span> <span class="n">query</span><span class="o">=</span><span class="n">request</span><span class="o">.</span><span class="n">q</span><span class="p">,</span> <span class="n">tags</span><span class="o">=</span><span class="n">request</span><span class="o">.</span><span class="n">tags</span><span class="p">,</span> <span class="n">limit</span><span class="o">=</span><span class="n">request</span><span class="o">.</span><span class="n">limit</span><span class="p">,</span> <span class="p">)</span> <span class="c1"># Slots for memory efficiency with many instances</span> <span class="nd">@dataclass</span><span class="p">(</span><span class="n">slots</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span> <span class="k">class</span><span class="w"> </span><span class="nc">EmbeddingBatch</span><span class="p">:</span> <span class="n">trace_id</span><span class="p">:</span> <span class="nb">str</span> <span class="n">text</span><span class="p">:</span> <span class="nb">str</span> <span class="n">created_at</span><span class="p">:</span> <span class="n">datetime</span> </code></pre></div> <p>Dataclasses are ~5x faster to construct than Pydantic models (no validation overhead). Use <code>frozen=True</code> for hashable/immutable value objects. Use <code>slots=True</code> (Python 3.10+) to reduce memory by ~30% when creating many instances. Reserve Pydantic for places where validation and serialization matter: API request/response models, config, external data parsing.</p>