Better dispatch docs; cleanup in validation

docs/dispatch.rst

@@ -12,20 +12,6 @@ Features:
 - Fast
 
 
-Decorator
----------
-
-.. autofunction:: runtype.multidispatch
-
-.. autofunction:: runtype.Dispatch
-
-.. autoclass:: runtype.dispatch.MultiDispatch
-    :members: choices, feed_token, copy, pretty, resume_parse, exhaust_lexer, accepts, as_immutable
-
-.. autoclass:: runtype.dispatch.DispatchError
-
-
-
 What is multiple-dispatch?
 --------------------------
 
@@ -120,6 +106,19 @@ Then, the group can be used as a decorator for any number of functions, in any m
 Functions will still be grouped by name.
 
 
+Decorator
+---------
+
+.. autofunction:: runtype.multidispatch
+
+.. autofunction:: runtype.Dispatch
+
+.. autoclass:: runtype.dispatch.MultiDispatch
+    :members: choices, feed_token, copy, pretty, resume_parse, exhaust_lexer, accepts, as_immutable
+
+.. autoclass:: runtype.dispatch.DispatchError
+
+
 Specificity
 -----------
 

runtype/__init__.py

@@ -57,25 +57,25 @@ def decorate(self, f: Callable) -> Callable:
                 >>> from runtype import multidispatch as md
 
                 >>> @md
-                ... def add1(i: Optional[int]):
+                ... def add1(i: int):
                 ...     return i + 1
 
                 >>> @md
-                ... def add1(s: Optional[str]):
-                ...     return s + "1"
+                ... def add1(s: str):
+                ...     return s + '1'
 
                 >>> @md
                 ... def add1(a):  # accepts any type (least-specific)
-                ...     return (a, 1)
+                ...     return ('add', a, 1)
 
                 >>> add1(1)
                 2
 
-                >>> add1("1")
+                >>> add1('1')
                 11
 
                 >>> add1(1.0)
-                (1.0, 1)
+                ('add', 1.0, 1)
 
 
         """

runtype/dispatch.py

@@ -19,9 +19,9 @@ class MultiDispatch:
     """Creates a dispatch group for multiple dispatch
 
     Parameters:
-        typesystem - instance for interfacing with the typesystem
+        typesystem (Typesystem): Which type-system to use for dispatch.
         test_subtypes: indices of params that should be matched by subclass instead of isinstance.
-                        (will be soon deprecated, and replaced by using Type[..] annotations)
+                        (will be soon deprecated and replaced by using Type[..] annotations)
     """
 
     def __init__(self, typesystem: TypeSystem, test_subtypes: Sequence[int] = ()):

runtype/validation.py

@@ -1,11 +1,10 @@
 "User-facing API for validation"
 
-from typing import Any, Dict, List, Tuple, Set, FrozenSet
 from functools import wraps
 
 from .common import CHECK_TYPES
 from .utils import get_func_signatures
-from .pytypes import TypeMismatchError, type_caster
+from .pytypes import TypeMismatchError, type_caster, All
 from .typesystem import TypeSystem
 
 def ensure_isa(obj, t, sampler=None):
@@ -54,24 +53,6 @@ def assert_isa(obj, t):
             raise TypeError(msg)
 
 
-_CANONICAL_TYPES = {
-    # Any: object,
-    List: list,
-    Set: set,
-    FrozenSet: frozenset,
-    Dict: dict,
-    Tuple: tuple,
-    List[Any]: list,
-    Set[Any]: set,
-    FrozenSet[Any]: frozenset,
-    Dict[Any, Any]: dict,
-    Tuple[Any, ...]: tuple,
-}
-
-def to_canonical_type(t):
-    "Turns List -> list, Dict -> dict, etc."
-    return _CANONICAL_TYPES.get(t, t)
-
 
 def issubclass(t1, t2):
     """Test if t1 is a subclass of t2
@@ -90,9 +71,9 @@ def issubclass(t1, t2):
 class PythonTyping(TypeSystem):
     isinstance = staticmethod(isa)
     issubclass = staticmethod(issubclass)
-    to_canonical_type = staticmethod(to_canonical_type)
+    to_canonical_type = type_caster.to_canon
     get_type = type
-    default_type = object
+    default_type = All
 
 
 def validate_func(f):