vtjson 2.1.7__py3-none-any.whl → 2.1.9__py3-none-any.whl

vtjson/vtjson.py

@@ -12,7 +12,17 @@ import urllib.parse
 import warnings
 from collections.abc import Sequence, Set, Sized
 from dataclasses import dataclass
-from typing import Any, Callable, Container, Mapping, Type, TypeVar, Union, cast
+from typing import (
+    Any,
+    Callable,
+    Container,
+    Generic,
+    Mapping,
+    Type,
+    TypeVar,
+    Union,
+    cast,
+)
 
 try:
     from typing import Literal
@@ -78,23 +88,88 @@ import idna
 T = TypeVar("T")
 
 
-def safe_cast(t: Type[T], object_: Any) -> T:
-    validate(t, object_)
-    return cast(T, object_)
+def safe_cast(schema: Type[T], obj: Any) -> T:
+    """
+    Validates the given object against the given schema and changes its type
+    accordingly.
+
+    :param schema: the given schema
+    :param obj: the object to be validated
+    :return: the validated object with its type changed
+
+    :raises ValidationError: exception thrown when the object does not
+      validate; the exception message contains an explanation about what went
+      wrong
+
+    :raises SchemaError: exception thrown when the schema definition is found
+      to contain an error
+    """
+
+    validate(schema, obj)
+    return cast(T, obj)
 
 
 class compiled_schema:
+    """
+    The result of compiling a schema. A :py:class:`compiled_schema` is
+    produced by the factory function :py:func:`vtjson.compile`.
+    """
+
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str,
         strict: bool,
         subs: Mapping[str, object],
     ) -> str:
+        """
+        Validates the given object against the given schema.
+
+        :param schema: the given schema
+        :param obj: the object to be validated
+        :param name: common name for the object to be validated; used in
+          non-validation messages
+        :param strict: indicates whether or not the object being validated is
+          allowed to have keys/entries which are not in the schema
+        :param subs: a dictionary whose keys are labels and whose values are
+          substitution schemas for schemas with those labels
+        :return: an empty string if validation succeeds; otherwise an
+          explanation about what went wrong
+        """
+
         return ""
 
 
+class wrapper:
+    """
+    Base class for schemas that refer to other schemas.
+
+    Handling such schemas is somewhat delicate since `vtjson` allows them to
+    be recursive.
+    """
+
+    def __compile__(
+        self, _deferred_compiles: _mapping | None = None
+    ) -> compiled_schema:
+        """
+        Compiles a schema.
+
+        :param _deferred_compiles: an opaque data structure used for handling
+          recursive schemas; it should be passed unmodifed to any internal
+          invocations of :py:func:`vtjson._compile` or
+          :py:meth:`vtjson.wrapper.__compile__`
+
+        :raises SchemaError: exception thrown when the schema definition is
+          found to contain an error
+        """
+        return anything()
+
+
 class comparable(Protocol):
+    """
+    Base class for objects that are comparable with each other.
+    """
+
     def __eq__(self, x: Any) -> bool: ...
 
     def __lt__(self, x: Any) -> bool: ...
@@ -114,18 +189,39 @@ except Exception:
 
 
 class ValidationError(Exception):
+    """
+    Raised if validation fails. The associated message explains what went
+    wrong.
+    """
+
     pass
 
 
 class SchemaError(Exception):
+    """
+    Raised if a schema contains an error.
+    """
+
     pass
 
 
-__version__ = "2.1.7"
+__version__ = "2.1.9"
 
 
 @dataclass
 class Apply:
+    """
+    Modifies the treatement of the previous arguments in an `Annotated` schema.
+
+    :param skip_first: if `True` do not use the first argument (the Python
+      type annotation) in an `Annotated` construct for validation because this
+      is already covered by the other arguments
+    :param name:  apply the corresponding :py:class:`vtjson.set_name` command
+      to the previous arguments
+    :param labels: apply the corresponding :py:class:`vtjson.set_label`
+      command  to the previous arguments
+    """
+
     skip_first: bool | None = None
     name: str | None = None
     labels: Sequence[str] | None = None
@@ -177,13 +273,13 @@ def _get_type_hints(schema: object) -> dict[str, object]:
 
 def _to_dict(
     type_hints: Mapping[str, object], total: bool = True
-) -> dict[object, object]:
-    d: dict[object, object] = {}
+) -> dict[str | optional_key[str], object]:
+    d: dict[str | optional_key[str], object] = {}
     if not supports_Generics:
         raise SchemaError("Generic types are not supported")
     for k, v in type_hints.items():
         v_ = v
-        k_: str | optional_key = k
+        k_: str | optional_key[str] = k
         value_type = typing.get_origin(v)
         if supports_NotRequired and value_type in (Required, NotRequired):
             v_ = typing.get_args(v)[0]
@@ -225,14 +321,14 @@ def _c(s: object) -> str:
 
 
 def _wrong_type_message(
-    object_: object,
+    obj: object,
     name: str,
     type_name: str,
     explanation: str | None = None,
     skip_value: bool = False,
 ) -> str:
     if not skip_value:
-        message = f"{name} (value:{_c(object_)}) is not of type '{type_name}'"
+        message = f"{name} (value:{_c(obj)}) is not of type '{type_name}'"
     else:
         message = f"{name} is not of type '{type_name}'"
     if explanation is not None:
@@ -246,9 +342,9 @@ class _validate_meta(type):
     __subs__: Mapping[str, object]
     __dbg__: bool
 
-    def __instancecheck__(cls, object_: object) -> bool:
+    def __instancecheck__(cls, obj: object) -> bool:
         valid = _validate(
-            cls.__schema__, object_, "object", strict=cls.__strict__, subs=cls.__subs__
+            cls.__schema__, obj, "object", strict=cls.__strict__, subs=cls.__subs__
         )
         if cls.__dbg__ and valid != "":
             print(f"DEBUG: {valid}")
@@ -262,6 +358,20 @@ def make_type(
     debug: bool = False,
     subs: Mapping[str, object] = {},
 ) -> _validate_meta:
+    """
+    Transforms a schema into a genuine Python type.
+
+    :param schema: the given schema
+    :param name: sets the `__name__` attribute of the type; if it is not
+      supplied then `vtjson` makes an educated guess
+    :param strict: indicates whether or not the object being validated is
+      allowed to have keys/entries which are not in the schema
+    :param debug: print feedback on the console if validation fails
+    :param subs: a dictionary whose keys are labels and whose values are
+      substitution schemas for schemas with those labels
+    :raises SchemaError: exception thrown when the schema definition is found
+      to contain an error
+    """
     if name is None:
         if hasattr(schema, "__name__"):
             name = schema.__name__
@@ -279,16 +389,28 @@ def make_type(
     )
 
 
-class optional_key:
-    key: object
+K = TypeVar("K")
+
+
+class optional_key(Generic[K]):
+    """
+    Make a key in a Mapping schema optional. In the common case that the key
+      is a string, the same effect can be achieved by appending `?`.
+    """
 
-    def __init__(self, key: object) -> None:
+    key: K
+
+    def __init__(self, key: K) -> None:
+        """
+        :param key: the key to be made optional
+        """
         self.key = key
 
     def __eq__(self, key: object) -> bool:
         if not isinstance(key, optional_key):
             return False
-        return self.key == key.key
+        k: object = key.key
+        return self.key == k
 
     def __hash__(self) -> int:
         return hash(self.key)
@@ -308,14 +430,14 @@ class _union(compiled_schema):
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
         messages = []
         for schema in self.schemas:
-            message = schema.__validate__(object_, name=name, strict=strict, subs=subs)
+            message = schema.__validate__(obj, name=name, strict=strict, subs=subs)
             if message == "":
                 return ""
             else:
@@ -323,10 +445,18 @@ class _union(compiled_schema):
         return " and ".join(messages)
 
 
-class union:
+class union(wrapper):
+    """
+    An object matches the schema `union(schema1, ..., schemaN)` if it matches
+    one of the schemas `schema1, ..., schemaN`.
+    """
+
     schemas: tuple[object, ...]
 
     def __init__(self, *schemas: object) -> None:
+        """
+        :param schemas: collection of schemas, one of which should match
+        """
         self.schemas = schemas
 
     def __compile__(self, _deferred_compiles: _mapping | None = None) -> _union:
@@ -347,22 +477,30 @@ class _intersect(compiled_schema):
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
         for schema in self.schemas:
-            message = schema.__validate__(object_, name=name, strict=strict, subs=subs)
+            message = schema.__validate__(obj, name=name, strict=strict, subs=subs)
             if message != "":
                 return message
         return ""
 
 
-class intersect:
+class intersect(wrapper):
+    """
+    An object matches the schema `intersect(schema1, ..., schemaN)` if it
+    matches all the schemas `schema1, ..., schemaN`.
+    """
+
     schemas: tuple[object, ...]
 
     def __init__(self, *schemas: object) -> None:
+        """
+        :param schemas: collection of schemas, all of which should match
+        """
         self.schemas = schemas
 
     def __compile__(self, _deferred_compiles: _mapping | None = None) -> _intersect:
@@ -379,22 +517,30 @@ class _complement(compiled_schema):
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
-        message = self.schema.__validate__(object_, name=name, strict=strict, subs=subs)
+        message = self.schema.__validate__(obj, name=name, strict=strict, subs=subs)
         if message != "":
             return ""
         else:
             return f"{name} does not match the complemented schema"
 
 
-class complement:
+class complement(wrapper):
+    """
+    An object matches the schema `complement(schema)` if it does not match
+    `schema`.
+    """
+
     schema: object
 
     def __init__(self, schema: object) -> None:
+        """
+        :param schema: the schema that should not be matched
+        """
         self.schema = schema
 
     def __compile__(self, _deferred_compiles: _mapping | None = None) -> _complement:
@@ -411,18 +557,27 @@ class _lax(compiled_schema):
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
-        return self.schema.__validate__(object_, name=name, strict=False, subs=subs)
+        return self.schema.__validate__(obj, name=name, strict=False, subs=subs)
+
 
+class lax(wrapper):
+    """
+    An object matches the schema `lax(schema)` if it matches `schema` when
+    validated with `strict=False`.
+    """
 
-class lax:
     schema: object
 
     def __init__(self, schema: object) -> None:
+        """
+        :param schema: schema that should be validated against with
+          `strict=False`
+        """
         self.schema = schema
 
     def __compile__(self, _deferred_compiles: _mapping | None = None) -> _lax:
@@ -439,16 +594,25 @@ class _strict(compiled_schema):
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
-        return self.schema.__validate__(object_, name=name, strict=True, subs=subs)
+        return self.schema.__validate__(obj, name=name, strict=True, subs=subs)
+
 
+class strict(wrapper):
+    """
+    An object matches the schema `strict(schema)` if it matches `schema` when
+    validated with `strict=True`.
+    """
 
-class strict:
     def __init__(self, schema: object) -> None:
+        """
+        :param schema: schema that should be validated against with
+          `strict=True`
+        """
         self.schema = schema
 
     def __compile__(self, _deferred_compiles: _mapping | None = None) -> _strict:
@@ -473,7 +637,7 @@ class _set_label(compiled_schema):
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
@@ -492,17 +656,31 @@ class _set_label(compiled_schema):
             # known at schema creation time.
             #
             # But the user can always pre-compile subs[key].
-            return _validate(subs[key], object_, name=name, strict=True, subs=subs)
+            return _validate(subs[key], obj, name=name, strict=True, subs=subs)
         else:
-            return self.schema.__validate__(object_, name=name, strict=True, subs=subs)
+            return self.schema.__validate__(obj, name=name, strict=True, subs=subs)
 
 
-class set_label:
+class set_label(wrapper):
+    """
+    An object matches the schema `set_label(schema, label1, ..., labelN,
+    debug=False)` if it matches `schema`, unless the schema is replaced by a
+    different one via the `subs` argument to `validate`.
+    """
+
     schema: object
     labels: set[str]
     debug: bool
 
     def __init__(self, schema: object, *labels: str, debug: bool = False) -> None:
+        """
+        :param schema: the schema that will be labeled
+        :param labels: labels that will be attached to the schema
+        :param debug:  it `True` print a message on the console if the schema
+          was changed via substitution
+        :raises SchemaError: exception thrown when the schema definition is
+          found to contain an error
+        """
         self.schema = schema
         for L in labels:
             if not isinstance(L, str):
@@ -519,19 +697,28 @@ class set_label:
 
 
 class quote(compiled_schema):
+    """
+    An object matches the schema `quote(schema)` if it is equal to `schema`.
+    For example the schema `str` matches strings but the schema `quote(str)`
+    matches the object `str`.
+    """
+
     schema: _const
 
     def __init__(self, schema: object) -> None:
+        """
+        :param schema: the schema to be quoted
+        """
         self.schema = _const(schema, strict_eq=True)
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
-        return self.schema.__validate__(object_, name=name, strict=strict, subs=subs)
+        return self.schema.__validate__(obj, name=name, strict=strict, subs=subs)
 
 
 class _set_name(compiled_schema):
@@ -552,28 +739,40 @@ class _set_name(compiled_schema):
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
-        message = self.schema.__validate__(object_, name=name, strict=strict, subs=subs)
+        message = self.schema.__validate__(obj, name=name, strict=strict, subs=subs)
         if message != "":
             if not self.reason:
-                return _wrong_type_message(object_, name, self.__name__)
+                return _wrong_type_message(obj, name, self.__name__)
             else:
                 return _wrong_type_message(
-                    object_, name, self.__name__, explanation=message, skip_value=True
+                    obj, name, self.__name__, explanation=message, skip_value=True
                 )
         return ""
 
 
-class set_name:
+class set_name(wrapper):
+    """
+    An object matches the schema `set_name(schema, name, reason=False)` if it
+    matches `schema`, but the `name` argument will be used in non-validation
+    messages.
+    """
+
     reason: bool
     schema: object
     name: str
 
     def __init__(self, schema: object, name: str, reason: bool = False) -> None:
+        """
+        :param schema: the original schema
+        :param name: name for use in non-validation messages
+        :param reason: indicates whether the original non-validation message
+          should be suppressed
+        """
         if not isinstance(name, str):
             raise SchemaError(f"The name {_c(name)} is not a string")
         self.schema = schema
@@ -590,6 +789,10 @@ class set_name:
 
 
 class regex(compiled_schema):
+    """
+    This matches the strings which match the given pattern.
+    """
+
     regex: str
     fullmatch: bool
     __name__: str
@@ -602,6 +805,17 @@ class regex(compiled_schema):
         fullmatch: bool = True,
         flags: int = 0,
     ) -> None:
+        """
+        :param regex: the regular expression pattern
+        :param name: common name for the pattern that will be used in
+          non-validation messages
+        :param fullmatch: indicates whether or not the full string should be
+          matched
+        :param flags: the flags argument used when invoking `re.compile`
+
+        :raises SchemaError: exception thrown when the schema definition is
+          found to contain an error
+        """
         self.regex = regex
         self.fullmatch = fullmatch
         if name is not None:
@@ -623,28 +837,42 @@ class regex(compiled_schema):
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
-        if not isinstance(object_, str):
-            return _wrong_type_message(object_, name, self.__name__)
+        if not isinstance(obj, str):
+            return _wrong_type_message(obj, name, self.__name__)
         try:
-            if self.fullmatch and self.pattern.fullmatch(object_):
+            if self.fullmatch and self.pattern.fullmatch(obj):
                 return ""
-            elif not self.fullmatch and self.pattern.match(object_):
+            elif not self.fullmatch and self.pattern.match(obj):
                 return ""
         except Exception:
             pass
-        return _wrong_type_message(object_, name, self.__name__)
+        return _wrong_type_message(obj, name, self.__name__)
 
 
 class glob(compiled_schema):
+    """
+    Unix style filename matching. This is implemented using
+    `pathlib.PurePath().match()`.
+    """
+
     pattern: str
     __name__: str
 
     def __init__(self, pattern: str, name: str | None = None) -> None:
+        """
+        :param pattern: the wild card pattern to match
+        :param name: common name for the pattern that will be used in
+          non-validation messages
+
+        :raises SchemaError: exception thrown when the schema definition is
+          found to contain an error
+        """
+
         self.pattern = pattern
 
         if name is None:
@@ -662,27 +890,39 @@ class glob(compiled_schema):
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
-        if not isinstance(object_, str):
-            return _wrong_type_message(object_, name, self.__name__)
+        if not isinstance(obj, str):
+            return _wrong_type_message(obj, name, self.__name__)
         try:
-            if pathlib.PurePath(object_).match(self.pattern):
+            if pathlib.PurePath(obj).match(self.pattern):
                 return ""
             else:
-                return _wrong_type_message(object_, name, self.__name__)
+                return _wrong_type_message(obj, name, self.__name__)
         except Exception as e:
-            return _wrong_type_message(object_, name, self.__name__, str(e))
+            return _wrong_type_message(obj, name, self.__name__, str(e))
 
 
 class magic(compiled_schema):
+    """
+    Checks if a buffer (for example a string or a byte array) has the given
+    mime type. This is implemented using the `python-magic` package.
+    """
+
     mime_type: str
     __name__: str
 
     def __init__(self, mime_type: str, name: str | None = None) -> None:
+        """
+        :param mime_type: the mime type
+        :param name: common name to refer to this mime type
+
+        :raises SchemaError: exception thrown when the schema definition is
+          found to contain an error
+        """
         if not HAS_MAGIC:
             raise SchemaError("Failed to load python-magic")
 
@@ -698,28 +938,32 @@ class magic(compiled_schema):
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
-        if not isinstance(object_, (str, bytes)):
-            return _wrong_type_message(object_, name, self.__name__)
+        if not isinstance(obj, (str, bytes)):
+            return _wrong_type_message(obj, name, self.__name__)
         try:
-            object_mime_type = magic_.from_buffer(object_, mime=True)
+            objmime_type = magic_.from_buffer(obj, mime=True)
         except Exception as e:
-            return _wrong_type_message(object_, name, self.__name__, str(e))
-        if object_mime_type != self.mime_type:
+            return _wrong_type_message(obj, name, self.__name__, str(e))
+        if objmime_type != self.mime_type:
             return _wrong_type_message(
-                object_,
+                obj,
                 name,
                 self.__name__,
-                f"{repr(object_mime_type)} is different from {repr(self.mime_type)}",
+                f"{repr(objmime_type)} is different from {repr(self.mime_type)}",
             )
         return ""
 
 
 class div(compiled_schema):
+    """
+    This matches the integers `x` such that `(x - remainder) % divisor` == 0.
+    """
+
     divisor: int
     remainder: int
     __name__: str
@@ -727,6 +971,15 @@ class div(compiled_schema):
     def __init__(
         self, divisor: int, remainder: int = 0, name: str | None = None
     ) -> None:
+        """
+        :param divisor: the divisor
+        :param remainder: the remainer
+        :param name: common name (e.g. `even` or `odd`) that will be used in
+          non-validation messages
+
+        :raises SchemaError: exception thrown when the schema definition is
+          found to contain an error
+        """
         if not isinstance(divisor, int):
             raise SchemaError(f"The divisor {repr(divisor)} is not an integer")
         if divisor == 0:
@@ -747,20 +1000,25 @@ class div(compiled_schema):
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
-        if not isinstance(object_, int):
-            return _wrong_type_message(object_, name, "int")
-        elif (object_ - self.remainder) % self.divisor == 0:
+        if not isinstance(obj, int):
+            return _wrong_type_message(obj, name, "int")
+        elif (obj - self.remainder) % self.divisor == 0:
             return ""
         else:
-            return _wrong_type_message(object_, name, self.__name__)
+            return _wrong_type_message(obj, name, self.__name__)
 
 
 class close_to(compiled_schema):
+    """
+    This matches the real numbers that are close to `x` in the sense of
+    `math.isclose`.
+    """
+
     kw: dict[str, float]
     x: int | float
     __name__: str
@@ -771,6 +1029,13 @@ class close_to(compiled_schema):
         rel_tol: int | float | None = None,
         abs_tol: int | float | None = None,
     ) -> None:
+        """
+        :param rel_tol: the maximal allowed relative deviation
+        :param abs_tol: the maximal allowed absolute deviation
+
+        :raises SchemaError: exception thrown when the schema definition is
+          found to contain an error
+        """
         self.kw = {}
         if not isinstance(x, (int, float)):
             raise SchemaError(f"{repr(x)} is not a number")
@@ -794,23 +1059,33 @@ class close_to(compiled_schema):
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
-        if not isinstance(object_, (float, int)):
-            return _wrong_type_message(object_, name, "number")
-        elif math.isclose(object_, self.x, **self.kw):
+        if not isinstance(obj, (float, int)):
+            return _wrong_type_message(obj, name, "number")
+        elif math.isclose(obj, self.x, **self.kw):
             return ""
         else:
-            return _wrong_type_message(object_, name, self.__name__)
+            return _wrong_type_message(obj, name, self.__name__)
 
 
 class gt(compiled_schema):
+    """
+    This checks if `object > lb`.
+    """
+
     lb: comparable
 
     def __init__(self, lb: comparable) -> None:
+        """
+        :param lb: the strict lower bound
+
+        :raises SchemaError: exception thrown when the schema definition is
+          found to contain an error
+        """
         try:
             lb <= lb
         except Exception:
@@ -819,29 +1094,39 @@ class gt(compiled_schema):
             ) from None
         self.lb = lb
 
-    def message(self, name: str, object_: object) -> str:
-        return f"{name} (value:{_c(object_)}) is not strictly greater than {self.lb}"
+    def message(self, name: str, obj: object) -> str:
+        return f"{name} (value:{_c(obj)}) is not strictly greater than {self.lb}"
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
         try:
-            if self.lb < object_:
+            if self.lb < obj:
                 return ""
             else:
-                return self.message(name, object_)
+                return self.message(name, obj)
         except Exception as e:
-            return f"{self.message(name, object_)}: {str(e)}"
+            return f"{self.message(name, obj)}: {str(e)}"
 
 
 class ge(compiled_schema):
+    """
+    This checks if `object >= lb`.
+    """
+
     lb: comparable
 
     def __init__(self, lb: comparable) -> None:
+        """
+        :param lb: the lower bound
+
+        :raises SchemaError: exception thrown when the schema definition is
+          found to contain an error
+        """
         try:
             lb <= lb
         except Exception:
@@ -850,29 +1135,39 @@ class ge(compiled_schema):
             ) from None
         self.lb = lb
 
-    def message(self, name: str, object_: object) -> str:
-        return f"{name} (value:{_c(object_)}) is not greater than or equal to {self.lb}"
+    def message(self, name: str, obj: object) -> str:
+        return f"{name} (value:{_c(obj)}) is not greater than or equal to {self.lb}"
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
         try:
-            if self.lb <= object_:
+            if self.lb <= obj:
                 return ""
             else:
-                return self.message(name, object_)
+                return self.message(name, obj)
         except Exception as e:
-            return f"{self.message(name, object_)}: {str(e)}"
+            return f"{self.message(name, obj)}: {str(e)}"
 
 
 class lt(compiled_schema):
+    """
+    This checks if `object < ub`.
+    """
+
     ub: comparable
 
     def __init__(self, ub: comparable) -> None:
+        """
+        :param ub: the strict upper bound
+
+        :raises SchemaError: exception thrown when the schema definition is
+          found to contain an error
+        """
         try:
             ub <= ub
         except Exception:
@@ -881,29 +1176,39 @@ class lt(compiled_schema):
             ) from None
         self.ub = ub
 
-    def message(self, name: str, object_: object) -> str:
-        return f"{name} (value:{_c(object_)}) is not strictly less than {self.ub}"
+    def message(self, name: str, obj: object) -> str:
+        return f"{name} (value:{_c(obj)}) is not strictly less than {self.ub}"
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
         try:
-            if self.ub > object_:
+            if self.ub > obj:
                 return ""
             else:
-                return self.message(name, object_)
+                return self.message(name, obj)
         except Exception as e:
-            return f"{self.message(name, object_)}: {str(e)}"
+            return f"{self.message(name, obj)}: {str(e)}"
 
 
 class le(compiled_schema):
+    """
+    This checks if `object <= ub`.
+    """
+
     ub: comparable
 
     def __init__(self, ub: comparable) -> None:
+        """
+        :param ub: the upper bound
+
+        :raises SchemaError: exception thrown when the schema definition is
+          found to contain an error
+        """
         try:
             ub <= ub
         except Exception:
@@ -912,26 +1217,30 @@ class le(compiled_schema):
             ) from None
         self.ub = ub
 
-    def message(self, name: str, object_: object) -> str:
-        return f"{name} (value:{_c(object_)}) is not less than or equal to {self.ub}"
+    def message(self, name: str, obj: object) -> str:
+        return f"{name} (value:{_c(obj)}) is not less than or equal to {self.ub}"
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
         try:
-            if self.ub >= object_:
+            if self.ub >= obj:
                 return ""
             else:
-                return self.message(name, object_)
+                return self.message(name, obj)
         except Exception as e:
-            return f"{self.message(name, object_)}: {str(e)}"
+            return f"{self.message(name, obj)}: {str(e)}"
 
 
 class interval(compiled_schema):
+    """
+    This checks if `lb <= object <= ub`, provided the comparisons make sense.
+    """
+
     lb_s: str
     ub_s: str
 
@@ -942,7 +1251,15 @@ class interval(compiled_schema):
         strict_lb: bool = False,
         strict_ub: bool = False,
     ) -> None:
-
+        """
+        :param lb: lower bound; ... (ellipsis) means no lower bound
+        :param ub: upper bound; ... (ellipsis) means no upper bound
+        :param strict_lb: if True use a strict lower bound
+        :param strict_ub: if True use a strict upper bound
+
+        :raises SchemaError: exception thrown when the schema definition is
+          found to contain an error
+        """
         self.lb_s = "..." if lb == ... else repr(lb)
         self.ub_s = "..." if ub == ... else repr(ub)
 
@@ -995,9 +1312,22 @@ class interval(compiled_schema):
 
 
 class size(compiled_schema):
+    """
+    Matches the objects (which support `len()` such as strings or lists) whose
+    length is in the interval `[lb, ub]`.
+    """
+
     interval_: interval
 
     def __init__(self, lb: int, ub: int | types.EllipsisType | None = None) -> None:
+        """
+        :param lb: the lower bound for the length
+        :param ub: the upper bound for the length; ... (ellipsis) means that
+          there is no upper bound; `None` means `lb==ub`
+
+        :raises SchemaError: exception thrown when the schema definition is
+          found to contain an error
+        """
         if ub is None:
             ub = lb
         if not isinstance(lb, int):
@@ -1021,15 +1351,15 @@ class size(compiled_schema):
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
-        if not isinstance(object_, Sized):
-            return f"{name} (value:{_c(object_)}) has no len()"
+        if not isinstance(obj, Sized):
+            return f"{name} (value:{_c(obj)}) has no len()"
 
-        L = len(object_)
+        L = len(obj)
 
         return self.interval_.__validate__(L, f"len({name})", strict, subs)
 
@@ -1044,7 +1374,7 @@ class _deferred(compiled_schema):
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
@@ -1052,7 +1382,7 @@ class _deferred(compiled_schema):
         if self.key not in self.collection:
             raise ValidationError(f"{name}: key {self.key} is unknown")
         return self.collection[self.key].__validate__(
-            object_, name=name, strict=strict, subs=subs
+            obj, name=name, strict=strict, subs=subs
         )
 
 
@@ -1092,12 +1422,32 @@ class _validate_schema(compiled_schema):
 
 
 def compile(schema: object) -> compiled_schema:
+    """
+    Compiles a schema. Internally invokes :py:func:`vtjson._compile`.
+
+    :param schema: the schema that should be compiled
+
+    :raises SchemaError: exception thrown when the schema definition is found
+      to contain an error
+    """
     return _compile(schema, _deferred_compiles=None)
 
 
 def _compile(
     schema: object, _deferred_compiles: _mapping | None = None
 ) -> compiled_schema:
+    """
+    Compiles a schema.
+
+    :param schema: the schema that should be compiled
+    :param _deferred_compiles: an opaque data structure used for handling
+      recursive schemas; it should be passed unmodifed to any internal
+      invocations of :py:func:`vtjson._compile` or
+      :py:meth:`vtjson.wrapper.__compile__`
+
+    :raises SchemaError: exception thrown when the schema definition is found
+      to contain an error
+    """
     if _deferred_compiles is None:
         _deferred_compiles = _mapping()
     # avoid infinite loop in case of a recursive schema
@@ -1123,7 +1473,7 @@ def _compile(
             ) from None
     elif hasattr(schema, "__validate__"):
         ret = _validate_schema(schema)
-    elif hasattr(schema, "__compile__"):
+    elif isinstance(schema, wrapper):
         ret = schema.__compile__(_deferred_compiles=_deferred_compiles)
     elif isinstance(schema, compiled_schema):
         ret = schema
@@ -1194,24 +1544,41 @@ def _compile(
 
 def _validate(
     schema: object,
-    object_: object,
+    obj: object,
     name: str = "object",
     strict: bool = True,
     subs: Mapping[str, object] = {},
 ) -> str:
-    return compile(schema).__validate__(object_, name=name, strict=strict, subs=subs)
+    return compile(schema).__validate__(obj, name=name, strict=strict, subs=subs)
 
 
 def validate(
     schema: object,
-    object_: object,
+    obj: object,
     name: str = "object",
     strict: bool = True,
     subs: Mapping[str, object] = {},
 ) -> None:
+    """
+    Validates the given object against the given schema.
+
+    :param schema: the given schema
+    :param obj: the object to be validated
+    :param name: common name for the object to be validated; used in
+      non-validation messages
+    :param strict: indicates whether or not the object being validated is
+      allowed to have keys/entries which are not in the schema
+    :param subs: a dictionary whose keys are labels and whose values are
+      substitution schemas for schemas with those labels
+    :raises ValidationError: exception thrown when the object does not
+      validate; the exception message contains an explanation about what went
+      wrong
+    :raises SchemaError: exception thrown when the schema definition is found
+      to contain an error
+    """
     message = _validate(
         schema,
-        object_,
+        obj,
         name=name,
         strict=strict,
         subs=subs,
@@ -1224,7 +1591,10 @@ def validate(
 
 
 class number(compiled_schema):
-    # functionally equivalent to float
+    """
+    A deprecated alias for `float`.
+    """
+
     def __init__(self) -> None:
         warnings.warn(
             "The schema 'number' is deprecated. Use 'float' instead.",
@@ -1233,21 +1603,31 @@ class number(compiled_schema):
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
-        if isinstance(object_, (int, float)):
+        if isinstance(obj, (int, float)):
             return ""
         else:
-            return _wrong_type_message(object_, name, "number")
+            return _wrong_type_message(obj, name, "number")
 
 
 class email(compiled_schema):
+    """
+    Checks if the object is a valid email address. This uses the package
+    `email_validator`. The `email` schema accepts the same options as
+    `validate_email` in loc. cit.
+    """
+
     kw: dict[str, Any]
 
     def __init__(self, **kw: Any) -> None:
+        """
+        :param kw: optional keyword arguments to be forwarded to
+          `email_validator.validate_email`
+        """
         self.kw = kw
         if "dns_resolver" not in kw:
             self.kw["dns_resolver"] = _get_dns_resolver()
@@ -1256,28 +1636,34 @@ class email(compiled_schema):
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
-        if not isinstance(object_, str):
-            return _wrong_type_message(
-                object_, name, "email", f"{_c(object_)} is not a string"
-            )
+        if not isinstance(obj, str):
+            return _wrong_type_message(obj, name, "email", f"{_c(obj)} is not a string")
         try:
-            email_validator.validate_email(object_, **self.kw)
+            email_validator.validate_email(obj, **self.kw)
             return ""
         except Exception as e:
-            return _wrong_type_message(object_, name, "email", str(e))
+            return _wrong_type_message(obj, name, "email", str(e))
 
 
 class ip_address(compiled_schema):
+    """
+    Matches ip addresses of the specified version which can be 4, 6 or None.
+    """
 
     __name__: str
     method: Callable[[Any], Any]
 
-    def __init__(self, version: Literal[4, 6] | None = None) -> None:
+    def __init__(self, version: Literal[4, 6, None] = None) -> None:
+        """
+        :param version: the version of the ip protocol
+        :raises SchemaError: exception thrown when the schema definition is
+          found to contain an error
+        """
         if version is not None and version not in (4, 6):
             raise SchemaError("version is not 4 or 6")
         if version is None:
@@ -1293,41 +1679,53 @@ class ip_address(compiled_schema):
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
-        if not isinstance(object_, (int, str, bytes)):
-            return _wrong_type_message(object_, name, self.__name__)
+        if not isinstance(obj, (int, str, bytes)):
+            return _wrong_type_message(obj, name, self.__name__)
         try:
-            self.method(object_)
+            self.method(obj)
         except ValueError as e:
-            return _wrong_type_message(object_, name, self.__name__, explanation=str(e))
+            return _wrong_type_message(obj, name, self.__name__, explanation=str(e))
         return ""
 
 
 class url(compiled_schema):
+    """
+    Matches valid urls.
+    """
+
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
-        if not isinstance(object_, str):
-            return _wrong_type_message(object_, name, "url")
-        result = urllib.parse.urlparse(object_)
+        if not isinstance(obj, str):
+            return _wrong_type_message(obj, name, "url")
+        result = urllib.parse.urlparse(obj)
         if all([result.scheme, result.netloc]):
             return ""
-        return _wrong_type_message(object_, name, "url")
+        return _wrong_type_message(obj, name, "url")
 
 
 class date_time(compiled_schema):
+    """
+    Without argument this represents an ISO 8601 date-time. The `format`
+    argument represents a format string for `strftime`.
+    """
+
     format: str | None
     __name__: str
 
     def __init__(self, format: str | None = None) -> None:
+        """
+        :param format: format string for `strftime`
+        """
         self.format = format
         if format is not None:
             self.__name__ = f"date_time({repr(format)})"
@@ -1336,75 +1734,91 @@ class date_time(compiled_schema):
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
-        if not isinstance(object_, str):
-            return _wrong_type_message(object_, name, self.__name__)
+        if not isinstance(obj, str):
+            return _wrong_type_message(obj, name, self.__name__)
         if self.format is not None:
             try:
-                datetime.datetime.strptime(object_, self.format)
+                datetime.datetime.strptime(obj, self.format)
             except Exception as e:
-                return _wrong_type_message(object_, name, self.__name__, str(e))
+                return _wrong_type_message(obj, name, self.__name__, str(e))
         else:
             try:
-                datetime.datetime.fromisoformat(object_)
+                datetime.datetime.fromisoformat(obj)
             except Exception as e:
-                return _wrong_type_message(object_, name, self.__name__, str(e))
+                return _wrong_type_message(obj, name, self.__name__, str(e))
         return ""
 
 
 class date(compiled_schema):
+    """
+    Matches an ISO 8601 date.
+    """
+
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
-        if not isinstance(object_, str):
-            return _wrong_type_message(object_, name, "date")
+        if not isinstance(obj, str):
+            return _wrong_type_message(obj, name, "date")
         try:
-            datetime.date.fromisoformat(object_)
+            datetime.date.fromisoformat(obj)
         except Exception as e:
-            return _wrong_type_message(object_, name, "date", str(e))
+            return _wrong_type_message(obj, name, "date", str(e))
         return ""
 
 
 class time(compiled_schema):
+    """
+    Matches an ISO 8601 time.
+    """
+
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
-        if not isinstance(object_, str):
-            return _wrong_type_message(object_, name, "date")
+        if not isinstance(obj, str):
+            return _wrong_type_message(obj, name, "date")
         try:
-            datetime.time.fromisoformat(object_)
+            datetime.time.fromisoformat(obj)
         except Exception as e:
-            return _wrong_type_message(object_, name, "time", str(e))
+            return _wrong_type_message(obj, name, "time", str(e))
         return ""
 
 
 class nothing(compiled_schema):
+    """
+    Matches nothing.
+    """
+
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
-        return _wrong_type_message(object_, name, "nothing")
+        return _wrong_type_message(obj, name, "nothing")
 
 
 class anything(compiled_schema):
+    """
+    Matchess anything.
+    """
+
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
@@ -1413,12 +1827,20 @@ class anything(compiled_schema):
 
 
 class domain_name(compiled_schema):
+    """
+    Checks if the object is a valid domain name.
+    """
+
     re_asci: re.Pattern[str]
     ascii_only: bool
     resolve: bool
     __name__: str
 
     def __init__(self, ascii_only: bool = True, resolve: bool = False) -> None:
+        """
+        :param ascii_only: if `False` then allow IDNA domain names
+        :param resolve: if `True` check if the domain names resolves
+        """
         self.re_ascii = re.compile(r"[\x00-\x7F]*")
         self.ascii_only = ascii_only
         self.resolve = resolve
@@ -1435,129 +1857,161 @@ class domain_name(compiled_schema):
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
-        if not isinstance(object_, str):
-            return _wrong_type_message(object_, name, self.__name__)
+        if not isinstance(obj, str):
+            return _wrong_type_message(obj, name, self.__name__)
         if self.ascii_only:
-            if not self.re_ascii.fullmatch(object_):
+            if not self.re_ascii.fullmatch(obj):
                 return _wrong_type_message(
-                    object_, name, self.__name__, "Non-ascii characters"
+                    obj, name, self.__name__, "Non-ascii characters"
                 )
         try:
-            idna.encode(object_, uts46=False)
+            idna.encode(obj, uts46=False)
         except idna.core.IDNAError as e:
-            return _wrong_type_message(object_, name, self.__name__, str(e))
+            return _wrong_type_message(obj, name, self.__name__, str(e))
 
         if self.resolve:
             try:
-                _get_dns_resolver().resolve(object_)
+                _get_dns_resolver().resolve(obj)
             except Exception as e:
-                return _wrong_type_message(object_, name, self.__name__, str(e))
+                return _wrong_type_message(obj, name, self.__name__, str(e))
         return ""
 
 
 class at_least_one_of(compiled_schema):
+    """
+    This represents a dictionary with a least one key among a collection of
+    keys.
+    """
+
     args: tuple[object, ...]
     __name__: str
 
     def __init__(self, *args: object) -> None:
+        """
+        :param args: a collection of keys
+        """
         self.args = args
         args_s = [repr(a) for a in args]
         self.__name__ = f"{self.__class__.__name__}({','.join(args_s)})"
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
-        if not isinstance(object_, Mapping):
-            return _wrong_type_message(object_, name, self.__name__)
+        if not isinstance(obj, Mapping):
+            return _wrong_type_message(obj, name, self.__name__)
         try:
-            if any([a in object_ for a in self.args]):
+            if any([a in obj for a in self.args]):
                 return ""
             else:
-                return _wrong_type_message(object_, name, self.__name__)
+                return _wrong_type_message(obj, name, self.__name__)
         except Exception as e:
-            return _wrong_type_message(object_, name, self.__name__, str(e))
+            return _wrong_type_message(obj, name, self.__name__, str(e))
 
 
 class at_most_one_of(compiled_schema):
+    """
+    This represents an dictionary with at most one key among a collection of
+    keys.
+    """
+
     args: tuple[object, ...]
     __name__: str
 
     def __init__(self, *args: object) -> None:
+        """
+        :param args: a collection of keys
+        """
         self.args = args
         args_s = [repr(a) for a in args]
         self.__name__ = f"{self.__class__.__name__}({','.join(args_s)})"
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
-        if not isinstance(object_, Mapping):
-            return _wrong_type_message(object_, name, self.__name__)
+        if not isinstance(obj, Mapping):
+            return _wrong_type_message(obj, name, self.__name__)
         try:
-            if sum([a in object_ for a in self.args]) <= 1:
+            if sum([a in obj for a in self.args]) <= 1:
                 return ""
             else:
-                return _wrong_type_message(object_, name, self.__name__)
+                return _wrong_type_message(obj, name, self.__name__)
         except Exception as e:
-            return _wrong_type_message(object_, name, self.__name__, str(e))
+            return _wrong_type_message(obj, name, self.__name__, str(e))
 
 
 class one_of(compiled_schema):
+    """
+    This represents a dictionary with exactly one key among a collection of
+    keys.
+    """
+
     args: tuple[object, ...]
     __name__: str
 
     def __init__(self, *args: object) -> None:
+        """
+        :param args: a collection of keys
+        """
         self.args = args
         args_s = [repr(a) for a in args]
         self.__name__ = f"{self.__class__.__name__}({','.join(args_s)})"
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
-        if not isinstance(object_, Mapping):
-            return _wrong_type_message(object_, name, self.__name__)
+        if not isinstance(obj, Mapping):
+            return _wrong_type_message(obj, name, self.__name__)
         try:
-            if sum([a in object_ for a in self.args]) == 1:
+            if sum([a in obj for a in self.args]) == 1:
                 return ""
             else:
-                return _wrong_type_message(object_, name, self.__name__)
+                return _wrong_type_message(obj, name, self.__name__)
         except Exception as e:
-            return _wrong_type_message(object_, name, self.__name__, str(e))
+            return _wrong_type_message(obj, name, self.__name__, str(e))
 
 
 class keys(compiled_schema):
+    """
+    This represents a dictionary containing all the keys in a collection of
+    keys
+    """
+
     args: tuple[object, ...]
 
     def __init__(self, *args: object) -> None:
+        """
+        :param args: a collection of keys
+        """
         self.args = args
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
-        if not isinstance(object_, Mapping):
-            return _wrong_type_message(object_, name, "Mapping")  # TODO: __name__
+        if not isinstance(obj, Mapping):
+            return _wrong_type_message(obj, name, "Mapping")  # TODO: __name__
         for k in self.args:
-            if k not in object_:
+            if k not in obj:
                 return f"{name}[{repr(k)}] is missing"
         return ""
 
@@ -1585,26 +2039,29 @@ class _ifthen(compiled_schema):
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
-        if (
-            self.if_schema.__validate__(object_, name=name, strict=strict, subs=subs)
-            == ""
-        ):
+        if self.if_schema.__validate__(obj, name=name, strict=strict, subs=subs) == "":
             return self.then_schema.__validate__(
-                object_, name=name, strict=strict, subs=subs
+                obj, name=name, strict=strict, subs=subs
             )
         elif self.else_schema is not None:
             return self.else_schema.__validate__(
-                object_, name=name, strict=strict, subs=subs
+                obj, name=name, strict=strict, subs=subs
             )
         return ""
 
 
-class ifthen:
+class ifthen(wrapper):
+    """
+    If the object matches the `if_schema` then it should also match the
+    `then_schema`. If the object does not match the `if_schema` then it should
+    match the `else_schema`, if present.
+    """
+
     if_schema: object
     then_schema: object
     else_schema: object | None
@@ -1615,6 +2072,11 @@ class ifthen:
         then_schema: object,
         else_schema: object | None = None,
     ) -> None:
+        """
+        :param if_schema: the `if_schema`
+        :param then_schema: the `then_schema`
+        :param else_schema: the `else_schema`
+        """
         self.if_schema = if_schema
         self.then_schema = then_schema
         self.else_schema = else_schema
@@ -1647,21 +2109,35 @@ class _cond(compiled_schema):
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
         for c in self.conditions:
-            if c[0].__validate__(object_, name=name, strict=strict, subs=subs) == "":
-                return c[1].__validate__(object_, name=name, strict=strict, subs=subs)
+            if c[0].__validate__(obj, name=name, strict=strict, subs=subs) == "":
+                return c[1].__validate__(obj, name=name, strict=strict, subs=subs)
         return ""
 
 
-class cond:
+class cond(wrapper):
+    """
+    An object is successively validated against `if_schema1`, `if_schema2`,
+    ... until a validation succeeds. When this happens the object should match
+    the corresponding `then_schema`. If no `if_schema` succeeds then the
+    object is considered to have been validated. If one sets `if_schemaN`
+    equal to `anything` then this serves as a catch all.
+    """
+
     args: tuple[tuple[object, object], ...]
 
     def __init__(self, *args: tuple[object, object]) -> None:
+        """
+        :param args: list of tuples pairing `if_schemas` with `then_schemas`
+
+        :raises SchemaError: exception thrown when the schema definition is
+          found to contain an error
+        """
         for c in args:
             if not isinstance(c, tuple) or len(c) != 2:
                 raise SchemaError(f"{repr(c)} is not a tuple of length two")
@@ -1672,10 +2148,12 @@ class cond:
 
 
 class _fields(compiled_schema):
-    d: dict[str, compiled_schema]
+    d: dict[str | optional_key[str], compiled_schema]
 
     def __init__(
-        self, d: Mapping[str, object], _deferred_compiles: _mapping | None = None
+        self,
+        d: Mapping[str | optional_key[str], object],
+        _deferred_compiles: _mapping | None = None,
     ) -> None:
         self.d = {}
         for k, v in d.items():
@@ -1683,31 +2161,56 @@ class _fields(compiled_schema):
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
         for k, v in self.d.items():
             name_ = f"{name}.{k}"
-            if not hasattr(object_, k):
+            if not isinstance(k, optional_key) and not hasattr(obj, k):
                 return f"{name_} is missing"
+            if isinstance(k, optional_key):
+                k_ = k.key
+            else:
+                k_ = k
             ret = self.d[k].__validate__(
-                getattr(object_, k), name=name_, strict=strict, subs=subs
+                getattr(obj, k_), name=name_, strict=strict, subs=subs
             )
             if ret != "":
                 return ret
         return ""
 
 
-class fields:
-    def __init__(self, d: object) -> None:
+class fields(wrapper):
+    """
+    Matches Python objects with attributes `field1, field2, ..., fieldN` whose
+    corresponding values should validate against `schema1, schema2, ...,
+    schemaN` respectively
+    """
+
+    d: dict[str | optional_key[str], object]
+
+    def __init__(self, d: Mapping[str | optional_key[str], object]) -> None:
+        """
+        :param d: a dictionary associating fields with schemas
+
+        :raises SchemaError: exception thrown when the schema definition is
+          found to contain an error
+        """
+        self.d = {}
         if not isinstance(d, Mapping):
             raise SchemaError(f"{repr(d)} is not a Mapping")
-        for k in d:
-            if not isinstance(k, str):
-                raise SchemaError(f"key {repr(k)} in {repr(d)} is not a string")
-        self.d = d
+        for k, v in d.items():
+            if not isinstance(k, str) and not isinstance(k, optional_key):
+                raise SchemaError(
+                    f"key {repr(k)} in {repr(d)} is not an instance of"
+                    " optional_key and not a string"
+                )
+            if isinstance(k, str) and k[-1] == "?":
+                self.d[optional_key(k[:-1])] = v
+            else:
+                self.d[k] = v
 
     def __compile__(self, _deferred_compiles: _mapping | None = None) -> _fields:
         return _fields(self.d, _deferred_compiles=_deferred_compiles)
@@ -1739,25 +2242,28 @@ class _filter(compiled_schema):
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
         try:
-            object_ = self.filter(object_)
+            obj = self.filter(obj)
         except Exception as e:
             return (
                 f"Applying {self.filter_name} to {name} "
-                f"(value: {_c(object_)}) failed: {str(e)}"
+                f"(value: {_c(obj)}) failed: {str(e)}"
             )
         name = f"{self.filter_name}({name})"
-        return self.schema.__validate__(
-            object_, name="object", strict=strict, subs=subs
-        )
+        return self.schema.__validate__(obj, name="object", strict=strict, subs=subs)
 
 
-class filter:
+class filter(wrapper):
+    """
+    Applies `callable` to the object and validates the result with `schema`.
+    If the callable throws an exception then validation fails.
+    """
+
     filter: Callable[[Any], object]
     schema: object
     filter_name: str | None
@@ -1768,6 +2274,15 @@ class filter:
         schema: object,
         filter_name: str | None = None,
     ) -> None:
+        """
+        :param filter: the filter to apply to the object
+        :param schema: the schema used for validation once the filter has been
+          applied
+        :param filter_name: common name to refer to the filter
+
+        :raises SchemaError: exception thrown when the schema definition is
+          found to contain an error
+        """
         if filter_name is not None and not isinstance(filter_name, str):
             raise SchemaError("The filter name is not a string")
         if not callable(filter):
@@ -1798,16 +2313,16 @@ class _type(compiled_schema):
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
         try:
-            if self.schema == float and isinstance(object_, int):
+            if self.schema == float and isinstance(obj, int):
                 return ""
-            if not isinstance(object_, self.schema):
-                return _wrong_type_message(object_, name, self.schema.__name__)
+            if not isinstance(obj, self.schema):
+                return _wrong_type_message(obj, name, self.schema.__name__)
             else:
                 return ""
         except Exception as e:
@@ -1815,29 +2330,29 @@ class _type(compiled_schema):
 
     def __validate_float__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
         # consider int as a subtype of float
-        if isinstance(object_, (int, float)):
+        if isinstance(obj, (int, float)):
             return ""
         else:
-            return _wrong_type_message(object_, name, "float")
+            return _wrong_type_message(obj, name, "float")
 
     def __validate_complex__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
         # consider int, float as subtypes of complex
-        if isinstance(object_, (int, float, complex)):
+        if isinstance(obj, (int, float, complex)):
             return ""
         else:
-            return _wrong_type_message(object_, name, "complex")
+            return _wrong_type_message(obj, name, "complex")
 
     def __str__(self) -> str:
         return self.schema.__name__
@@ -1871,15 +2386,15 @@ class _sequence(compiled_schema):
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
-        if not isinstance(object_, self.type_schema):
-            return _wrong_type_message(object_, name, self.type_schema.__name__)
+        if not isinstance(obj, self.type_schema):
+            return _wrong_type_message(obj, name, self.type_schema.__name__)
         ls = len(self.schema)
-        lo = len(object_)
+        lo = len(obj)
         if strict:
             if lo > ls:
                 return f"{name}[{ls}] is not in the schema"
@@ -1887,32 +2402,32 @@ class _sequence(compiled_schema):
             return f"{name}[{lo}] is missing"
         for i in range(ls):
             name_ = f"{name}[{i}]"
-            ret = self.schema[i].__validate__(object_[i], name_, strict, subs)
+            ret = self.schema[i].__validate__(obj[i], name_, strict, subs)
             if ret != "":
                 return ret
         return ""
 
     def __validate_ellipsis__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
-        if not isinstance(object_, self.type_schema):
-            return _wrong_type_message(object_, name, self.type_schema.__name__)
+        if not isinstance(obj, self.type_schema):
+            return _wrong_type_message(obj, name, self.type_schema.__name__)
         ls = len(self.schema)
-        lo = len(object_)
+        lo = len(obj)
         if ls > lo:
             return f"{name}[{lo}] is missing"
         for i in range(ls):
             name_ = f"{name}[{i}]"
-            ret = self.schema[i].__validate__(object_[i], name_, strict, subs)
+            ret = self.schema[i].__validate__(obj[i], name_, strict, subs)
             if ret != "":
                 return ret
         for i in range(ls, lo):
             name_ = f"{name}[{i}]"
-            ret = self.fill.__validate__(object_[i], name_, strict, subs)
+            ret = self.fill.__validate__(obj[i], name_, strict, subs)
             if ret != "":
                 return ret
         return ""
@@ -1929,18 +2444,18 @@ class _const(compiled_schema):
         if isinstance(schema, float) and not strict_eq:
             setattr(self, "__validate__", close_to(schema).__validate__)
 
-    def message(self, name: str, object_: object) -> str:
-        return f"{name} (value:{_c(object_)}) is not equal to {repr(self.schema)}"
+    def message(self, name: str, obj: object) -> str:
+        return f"{name} (value:{_c(obj)}) is not equal to {repr(self.schema)}"
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
-        if object_ != self.schema:
-            return self.message(name, object_)
+        if obj != self.schema:
+            return self.message(name, obj)
         return ""
 
     def __str__(self) -> str:
@@ -1960,18 +2475,18 @@ class _callable(compiled_schema):
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
         try:
-            if self.schema(object_):
+            if self.schema(obj):
                 return ""
             else:
-                return _wrong_type_message(object_, name, self.__name__)
+                return _wrong_type_message(obj, name, self.__name__)
         except Exception as e:
-            return _wrong_type_message(object_, name, self.__name__, str(e))
+            return _wrong_type_message(obj, name, self.__name__, str(e))
 
     def __str__(self) -> str:
         return str(self.schema)
@@ -2016,25 +2531,25 @@ class _dict(compiled_schema):
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
-        if not isinstance(object_, self.type_schema):
-            return _wrong_type_message(object_, name, self.type_schema.__name__)
+        if not isinstance(obj, self.type_schema):
+            return _wrong_type_message(obj, name, self.type_schema.__name__)
 
         for k in self.min_keys:
-            if k not in object_:
+            if k not in obj:
                 name_ = f"{name}[{repr(k)}]"
                 return f"{name_} is missing"
 
-        for k in object_:
+        for k in obj:
             vals = []
             name_ = f"{name}[{repr(k)}]"
             if k in self.const_keys:
                 val = self.schema[k].__validate__(
-                    object_[k], name=name_, strict=strict, subs=subs
+                    obj[k], name=name_, strict=strict, subs=subs
                 )
                 if val == "":
                     continue
@@ -2044,7 +2559,7 @@ class _dict(compiled_schema):
             for kk in self.other_keys:
                 if kk.__validate__(k, name="key", strict=strict, subs=subs) == "":
                     val = self.schema[kk].__validate__(
-                        object_[k], name=name_, strict=strict, subs=subs
+                        obj[k], name=name_, strict=strict, subs=subs
                     )
                     if val == "":
                         break
@@ -2085,27 +2600,27 @@ class _set(compiled_schema):
 
     def __validate_empty_set__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
-        if not isinstance(object_, self.type_schema):
-            return _wrong_type_message(object_, name, self.type_schema.__name__)
-        if len(object_) != 0:
-            return f"{name} (value:{_c(object_)}) is not empty"
+        if not isinstance(obj, self.type_schema):
+            return _wrong_type_message(obj, name, self.type_schema.__name__)
+        if len(obj) != 0:
+            return f"{name} (value:{_c(obj)}) is not empty"
         return ""
 
     def __validate_singleton__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
-        if not isinstance(object_, set):
-            return _wrong_type_message(object_, name, self.type_schema.__name__)
-        for i, o in enumerate(object_):
+        if not isinstance(obj, set):
+            return _wrong_type_message(obj, name, self.type_schema.__name__)
+        for i, o in enumerate(obj):
             name_ = f"{name}{{{i}}}"
             v = self.schema.__validate__(o, name=name_, strict=True, subs=subs)
             if v != "":
@@ -2114,14 +2629,14 @@ class _set(compiled_schema):
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
-        if not isinstance(object_, self.type_schema):
-            return _wrong_type_message(object_, name, self.type_schema.__name__)
-        for i, o in enumerate(object_):
+        if not isinstance(obj, self.type_schema):
+            return _wrong_type_message(obj, name, self.type_schema.__name__)
+        for i, o in enumerate(obj):
             name_ = f"{name}{{{i}}}"
             v = self.schema.__validate__(o, name=name_, strict=True, subs=subs)
             if v != "":
@@ -2132,12 +2647,26 @@ class _set(compiled_schema):
         return str(self.schema_)
 
 
-class protocol:
-    type_dict: dict[object, object]
+class protocol(wrapper):
+    """
+    An object matches the schema `protocol(schema, dict=False)` if `schema` is
+    a class (or class like object) and its fields are annotated with schemas
+    which validate the corresponding fields in the object.
+    """
+
+    type_dict: dict[str | optional_key[str], object]
     dict: bool
     __name__: str
 
     def __init__(self, schema: object, dict: bool = False):
+        """
+        :param schema: a type annotated class (or class like object such as
+          Protocol or TypedDict) serving as prototype
+        :param dict: if `True` parse the object as a `dict`
+
+        :raises SchemaError: exception thrown when the schema does not support
+          type_hints
+        """
         if not isinstance(dict, bool):
             raise SchemaError("bool flag is not a bool")
         type_hints = _get_type_hints(schema)
@@ -2225,16 +2754,16 @@ class _Mapping(compiled_schema):
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
 
-        if not isinstance(object_, self.type_schema):
-            return _wrong_type_message(object_, name, self.__name__)
+        if not isinstance(obj, self.type_schema):
+            return _wrong_type_message(obj, name, self.__name__)
 
-        for k, v in object_.items():
+        for k, v in obj.items():
             _name = f"{name}[{repr(k)}]"
             message = self.key.__validate__(k, name=str(k), strict=strict, subs=subs)
             if message != "":
@@ -2265,17 +2794,17 @@ class _Container(compiled_schema):
 
     def __validate__(
         self,
-        object_: object,
+        obj: object,
         name: str = "object",
         strict: bool = True,
         subs: Mapping[str, object] = {},
     ) -> str:
 
-        if not isinstance(object_, self.type_schema):
-            return _wrong_type_message(object_, name, self.type_schema.__name__)
+        if not isinstance(obj, self.type_schema):
+            return _wrong_type_message(obj, name, self.type_schema.__name__)
 
         try:
-            for i, o in enumerate(object_):
+            for i, o in enumerate(obj):
                 _name = f"{name}[{i}]"
                 message = self.schema.__validate__(
                     o, name=_name, strict=strict, subs=subs
@@ -2283,7 +2812,7 @@ class _Container(compiled_schema):
                 if message != "":
                     return message
         except Exception as e:
-            return _wrong_type_message(object_, name, self.__name__, explanation=str(e))
+            return _wrong_type_message(obj, name, self.__name__, explanation=str(e))
 
         return ""