Python type narrowing with TypeGuard and isinstance

<p>Working with union types and need TypeScript-style type guards in Python. After checking <code>isinstance(x, str)</code>, the type checker should know <code>x</code> is a <code>str</code> in that branch. Also need custom narrowing functions for complex types.</p>

<p>Use <code>isinstance</code> for built-in types and <code>TypeGuard</code> for custom narrowing:</p> <div class="highlight"><pre><span></span><code><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">TypeGuard</span><span class="p">,</span> <span class="n">Union</span><span class="p">,</span> <span class="n">Any</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="c1"># Basic isinstance narrowing — mypy/pyright understand this automatically</span> <span class="k">def</span><span class="w"> </span><span class="nf">process_value</span><span class="p">(</span><span class="n">value</span><span class="p">:</span> <span class="nb">str</span> <span class="o">|</span> <span class="nb">int</span> <span class="o">|</span> <span class="kc">None</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">str</span><span class="p">:</span> <span class="k">if</span> <span class="n">value</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span> <span class="k">return</span> <span class="s1">''</span> <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="nb">int</span><span class="p">):</span> <span class="k">return</span> <span class="nb">str</span><span class="p">(</span><span class="n">value</span><span class="p">)</span> <span class="c1"># value is int here</span> <span class="k">return</span> <span class="n">value</span><span class="o">.</span><span class="n">upper</span><span class="p">()</span> <span class="c1"># value is str here</span> <span class="c1"># TypeGuard for custom type predicates</span> <span class="nd">@dataclass</span> <span class="k">class</span><span class="w"> </span><span class="nc">ValidTrace</span><span class="p">:</span> <span class="nb">id</span><span class="p">:</span> <span class="nb">str</span> <span class="n">title</span><span class="p">:</span> <span class="nb">str</span> <span class="n">trust_score</span><span class="p">:</span> <span class="nb">float</span> <span class="k">def</span><span class="w"> </span><span class="nf">is_valid_trace</span><span class="p">(</span><span class="n">obj</span><span class="p">:</span> <span class="n">Any</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">TypeGuard</span><span class="p">[</span><span class="n">ValidTrace</span><span class="p">]:</span> <span class="k">return</span> <span class="p">(</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="nb">dict</span><span class="p">)</span> <span class="ow">and</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">obj</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'id'</span><span class="p">),</span> <span class="nb">str</span><span class="p">)</span> <span class="ow">and</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">obj</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'title'</span><span class="p">),</span> <span class="nb">str</span><span class="p">)</span> <span class="ow">and</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">obj</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'trust_score'</span><span class="p">),</span> <span class="nb">float</span><span class="p">)</span> <span class="p">)</span> <span class="k">def</span><span class="w"> </span><span class="nf">process_api_response</span><span class="p">(</span><span class="n">data</span><span class="p">:</span> <span class="n">Any</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">ValidTrace</span> <span class="o">|</span> <span class="kc">None</span><span class="p">:</span> <span class="k">if</span> <span class="n">is_valid_trace</span><span class="p">(</span><span class="n">data</span><span class="p">):</span> <span class="k">return</span> <span class="n">data</span> <span class="c1"># Type is narrowed to ValidTrace here</span> <span class="k">return</span> <span class="kc">None</span> <span class="c1"># Narrowing with literal types</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">Literal</span> <span class="n">Status</span> <span class="o">=</span> <span class="n">Literal</span><span class="p">[</span><span class="s1">'pending'</span><span class="p">,</span> <span class="s1">'validated'</span><span class="p">,</span> <span class="s1">'rejected'</span><span class="p">]</span> <span class="k">def</span><span class="w"> </span><span class="nf">is_status</span><span class="p">(</span><span class="n">value</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">TypeGuard</span><span class="p">[</span><span class="n">Status</span><span class="p">]:</span> <span class="k">return</span> <span class="n">value</span> <span class="ow">in</span> <span class="p">(</span><span class="s1">'pending'</span><span class="p">,</span> <span class="s1">'validated'</span><span class="p">,</span> <span class="s1">'rejected'</span><span class="p">)</span> <span class="k">def</span><span class="w"> </span><span class="nf">handle_status</span><span class="p">(</span><span class="n">raw</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span> <span class="k">if</span> <span class="n">is_status</span><span class="p">(</span><span class="n">raw</span><span class="p">):</span> <span class="n">handle_trace_status</span><span class="p">(</span><span class="n">raw</span><span class="p">)</span> <span class="c1"># raw is Status here</span> <span class="c1"># assert_never for exhaustive matching</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">Never</span> <span class="k">def</span><span class="w"> </span><span class="nf">handle_event</span><span class="p">(</span><span class="n">event</span><span class="p">:</span> <span class="n">Literal</span><span class="p">[</span><span class="s1">'created'</span><span class="p">,</span> <span class="s1">'updated'</span><span class="p">,</span> <span class="s1">'deleted'</span><span class="p">])</span> <span class="o">-&gt;</span> <span class="nb">str</span><span class="p">:</span> <span class="k">match</span> <span class="n">event</span><span class="p">:</span> <span class="k">case</span> <span class="s1">'created'</span><span class="p">:</span> <span class="k">return</span> <span class="s1">'New item'</span> <span class="k">case</span> <span class="s1">'updated'</span><span class="p">:</span> <span class="k">return</span> <span class="s1">'Item changed'</span> <span class="k">case</span> <span class="s1">'deleted'</span><span class="p">:</span> <span class="k">return</span> <span class="s1">'Item removed'</span> <span class="k">case</span><span class="w"> </span><span class="k">_</span> <span class="k">as</span> <span class="n">unreachable</span><span class="p">:</span> <span class="c1"># Type checker errors if any case is missed</span> <span class="n">assert_never</span><span class="p">(</span><span class="n">unreachable</span><span class="p">)</span> <span class="k">def</span><span class="w"> </span><span class="nf">assert_never</span><span class="p">(</span><span class="n">value</span><span class="p">:</span> <span class="n">Never</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Never</span><span class="p">:</span> <span class="k">raise</span> <span class="ne">AssertionError</span><span class="p">(</span><span class="sa">f</span><span class="s1">'Unhandled case: </span><span class="si">{</span><span class="n">value</span><span class="si">}</span><span class="s1">'</span><span class="p">)</span> </code></pre></div> <p><code>TypeGuard[T]</code> tells the type checker that when the function returns <code>True</code>, the argument is of type <code>T</code>. Without it, custom predicate functions don't narrow types. Works with mypy, pyright, and pyright-based editors.</p>