betty.serde.load module - Betty 0.4.0a1 documentation

Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# betty.serde.load module

Provide a deserialization API.

class betty.serde.load.AssertionChain

  Bases: `Generic`[`_AssertionValueT`, `_AssertionReturnT`]

  An assertion chain.

  Assertion chains let you chain/link/combine assertions into pipelines that take an input value and, if the assertions pass, return an output value. Each chain may be (re)used as many times as needed.

  Assertion chains are assertions themselves: you can use a chain wherever you can use a ‘plain’ assertion.

  Assertions chains are monads. While uncommon in Python, this allows us to create these chains in a type-safe way, and tools like mypy can confirm that all assertions in any given chain are compatible with each other.

  Parameters:

    _assertion (`typing.Callable`[[`typing.TypeVar`(`_AssertionValueT`)], `typing.TypeVar`(`_AssertionReturnT`)])

  __init__(_assertion: Callable[[betty.serde.load._AssertionValueT], betty.serde.load._AssertionReturnT])
    Parameters:

      _assertion (`typing.Callable`[[`typing.TypeVar`(`_AssertionValueT`)], `typing.TypeVar`(`_AssertionReturnT`)])

  chain(assertion: Callable[[betty.serde.load._AssertionReturnT], betty.serde.load._AssertionsExtendReturnT]) → betty.serde.load.AssertionChain[betty.serde.load._AssertionValueT, betty.serde.load._AssertionsExtendReturnT]

    Extend the chain with the given assertion.

    Parameters:

      assertion (`typing.Callable`[[`typing.TypeVar`(`_AssertionReturnT`)], `typing.TypeVar`(`_AssertionsExtendReturnT`)])

    Return type:

      `betty.serde.load.AssertionChain`[`typing.TypeVar`(`_AssertionValueT`), `typing.TypeVar`(`_AssertionsExtendReturnT`)]

exception betty.serde.load.AssertionFailed

  Bases: `LoadError`

  Raised when an assertion failed while deserializing data.

  Parameters:

    message (`betty.locale.Localizable`)

exception betty.serde.load.FormatError

  Bases: `LoadError`

  Raised when data that is being deserialized is provided in an unknown (undeserializable) format.

  Parameters:

    message (`betty.locale.Localizable`)

exception betty.serde.load.LoadError

  Bases: `SerdeError`

  Raised for any error while deserializing data.

  Parameters:

    message (`betty.locale.Localizable`)

class betty.serde.load.OptionalField

  Bases: `Generic`[`_AssertionValueT`, `_AssertionReturnT`], `_Field`[`_AssertionValueT`, `_AssertionReturnT`]

  An optional key-value mapping field.

  Parameters:

    - name (`str`)

    - assertion (`typing.Optional`[`typing.Callable`[[`typing.TypeVar`(`_AssertionValueT`)], `typing.TypeVar`(`_AssertionReturnT`)]])

  __init__(name: str, assertion: Callable[[betty.serde.load._AssertionValueT], betty.serde.load._AssertionReturnT] | None = None) → None
    Parameters:

      - name (`str`)

      - assertion (`typing.Optional`[`typing.Callable`[[`typing.TypeVar`(`_AssertionValueT`)], `typing.TypeVar`(`_AssertionReturnT`)]])

class betty.serde.load.RequiredField

  Bases: `Generic`[`_AssertionValueT`, `_AssertionReturnT`], `_Field`[`_AssertionValueT`, `_AssertionReturnT`]

  A required key-value mapping field.

  Parameters:

    - name (`str`)

    - assertion (`typing.Optional`[`typing.Callable`[[`typing.TypeVar`(`_AssertionValueT`)], `typing.TypeVar`(`_AssertionReturnT`)]])

  __init__(name: str, assertion: Callable[[betty.serde.load._AssertionValueT], betty.serde.load._AssertionReturnT] | None = None) → None
    Parameters:

      - name (`str`)

      - assertion (`typing.Optional`[`typing.Callable`[[`typing.TypeVar`(`_AssertionValueT`)], `typing.TypeVar`(`_AssertionReturnT`)]])

betty.serde.load.assert_bool() → betty.serde.load.AssertionChain[Any, bool]

  Assert that a value is a Python `bool`.

  Return type:

    `betty.serde.load.AssertionChain`[`typing.Any`, `bool`]

betty.serde.load.assert_dict() → betty.serde.load.AssertionChain[Any, dict[str, Any]]

  Assert that a value is a Python `dict`.

  Return type:

    `betty.serde.load.AssertionChain`[`typing.Any`, `dict`[`str`, `typing.Any`]]

betty.serde.load.assert_directory_path() → betty.serde.load.AssertionChain[Any, pathlib.Path]

  Assert that a value is a path to an existing directory.

  Return type:

    `betty.serde.load.AssertionChain`[`typing.Any`, `pathlib.Path`]

betty.serde.load.assert_entity_type() → betty.serde.load.AssertionChain[Any, type[betty.model.Entity]]

  Assert that a value is an entity type.

  This assertion passes if the value is fully qualified `betty.model.Entity` subclass name.

  Return type:

    `betty.serde.load.AssertionChain`[`typing.Any`, `type`[`betty.model.Entity`]]

betty.serde.load.assert_extension_type() → betty.serde.load.AssertionChain[Any, type[betty.app.extension.Extension]]

  Assert that a value is an extension type.

  This assertion passes if the value is fully qualified `betty.app.extension.Extension` subclass name.

  Return type:

    `betty.serde.load.AssertionChain`[`typing.Any`, `type`[`betty.app.extension.Extension`]]

betty.serde.load.assert_field(field: betty.serde.load._Field[betty.serde.load._AssertionValueT, betty.serde.load._AssertionReturnT]) → betty.serde.load.AssertionChain[betty.serde.load._AssertionValueT, betty.serde.load._AssertionReturnT] | betty.serde.load.AssertionChain[betty.serde.load._AssertionValueT, betty.serde.load._AssertionReturnT | type[betty.serde.dump.Void]]

  Assert that a value is a key-value mapping of arbitrary value types, and assert a single of its values.

  Parameters:

    field (`betty.serde.load._Field`[`typing.TypeVar`(`_AssertionValueT`), `typing.TypeVar`(`_AssertionReturnT`)])

  Return type:

    `typing.Union`[`betty.serde.load.AssertionChain`[`typing.TypeVar`(`_AssertionValueT`), `typing.TypeVar`(`_AssertionReturnT`)], `betty.serde.load.AssertionChain`[`typing.TypeVar`(`_AssertionValueT`), `typing.Union`[`typing.TypeVar`(`_AssertionReturnT`), `type`[`betty.serde.dump.Void`]]]]

betty.serde.load.assert_fields(*fields: betty.serde.load._Field[Any, Any]) → betty.serde.load.AssertionChain[Any, MutableMapping[str, Any]]

  Assert that a value is a key-value mapping of arbitrary value types, and assert several of its values.

  Parameters:

    fields (`betty.serde.load._Field`[`typing.Any`, `typing.Any`])

  Return type:

    `betty.serde.load.AssertionChain`[`typing.Any`, `typing.MutableMapping`[`str`, `typing.Any`]]

betty.serde.load.assert_float() → betty.serde.load.AssertionChain[Any, float]

  Assert that a value is a Python `float`.

  Return type:

    `betty.serde.load.AssertionChain`[`typing.Any`, `float`]

betty.serde.load.assert_int() → betty.serde.load.AssertionChain[Any, int]

  Assert that a value is a Python `int`.

  Return type:

    `betty.serde.load.AssertionChain`[`typing.Any`, `int`]

betty.serde.load.assert_list() → betty.serde.load.AssertionChain[Any, list[Any]]

  Assert that a value is a Python `list`.

  Return type:

    `betty.serde.load.AssertionChain`[`typing.Any`, `list`[`typing.Any`]]

betty.serde.load.assert_locale() → betty.serde.load.AssertionChain[Any, str]

  Assert that a value is a valid IETF BCP 47 language tag.

  Return type:

    `betty.serde.load.AssertionChain`[`typing.Any`, `str`]

betty.serde.load.assert_mapping(item_assertion: Callable[[Any], betty.serde.load._AssertionReturnT]) → betty.serde.load.AssertionChain[Any, MutableMapping[str, betty.serde.load._AssertionReturnT]]

  Assert that a value is a key-value mapping and assert that all item values are of the given type.

  Parameters:

    item_assertion (`typing.Callable`[[`typing.Any`], `typing.TypeVar`(`_AssertionReturnT`)])

  Return type:

    `betty.serde.load.AssertionChain`[`typing.Any`, `typing.MutableMapping`[`str`, `typing.TypeVar`(`_AssertionReturnT`)]]

betty.serde.load.assert_none() → betty.serde.load.AssertionChain[Any, None]

  Assert that a value is `None`.

  Return type:

    `betty.serde.load.AssertionChain`[`typing.Any`, `None`]

betty.serde.load.assert_number() → betty.serde.load.AssertionChain[Any, int | float]

  Assert that a value is a number (a Python `int` or `float`).

  Return type:

    `betty.serde.load.AssertionChain`[`typing.Any`, `int` | `float`]

betty.serde.load.assert_or(if_assertion: Callable[[betty.serde.load._AssertionValueT], betty.serde.load._AssertionReturnT], else_assertion: Callable[[betty.serde.load._AssertionValueT], betty.serde.load._AssertionReturnU]) → betty.serde.load.AssertionChain[betty.serde.load._AssertionValueT, betty.serde.load._AssertionReturnT | betty.serde.load._AssertionReturnU]

  Assert that at least one of the given assertions passed.

  Parameters:

    - if_assertion (`typing.Callable`[[`typing.TypeVar`(`_AssertionValueT`)], `typing.TypeVar`(`_AssertionReturnT`)])

    - else_assertion (`typing.Callable`[[`typing.TypeVar`(`_AssertionValueT`)], `typing.TypeVar`(`_AssertionReturnU`)])

  Return type:

    `betty.serde.load.AssertionChain`[`typing.TypeVar`(`_AssertionValueT`), `typing.Union`[`typing.TypeVar`(`_AssertionReturnT`), `typing.TypeVar`(`_AssertionReturnU`)]]

betty.serde.load.assert_path() → betty.serde.load.AssertionChain[Any, pathlib.Path]

  Assert that a value is a path to a file or directory on disk that may or may not exist.

  Return type:

    `betty.serde.load.AssertionChain`[`typing.Any`, `pathlib.Path`]

betty.serde.load.assert_positive_number() → betty.serde.load.AssertionChain[Any, int | float]

  Assert that a vaue is a positive nu,ber.

  Return type:

    `betty.serde.load.AssertionChain`[`typing.Any`, `int` | `float`]

betty.serde.load.assert_record(*fields: betty.serde.load._Field[Any, Any]) → betty.serde.load.AssertionChain[Any, MutableMapping[str, Any]]

  Assert that a value is a record: a key-value mapping of arbitrary value types, with a known structure.

  To validate a key-value mapping as a records, assertions for all possible keys MUST be provided. Any keys present in the value for which no field assertions are provided will cause the entire record assertion to fail.

  Parameters:

    fields (`betty.serde.load._Field`[`typing.Any`, `typing.Any`])

  Return type:

    `betty.serde.load.AssertionChain`[`typing.Any`, `typing.MutableMapping`[`str`, `typing.Any`]]

betty.serde.load.assert_sequence(item_assertion: Callable[[Any], betty.serde.load._AssertionReturnT]) → betty.serde.load.AssertionChain[Any, MutableSequence[betty.serde.load._AssertionReturnT]]

  Assert that a value is a sequence and that all item values are of the given type.

  Parameters:

    item_assertion (`typing.Callable`[[`typing.Any`], `typing.TypeVar`(`_AssertionReturnT`)])

  Return type:

    `betty.serde.load.AssertionChain`[`typing.Any`, `typing.MutableSequence`[`typing.TypeVar`(`_AssertionReturnT`)]]

betty.serde.load.assert_setattr(instance: object, attr_name: str) → betty.serde.load.AssertionChain[Any, Any]

  Set a value for the given object’s attribute.

  Parameters:

    - instance (`object`)

    - attr_name (`str`)

  Return type:

    `betty.serde.load.AssertionChain`[`typing.Any`, `typing.Any`]

betty.serde.load.assert_str() → betty.serde.load.AssertionChain[Any, str]

  Assert that a value is a Python `str`.

  Return type:

    `betty.serde.load.AssertionChain`[`typing.Any`, `str`]