From 9f8f5b4bdd5992253b6075fc51a029738d77039d Mon Sep 17 00:00:00 2001 From: sg495 Date: Tue, 30 Jan 2024 11:56:35 +0000 Subject: [PATCH] Updated docs --- README.rst | 22 +++++++++++++- docs/api/typing_validation.rst | 1 + docs/api/typing_validation.validation.rst | 5 +++ docs/getting-started.rst | 37 ++++++++++++++--------- docs/index.rst | 9 ++++-- 5 files changed, 57 insertions(+), 17 deletions(-) diff --git a/README.rst b/README.rst index 6ed5ae0..994c086 100644 --- a/README.rst +++ b/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 , 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 , 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 --- diff --git a/docs/api/typing_validation.rst b/docs/api/typing_validation.rst index c50e589..1db0a5e 100644 --- a/docs/api/typing_validation.rst +++ b/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` diff --git a/docs/api/typing_validation.validation.rst b/docs/api/typing_validation.validation.rst index 3895f66..008f6c0 100644 --- a/docs/api/typing_validation.validation.rst +++ b/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 -------- diff --git a/docs/getting-started.rst b/docs/getting-started.rst index 181f780..9ab03f9 100644 --- a/docs/getting-started.rst +++ b/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 , 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 , 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 diff --git a/docs/index.rst b/docs/index.rst index 31d1185..2ef507e 100644 --- a/docs/index.rst +++ b/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 , 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