6. Plugin API

This section describes some of the elements in src/ucsschool_id_connector/plugins.py of the ID Connector source code.

6.1. Postprocessing

class ucsschool_id_connector.plugins.Postprocessing

Pluggy hook specifications for all hooks modifying data in post processing. The implementations of these hooks need to be registered with a name, since the set of plugins executed can be configured for every school authority individually.

async create_request_kwargs(http_method: str, url: str, school_authority: SchoolAuthorityConfiguration) → Dict[Any, Any]

Creates a dictionary the keyword arguments for the http request should be updated with.

The configured create_request_kwargs hooks for a given school authority will be executed. The returned dictionaries are used to update the keyword arguments for aiohttp with. Common use cases would be the addition of headers or authentication strategies.

Parameters:

• http_method – The HTTP method used, e.g. POST

• url – The complete URL this request goes to

• school_authority – The school authority configuration that this request targets

Returns:

The dictionary to update the request keyword arguments with

async handle_listener_object(school_authority: SchoolAuthorityConfiguration, obj: ListenerObject) → bool

This hook is the entry point for the entire handling logic of ListenerObjects in the out queue. All handler hooks that have been registered and appear in a specific school authority configuration are executed. If no registered hook handles the object and thus none returned True, an error will be logged.

Parameters:

• school_authority – The school authority this object is handled for

• obj – The ListenerObject to handle

Returns:

True if this hook handled the object, otherwise False

async school_authority_ping(school_authority: SchoolAuthorityConfiguration) → bool

This hook can be defined to implement a connectivity check to the API of a school authority. If any registered ping hooks for a school authority returns False, the communication is considered faulty.

Parameters:

school_authority – The school authority to check the connectivity to.

Returns:

True if check succeeds, otherwise False

6.2. filter_plugins

ucsschool_id_connector.plugins.filter_plugins(hook_name: str, plugins: List[str]) → Any

This function returns a HookCaller containing only the implementations of the specified plugins. If the given list is empty, or no specified plugin implements the hook, the default plugin is chosen.

Parameters:

• hook_name – The hook to be executed

• plugins – The plugins to be filtered for

Returns:

A _HookCaller instance that can be used just like plugin_manager.hook.hook_name.

6.3. hook_*

ucsschool_id_connector.plugins.hook_impl = <pluggy._hooks.HookimplMarker object>

Decorator for marking functions as hook implementations.

Instantiate it with a project_name to get a decorator. Calling PluginManager.register() later will discover all marked functions if the PluginManager uses the same project name.

ucsschool_id_connector.plugins.hook_spec = <pluggy._hooks.HookspecMarker object>

Decorator for marking functions as hook specifications.

Instantiate it with a project_name to get a decorator. Calling PluginManager.add_hookspecs() later will discover all marked functions if the PluginManager uses the same project name.