parasite.array

Brief

Reference for the array submodule of the parasite package. This submodule contains the parasite.array.Array class, which is a generic container for a list of elements of a specific type.

Usage

from parasite import p

schema = p.array()
schema.parse([1])  # 1
schema.parse(['hello'])  # 'hello'
...

schema = p.array(p.number().integer())
schema.parse([1, 2, 3])  # [1, 2, 3]
schema.parse(["hello", "world"])  # ValidationError: Expected an integer, got 'hello'
...

Member Reference

class parasite.array.K

Template type for the key in a dictionary.

alias of TypeVar(‘K’)

class parasite.array.Array(element: ParasiteType | None = None)

parasite type for creating and parsing list/array based schemas. Will return a python list[Any] with the parsed values on success.

Note

Please use p.array(...) instead of instantiating this class directly. p can be imported with:

from parasite import p

schema = p.array(...)
...

Note

Calling the constructor with an element type will set the element type of the list. This is equivalent to calling p.array().element(element) (see element()). If no element type is specified, the list will skip parsing the elements, and therefore accept any type of object or value.

Inheritance:

Parameters:

element (ParasiteType | None) – The element type of the list. Default: None

Example usage:

Lets assume we have the following schemas:

from parasite import p

schema = p.array()
schema2 = p.array(p.string())

The resulting schemas will parse the following objects:

>>> schema.parse(["John", "Doe"])
["John", "Doe"]
>>> schema.parse(["John", 1])
["John", 1]

>>> schema.parse(["John", "Doe"])
["John", "Doe"]
>>> schema.parse(["John", 1])
ValidationError: element at index 1 is invalid: object has to be a string, but is 1

optional() → Array

Makes the value optional, when parsing with _find_and_parse(). Has no effect on parse(). Inverse of required().

Warning

This function has no effect if the value is parsed as a standalone value.

Returns:

The updated instance of the class.

Return type:

Array

Example usage:

Lets assume we have the following schemas:

from parasite import p

schema = p.obj({"name": p.array().optional()})
schema2 = p.obj({"name": p.array()})

The resulting schemas will parse the following objects:

>>> schema.parse({ "name": ["John", "Doe"] })
{ "name": ["John", "Doe"] }
>>> schema.parse({ })
{ }

>>> schema2.parse({ "name": ["John", "Doe"] })
{ "name": ["John", "Doe"] }
>>> schema2.parse({ })
ValidationError: key "name" not found, but is required

required() → Array

Makes the value required, when parsing with _find_and_parse(). Has no effect on parse(). Inverse of optional(). Default behavior.

Note

This function is default behavior for the class and therefore only has an effect if the function optional() may have been called before.

Warning

This function has no effect if the value is parsed as a standalone value.

Returns:

The updated instance of the class.

Return type:

Array

Example usage:

Lets assume we have the following schemas:

from parasite import p

schema = p.obj({"name": p.array().optional().required()})
schema2 = p.obj({"name": p.array()})

The resulting schemas will parse the following objects:

>>> schema.parse({ "name": ["John", "Doe"] })
{ "name": ["John", "Doe"] }
>>> schema.parse({ })
ValidationError: key "name" not found, but is required

>>> schema2.parse({ "name": ["John", "Doe"] })
{ "name": ["John", "Doe"] }
>>> schema2.parse({ })
ValidationError: key "name" not found, but is required

nullable() → Array

Makes the value nullable, when parsing with _find_and_parse(). Has no effect on parse(). Inverse of not_nullable().

Warning

This function has no effect if the value is parsed as a standalone value.

Returns:

The updated instance of the class.

Return type:

Array

Example usage:

Lets assume we have the following schemas:

from parasite import p

schema = p.obj({"name": p.array().nullable()})
schema2 = p.obj({"name": p.array()})

The resulting schemas will parse the following objects:

>>> schema.parse({ "name": ["John", "Doe"] })
{ "name": ["John", "Doe"] }
>>> schema.parse({ "name": None })
{ "name": None }

>>> schema2.parse({ "name": ["John", "Doe"] })
{ "name": ["John", "Doe"] }
>>> schema2.parse({ "name": None })
ValidationError: key "name" is not nullable, but is None

not_nullable() → Array

Makes the value not-nullable, when parsing with _find_and_parse(). Has no effect on parse(). Inverse of nullable(). Default behavior.

Note

This function is default behavior for the class and therefore only has an effect if the function nullable() may have been called before.

Warning

This function has no effect if the value is parsed as a standalone value.

Returns:

The updated instance of the class.

Return type:

Array

Example usage:

Lets assume we have the following schemas:

from parasite import p

schema = p.obj({"name": p.array().nullable().not_nullable()})
schema2 = p.obj({"name": p.array()})

The resulting schemas will parse the following objects:

>>> schema.parse({ "name": ["John", "Doe"] })
{ "name": ["John", "Doe"] }
>>> schema.parse({ "name": None })
ValidationError: key "name" is not nullable, but is None

>>> schema2.parse({ "name": ["John", "Doe"] })
{ "name": ["John", "Doe"] }
>>> schema2.parse({ "name": None })
ValidationError: key "name" is not nullable, but is None

min(value: int) → Array

Enforce the minimum length of the list.

Parameters:

value (int) – The minimum length of the list.

Returns:

The updated instance of the class.

Return type:

Array

Example usage:

Lets assume we have the following schemas:

from parasite import p

schema = p.array().min(2)

The resulting schemas will parse the following objects:

>>> schema.parse(["John", "Doe"])
["John", "Doe"]

>>> schema.parse(["John"])
ValidationError: list has to have at least 2 elements, but has 1

max(value: int) → Array

Enforce the maximum length of the list.

Parameters:

value (int) – The maximum length of the list.

Returns:

The updated instance of the class.

Return type:

Array

Example usage:

Lets assume we have the following schemas:

from parasite import p

schema = p.array().max(2)

The resulting schemas will parse the following objects:

>>> schema.parse(["John", "Doe"])
["John", "Doe"]

>>> schema.parse(["John", "Doe", "Smith"])
ValidationError: list has to have at most 2 elements, but has 3

not_empty() → Array

Enforce the list to not be empty. Equivalent to calling min(1).

Returns:

The updated instance of the class.

Return type:

Array

Example usage:

Lets assume we have the following schemas:

from parasite import p

schema = p.array().not_empty()

The resulting schemas will parse the following objects:

>>> schema.parse(["John", "Doe"])
["John", "Doe"]

>>> schema.parse([ ])
ValidationError: list has to have at least 1 elements, but has 0

empty() → Array

Enforce the list to be empty. Equivalent to calling max(0).

Returns:

The updated instance of the class.

Return type:

Array

Example usage:

Lets assume we have the following schemas:

from parasite import p

schema = p.array().empty()

The resulting schemas will parse the following objects:

>>> schema.parse([ ])
[ ]

>>> schema.parse(["John", "Doe"])
ValidationError: list has to have at most 0 elements, but has 2

length(value: int) → Array

Enforce the list to have exactly the given length. Equivalent to calling min(value).max(value).

Parameters:

value (int) – The length of the list.

Returns:

The updated instance of the class.

Return type:

Array

Example usage:

Lets assume we have the following schemas:

from parasite import p

schema = p.array().length(2)

The resulting schemas will parse the following objects:

>>> schema.parse(["John", "Doe"])
["John", "Doe"]

>>> schema.parse(["John", "Doe", "Smith"])
ValidationError: list has to have exactly 2 elements, but has 3

>>> schema.parse(["John"])
ValidationError: list has to have exactly 2 elements, but has 1

element(element: ParasiteType) → Array

Set the ParsiteType schema of the elements in the list. Can also be set in the constructor. .. note:

If not set, the list will skip parsing the elements, and therefore accept any type of
object or value.

Parameters:

element (ParasiteType[T]) – The element type of the list.

Returns:

The updated instance of the class.

Return type:

Array

Example usage:

Lets assume we have the following schemas:

from parasite import p

schema = p.array().element(p.string())

The resulting schemas will parse the following objects:

>>> schema.parse(["John", "Doe"])
["John", "Doe"]

>>> schema.parse(["John", 1])
ValidationError: element at index 1 is invalid: object has to be a string, but is 1

parse(obj: Any) → list[Any]

Default method for parsing a value. This method should be overridden by subclasses.

Throws:

ValidationError: if the value could not be parsed or was invalid

Parameters:

obj (Any) – value to parse

Returns:

parsed destination value

Return type:

T

parse_safe(obj: Any) → Result[T, ValidationError]

Converts the result of parse() into a rusttypes.result.Result type. Should be used when safe parsing is required.

Note

Will only catch parasite.errors.ValidationError exceptions!!!

Parameters:

obj (Any) – value to parse

Returns:

parsed destination value or an error

Return type:

Result[T, ValidationError]