betty.app.extension 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.app.extension package

## Submodules

- betty.app.extension.requirement module
  - `AllRequirements`
    - `AllRequirements.__init__()`
    - `AllRequirements.is_met()`
    - `AllRequirements.summary()`
  - `AnyRequirement`
    - `AnyRequirement.__init__()`
    - `AnyRequirement.is_met()`
    - `AnyRequirement.summary()`
  - `Requirement`
    - `Requirement.assert_met()`
    - `Requirement.details()`
    - `Requirement.is_met()`
    - `Requirement.localize()`
    - `Requirement.reduce()`
    - `Requirement.summary()`
  - `RequirementCollection`
    - `RequirementCollection.__init__()`
    - `RequirementCollection.localize()`
    - `RequirementCollection.reduce()`
  - `RequirementError`
    - `RequirementError.__init__()`
    - `RequirementError.requirement()`

## Module contents

Provide Betty’s extension API.

class betty.app.extension.ConfigurableExtension

  Bases: `Extension`, `Generic`[`ConfigurationT`], `Configurable`[`ConfigurationT`]

  A configurable extension.

  Parameters:

    - args (`typing.Any`)

    - configuration (`typing.Optional`[`typing.TypeVar`(`ConfigurationT`, bound= `betty.config.Configuration`)])

    - kwargs (`typing.Any`)

  __init__(*args: Any, configuration: betty.config.ConfigurationT | None = None, **kwargs: Any)
    Parameters:

      - args (`typing.Any`)

      - configuration (`typing.Optional`[`typing.TypeVar`(`ConfigurationT`, bound= `betty.config.Configuration`)])

      - kwargs (`typing.Any`)

  classmethod default_configuration() → betty.config.ConfigurationT

    Get this extension’s default configuration.

    Return type:

      `typing.TypeVar`(`ConfigurationT`, bound= `betty.config.Configuration`)

exception betty.app.extension.CyclicDependencyError

  Bases: `ExtensionError`, `RuntimeError`

  Raised when extensions define a cyclic dependency, e.g. two extensions depend on each other.

  Parameters:

    extension_types (`typing.Iterable`[`type`[`betty.app.extension.Extension`]])

  __init__(extension_types: Iterable[type[betty.app.extension.Extension]])
    Parameters:

      extension_types (`typing.Iterable`[`type`[`betty.app.extension.Extension`]])

class betty.app.extension.Dependencies

  Bases: `AllRequirements`

  Check a dependent’s dependency requirements.

  Parameters:

    dependent_type (`type`[`betty.app.extension.Extension`])

  __init__(dependent_type: type[betty.app.extension.Extension])
    Parameters:

      dependent_type (`type`[`betty.app.extension.Extension`])

  classmethod for_dependent(dependent_type: type[betty.app.extension.Extension]) → Self

    Create a new requirement for the given dependent.

    Parameters:

      dependent_type (`type`[`betty.app.extension.Extension`])

    Return type:

      `typing.Self`

  summary() → betty.locale.Str

    Get the requirement’s human-readable summary.

    Return type:

      `betty.locale.Str`

class betty.app.extension.Dependents

  Bases: `Requirement`

  Check a dependency’s dependent requirements.

  Parameters:

    - dependency (`betty.app.extension.Extension`)

    - dependents (`typing.Sequence`[`betty.app.extension.Extension`])

  __init__(dependency: betty.app.extension.Extension, dependents: Sequence[betty.app.extension.Extension])
    Parameters:

      - dependency (`betty.app.extension.Extension`)

      - dependents (`typing.Sequence`[`betty.app.extension.Extension`])

  classmethod for_dependency(dependency: betty.app.extension.Extension) → Self

    Create a new requirement for the given dependency.

    Parameters:

      dependency (`betty.app.extension.Extension`)

    Return type:

      `typing.Self`

  is_met() → bool

    Check if the requirement is met.

    Return type:

      `bool`

  summary() → betty.locale.Str

    Get the requirement’s human-readable summary.

    Return type:

      `betty.locale.Str`

class betty.app.extension.Extension

  Bases: `object`

  Integrate optional functionality with the Betty app.

  Parameters:

    - app (`betty.app.App`)

    - args (`typing.Any`)

    - kwargs (`typing.Any`)

  __init__(app: betty.app.App, *args: Any, **kwargs: Any)
    Parameters:

      - app (`betty.app.App`)

      - args (`typing.Any`)

      - kwargs (`typing.Any`)

  property app: App

    The Betty application the extension runs within.

  classmethod assets_directory_path() → pathlib.Path | None

    Return the path on disk where the extension’s assets are located.

    This may be anywhere in your Python package.

    Return type:

      `pathlib.Path` | `None`

  classmethod comes_after() → set[type[betty.app.extension.Extension]]

    The extensions that this one comes after.

    The other extensions may or may not be enabled.

    Return type:

      `set`[`type`[`betty.app.extension.Extension`]]

  classmethod comes_before() → set[type[betty.app.extension.Extension]]

    The extensions that this one comes before.

    The other extensions may or may not be enabled.

    Return type:

      `set`[`type`[`betty.app.extension.Extension`]]

  classmethod depends_on() → set[type[betty.app.extension.Extension]]

    The extensions this one depends on, and comes after.

    Return type:

      `set`[`type`[`betty.app.extension.Extension`]]

  disable_requirement() → betty.requirement.Requirement

    Define the requirement for this extension to be disabled.

    This defaults to the extension’s dependents.

    Return type:

      `betty.requirement.Requirement`

  classmethod enable_requirement() → betty.requirement.Requirement

    Define the requirement for this extension to be enabled.

    This defaults to the extension’s dependencies.

    Return type:

      `betty.requirement.Requirement`

  classmethod name() → str

    The machine name.

    Return type:

      `str`

class betty.app.extension.ExtensionDispatcher

  Bases: `Dispatcher`

  Dispatch events to extensions.

  Parameters:

    extensions (`betty.app.extension.Extensions`)

  __init__(extensions: betty.app.extension.Extensions)
    Parameters:

      extensions (`betty.app.extension.Extensions`)

  dispatch(target_type: type[Any]) → Callable[[...], Awaitable[Sequence[Any]]]

    Dispatch a single target.

    Parameters:

      target_type (`type`[`typing.Any`])

    Return type:

      `typing.Callable`[`...`, `typing.Awaitable`[`typing.Sequence`[`typing.Any`]]]

exception betty.app.extension.ExtensionError

  Bases: `BaseException`

  A generic extension API error.

exception betty.app.extension.ExtensionTypeError

  Bases: `ExtensionError`, `ValueError`

  A generic error regarding an extension type.

exception betty.app.extension.ExtensionTypeImportError

  Bases: `ExtensionTypeError`, `ImportError`

  Raised when an alleged extension type cannot be imported.

  Parameters:

    extension_type_name (`str`)

  __init__(extension_type_name: str)
    Parameters:

      extension_type_name (`str`)

exception betty.app.extension.ExtensionTypeInvalidError

  Bases: `ExtensionTypeError`, `ImportError`

  Raised for types that are not valid extension types.

  Parameters:

    extension_type (`type`)

  __init__(extension_type: type)
    Parameters:

      extension_type (`type`)

class betty.app.extension.Extensions

  Bases: `object`

  Manage available extensions.

  flatten() → Iterator[betty.app.extension.Extension]

    Get a sequence of topologically sorted extensions.

    Return type:

      `typing.Iterator`[`betty.app.extension.Extension`]

class betty.app.extension.ListExtensions

  Bases: `Extensions`

  Manage available extensions, backed by a list.

  Parameters:

    extensions (`list`[`list`[`betty.app.extension.Extension`]])

  __init__(extensions: list[list[betty.app.extension.Extension]])
    Parameters:

      extensions (`list`[`list`[`betty.app.extension.Extension`]])

  flatten() → Iterator[betty.app.extension.Extension]

    Get a sequence of topologically sorted extensions.

    Return type:

      `typing.Iterator`[`betty.app.extension.Extension`]

class betty.app.extension.Theme

  Bases: `UserFacingExtension`

  An extension that is a front-end theme.

  Parameters:

    - app (`betty.app.App`)

    - args (`typing.Any`)

    - kwargs (`typing.Any`)

class betty.app.extension.UserFacingExtension

  Bases: `Extension`

  A sentinel to mark an extension as being visible to users (e.g. not internal).

  Parameters:

    - app (`betty.app.App`)

    - args (`typing.Any`)

    - kwargs (`typing.Any`)

  classmethod description() → betty.locale.Str

    Get the human-readable extension description.

    Return type:

      `betty.locale.Str`

  classmethod label() → betty.locale.Str

    Get the human-readable extension label.

    Return type:

      `betty.locale.Str`

betty.app.extension.build_extension_type_graph(extension_types: Iterable[type[betty.app.extension.Extension]]) → dict[type[betty.app.extension.Extension], set[type[betty.app.extension.Extension]]]

  Build a dependency graph of the given extension types.

  Parameters:

    extension_types (`typing.Iterable`[`type`[`betty.app.extension.Extension`]])

  Return type:

    `dict`[`type`[`betty.app.extension.Extension`], `set`[`type`[`betty.app.extension.Extension`]]]

betty.app.extension.discover_extension_types() → set[type[betty.app.extension.Extension]]

  Gather the available extension types.

  Return type:

    `set`[`type`[`betty.app.extension.Extension`]]

betty.app.extension.format_extension_type(extension_type: type[betty.app.extension.Extension]) → betty.locale.Str

  Format an extension type to a human-readable label.

  Parameters:

    extension_type (`type`[`betty.app.extension.Extension`])

  Return type:

    `betty.locale.Str`

betty.app.extension.get_extension_type(extension_type_definition: str | type[betty.app.extension.Extension] | betty.app.extension.Extension) → type[betty.app.extension.Extension]

  Get the extension type for an extension, extension type, or extension type name.

  Parameters:

    extension_type_definition (`str` | `type`[`betty.app.extension.Extension`] | `betty.app.extension.Extension`)

  Return type:

    `type`[`betty.app.extension.Extension`]

betty.app.extension.get_extension_type_by_extension(extension: betty.app.extension.Extension) → type[betty.app.extension.Extension]

  Get the extension type for an extension.

  Parameters:

    extension (`betty.app.extension.Extension`)

  Return type:

    `type`[`betty.app.extension.Extension`]

betty.app.extension.get_extension_type_by_name(extension_type_name: str) → type[betty.app.extension.Extension]

  Get the extension type for an extension type name.

  Parameters:

    extension_type_name (`str`)

  Return type:

    `type`[`betty.app.extension.Extension`]

betty.app.extension.get_extension_type_by_type(extension_type: type) → type[betty.app.extension.Extension]

  Get the extension type for an extension type.

  Parameters:

    extension_type (`type`)

  Return type:

    `type`[`betty.app.extension.Extension`]