add typing information (#475)

.github/workflows/tests.yml

@@ -19,8 +19,6 @@ jobs:
           - { python-version: "3.9",  session: "py39" }
           - { python-version: "3.8",  session: "py38" }
           - { python-version: "3.7",  session: "py37" }
-          - { python-version: "3.6",  session: "py36" }
-          - { python-version: "2.7",  session: "py27" }
 
     steps:
       - name: Check out the repository
@@ -31,11 +29,6 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
-      - name: Install tox-setuptools-version
-        if: ${{ matrix.session != 'py27' }}
-        run: |
-          pip install tox-setuptools-version
-
       - name: Run tox
         run: |
           pip install tox

setup.py

@@ -22,6 +22,9 @@
     license='BSD-3-Clause',
     platforms=['any'],
     packages=['voluptuous'],
+    package_data={
+        'voluptuous': ['py.typed'],
+    },
     author='Alec Thomas',
     author_email='alec@swapoff.org',
     classifiers=[

tox.ini

@@ -1,5 +1,5 @@
 [tox]
-envlist = flake8,py27,py36,py37,py38,py39,py310
+envlist = flake8,py37,py38,py39,py310
 
 [flake8]
 ; E501: line too long (X > 79 characters)

voluptuous/error.py

@@ -1,3 +1,5 @@
+import typing
+
 
 class Error(Exception):
     """Base validation exception."""
@@ -17,54 +19,54 @@ class Invalid(Error):
 
     """
 
-    def __init__(self, message, path=None, error_message=None, error_type=None):
+    def __init__(self, message: str, path: typing.Optional[typing.List[str]] = None, error_message: typing.Optional[str] = None, error_type: typing.Optional[str] = None) -> None:
         Error.__init__(self, message)
         self.path = path or []
         self.error_message = error_message or message
         self.error_type = error_type
 
     @property
-    def msg(self):
+    def msg(self) -> str:
         return self.args[0]
 
-    def __str__(self):
+    def __str__(self) -> str:
         path = ' @ data[%s]' % ']['.join(map(repr, self.path)) \
             if self.path else ''
         output = Exception.__str__(self)
         if self.error_type:
             output += ' for ' + self.error_type
         return output + path
 
-    def prepend(self, path):
+    def prepend(self, path: typing.List[str]) -> None:
         self.path = path + self.path
 
 
 class MultipleInvalid(Invalid):
-    def __init__(self, errors=None):
+    def __init__(self, errors: typing.Optional[typing.List[Invalid]] = None) -> None:
         self.errors = errors[:] if errors else []
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return 'MultipleInvalid(%r)' % self.errors
 
     @property
-    def msg(self):
+    def msg(self) -> str:
         return self.errors[0].msg
 
     @property
-    def path(self):
+    def path(self) -> typing.List[str]:
         return self.errors[0].path
 
     @property
-    def error_message(self):
+    def error_message(self) -> str:
         return self.errors[0].error_message
 
-    def add(self, error):
+    def add(self, error: Invalid) -> None:
         self.errors.append(error)
 
-    def __str__(self):
+    def __str__(self) -> str:
         return str(self.errors[0])
 
-    def prepend(self, path):
+    def prepend(self, path: typing.List[str]) -> None:
         for error in self.errors:
             error.prepend(path)
 

voluptuous/humanize.py

@@ -1,11 +1,16 @@
 from voluptuous import Invalid, MultipleInvalid
 from voluptuous.error import Error
+from voluptuous.schema_builder import Schema
+import typing
 
 
 MAX_VALIDATION_ERROR_ITEM_LENGTH = 500
 
 
-def _nested_getitem(data, path):
+IndexT = typing.TypeVar("IndexT")
+
+
+def _nested_getitem(data: typing.Dict[IndexT, typing.Any], path: typing.List[IndexT]) -> typing.Optional[typing.Any]:
     for item_index in path:
         try:
             data = data[item_index]
@@ -16,7 +21,7 @@ def _nested_getitem(data, path):
     return data
 
 
-def humanize_error(data, validation_error, max_sub_error_length=MAX_VALIDATION_ERROR_ITEM_LENGTH):
+def humanize_error(data, validation_error: Invalid, max_sub_error_length: int = MAX_VALIDATION_ERROR_ITEM_LENGTH) -> str:
     """ Provide a more helpful + complete validation error message than that provided automatically
     Invalid and MultipleInvalid do not include the offending value in error messages,
     and MultipleInvalid.__str__ only provides the first error.
@@ -33,7 +38,7 @@ def humanize_error(data, validation_error, max_sub_error_length=MAX_VALIDATION_E
         return '%s. Got %s' % (validation_error, offending_item_summary)
 
 
-def validate_with_humanized_errors(data, schema, max_sub_error_length=MAX_VALIDATION_ERROR_ITEM_LENGTH):
+def validate_with_humanized_errors(data, schema: Schema, max_sub_error_length: int = MAX_VALIDATION_ERROR_ITEM_LENGTH) -> typing.Any:
     try:
         return schema(data)
     except (Invalid, MultipleInvalid) as e:

voluptuous/schema_builder.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import collections
 import inspect
 import re
@@ -7,6 +9,9 @@
 
 import itertools
 from voluptuous import error as er
+from collections.abc import Generator
+import typing
+from voluptuous.error import Error
 
 if sys.version_info >= (3,):
     long = int
@@ -127,18 +132,21 @@ def __repr__(self):
 UNDEFINED = Undefined()
 
 
-def Self():
+def Self() -> None:
     raise er.SchemaError('"Self" should never be called')
 
 
-def default_factory(value):
+DefaultFactory = typing.Union[Undefined, typing.Callable[[], typing.Any]]
+
+
+def default_factory(value) -> DefaultFactory:
     if value is UNDEFINED or callable(value):
         return value
     return lambda: value
 
 
 @contextmanager
-def raises(exc, msg=None, regex=None):
+def raises(exc, msg: typing.Optional[str] = None, regex: typing.Optional[re.Pattern] = None) -> Generator[None, None, None]:
     try:
         yield
     except exc as e:
@@ -148,7 +156,7 @@ def raises(exc, msg=None, regex=None):
             assert re.search(regex, str(e)), '%r does not match %r' % (str(e), regex)
 
 
-def Extra(_):
+def Extra(_) -> None:
     """Allow keys in the data that are not present in the schema."""
     raise er.SchemaError('"Extra" should never be called')
 
@@ -157,6 +165,8 @@ def Extra(_):
 # deprecated object, so we just leave an alias here instead.
 extra = Extra
 
+Schemable = typing.Union[dict, list, type, typing.Callable]
+
 
 class Schema(object):
     """A validation schema.
@@ -186,7 +196,7 @@ class Schema(object):
         PREVENT_EXTRA: 'PREVENT_EXTRA',
     }
 
-    def __init__(self, schema, required=False, extra=PREVENT_EXTRA):
+    def __init__(self, schema: Schemable, required: bool = False, extra: int = PREVENT_EXTRA) -> None:
         """Create a new Schema.
 
         :param schema: Validation schema. See :module:`voluptuous` for details.
@@ -207,7 +217,7 @@ def __init__(self, schema, required=False, extra=PREVENT_EXTRA):
         self._compiled = self._compile(schema)
 
     @classmethod
-    def infer(cls, data, **kwargs):
+    def infer(cls, data, **kwargs) -> Schema:
         """Create a Schema from concrete data (e.g. an API response).
 
         For example, this will take a dict like:
@@ -723,7 +733,7 @@ def validate_set(path, data):
 
         return validate_set
 
-    def extend(self, schema, required=None, extra=None):
+    def extend(self, schema: dict, required: typing.Optional[bool] = None, extra: typing.Optional[int] = None) -> Schema:
         """Create a new `Schema` by merging this and the provided `schema`.
 
         Neither this `Schema` nor the provided `schema` are modified. The
@@ -738,6 +748,7 @@ def extend(self, schema, required=None, extra=None):
         """
 
         assert type(self.schema) == dict and type(schema) == dict, 'Both schemas must be dictionary-based'
+        assert isinstance(self.schema, dict)
 
         result = self.schema.copy()
 
@@ -936,7 +947,7 @@ class Msg(object):
     ...   assert isinstance(e.errors[0], er.RangeInvalid)
     """
 
-    def __init__(self, schema, msg, cls=None):
+    def __init__(self, schema: dict, msg: str, cls: typing.Optional[typing.Type[Error]] = None) -> None:
         if cls and not issubclass(cls, er.Invalid):
             raise er.SchemaError("Msg can only use subclases of"
                                  " Invalid as custom class")
@@ -961,7 +972,7 @@ def __repr__(self):
 class Object(dict):
     """Indicate that we should work with attributes, not keys."""
 
-    def __init__(self, schema, cls=UNDEFINED):
+    def __init__(self, schema, cls: object = UNDEFINED) -> None:
         self.cls = cls
         super(Object, self).__init__(schema)
 
@@ -977,7 +988,7 @@ def __repr__(self):
 class Marker(object):
     """Mark nodes for special treatment."""
 
-    def __init__(self, schema_, msg=None, description=None):
+    def __init__(self, schema_: dict, msg: typing.Optional[str] = None, description: typing.Optional[str] = None) -> None:
         self.schema = schema_
         self._schema = Schema(schema_)
         self.msg = msg
@@ -1009,7 +1020,7 @@ def __eq__(self, other):
         return self.schema == other
 
     def __ne__(self, other):
-        return not(self.schema == other)
+        return not (self.schema == other)
 
 
 class Optional(Marker):
@@ -1035,7 +1046,7 @@ class Optional(Marker):
     {'key2': 'value'}
     """
 
-    def __init__(self, schema, msg=None, default=UNDEFINED, description=None):
+    def __init__(self, schema: dict, msg: typing.Optional[str] = None, default=UNDEFINED, description: typing.Optional[str] = None) -> None:
         super(Optional, self).__init__(schema, msg=msg,
                                        description=description)
         self.default = default_factory(default)
@@ -1077,7 +1088,7 @@ class Exclusive(Optional):
     ...             'social': {'social_network': 'barfoo', 'token': 'tEMp'}})
     """
 
-    def __init__(self, schema, group_of_exclusion, msg=None, description=None):
+    def __init__(self, schema: dict, group_of_exclusion: str, msg: typing.Optional[str] = None, description: typing.Optional[str] = None) -> None:
         super(Exclusive, self).__init__(schema, msg=msg,
                                         description=description)
         self.group_of_exclusion = group_of_exclusion
@@ -1125,8 +1136,8 @@ class Inclusive(Optional):
     True
     """
 
-    def __init__(self, schema, group_of_inclusion,
-                 msg=None, description=None, default=UNDEFINED):
+    def __init__(self, schema: dict, group_of_inclusion: str,
+                 msg: typing.Optional[str] = None, description: typing.Optional[str] = None, default=UNDEFINED) -> None:
         super(Inclusive, self).__init__(schema, msg=msg,
                                         default=default,
                                         description=description)
@@ -1148,7 +1159,7 @@ class Required(Marker):
     {'key': []}
     """
 
-    def __init__(self, schema, msg=None, default=UNDEFINED, description=None):
+    def __init__(self, schema: dict, msg: typing.Optional[str] = None, default=UNDEFINED, description: typing.Optional[str] = None) -> None:
         super(Required, self).__init__(schema, msg=msg,
                                        description=description)
         self.default = default_factory(default)
@@ -1169,7 +1180,7 @@ class Remove(Marker):
     [1, 2, 3, 5, '7']
     """
 
-    def __call__(self, v):
+    def __call__(self, v: object):
         super(Remove, self).__call__(v)
         return self.__class__
 
@@ -1180,7 +1191,7 @@ def __hash__(self):
         return object.__hash__(self)
 
 
-def message(default=None, cls=None):
+def message(default: typing.Optional[str] = None, cls: typing.Optional[typing.Type[Error]] = None) -> typing.Callable:
     """Convenience decorator to allow functions to provide a message.
 
     Set a default message:
@@ -1251,7 +1262,7 @@ def _merge_args_with_kwargs(args_dict, kwargs_dict):
     return ret
 
 
-def validate(*a, **kw):
+def validate(*a, **kw) -> typing.Callable:
     """Decorator for validating arguments of a function against a given schema.
 
     Set restrictions for arguments:

voluptuous/tests/tests.py

@@ -1,14 +1,5 @@
-import collections
-import copy
-
-try:
-    from enum import Enum
-except ImportError:
-    Enum = None
-import os
-import sys
-
-import pytest
+from voluptuous.util import Capitalize, Lower, Strip, Title, Upper, u
+from voluptuous.humanize import humanize_error
 from voluptuous import (ALLOW_EXTRA, PREVENT_EXTRA, All, Any, Clamp, Coerce,
                         Contains, Date, Datetime, Email, Equal, ExactSequence,
                         Exclusive, Extra, FqdnUrl, In, Inclusive, Invalid,
@@ -17,8 +8,18 @@
                         Optional, PathExists, Range, Remove, Replace, Required,
                         Schema, Self, SomeOf, TooManyValid, TypeInvalid, Union,
                         Unordered, Url, raises, validate)
-from voluptuous.humanize import humanize_error
-from voluptuous.util import Capitalize, Lower, Strip, Title, Upper, u
+import pytest
+import sys
+import os
+import collections
+import copy
+import typing
+
+Enum: typing.Union[type, None]
+try:
+    from enum import Enum
+except ImportError:
+    Enum = None
 
 
 def test_new_required_test():