Skip to content
Reference of plugins_api 2.0.1, an older major version. See this page for plugins_api 3.0.0.

plugins_api.decorators

Plugin decorators.

This module contains decorators used for plugin registration and management.

Attributes

NameDescription
TNo description.
plugin_class_namesNo description.

Functions

NameDescription
base_plugin_classMark a class as a plugin.
enforce_constructor_signatureEnforce the constructor signature of a class.

Tattributemodule attribute#

T = TypeVar('T')

plugin_class_namesattributemodule attribute#

plugin_class_names: set[str] = set()

base_plugin_classfunction#

def base_plugin_class() -> type[T]

Mark a class as a plugin.

This function adds the name of the decorated class to the plugin_class_names set, indicating that the class is recognized as a base plugin class.

Parameters

NameTypeDescription
clstypeThe class to mark as a plugin.

Returns

type
The decorated class.

enforce_constructor_signaturefunction#

def enforce_constructor_signature(reference_class: type | None = None) -> Callable

Enforce the constructor signature of a class.

A class decorator to enforce that all subclasses of the decorated class define an __init__ method with the same signature as a given reference.

If no argument is provided, the decorated class itself is used as the reference.

Subclasses must:

  • Include all the required parameters in the same order

Subclasses may:

  • Add optional parameters (with or without defaults)
  • Change default values
  • Use *args / **kwargs

Subclasses must not:

  • Have missing required parameters
  • Have a different order of required parameters

Parameters

NameTypeDefaultDescription
reference_classtypeNoneA class whose __init__ signature should be enforced on subclasses of the decorated class. If None (or the decorator is used without parentheses), the signature of the decorated class’s own __init__ method is used as the reference.

Returns

Callable
A class decorator that modifies the class’s __init_subclass__ method to enforce the constructor signature.

Raises

TypeError
If a subclass defines an __init__ method with a different signature than the reference.

Examples

Enforcing a class’s own constructor:

>>> @enforce_constructor_signature
>>> class SubmissionPlugin(ConnectionPlugin):
... def __init__(self, submission_id: str, user: str):
... ...

Enforcing a different class’s constructor:

>>> @enforce_constructor_signature(SubmissionPlugin)
>>> class AnotherPlugin(SubmissionPlugin):
... def __init__(self, ignored): # signature doesn't matter, you don't even need to define it
... ...