`parasite.variant`¶

Brief¶

Reference for the variant submodule of the parasite package. This submodule contains the Variant class, which is a generic container for a union of various Python objects.

Usage¶

from parasite import p

schema = p.variant([
   p.string(),
   p.number().integer(),
])

schema.parse("42")  # -> "42"
schema.parse(42)  # -> 42
...

Member Reference¶

class parasite.variant.K¶

Template type for the key in a dictionary.

alias of TypeVar(‘K’)

class parasite.variant.Variant(variants: Iterable[ParasiteType] | None = None)[source]¶

parasite type for representing variant values. The value can be one of the variants specified in the constructor or added through the add_item() function. The value is parsed by trying to parse it with each variant in the order they are added. If none of the variants can parse the value, a ValidationError is raised.

Inheritance:

Parameters:: variants (Iterable[ParasiteType], optional) – The variants of the variant. Default: [].

Example usage:

You can create a variant schema by passing the variants as a list to the constructor. The variants can be any of the parasite types. The following example shows how to create a variant schema with a string and an integer variant:

from parasite import p

schema = p.variant([
    p.string(),
    p.number().integer(),
])

schema2 = p.variant()

The resulting schemas will parse the following objects:

>>> schema.parse("42")
"42"
>>> schema.parse(42)
42

>>> schema2.parse("42")
ValidationError: object has to be one of [], but is "42"

optional() → Variant[source]¶

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:: Variant

Example usage:

Lets assume we have the following schemas:

from parasite import p

schema = p.obj({
    "sub": p.variant([
        p.string(),
        p.number().integer(),
    ]).optional()
})

schema2 = p.obj({
    "sub": p.variant([
        p.string(),
        p.number().integer(),
    ])
})

The resulting schemas will parse the following objects:

>>> schema.parse({ "sub": "42" })
{ "sub": "42" }
>>> schema.parse({ })
{ }

>>> schema2.parse({ "sub": 42 })
{ "sub": 42 }
>>> schema2.parse({ })
ValidationError: key "sub" not found, but is required

required() → Variant[source]¶

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:: Variant

Example usage:

Lets assume we have the following schemas:

from parasite import p

schema = p.obj({
    "sub": p.variant([
        p.string(),
        p.number().integer(),
    ]).optional().required()
})

schema2 = p.obj({
    "sub": p.variant([
        p.string(),
        p.number().integer(),
    ])
})

The resulting schemas will parse the following objects:

>>> schema.parse({ "sub": "42" })
{ "sub": "42" }
>>> schema.parse({ })
ValidationError: key "sub" not found, but is required

>>> schema2.parse({ "sub": 42 })
{ "sub": 42 }
>>> schema2.parse({ })
ValidationError: key "sub" not found, but is required

nullable() → Variant[source]¶

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:: Variant

Example usage:

Lets assume we have the following schemas:

from parasite import p

schema = p.obj({
    "sub": p.variant([
        p.string(),
        p.number().integer(),
    ]).nullable()
})

schema2 = p.obj({
    "sub": p.variant([
        p.string(),
        p.number().integer(),
    ])
})

The resulting schemas will parse the following objects:

>>> schema.parse({ "sub": "42" })
{ "sub": "42" }
>>> schema.parse({ "sub": None })
{ "sub": None }

>>> schema2.parse({ "sub": 42 })
{ "sub": 42 }
>>> schema2.parse({ "sub": None })
ValidationError: object has to be a dictionary, but is 'None'

not_nullable() → Variant[source]¶

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:: Variant

Example usage:

Lets assume we have the following schemas:

from parasite import p

schema = p.obj({
    "sub": p.variant([
        p.string(),
        p.number().integer(),
    ]).nullable().not_nullable()
})

schema2 = p.obj({
    "sub": p.variant([
        p.string(),
        p.number().integer(),
    ])
})

The resulting schemas will parse the following objects:

>>> schema.parse({ "sub": "42" })
{ "sub": "42" }
>>> schema.parse({ "sub": None })
ValidationError: key "sub" cannot be None

>>> schema2.parse({ "sub": 42 })
{ "sub": 42 }
>>> schema2.parse({ "sub": None })
ValidationError: key "sub" not found, but is required

add_variant(variant: ParasiteType) → Variant[source]¶

Add a variant to the variant.

Note

The order of the variants is important, as the value is parsed by trying to parse it with each variant in the order they are added. The first variant that can parse the value is used.

Parameters:: variant (ParasiteType) – The variant to add.
Returns:: The updated instance of the class.
Return type:: Variant

Example usage:

You can add a variant to the variant by calling the add_variant() function. The following example shows how to add a string variant to a variant schema:

from parasite import p

schema = p.variant()
schema.add_variant(p.string())

The resulting schema will parse the following objects:

>>> schema.parse("42")
"42"

>>> schema.parse(42)
ValidationError: object has to be one of [String(...)], but is 42

rm_variant(variant: ParasiteType) → Variant[source]¶

Remove a variant from the variant.

Warning

The variant is removed by reference, so the variant has to be the same instance as the one added to the variant. Equivalent ro the list.remove function.

Throws:: ValueError: If the variant is not found in the variant.

Parameters:: variant (ParasiteType) – The variant to remove.
Returns:: The updated instance of the class.
Return type:: Variant

Example usage:

You can remove a variant from the variant by calling the rm_variant() function. The following example shows how to remove a string variant from a variant schema:

from parasite import p

schema = p.variant([
    p.string(),
    p.number().integer(),
])
schema.rm_variant(p.string())

The resulting schema will parse the following objects:

>>> schema.parse(42)
42

>>> schema.parse("42")
ValidationError: object has to be one of [Number(...)], but is '42'

rm_variant_safe(variant: ParasiteType) → Result[Variant, ValueError][source]¶

Remove a variant from the variant.

Warning

The variant is removed by reference, so the variant has to be the same instance as the one added to the variant. Equivalent ro the list.remove function.

Parameters:: variant (ParasiteType) – The variant to remove.
Returns:: The updated instance of the class or an error
Return type:: Result[Variant, ValueError]

Example usage:

You can remove a variant from the variant by calling the rm_variant_safe() function. The following example shows how to remove a string variant from a variant schema:

from parasite import p

schema = (
    p.variant([
        p.string(),
        p.number().integer(),
    ])
    .rm_variant_safe(p.string())
    .expect("Variant not found")
)

The resulting schema will parse the following objects:

>>> schema.parse(42)
42

>>> schema.parse("42")
ValidationError: object has to be one of [Number(...)], but is '42'

If the variant is not found, an error is returned:

>>> schema.rm_variant_safe(p.string())
Err(ValueError: "Variant String(...) not found in Variant(...)")

parse(obj: Any) → Any[source]¶

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]

parasite.variant¶

Brief¶

Usage¶

Member Reference¶

`parasite.variant`¶