Plugins#

modelly.plugins finds third-party extensions through package entry points. The guide is Plugins.

Third-party extensions found through package entry points.

A package extends Modelly by declaring entry points in one of the groups of GROUPS, for example in its pyproject.toml:

[project.entry-points."modelly.spaces"]
hexworld = "hexworld.space:HexWorld"

discover(group) lists what is installed without importing anything; each Plugin is imported the first time it is loaded. A plugin that fails to import raises PluginError naming the plugin and its distribution, and never stops the others from being found or loaded: load_all returns the loaded objects and the errors apart.

from modelly.plugins import discover

spaces = discover(“modelly.spaces”) # {“hexworld”: Plugin(…)} HexWorld = spaces[“hexworld”].load()

exception PluginError[source]#

A plugin could not be loaded; __cause__ is the original error.

class Plugin(name: str, group: str, value: str, distribution: str | None, _entry_point: EntryPoint, _loaded: Any = <object object>)[source]#

One entry point: imported on the first load and cached.

Variables:

  • name (str) – the entry point’s name, the key in discover’s result.

  • group (str) – its group, such as "modelly.spaces".

  • value (str) – the module:attribute it points to.

  • distribution (str | None) – the installed distribution that declares it, if known.

load() → Any[source]#

Import and return the object the entry point names.

Raises:

PluginError – if importing or resolving it fails, with the original error as its cause.

discover(group: str) → dict[str, Plugin][source]#

The installed plugins of group, by name, sorted; nothing is imported.

Any group name works, so a feature may define its own; GROUPS lists Modelly’s. When two distributions declare the same name, the first distribution in alphabetical order wins and a RuntimeWarning names both.

Example

>>> discover("modelly.no_such_group")
{}
load_all(group: str) → tuple[dict[str, Any], dict[str, PluginError]][source]#

Load every plugin of group: (objects by name, errors by name).

A plugin that fails is reported in the second dictionary; the others still load.