pyrot.eye_modelling.datamodels.validators
=========================================

.. py:module:: pyrot.eye_modelling.datamodels.validators

.. autoapi-nested-parse::

   Data validation and field descriptors for pyROT data models.



Exceptions
----------

.. autoapisummary::

   pyrot.eye_modelling.datamodels.validators.ValidationError


Classes
-------

.. autoapisummary::

   pyrot.eye_modelling.datamodels.validators.RayOcularField
   pyrot.eye_modelling.datamodels.validators.Vector3


Functions
---------

.. autoapisummary::

   pyrot.eye_modelling.datamodels.validators.dataclass
   pyrot.eye_modelling.datamodels.validators.positive_float
   pyrot.eye_modelling.datamodels.validators.vector3
   pyrot.eye_modelling.datamodels.validators.literal
   pyrot.eye_modelling.datamodels.validators.optional


Module Contents
---------------

.. py:exception:: ValidationError(value: Any, field_name: str)

   Bases: :py:obj:`Exception`


   Exception raised when a validation error occurs.


.. py:class:: RayOcularField(validator: Callable[[Any], Value], name: str, *, default: Value = ...)

   Bases: :py:obj:`ValidatedField`\ [\ :py:obj:`Value`\ ]


   A descriptor class that provides validation for a RayOcular field.

   Parameters
   ----------
   validator : Callable[[Any], Value]
       A callable object that performs the validation.
   name : str
       The RayOcular name of the field. This is used for serialization and deserialization to RayOcular.
   default : Value, optional
       The default value for the field. If not provided, the field will be required and must be set explicitly.

   Attributes
   ----------
   public_name : str
       The public name of the field.
   private_name : str
       The private name of the field.

   Methods
   -------
   __get__(self, instance: Instance, owner: type[Instance] | None = None) -> Value:
       Retrieves the value of the field.

   __set__(self, instance: Instance, value: Value):
       Sets the value of the field after validating it.

   validate(self, value):
       Validates the given value using the provided validator.

   Raises
   ------
   ValueError
       If the validation fails.

   Notes
   -----
   Define a `ValidatedField` descriptor for a class attribute and provide a validator function.
   The validator function should take a single argument and return the validated value.

   Examples
   --------
   >>> class Person:
   ...     age = ValidatedField(int)
   ...
   ...     def __init__(self, age):
   ...         self.age = age


.. py:function:: dataclass(cls: type[T]) -> Callable[Ellipsis, T]

   Validate dataclasses.

   Checks if the value is an instance of the dataclass or a dict that can be used to create an instance of the dataclass.

   Parameters
   ----------
   cls : type[T]
       The dataclass type to validate against.

   Returns
   -------
   Callable[..., T]
       A validator function that can be used to validate instances of the dataclass.


.. py:function:: positive_float(value: Any) -> float

   Validate positive floats.

   Parameters
   ----------
   value : Any
       The value to validate.

   Returns
   -------
   float
       The validated positive float value.

   Raises
   ------
   ValueError
       If the value is not a positive float.


.. py:class:: Vector3

   Bases: :py:obj:`Generic`\ [\ :py:obj:`T`\ ]


   Three-dimensional vector with components of a given type.

   Attributes
   ----------
   x : T
       X component of the vector.
   y : T
       Y component of the vector.
   z : T
       Z component of the vector.


.. py:function:: vector3(item_validator: Callable[Ellipsis, T]) -> Callable[[Any], Vector3[T]]

   Validate Vector3 objects.

   Parameters
   ----------
   item_validator : Callable[..., T]
       A validator function for the individual components of the vector.

   Returns
   -------
   Callable[[Any], Vector3[T]]
       A validator function that can be used to validate Vector3 objects.


.. py:function:: literal(type_: type[T]) -> Callable[[Any], T]

   Validate literal values.

   Parameters
   ----------
   type_ : type[T]
       The type containing the allowed literal values.

   Returns
   -------
   Callable[[Any], T]
       A validator function that can be used to validate literal values.


.. py:function:: optional(inner: Callable[Ellipsis, T]) -> Callable[[Any], T | None]

   Validate optional values.

   Parameters
   ----------
   inner : Callable[..., T]
       The validator function for the non-optional value.

   Returns
   -------
   Callable[[Any], T | None]
       A validator function to validate optional values.