Python dataclass vs Pydantic model vs TypedDict comparison

<p>I need to decide when to use Python dataclasses, Pydantic models, TypedDict, or NamedTuple for different data structures in my application. Each has tradeoffs in validation, serialization, and overhead.</p>

<p>Choose the right data container for the use case:</p> <div class="highlight"><pre><span></span><code><span class="c1"># Pydantic BaseModel -- API boundaries: 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="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"># Validates on creation, serializes with model_dump()</span> <span class="c1"># dataclass -- internal DTOs: fast, simple, no validation overhead</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 data 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 -- dict-compatible type hints for 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="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"># NamedTuple -- small 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> <span class="n">pages</span><span class="p">:</span> <span class="nb">int</span> <span class="c1"># Pydantic Settings -- configuration</span> <span class="kn">from</span><span class="w"> </span><span class="nn">pydantic_settings</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseSettings</span> <span class="k">class</span><span class="w"> </span><span class="nc">Settings</span><span class="p">(</span><span class="n">BaseSettings</span><span class="p">):</span> <span class="n">database_url</span><span class="p">:</span> <span class="nb">str</span> <span class="n">redis_url</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s1">'redis://localhost:6379'</span> </code></pre></div> <p>Decision guide: - API boundary (in/out): Pydantic -- validation + OpenAPI schema - Configuration: Pydantic Settings -- env var support - Internal DTOs: dataclass -- fast, no overhead, stdlib - Dict-like JSON: TypedDict -- type hints without instantiation cost - Small immutable: NamedTuple -- readable, hashable</p>