deploy: 234cc4b

Author: wesselb

_modules/plum/signature.html

@@ -477,16 +477,26 @@ <h1>Source code for plum.signature</h1><div class="highlight"><pre>
 
     <span class="k">def</span><span class="w"> </span><span class="fm">__eq__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">:</span> <span class="n">Any</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">bool</span><span class="p">:</span>
         <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">other</span><span class="p">,</span> <span class="n">Signature</span><span class="p">):</span>
+            <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">varargs</span> <span class="ow">is</span> <span class="n">Missing</span><span class="p">:</span>
+                <span class="n">self_varargs</span> <span class="o">=</span> <span class="n">Missing</span>
+            <span class="k">else</span><span class="p">:</span>
+                <span class="n">self_varargs</span> <span class="o">=</span> <span class="n">beartype</span><span class="o">.</span><span class="n">door</span><span class="o">.</span><span class="n">TypeHint</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">varargs</span><span class="p">)</span>
+
+            <span class="k">if</span> <span class="n">other</span><span class="o">.</span><span class="n">varargs</span> <span class="ow">is</span> <span class="n">Missing</span><span class="p">:</span>
+                <span class="n">other_varargs</span> <span class="o">=</span> <span class="n">Missing</span>
+            <span class="k">else</span><span class="p">:</span>
+                <span class="n">other_varargs</span> <span class="o">=</span> <span class="n">beartype</span><span class="o">.</span><span class="n">door</span><span class="o">.</span><span class="n">TypeHint</span><span class="p">(</span><span class="n">other</span><span class="o">.</span><span class="n">varargs</span><span class="p">)</span>
+
+            <span class="c1"># We don&#39;t need to check faithfulness, because that is automatically derived</span>
+            <span class="c1"># from the arguments.</span>
             <span class="k">return</span> <span class="p">(</span>
-                <span class="bp">self</span><span class="o">.</span><span class="n">types</span><span class="p">,</span>
-                <span class="bp">self</span><span class="o">.</span><span class="n">varargs</span><span class="p">,</span>
+                <span class="nb">tuple</span><span class="p">(</span><span class="n">beartype</span><span class="o">.</span><span class="n">door</span><span class="o">.</span><span class="n">TypeHint</span><span class="p">(</span><span class="n">t</span><span class="p">)</span> <span class="k">for</span> <span class="n">t</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">types</span><span class="p">),</span>
+                <span class="n">self_varargs</span><span class="p">,</span>
                 <span class="bp">self</span><span class="o">.</span><span class="n">precedence</span><span class="p">,</span>
-                <span class="bp">self</span><span class="o">.</span><span class="n">is_faithful</span><span class="p">,</span>
             <span class="p">)</span> <span class="o">==</span> <span class="p">(</span>
-                <span class="n">other</span><span class="o">.</span><span class="n">types</span><span class="p">,</span>
-                <span class="n">other</span><span class="o">.</span><span class="n">varargs</span><span class="p">,</span>
+                <span class="nb">tuple</span><span class="p">(</span><span class="n">beartype</span><span class="o">.</span><span class="n">door</span><span class="o">.</span><span class="n">TypeHint</span><span class="p">(</span><span class="n">t</span><span class="p">)</span> <span class="k">for</span> <span class="n">t</span> <span class="ow">in</span> <span class="n">other</span><span class="o">.</span><span class="n">types</span><span class="p">),</span>
+                <span class="n">other_varargs</span><span class="p">,</span>
                 <span class="n">other</span><span class="o">.</span><span class="n">precedence</span><span class="p">,</span>
-                <span class="n">other</span><span class="o">.</span><span class="n">is_faithful</span><span class="p">,</span>
             <span class="p">)</span>
         <span class="k">return</span> <span class="kc">False</span>
 

_modules/plum/type.html

@@ -644,7 +644,7 @@ <h1>Source code for plum.type</h1><div class="highlight"><pre>
             <span class="c1"># counter-example, we will refine this logic.</span>
             <span class="k">return</span> <span class="kc">True</span>
         <span class="k">else</span><span class="p">:</span>
-            <span class="k">if</span> <span class="n">origin</span> <span class="ow">in</span> <span class="p">{</span><span class="n">typing</span><span class="o">.</span><span class="n">Union</span><span class="p">,</span> <span class="n">typing</span><span class="o">.</span><span class="n">Optional</span><span class="p">}:</span>
+            <span class="k">if</span> <span class="n">origin</span> <span class="ow">in</span> <span class="p">{</span><span class="n">typing</span><span class="o">.</span><span class="n">Union</span><span class="p">,</span> <span class="n">UnionType</span><span class="p">,</span> <span class="n">typing</span><span class="o">.</span><span class="n">Optional</span><span class="p">}:</span>
                 <span class="k">return</span> <span class="nb">all</span><span class="p">(</span><span class="n">is_faithful</span><span class="p">(</span><span class="n">arg</span><span class="p">)</span> <span class="k">for</span> <span class="n">arg</span> <span class="ow">in</span> <span class="n">args</span><span class="p">)</span>
             <span class="k">else</span><span class="p">:</span>
                 <span class="k">return</span> <span class="kc">False</span>

_sources/types.md

@@ -48,12 +48,41 @@ def f(x: Dict[int, str]) -> str:
    return "dict of int to str"
 ```
 
-**Note:**
 Although parametric types such as `List[int]` and `Dict[int, str]` are fully
 supported, they do incur a performance penalty.
 For optimal performance, is recommended to use parametric types only where necessary.
 `Union` and `Optional` do not incur a performance penalty.
 
+````{important}
+Plum's type system is powered by [Beartype](https://github.com/beartype/beartype).
+To ensure constant-time performance,
+Beartype checks the types of containers by checking the type of a random single element.
+This means that it is not safe to use containers with mixed element types!
+
+```python
+from typing import List
+
+from plum import dispatch
+
+
+@dispatch
+def f(x: List[int]) -> str:
+    return "list of int"
+```
+
+```
+>>> f([1, "1"])  # It might happen to check the first element.
+"list of int"
+
+>>> f([1, "1"])  # Or it might check the second. :(
+NotFoundLookupError: `f([1, '1'])` could not be resolved.
+```
+
+In the future, Beartype
+[will support exhaustive type checking](https://beartype.readthedocs.io/en/latest/api_decor/#beartype.BeartypeStrategy.On).
+Plum already opts into this behaviour and will use it once it becomes available.
+````
+
 The type system is *covariant*, as opposed to Julia's type
 system, which is *invariant*.
 For example, this means that `List[T1]` is a subtype of `List[T2]` whenever

searchindex.js

@@ -457,11 +457,37 @@ <h1>Types<a class="headerlink" href="#types" title="Link to this heading">#</a><
    <span class="k">return</span> <span class="s2">&quot;dict of int to str&quot;</span>
 </pre></div>
 </div>
-<p><strong>Note:</strong>
-Although parametric types such as <code class="docutils literal notranslate"><span class="pre">List[int]</span></code> and <code class="docutils literal notranslate"><span class="pre">Dict[int,</span> <span class="pre">str]</span></code> are fully
+<p>Although parametric types such as <code class="docutils literal notranslate"><span class="pre">List[int]</span></code> and <code class="docutils literal notranslate"><span class="pre">Dict[int,</span> <span class="pre">str]</span></code> are fully
 supported, they do incur a performance penalty.
 For optimal performance, is recommended to use parametric types only where necessary.
 <code class="docutils literal notranslate"><span class="pre">Union</span></code> and <code class="docutils literal notranslate"><span class="pre">Optional</span></code> do not incur a performance penalty.</p>
+<div class="admonition important">
+<p class="admonition-title">Important</p>
+<p>Plum’s type system is powered by <a class="reference external" href="https://github.com/beartype/beartype">Beartype</a>.
+To ensure constant-time performance,
+Beartype checks the types of containers by checking the type of a random single element.
+This means that it is not safe to use containers with mixed element types!</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></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">List</span>
+
+<span class="kn">from</span><span class="w"> </span><span class="nn">plum</span><span class="w"> </span><span class="kn">import</span> <span class="n">dispatch</span>
+
+
+<span class="nd">@dispatch</span>
+<span class="k">def</span><span class="w"> </span><span class="nf">f</span><span class="p">(</span><span class="n">x</span><span class="p">:</span> <span class="n">List</span><span class="p">[</span><span class="nb">int</span><span class="p">])</span> <span class="o">-&gt;</span> <span class="nb">str</span><span class="p">:</span>
+    <span class="k">return</span> <span class="s2">&quot;list of int&quot;</span>
+</pre></div>
+</div>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="s2">&quot;1&quot;</span><span class="p">])</span>  <span class="c1"># It might happen to check the first element.</span>
+<span class="go">&quot;list of int&quot;</span>
+
+<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="s2">&quot;1&quot;</span><span class="p">])</span>  <span class="c1"># Or it might check the second. :(</span>
+<span class="go">NotFoundLookupError: `f([1, &#39;1&#39;])` could not be resolved.</span>
+</pre></div>
+</div>
+<p>In the future, Beartype
+<a class="reference external" href="https://beartype.readthedocs.io/en/latest/api_decor/#beartype.BeartypeStrategy.On">will support exhaustive type checking</a>.
+Plum already opts into this behaviour and will use it once it becomes available.</p>
+</div>
 <p>The type system is <em>covariant</em>, as opposed to Julia’s type
 system, which is <em>invariant</em>.
 For example, this means that <code class="docutils literal notranslate"><span class="pre">List[T1]</span></code> is a subtype of <code class="docutils literal notranslate"><span class="pre">List[T2]</span></code> whenever