Widened type interface

docs/creating.rst

@@ -29,10 +29,16 @@ Creating or Extending Validator Classes
         will have :func:`validates` automatically called for the given
         version.
 
-    :argument dict default_types: a default mapping to use for instances
-        of the validator class when mapping between JSON types to Python
-        types. The default for this argument is probably fine. Instances
-        can still have their types customized on a per-instance basis.
+    :argument dict default_types: Deprecated. Please use the type_checker
+        argument instead.
+
+        If set, it provides mappings of JSON types to Python types that will
+        be converted to functions and redefined in this object's TypeChecker
+
+    :argument jsonschema.TypeChecker type_checker: an instance
+        of :class:`TypeChecker`, whose :meth:`is_type` will be called to
+        validate the :validator:`type` property If unprovided, a default
+        :class:`TypeChecker` will be created, with no support types.
 
     :returns: a new :class:`jsonschema.IValidator` class
 
@@ -59,6 +65,10 @@ Creating or Extending Validator Classes
 
     :argument str version: a version for the new validator class
 
+    :argument jsonschema.TypeChecker type_checker: an instance
+        of :class:`TypeChecker`. If unprovided, the existing
+        :class:`TypeChecker` will be used.
+
     :returns: a new :class:`jsonschema.IValidator` class
 
     .. note:: Meta Schemas

docs/index.rst

@@ -47,6 +47,7 @@ Contents:
     references
     creating
     faq
+    types
 
 
 Indices and tables

docs/types.rst

@@ -0,0 +1,23 @@
+.. currentmodule:: jsonschema
+
+=============
+Type Checking
+=============
+
+Each :class:`IValidator` has an associated :class:`TypeChecker`. The
+TypeChecker provides an immutable mapping between names of types and
+functions that can test if an instance is of that type. The defaults are
+suitable for most users - each of the predefined Validators (Draft3, Draft4)
+has a :class:`TypeChecker` that can correctly handle that draft.
+
+See :ref:`validating-types` for an example of providing a custom type check.
+
+.. autoclass:: TypeChecker
+    :members:
+
+.. autoexception:: jsonschema.exceptions.UndefinedTypeCheck
+
+    Raised when trying to remove a type check that is not known to this
+    TypeChecker. Internally this is also raised when calling
+    :meth:`TypeChecker.is_type`, but is caught and re-raised as a
+    :class:`jsonschema.exceptions.UnknownType` exception.

docs/validate.rst

@@ -32,10 +32,12 @@ classes should adhere to.
         will validate with. It is assumed to be valid, and providing
         an invalid schema can lead to undefined behavior. See
         :meth:`IValidator.check_schema` to validate a schema first.
-    :argument types: Override or extend the list of known types when
+    :argument types: Deprecated. Instead, create a custom TypeChecker
+        and extend the validator. See :ref:`validating-types` for details.
+
+        If used, this overrides or extends the list of known type when
         validating the :validator:`type` property. Should map strings (type
         names) to class objects that will be checked via :func:`isinstance`.
-        See :ref:`validating-types` for details.
     :type types: dict or iterable of 2-tuples
     :argument resolver: an instance of :class:`RefResolver` that will be
         used to resolve :validator:`$ref` properties (JSON references). If
@@ -48,8 +50,10 @@ classes should adhere to.
 
     .. attribute:: DEFAULT_TYPES
 
-        The default mapping of JSON types to Python types used when validating
-        :validator:`type` properties in JSON schemas.
+        Deprecated. Under normal usage, this will be an empty dictionary.
+
+        If set, it provides mappings of JSON types to Python types that will
+        be converted to functions and redefined in this object's TypeChecker
 
     .. attribute:: META_SCHEMA
 
@@ -62,6 +66,10 @@ classes should adhere to.
         that validate the validator property with that name. For more
         information see :ref:`creating-validators`.
 
+    .. attribute:: TYPE_CHECKER
+        A :class:`TypeChecker` that can be used validating :validator:`type`
+         properties in JSON schemas.
+
     .. attribute:: schema
 
         The schema that was passed in when initializing the object.
@@ -134,10 +142,7 @@ Validating With Additional Types
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Occasionally it can be useful to provide additional or alternate types when
-validating the JSON Schema's :validator:`type` property. Validators allow this
-by taking a ``types`` argument on construction that specifies additional types,
-or which can be used to specify a different set of Python types to map to a
-given JSON type.
+validating the JSON Schema's :validator:`type` property.
 
 :mod:`jsonschema` tries to strike a balance between performance in the common
 case and generality. For instance, JSON Schema defines a ``number`` type, which
@@ -152,24 +157,24 @@ more general instance checks can introduce significant slowdown, especially
 given how common validating these types are.
 
 If you *do* want the generality, or just want to add a few specific additional
-types as being acceptable for a validator object, :class:`IValidator`\s have a
-``types`` argument that can be used to provide additional or new types.
+types as being acceptable for a validator object, then you should update an
+existing :class:`TypeChecker` or create a new one. You may then create a new
+:class:`IValidator` via :meth:`extend`.
 
 .. code-block:: python
 
     class MyInteger(object):
-        ...
+        pass
+
+    def is_my_int(instance):
+        return Draft3Validator.TYPE_CHECKER.is_type(instance, "number") or \
+        isinstance(instance, MyInteger)
+
+    type_checker = Draft3Validator.TYPE_CHECKER.redefine("number", is_my_int)
 
-    Draft3Validator(
-        schema={"type" : "number"},
-        types={"number" : (numbers.Number, MyInteger)},
-    )
+    CustomValidator = extend(Draft3Validator, type_checker=type_checker)
+    validator = CustomValidator(schema={"type" : "number"})
 
-The list of default Python types for each JSON type is available on each
-validator object in the :attr:`IValidator.DEFAULT_TYPES` attribute. Note
-that you need to specify all types to match if you override one of the
-existing JSON types, so you may want to access the set of default types
-when specifying your additional type.
 
 .. _versioned-validators:
 

jsonschema/__init__.py

@@ -15,6 +15,11 @@
 from jsonschema._format import (
     FormatChecker, draft3_format_checker, draft4_format_checker,
 )
+from jsonschema._types import (
+    TypeChecker,
+    draft3_type_checker,
+    draft4_type_checker,
+)
 from jsonschema.validators import (
     Draft3Validator, Draft4Validator, RefResolver, validate
 )

jsonschema/_types.py

@@ -0,0 +1,206 @@
+import numbers
+
+import attr
+import pyrsistent
+
+from jsonschema.compat import str_types, int_types, iteritems
+from jsonschema.exceptions import UndefinedTypeCheck
+
+
+def is_array(instance):
+    return isinstance(instance, list)
+
+
+def is_bool(instance):
+    return isinstance(instance, bool)
+
+
+def is_integer(instance):
+    # bool inherits from int, so ensure bools aren't reported as ints
+    if isinstance(instance, bool):
+        return False
+    return isinstance(instance, int_types)
+
+
+def is_null(instance):
+    return instance is None
+
+
+def is_number(instance):
+    # bool inherits from int, so ensure bools aren't reported as ints
+    if isinstance(instance, bool):
+        return False
+    return isinstance(instance, numbers.Number)
+
+
+def is_object(instance):
+    return isinstance(instance, dict)
+
+
+def is_string(instance):
+    return isinstance(instance, str_types)
+
+
+def is_any(instance):
+    return True
+
+
+@attr.s(frozen=True)
+class TypeChecker(object):
+    """
+    A ``type`` property checker.
+
+    A :class:`TypeChecker` performs type checking for an instance of
+    :class:`Validator`. Type checks to perform are set using
+    :meth:`TypeChecker.redefine` or :meth:`TypeChecker.redefine_many` and
+    removed via :meth:`TypeChecker.remove` or
+    :meth:`TypeChecker.remove_many`. Each of these return a new
+    :class:`TypeChecker` object.
+
+    Arguments:
+
+        type_checkers (pyrsistent.pmap):
+
+            It is recommend to set type checkers through
+            :meth:`TypeChecker.redefine` or :meth:`TypeChecker.redefine_many`
+    """
+    _type_checkers = attr.ib(default=pyrsistent.pmap({}))
+
+    def is_type(self, instance, type):
+        """
+        Check if the instance is of the appropriate type.
+
+        Arguments:
+
+            instance (any primitive type, i.e. str, number, bool):
+
+                The instance to check
+
+            type (str):
+
+                The name of the type that is expected.
+
+        Returns:
+
+            bool: Whether it conformed.
+
+
+        Raises:
+
+            :exc:`jsonschema.exceptions.UndefinedTypeCheck`:
+                if type is unknown to this object.
+        """
+        try:
+            return self._type_checkers[type](instance)
+        except KeyError:
+            raise UndefinedTypeCheck
+
+    def redefine(self, type, fn):
+        """
+        Redefine the checker for type to the function fn.
+
+        Arguments:
+
+            type (str):
+
+                The name of the type to check.
+
+            fn (callable):
+
+                A function taking exactly one parameter, instance,
+                that checks if instance is of this type.
+
+        Returns:
+
+            A new :class:`TypeChecker` instance.
+
+        """
+        return self.redefine_many({type:fn})
+
+    def redefine_many(self, definitions=()):
+        """
+        Redefine multiple type checkers.
+
+        Arguments:
+
+            definitions (dict):
+
+                A dictionary mapping types to their checking functions.
+
+        Returns:
+
+            A new :class:`TypeChecker` instance.
+
+        """
+        definitions = dict(definitions)
+        evolver = self._type_checkers.evolver()
+
+        for type_, checker in iteritems(definitions):
+            evolver[type_] = checker
+
+        return attr.evolve(self, type_checkers=evolver.persistent())
+
+    def remove(self, type):
+        """
+        Remove the type from the checkers that this object understands.
+
+        Arguments:
+
+            type (str):
+
+                The name of the type to remove.
+
+        Returns:
+
+            A new :class:`TypeChecker` instance
+
+        Raises:
+
+            :exc:`jsonschema.exceptions.UndefinedTypeCheck`:
+                if type is unknown to this object
+
+        """
+        return self.remove_many((type,))
+
+    def remove_many(self, types):
+        """
+        Remove multiple types from the checkers that this object understands.
+
+        Arguments:
+
+            types (iterable):
+
+                An iterable of types to remove.
+
+        Returns:
+
+            A new :class:`TypeChecker` instance
+
+        Raises:
+
+            :exc:`jsonschema.exceptions.UndefinedTypeCheck`:
+                if any of the types are unknown to this object
+        """
+        evolver = self._type_checkers.evolver()
+
+        for type_ in types:
+            try:
+                del evolver[type_]
+            except KeyError:
+                raise UndefinedTypeCheck
+
+        return attr.evolve(self, type_checkers=evolver.persistent())
+
+
+draft3_type_checker = TypeChecker().redefine_many({
+    u"any": is_any,
+    u"array": is_array,
+    u"boolean": is_bool,
+    u"integer": is_integer,
+    u"object": is_object,
+    u"null": is_null,
+    u"number": is_number,
+    u"string": is_string
+})
+
+draft4_type_checker = draft3_type_checker.remove(u"any")

jsonschema/compat.py

@@ -28,7 +28,7 @@
     )
     from urllib import unquote  # noqa
     from urllib2 import urlopen  # noqa
-    str_types = basestring
+    str_types = basestring,
     int_types = int, long
     iteritems = operator.methodcaller("iteritems")
 

jsonschema/exceptions.py

@@ -140,6 +140,9 @@ class RefResolutionError(Exception):
     pass
 
 
+class UndefinedTypeCheck(Exception):
+    pass
+
 class UnknownType(Exception):
     def __init__(self, type, instance, schema):
         self.type = type