betty.assertion package - Betty documentation

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

# betty.assertion package

## Submodules

- betty.assertion.error module
  - `AssertionContext`
    - `AssertionContext.format()`
  - `AssertionFailed`
    - `AssertionFailed.__init__()`
    - `AssertionFailed.contexts`
    - `AssertionFailed.localize()`
    - `AssertionFailed.raised()`
    - `AssertionFailed.with_context()`
  - `AssertionFailedGroup`
    - `AssertionFailedGroup.__init__()`
    - `AssertionFailedGroup.append()`
    - `AssertionFailedGroup.assert_valid()`
    - `AssertionFailedGroup.catch()`
    - `AssertionFailedGroup.invalid`
    - `AssertionFailedGroup.localize()`
    - `AssertionFailedGroup.raised()`
    - `AssertionFailedGroup.valid`
    - `AssertionFailedGroup.with_context()`
  - `Attr`
    - `Attr.__init__()`
    - `Attr.format()`
  - `Index`
    - `Index.__init__()`
    - `Index.format()`
  - `Key`
    - `Key.__init__()`
    - `Key.format()`
  - `localizable_contexts()`

## Module contents

The Assertion API.

class betty.assertion.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.

  __init__(_assertion: Callable[[_AssertionValueT], _AssertionReturnT])
  chain(assertion: Callable[[_AssertionReturnT], _AssertionsExtendReturnT]) → AssertionChain[_AssertionValueT, _AssertionsExtendReturnT]

    Extend the chain with the given assertion.

class betty.assertion.Field

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

  A key-value mapping field.

  Do not instantiate this class directly. Use `betty.assertion.RequiredField` or `betty.assertion.OptionalField` instead.

  This is internal. It MAY be used anywhere in Betty’s source code, but MUST NOT be used by third-party code.

  __init__(name: str, assertion: Callable[[_AssertionValueT], _AssertionReturnT] | None = None) → None
  assertion: Callable[[_AssertionValueT], _AssertionReturnT] | None = None
  name: str

final class betty.assertion.OptionalField

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

  An optional key-value mapping field.

  __init__(name: str, assertion: Callable[[_AssertionValueT], _AssertionReturnT] | None = None) → None

final class betty.assertion.RequiredField

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

  A required key-value mapping field.

  __init__(name: str, assertion: Callable[[_AssertionValueT], _AssertionReturnT] | None = None) → None

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

  Assert that a value is a Python `bool`.

betty.assertion.assert_directory_path() → AssertionChain[Any, Path]

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

betty.assertion.assert_field(field: RequiredField[_AssertionValueT, _AssertionReturnT]) → AssertionChain[_AssertionValueT, _AssertionReturnT]
betty.assertion.assert_field(field: OptionalField[_AssertionValueT, _AssertionReturnT]) → AssertionChain[_AssertionValueT, _AssertionReturnT | type[Void]]

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

betty.assertion.assert_fields(*fields: Field[Any, Any]) → AssertionChain[Any, MutableMapping[str, Any]]

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

betty.assertion.assert_file_path() → AssertionChain[Any, Path]

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

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

  Assert that a value is a Python `float`.

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

  Assert that a value is a Python `int`.

betty.assertion.assert_isinstance(alleged_type: type[_AssertionValueT]) → Callable[[Any], _AssertionValueT]

  Assert that a value is an instance of the given type.

  This assertion is NOT optimized to be user-facing (it is untranslated) because Python types are not user-facing.

betty.assertion.assert_len(exact: int) → AssertionChain[Sized, Sized]
betty.assertion.assert_len(*, minimum: int | None, maximum: int | None = None) → AssertionChain[Sized, Sized]
betty.assertion.assert_len(*, minimum: int | None = None, maximum: int | None) → AssertionChain[Sized, Sized]

  Assert the length of a value.

  This assertion can be used in two ways: - with an exact required length - with minimum and/or maximum bounds (inclusive)

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

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

betty.assertion.assert_locale_identifier() → AssertionChain[Any, str]

  Assert that a value could be a valid IETF BCP 47 language tag.

betty.assertion.assert_mapping(value_assertion: None = None, key_assertion: None = None, /) → AssertionChain[Any, MutableMapping[Any, Any]]
betty.assertion.assert_mapping(value_assertion: Callable[[Any], _AssertionReturnT], key_assertion: None = None, /) → AssertionChain[Any, MutableMapping[Any, _AssertionReturnT]]
betty.assertion.assert_mapping(value_assertion: None, key_assertion: Callable[[Any], _AssertionKeyT], /) → AssertionChain[Any, MutableMapping[_AssertionKeyT, Any]]
betty.assertion.assert_mapping(value_assertion: Callable[[Any], _AssertionReturnT], key_assertion: Callable[[Any], _AssertionKeyT], /) → AssertionChain[Any, MutableMapping[_AssertionKeyT, _AssertionReturnT]]

  Assert that a value is a key-value mapping.

  Optionally assert that keys and/or values are of a given type.

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

  Assert that a value is `None`.

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

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

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

  Assert that at least one of the given assertions passed.

betty.assertion.assert_path() → AssertionChain[Any, Path]

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

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

  Assert that a vaue is a positive nu,ber.

betty.assertion.assert_record(*fields: Field[Any, Any]) → 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.

betty.assertion.assert_sequence(value_assertion: None = None, /) → AssertionChain[Any, MutableSequence[Any]]
betty.assertion.assert_sequence(value_assertion: Callable[[Any], _AssertionReturnT], /) → AssertionChain[Any, MutableSequence[_AssertionReturnT]]

  Assert that a value is a sequence.

  Optionally assert that values are of a given type.

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

  Set a value for the given object’s attribute.

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

  Assert that a value is a Python `str`.