7152741451

Committed 09 Dec 2023 06:06PM UTC coverage: 98.886% (+0.03%) from 98.857%

Build # 7152741451

Build Type

push

github

Committed by

danielmbomfim

Commit Message

docs: updates README.md

Run Details

355 of 359 relevant lines covered (98.89%)

0.99 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

99.0

/PyYep/__init__.py

"""
Allows simple schema parsing and validation for inputs.

Classes:
    Schema
    InputItem
    StringValidator
    NumericValidator
    ArrayValidator
    DictValidator
    ValidationError
"""
from typing import (
    List,
    Optional,
    Callable,
    Union,
    Dict,
    TypeVar,
    TYPE_CHECKING,
)
from PyYep.validators.string import StringValidator
from PyYep.validators.numeric import NumericValidator
from PyYep.validators.array import ArrayValidator
from PyYep.validators.dict import DictValidator
from PyYep.exceptions import ValidationError

if TYPE_CHECKING:
    from .validators import Validator


InputT = TypeVar("InputT")
InputValueT = TypeVar("InputValueT")


class Schema:
    """
    A class to represent a schema.

    ...

    Attributes
    ----------
    _inputs: Union[List[InputItem], List[Validator]]
            the schema inputs
    on_fail: Callable[[], None]
            a callable to be used as a error hook
    abort_early: bool
            sets if the schema will raise a exception soon after
            a validation error happens

    Methods
    -------
    validate():
            Execute the inputs validators and return a dict containing all the
            inputs' values
    """

    def __init__(
        self,
        inputs: Union[List["InputItem"], List["Validator"]],
        on_fail: Optional[Callable[[], None]] = None,
        abort_early: Optional[int] = True,
    ) -> None:
        """
        Constructs all the necessary attributes for the schema object.

        Parameters
        ----------
                inputs (Union[List[InputItem], List[Validator]]):
                    the schema inputs
                on_fail (Callable[[], None]):
                    a callable to be used as a error hook
                abort_early (bool):
                    sets if the schema will raise a exception soon after
                    an error happens
        """

        for item in inputs:
            item._set_parent_form(self)

        self._inputs = inputs
        self.on_fail = on_fail
        self.abort_early = abort_early

    def validate(self) -> Dict[str, InputValueT]:
        """
        Execute the inputs validators and return a dict containing
        all the inputs' values

        Raises
        -------
        ValidationError: if any validation error happens in the
        inputs validation methods

        Returns
        -------
        result (dict): a dict containing all the validated values
        """

        result = {}
        errors = []

        for item in self._inputs:
            try:
                result[item.name] = item.verify()
            except ValidationError as error:
                if self.abort_early:
                    raise error

                if error.inner:
                    errors.extend(error.inner)
                    continue

                errors.append(error)

        if not self.abort_early and errors:
            raise ValidationError(
                "", "One or more inputs failed during validation", inner=errors
            )

        return result


class InputItem:
    """
    A class to represent a input item.

    ...

    Attributes
    ----------
    name: str
            the name of the input item
    _form: Schema
            the parent schema
    _input: InputT
            the input itself
    _path: str
            the property or method name that store the value in the input
    _validators: List[Callable[[InputValueT], None]]
            a list of validators
    on_success: Callable[[], None]
            a callable used as a local success hook
    on_fail: Callable[[], None]
            a callable used as a local error hook

    Methods
    -------
    _set_parent_form(form):
            Set the parent schema of the input item

    verify(result):
            Execute the inputs validators and return the result

    validate(validator):
            receives a validator and appends it on the validators list

    condition(condition):
            Set a condition for the execution of the previous validator

    modifier(modifier):
            Set a modifier to allow changes in the value after validation

    string():
            create a StringValidator using the input item as base

    number():
            create a NumericValidator using the input item as base
    """

    def __init__(
        self,
        name: str,
        input_: InputT,
        path: str,
        on_success: Optional[Callable[[], None]] = None,
        on_fail: Optional[Callable[[], None]] = None,
    ):
        """
        Constructs all the necessary attributes for the input item object.

        Parameters
        ----------
                name (str):
                    the name of the input item
                input_ (InputT):
                    the input itself
                path (str):
                    the input's property or method name that store the value
                on_success (Callable[[], None]):
                    a callable to be used as a local success hook
                on_fail (Callable[[], None]):
                    a callable to be used as a local error hook
        """

        self.name = name
        self._form = None
        self._input = input_
        self._path = path

        self._validators = []
        self._conditions = {}
        self._modifier = None
        self.on_fail = on_fail
        self.on_success = on_success

    def set_input(self, name: str, input_: InputT, path: str):
        """
        Sets the item

        Parameters
        ----------
                name (str):
                    the name of the input item
                input_ (InputT):
                    the input itself
                path (str):
                    the input's property or method name that store the value
        """

        self.name = name
        self._input = input_
        self._path = path

    def _set_parent_form(self, form: Schema) -> None:
        """
        Set the parent schema of the input item

        Parameters
        ----------
        form : Schema
                the input item parent schema

        Returns
        -------
        None
        """

        self._form = form

    def verify(self, result: Optional[InputValueT] = None) -> InputValueT:
        """
        Get the input value and execute all the validators

        Parameters
        ----------
        result : Optional[InputValueT]
                the value stored on the input, if not passed it will use
                the value returned by the method or attribute with the name
                stored on the input item _path attribute

        Raises:
        _______
        ValidationError:
                if any error happens during the validation process

        Returns
        -------
        result (InputValueT): The value received after all the validation
        """

        if result is None:
            result = getattr(self._input, self._path)

        if callable(result):
            result = result()

        for validator in self._validators:
            if validator in self._conditions and not self._conditions[
                validator
            ](result):
                continue

            try:
                validator(result)
            except ValidationError as error:
                if self.on_fail is not None:
                    self.on_fail()
                elif self._form is not None and self._form.on_fail is not None:
                    self._form.on_fail()

                raise error

        if self.on_success is not None:
            self.on_success()

        return result if self._modifier is None else self._modifier(result)

    def validate(
        self, validator: Callable[[InputValueT], None]
    ) -> "InputItem":
        """
        Append a validator in the input item validators list

        Returns
        -------
        self (InputItem): The input item itself
        """

        self._validators.append(validator)
        return self

    def condition(
        self, condition: Callable[[InputValueT], bool]
    ) -> "InputItem":
        """
        Set a condition for the execution of the previous validator

        Parameters
        ----------
        condition : Callable
                a callable that return a boolean that defines if the condition
                was satisfied

        Returns
        -------
        InputItem
        """

        self._conditions[self._validators[-1]] = condition
        return self

    def modifier(self, modifier: Callable[[InputValueT], bool]) -> "InputItem":
        """
        Set a modifier to allow changes in the value after validation

        Parameters
        ----------
        modifier : Callable
                a callable that executes changes in the value after validation

        Returns
        -------
        InputItem
        """

        self._modifier = modifier
        return self

    def string(self) -> StringValidator:
        """
        create a StringValidator using the input item as base

        Returns
        -------
        result (StringValidator): A string validator object
        """
        return StringValidator(self)

    def number(self) -> NumericValidator:
        """
        create a NumericValidator using the input item as base

        Returns
        -------
        result (NumericValidator): A numeric validator object
        """
        return NumericValidator(self)

    def array(self) -> ArrayValidator:
        """
        create a ArrayValidator using the input item as base

        Returns
        -------
        result (ArrayValidator): An array validator object
        """
        return ArrayValidator(self)

    def dict(self) -> DictValidator:
        """
        create a DictValidator using the input item as base

        Returns
        -------
        result (DictValidator): A dict validator object
        """
        return DictValidator(self)

1	"""
2	Allows simple schema parsing and validation for inputs.
3
4	Classes:
5	Schema
6	InputItem
7	StringValidator
8	NumericValidator
9	ArrayValidator
10	DictValidator
11	ValidationError
12	"""
13	from typing import (	1✔
14	List,
15	Optional,
16	Callable,
17	Union,
18	Dict,
19	TypeVar,
20	TYPE_CHECKING,
21	)
22	from PyYep.validators.string import StringValidator	1✔
23	from PyYep.validators.numeric import NumericValidator	1✔
24	from PyYep.validators.array import ArrayValidator	1✔
25	from PyYep.validators.dict import DictValidator	1✔
26	from PyYep.exceptions import ValidationError	1✔
27
28	if TYPE_CHECKING:	1✔
29	from .validators import Validator	×
30
31
32	InputT = TypeVar("InputT")	1✔
33	InputValueT = TypeVar("InputValueT")	1✔
34
35
36	class Schema:	1✔
37	"""
38	A class to represent a schema.
39
40	...
41
42	Attributes
43	----------
44	_inputs: Union[List[InputItem], List[Validator]]
45	the schema inputs
46	on_fail: Callable[[], None]
47	a callable to be used as a error hook
48	abort_early: bool
49	sets if the schema will raise a exception soon after
50	a validation error happens
51
52	Methods
53	-------
54	validate():
55	Execute the inputs validators and return a dict containing all the
56	inputs' values
57	"""
58
59	def __init__(	1✔
60	self,
61	inputs: Union[List["InputItem"], List["Validator"]],	1✔
62	on_fail: Optional[Callable[[], None]] = None,	1✔
63	abort_early: Optional[int] = True,	1✔
64	) -> None:	1✔
65	"""
66	Constructs all the necessary attributes for the schema object.
67
68	Parameters
69	----------
70	inputs (Union[List[InputItem], List[Validator]]):
71	the schema inputs
72	on_fail (Callable[[], None]):
73	a callable to be used as a error hook
74	abort_early (bool):
75	sets if the schema will raise a exception soon after
76	an error happens
77	"""
78
79	for item in inputs:	1✔
80	item._set_parent_form(self)	1✔
81
82	self._inputs = inputs	1✔
83	self.on_fail = on_fail	1✔
84	self.abort_early = abort_early	1✔
85
86	def validate(self) -> Dict[str, InputValueT]:	1✔
87	"""
88	Execute the inputs validators and return a dict containing
89	all the inputs' values
90
91	Raises
92	-------
93	ValidationError: if any validation error happens in the
94	inputs validation methods
95
96	Returns
97	-------
98	result (dict): a dict containing all the validated values
99	"""
100
101	result = {}	1✔
102	errors = []	1✔
103
104	for item in self._inputs:	1✔
105	try:	1✔
106	result[item.name] = item.verify()	1✔
107	except ValidationError as error:	1✔
108	if self.abort_early:	1✔
109	raise error	1✔
110
111	if error.inner:	1✔
112	errors.extend(error.inner)
113	continue
114
115	errors.append(error)	1✔
116
117	if not self.abort_early and errors:	1✔
118	raise ValidationError(	1✔
119	"", "One or more inputs failed during validation", inner=errors	1✔
120	)
121
122	return result	1✔
123
124
125	class InputItem:	1✔
126	"""
127	A class to represent a input item.
128
129	...
130
131	Attributes
132	----------
133	name: str
134	the name of the input item
135	_form: Schema
136	the parent schema
137	_input: InputT
138	the input itself
139	_path: str
140	the property or method name that store the value in the input
141	_validators: List[Callable[[InputValueT], None]]
142	a list of validators
143	on_success: Callable[[], None]
144	a callable used as a local success hook
145	on_fail: Callable[[], None]
146	a callable used as a local error hook
147
148	Methods
149	-------
150	_set_parent_form(form):
151	Set the parent schema of the input item
152
153	verify(result):
154	Execute the inputs validators and return the result
155
156	validate(validator):
157	receives a validator and appends it on the validators list
158
159	condition(condition):
160	Set a condition for the execution of the previous validator
161
162	modifier(modifier):
163	Set a modifier to allow changes in the value after validation
164
165	string():
166	create a StringValidator using the input item as base
167
168	number():
169	create a NumericValidator using the input item as base
170	"""
171
172	def __init__(	1✔
173	self,
174	name: str,	1✔
175	input_: InputT,	1✔
176	path: str,	1✔
177	on_success: Optional[Callable[[], None]] = None,	1✔
178	on_fail: Optional[Callable[[], None]] = None,	1✔
179	):
180	"""
181	Constructs all the necessary attributes for the input item object.
182
183	Parameters
184	----------
185	name (str):
186	the name of the input item
187	input_ (InputT):
188	the input itself
189	path (str):
190	the input's property or method name that store the value
191	on_success (Callable[[], None]):
192	a callable to be used as a local success hook
193	on_fail (Callable[[], None]):
194	a callable to be used as a local error hook
195	"""
196
197	self.name = name	1✔
198	self._form = None	1✔
199	self._input = input_	1✔
200	self._path = path	1✔
201
202	self._validators = []	1✔
203	self._conditions = {}	1✔
204	self._modifier = None	1✔
205	self.on_fail = on_fail	1✔
206	self.on_success = on_success	1✔
207
208	def set_input(self, name: str, input_: InputT, path: str):	1✔
209	"""
210	Sets the item
211
212	Parameters
213	----------
214	name (str):
215	the name of the input item
216	input_ (InputT):
217	the input itself
218	path (str):
219	the input's property or method name that store the value
220	"""
221
222	self.name = name	1✔
223	self._input = input_	1✔
224	self._path = path	1✔
225
226	def _set_parent_form(self, form: Schema) -> None:	1✔
227	"""
228	Set the parent schema of the input item
229
230	Parameters
231	----------
232	form : Schema
233	the input item parent schema
234
235	Returns
236	-------
237	None
238	"""
239
240	self._form = form	1✔
241
242	def verify(self, result: Optional[InputValueT] = None) -> InputValueT:	1✔
243	"""
244	Get the input value and execute all the validators
245
246	Parameters
247	----------
248	result : Optional[InputValueT]
249	the value stored on the input, if not passed it will use
250	the value returned by the method or attribute with the name
251	stored on the input item _path attribute
252
253	Raises:
254	_______
255	ValidationError:
256	if any error happens during the validation process
257
258	Returns
259	-------
260	result (InputValueT): The value received after all the validation
261	"""
262
263	if result is None:	1✔
264	result = getattr(self._input, self._path)	1✔
265
266	if callable(result):	1✔
267	result = result()	1✔
268
269	for validator in self._validators:	1✔
270	if validator in self._conditions and not self._conditions[	1✔
271	validator	1✔
272	](result):	1✔
273	continue	1✔
274
275	try:	1✔
276	validator(result)	1✔
277	except ValidationError as error:	1✔
278	if self.on_fail is not None:	1✔
279	self.on_fail()	1✔
280	elif self._form is not None and self._form.on_fail is not None:	1✔
281	self._form.on_fail()	1✔
282
283	raise error	1✔
284
285	if self.on_success is not None:	1✔
286	self.on_success()	1✔
287
288	return result if self._modifier is None else self._modifier(result)	1✔
289
290	def validate(	1✔
291	self, validator: Callable[[InputValueT], None]	1✔
292	) -> "InputItem":	1✔
293	"""
294	Append a validator in the input item validators list
295
296	Returns
297	-------
298	self (InputItem): The input item itself
299	"""
300
301	self._validators.append(validator)	1✔
302	return self	1✔
303
304	def condition(	1✔
305	self, condition: Callable[[InputValueT], bool]	1✔
306	) -> "InputItem":	1✔
307	"""
308	Set a condition for the execution of the previous validator
309
310	Parameters
311	----------
312	condition : Callable
313	a callable that return a boolean that defines if the condition
314	was satisfied
315
316	Returns
317	-------
318	InputItem
319	"""
320
321	self._conditions[self._validators[-1]] = condition	1✔
322	return self	1✔
323
324	def modifier(self, modifier: Callable[[InputValueT], bool]) -> "InputItem":	1✔
325	"""
326	Set a modifier to allow changes in the value after validation
327
328	Parameters
329	----------
330	modifier : Callable
331	a callable that executes changes in the value after validation
332
333	Returns
334	-------
335	InputItem
336	"""
337
338	self._modifier = modifier	1✔
339	return self	1✔
340
341	def string(self) -> StringValidator:	1✔
342	"""
343	create a StringValidator using the input item as base
344
345	Returns
346	-------
347	result (StringValidator): A string validator object
348	"""
349	return StringValidator(self)	1✔
350
351	def number(self) -> NumericValidator:	1✔
352	"""
353	create a NumericValidator using the input item as base
354
355	Returns
356	-------
357	result (NumericValidator): A numeric validator object
358	"""
359	return NumericValidator(self)	1✔
360
361	def array(self) -> ArrayValidator:	1✔
362	"""
363	create a ArrayValidator using the input item as base
364
365	Returns
366	-------
367	result (ArrayValidator): An array validator object
368	"""
369	return ArrayValidator(self)	1✔
370
371	def dict(self) -> DictValidator:	1✔
372	"""
373	create a DictValidator using the input item as base
374
375	Returns
376	-------
377	result (DictValidator): A dict validator object
378	"""
379	return DictValidator(self)	1✔

danielmbomfim / PyYep / 7152741451

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous