betty.plugin package

Submodules

• betty.plugin.assertion module
  • assert_plugin()
• betty.plugin.config module
  • PluginConfiguration
    • PluginConfiguration.__init__()
    • PluginConfiguration.description
    • PluginConfiguration.dump()
    • PluginConfiguration.id
    • PluginConfiguration.label
    • PluginConfiguration.load()
  • PluginConfigurationMapping
    • PluginConfigurationMapping.new_plugins()
  • PluginConfigurationPluginConfigurationMapping
  • PluginIdentifierKeyConfigurationMapping
  • PluginInstanceConfiguration
    • PluginInstanceConfiguration.__init__()
    • PluginInstanceConfiguration.configuration
    • PluginInstanceConfiguration.dump()
    • PluginInstanceConfiguration.id
    • PluginInstanceConfiguration.load()
    • PluginInstanceConfiguration.new_plugin_instance()
  • PluginInstanceConfigurationMapping
    • PluginInstanceConfigurationMapping.__init__()
• betty.plugin.entry_point module
  • EntryPointPluginRepository
    • EntryPointPluginRepository.__init__()
• betty.plugin.lazy module
  • LazyPluginRepositoryBase
    • LazyPluginRepositoryBase.__init__()
    • LazyPluginRepositoryBase.get()
• betty.plugin.proxy module
  • ProxyPluginRepository
    • ProxyPluginRepository.__init__()
    • ProxyPluginRepository.get()
    • ProxyPluginRepository.new_target()
• betty.plugin.static module
  • StaticPluginRepository
    • StaticPluginRepository.__init__()
    • StaticPluginRepository.get()

Module contents

The Plugin API.

Plugins allow third-party code (e.g. your own Python package) to add functionality to Betty.

Read more at Plugins.

exception betty.plugin.CyclicDependencyError

Bases: PluginError

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

__init__(plugin_types: Iterable[type[Plugin]])

class betty.plugin.DependentPlugin

Bases: Generic[_PluginT], Plugin

A plugin that can declare its dependency on other plugins.

classmethod depends_on() → set[type[_PluginT] | str]

The plugins this one depends on.

class betty.plugin.OrderedPlugin

Bases: Generic[_PluginT], Plugin

A plugin that can declare its order with respect to other plugins.

classmethod comes_after() → set[type[_PluginT] | str]

Get the plugins that this plugin comes after.

The returned plugins come before this plugin.

classmethod comes_before() → set[type[_PluginT] | str]

Get the plugins that this plugin comes before.

The returned plugins come after this plugin.

class betty.plugin.Plugin

Bases: ABC

A plugin.

Plugins are identified by their IDs as well as their types. Each must be able to uniquely identify the plugin within a plugin repository.

To test your own subclasses, use betty.test_utils.plugin.PluginTestBase.

classmethod plugin_description() → Localizable | None

Get the human-readable long plugin description.

abstract classmethod plugin_id() → str

Get the plugin ID.

IDs are unique per plugin type:

• A plugin repository MUST at most have a single plugin for any ID.

• Different plugin repositories MAY each have a plugin with the same ID.

abstract classmethod plugin_label() → Localizable

Get the human-readable short plugin label.

exception betty.plugin.PluginError

Bases: Exception

Any error originating from the Plugin API.

class betty.plugin.PluginIdToTypeMapping

Bases: Generic[_PluginT]

Map plugin IDs to their types.

__init__(id_to_type_mapping: Mapping[MachineName, type[_PluginT]])

get(plugin_identifier: str | type[_PluginT]) → type[_PluginT]

Get the type for the given plugin identifier.

async classmethod new(plugins: PluginRepository[_PluginT]) → Self

Create a new instance.

exception betty.plugin.PluginNotFound

Bases: PluginError, UserFacingError

Raised when a plugin cannot be found.

classmethod new(plugin_id: MachineName, available_plugins: Sequence[type[Plugin]]) → Self

Create a new instance.

class betty.plugin.PluginRepository

Bases: Generic[_PluginT], TargetFactory, ABC

Discover and manage plugins.

__init__(*, factory: Factory | None = None)

abstract async get(plugin_id: str) → type[_PluginT]

Get a single plugin by its ID.

Raises:

PluginNotFound – if no plugin can be found for the given ID.

async mapping() → PluginIdToTypeMapping[_PluginT]

Get the plugin ID to type mapping.

async new_target(cls: type[_T]) → _T

async new_target(cls: str) → _PluginT

Create a new instance.

Raises:

FactoryError – raised when cls could not be instantiated.

async resolve_identifier(plugin_identifier: type[_PluginT] | str) → type[_PluginT]

Resolve a plugin identifier to a plugin type.

async resolve_identifiers(plugin_identifiers: Iterable[PluginIdentifier[_PluginT]]) → Sequence[type[_PluginT]]

Resolve plugin identifiers to plugin types.

async select() → Sequence[type[_PluginT]]

async select(mixin_one: type[_PluginMixinOneT]) → Sequence[type[_PluginT & _PluginMixinOneT]]

async select(mixin_one: type[_PluginMixinOneT], mixin_two: type[_PluginMixinTwoT]) → Sequence[type[_PluginT & _PluginMixinOneT & _PluginMixinTwoT]]

async select(mixin_one: type[_PluginMixinOneT], mixin_two: type[_PluginMixinTwoT], mixin_three: type[_PluginMixinThreeT]) → Sequence[type[_PluginT & _PluginMixinOneT & _PluginMixinTwoT & _PluginMixinThreeT]]

Select a subset of the known plugins.

When called without arguments, this returns all known plugins. When called with one or more arguments, this returns all known plugins that are also subclasses or all of the given mixins.

This method is overloaded to provide for the majority use case of at most three mixins, because when using *args: *Ts, we cannot unpack Ts into an basedtyping.Intersection return type.

class betty.plugin.ShorthandPluginBase

Bases: Plugin

Allow shorthand declaration of plugins.

classmethod plugin_description() → Localizable | None

Get the human-readable long plugin description.

classmethod plugin_id() → str

Get the plugin ID.

IDs are unique per plugin type:

• A plugin repository MUST at most have a single plugin for any ID.

• Different plugin repositories MAY each have a plugin with the same ID.

classmethod plugin_label() → Localizable

Get the human-readable short plugin label.

betty.plugin.resolve_identifier(plugin_identifier: type[Plugin] | str) → str

Resolve a plugin identifier to a plugin ID.

async betty.plugin.sort_dependent_plugin_graph(sorter: TopologicalSorter[type[_PluginT]], plugins: PluginRepository[_PluginT], entry_point_plugins: Iterable[type[_PluginT & DependentPlugin[_PluginT]]]) → None

Build a graph of the given plugins and their dependencies.

async betty.plugin.sort_ordered_plugin_graph(sorter: TopologicalSorter[type[_PluginT]], plugins: PluginRepository[_PluginT & OrderedPlugin[_PluginT]], entry_point_plugins: Iterable[type[_PluginT & OrderedPlugin[_PluginT]]]) → None

Build a graph of the given plugins.