Updated docs

README.rst

@@ -56,7 +56,7 @@ The core functionality of this library is provided by the `validate` function:
 The `validate` function is invoked with a value and a type as its arguments and it returns nothing when the given value is valid for the given type:
 
 >>> validate(12, int)
-# nothing is returned => 12 is a valid int
+True # no error raised => 12 is a valid int
 
 If the value is invalid for the given type, the `validate` function raises a `TypeError`:
 
@@ -72,6 +72,26 @@ For type list[int], invalid value at idx: 2
   For type <class 'int'>, invalid value: 'hi'
 
 
+The function `is_valid` is a variant of the `validate` function which returns `False` in case of validation failure, instead of raising `TypeError`:
+
+>>> from typing_validation import is_valid
+>>> is_valid([0, 1, "hi"], list[int])
+False
+
+The function `latest_validation_failure` can be used to access detailed information immediately after a failure:
+
+>>> from typing_validation import latest_validation_failure
+>>> is_valid([0, 1, "hi"], list[int])
+False
+>>> failure = latest_validation_failure()
+>>> print(failure)
+Runtime validation error raised by validate(val, t), details below.
+For type list[int], invalid value at idx: 2
+  For type <class 'int'>, invalid value: 'hi'
+
+Please note that `latest_validation_failure` clears the internal failure logs after returning the latest failure, so the latter must be manually stored if it needs to be accessed multiple times.
+
+
 API
 ---
 

docs/api/typing_validation.rst

@@ -12,6 +12,7 @@ The following members were explicitly reexported using ``__all__``:
     - :py:class:`typing_validation.inspector.UnsupportedType`
     - :py:func:`typing_validation.validation.can_validate`
     - :py:func:`typing_validation.validation_failure.get_validation_failure`
+    - :py:func:`typing_validation.validation.is_valid`
     - :py:func:`typing_validation.validation_failure.latest_validation_failure`
     - :py:func:`typing_validation.validation.validate`
     - :py:func:`typing_validation.validation.validated`

docs/api/typing_validation.validation.rst

@@ -13,6 +13,11 @@ can_validate
 
 .. autofunction:: typing_validation.validation.can_validate
 
+is_valid
+--------
+
+.. autofunction:: typing_validation.validation.is_valid
+
 validate
 --------
 

docs/getting-started.rst

@@ -22,11 +22,10 @@ The core functionality of this library is provided by the :func:`~typing_validat
 
 >>> from typing_validation import validate
 
-The :func:`~typing_validation.validation.validate` function is invoked with a value and a type as its arguments and
-it returns nothing when the given value is valid for the given type:
+The :func:`~typing_validation.validation.validate` function is invoked with a value and a type as its arguments and it returns :obj:`True` when the given value is valid for the given type:
 
 >>> validate(12, int)
-# nothing is returned => 12 is a valid int
+True # no error raised => 12 is a valid int
 
 If the value is invalid for the given type, the :func:`~typing_validation.validation.validate` function raises a :exc:`TypeError`:
 
@@ -53,14 +52,28 @@ For type list[typing.Union[typing.Collection[int], dict[str, str]]], invalid val
     For member type dict[str, str], invalid value at key: 'hi'
       For type <class 'str'>, invalid value: 0
 
-Detailed information about types supported by :func:`~typing_validation.validation.validate` is provided by
-the :func:`~typing_validation.validation.can_validate` function:
+The function :func:`~typing_validation.validation.is_valid` is a variant of the :func:`~typing_validation.validation.validate` function which returns :obj:`False` in case of validation failure, instead of raising `TypeError`:
+
+>>> from typing_validation import is_valid
+>>> is_valid([0, 1, "hi"], list[int])
+False
+
+The function `latest_validation_failure` can be used to access detailed information immediately after a failure:
+
+>>> from typing_validation import latest_validation_failure
+>>> is_valid([0, 1, "hi"], list[int])
+False
+>>> failure = latest_validation_failure()
+>>> print(failure)
+Runtime validation error raised by validate(val, t), details below.
+For type list[int], invalid value at idx: 2
+  For type <class 'int'>, invalid value: 'hi'
+
+Detailed information about types supported by :func:`~typing_validation.validation.validate` is provided by the :func:`~typing_validation.validation.can_validate` function:
 
 >>> from typing_validation import can_validate
 
-The :func:`~typing_validation.validation.can_validate` function is invoked with a type as its argument and it returns a
-:class:`~typing_validation.validation.TypeInspector` object, containing detailed information about the structure of the type that was being validated,
-including the presence of types not supported by :func:`~typing_validation.validation.validate` (wrapped into a
+The :func:`~typing_validation.validation.can_validate` function is invoked with a type as its argument and it returns a :class:`~typing_validation.validation.TypeInspector` object, containing detailed information about the structure of the type that was being validated, including the presence of types not supported by :func:`~typing_validation.validation.validate` (wrapped into a
 :class:`~typing_validation.validation.UnsupportedType`):
 
 >>> from typing import *
@@ -80,10 +93,7 @@ tuple[
     ],
 ]
 
-The :func:`~typing_validation.validation.validation_aliases` can be used to define set simple type aliases that can be used by
-:func:`~typing_validation.validation.validate` to resolve forward references.
-For example, the following snippet validates a value against a recursive type alias for JSON-like objects, using :func:`typing_validation.validation.validation_aliases` to create a
-context where :func:`typing_validation.validation.validate` internally evaluates the forward reference ``"JSON"`` to the type alias ``JSON``:
+The :func:`~typing_validation.validation.validation_aliases` can be used to define set simple type aliases that can be used by :func:`~typing_validation.validation.validate` to resolve forward references. For example, the following snippet validates a value against a recursive type alias for JSON-like objects, using :func:`typing_validation.validation.validation_aliases` to create a context where :func:`typing_validation.validation.validate` internally evaluates the forward reference ``"JSON"`` to the type alias ``JSON``:
 
 >>> from typing import *
 >>> from typing_validation import validate, validation_aliases
@@ -92,8 +102,7 @@ context where :func:`typing_validation.validation.validate` internally evaluates
 >>>     validate([1, 2.2, {"a": ["Hello", None, {"b": True}]}], list["JSON"])
 
 
-The result of :func:`~typing_validation.validation.can_validate` can be used wherever a :obj:`bool` is expected, returning :obj:`True` upon (implicit or
-explicit) :obj:`bool` conversion if and only if the type can be validated:
+The result of :func:`~typing_validation.validation.can_validate` can be used wherever a :obj:`bool` is expected, returning :obj:`True` upon (implicit or explicit) :obj:`bool` conversion if and only if the type can be validated:
 
 >>> bool(can_validate(Callable[[int], int]))
 False

docs/index.rst

@@ -10,11 +10,10 @@ If ``val`` is a value of type ``t``, the call ``validate(val, t)`` raises no err
 
 >>> from typing_validation import validate
 >>> validate([0, 1, 2], list[int])
-# no error raised => [0, 1, 2] is a value of type list[int]
+True # no error raised => [0, 1, 2] is a value of type list[int]
 
 If ``val`` is **not** a value of type ``t``, the call ``validate(val, t)`` raises a :exc:`TypeError`, with detailed information about validation failure(s):
 
-
 >>> validate([[0, 1, 2], {"hi": 0}], list[Union[Collection[int], dict[str, str]]])
 TypeError: Runtime validation error raised by validate(val, t), details below.
 For type list[typing.Union[typing.Collection[int], dict[str, str]]], invalid value at idx: 1
@@ -24,6 +23,12 @@ For type list[typing.Union[typing.Collection[int], dict[str, str]]], invalid val
     For member type dict[str, str], invalid value at key: 'hi'
       For type <class 'str'>, invalid value: 0
 
+The function :func:`~typing_validation.validation.is_valid` is a variant of the `validate` function which returns :obj:`False` in case of validation failure, instead of raising `TypeError`:
+
+>>> from typing_validation import is_valid
+>>> is_valid([0, 1, "hi"], list[int])
+False
+
 
 .. toctree::
     :maxdepth: 3