Plugin

Represents a plugin.

Attributes

_added_variable_names : list of str

A list of the added variables' names to the module.

_child_plugins : None, WeakSet of Plugin

Child plugins.

_default_variables : None, HybridValueDictionary of (str, object) items

An optionally weak value dictionary to store objects for assigning them to modules before loading them. If it would be set as empty, then it is set as None instead.

_entry_point : None, str, callable

Internal slot used by the .entry_point property.

_exit_point : None, str, callable

Internal slot used by the .exit_point property.

_extend_default_variables : bool

Internal slot used by the .extend_default_variables property.

_locked : bool

The internal slot used for the .locked property.

_parent_plugins : None, WeakSet of Plugin

Parent plugins.

_snapshot_difference : None, list of BaseSnapshotType

Snapshot difference if applicable. Defaults to None.

_snapshot_extractions : None, list of list of BaseSnapshotType

Additional snapshots to extract from own.

_spec : PluginModuleSpecType

The module specification for the plugin's module's import system related state.

_state : int

The state of the plugin. Can be:

Respective nameValue
PLUGIN_STATE_UNDEFINED0
PLUGIN_STATE_LOADED1
PLUGIN_STATE_UNLOADED2
PLUGIN_STATE_UNSATISFIED3
_sub_module_plugins : None, WeakSet of Plugin

Sub module plugins.

_take_snapshot : bool

Whether snapshot difference should be taken.

Properties

entry_point

Get-set-del descriptor for modifying the plugin's entry point.

Accepts and returns None, str or a callable. If invalid type is given, raises TypeError.

exit_point

Get-set-del descriptor for modifying the plugin's exit point.

Accepts and returns None, str or a callable. If invalid type is given, raises TypeError.

extend_default_variables

Get-set descriptor to define whether the plugin uses the loader's default variables or just it's own.

Accepts and returns bool.

file_name

Returns the plugin's file's name.

Returns

file_name : str

locked

Get-set property to define whether the plugin should be picked up by the {}_all methods of the plugin loader.

Accepts and returns bool.

name

Returns the plugin's name.

Returns

name : str

path

Returns the plugin's name.

Returns

name : str

short_name

Returns the plugin's name's shortened version.

Returns

name : str

sort_key

Returns the plugin's sort key.

Returns

sort_key : tuple of str

_module

Deprecated attribute of Plugin.

Methods

__new__(name, path, entry_point, exit_point, extend_default_variables, locked, take_snapshot_difference, default_variables)

Creates a plugin with the given parameters. If a plugin already exists with the given name, returns that.

ParameterTypeDescription
name

None, str

The plugin's name (or import path).

path

str

Path to the plugin file.

entry_point

None, str, callable

The entry point of the plugin.

exit_point

None, str, callable

The exit point of the plugin.

extend_default_variables

bool

Whether the plugin should use the loader's default variables or just it's own.

locked

bool

Whether the plugin should be picked up by the {}_all methods of the plugin loader.

take_snapshot_difference

bool

Whether snapshots should be taken before and after loading a plugin, and when the plugin is unloaded, the snapshot difference should be reverted.

default_variables

None, HybridValueDictionary of (str, object) items

An optionally weak value dictionary to store objects for assigning them to modules before loading them. If would be empty, is set as None instead.

Returns

self : Plugin

Raises

ModuleNotFoundError

If the plugin was not found.

add_child_plugin(plugin)

Registers a child plugin.

ParameterTypeDescription
plugin

Plugin

The plugin to register.

add_default_variables(...)

Adds default variables to the plugin.

ParameterTypeOptionalKeyword onlyDescription
**variables

Keyword Parameters

Variables to assigned to the plugin's module before it is loaded.

Raises

ValueError

If a variable name is would be used, what is module attribute.

add_parent_plugin(plugin)

Registers a parent plugin.

ParameterTypeDescription
plugin

Plugin

The plugin to register.

add_snapshot_extraction(snapshots)

Adds snapshot extraction to the plugin.

ParameterType
snapshots

list of BaseSnapshotType

add_sub_module_plugin(plugin)

Registers a sub module plugin.

ParameterTypeDescription
plugin

Plugin

The plugin to register.

are_child_plugins_present_in(plugins)

Returns whether all the child plugins are present in the given plugins.

ParameterTypeDescription
plugins

iterable of Plugin

Already present plugins to check satisfaction form.

Returns

are_child_plugins_present_in : bool

are_parent_plugins_present_in(plugins)

Returns whether all the parent plugins are present in the given plugins.

ParameterTypeDescription
plugins

iterable of Plugin

Already present plugins to check satisfaction form.

Returns

are_parent_plugins_present_in : bool

are_sub_module_plugins_present_in(plugins)

Returns whether all the sub module plugins are present in the given plugins.

ParameterTypeDescription
plugins

iterable of Plugin

Already present plugins to check satisfaction form.

Returns

are_sub_module_plugins_present_in : bool

clear_child_plugins()

Clears the child plugins of the plugin.

clear_default_variables()

Removes all the default variables of the plugin.

clear_parent_plugins()

Clears the parent plugins of the plugin.

clear_snapshot_extractions()

Clears the snapshot extractions of the plugin.

clear_sub_module_plugins()

Clears the sub module plugins of the plugin.

get_module()

Returns the module of the plugin.

Returns

module : None, ModuleType

get_module_proxy()

Returns a proxy to the plugin.

Returns

module_proxy : PluginModuleProxyType

is_directory()

Returns whether the plugin is a directory.

Returns

is_directory : bool

is_loaded()

Returns whether the plugin is loaded.

Returns

is_loaded : bool

is_unsatisfied()

Returns whether the plugin is unsatisfied.

Returns

is_unsatisfied : bool

iter_child_plugins()

Iterates over the child plugins.

This method is an iterable generator.

Yields

child_plugin : None

iter_loaded_plugins_in_directory()

Iterates over the loaded plugins directly under this one. This one must be a directory (so an __init__ file).

This method is an iterable generator.

Yields

plugin : Plugin

iter_parent_plugins()

Iterates over the parent plugins.

This method is an iterable generator.

Yields

parent_plugin : None

iter_snapshot_extractions()

Iterates over the snapshot extractions of the plugin.

This method is an iterable generator.

Yields

snapshots : list of BaseSnapshotType

iter_sub_module_plugins()

Iterates over the sub module plugins.

This method is an iterable generator.

Yields

sub_module_plugin : None

remove_child_plugin(child_plugin)

Removes the given plugin from the plugin's children.

ParameterTypeDescription
child_plugin

Plugin

The plugin to remove.

remove_default_variables(...)

Removes the mentioned default variables of the plugin.

If a variable with a specified name is not found, no error is raised.

ParameterTypeOptionalDescription
*names

str

Default variable names.

remove_parent_plugin(parent_plugin)

Removes the given plugin from the plugin's parents.

ParameterTypeDescription
parent_plugin

Plugin

The plugin to remove.

remove_sub_module_plugin(sub_module_plugin)

Removes the given plugin from the plugin's sub modules.

ParameterTypeDescription
sub_module_plugin

Plugin

The plugin to remove.

_check_for_syntax()

Checks the file's new syntax.

Used when reloading, to avoid unloading un-loadable files.

This method is blocking. Run it inside of an executor.

Returns

exception : PluginError

PluginError wrapping invalid syntax.

_load()

Loads the module and returns it. If it is already loaded returns None.

Returns

module : None, ModuleType

Raises

ImportError

Circular imports.

RuntimeError

Module already imported.

BaseException

Any exception raised from the plugin file.

_load_module()

Loads the module and returns whether it was successfully loaded.

Returns

loaded : bool

Raises

BaseException

Any exception raised from the plugin file.

_unassign_variables()

Unassigns the assigned variables to the respective module and clears ._added_variable_names.

_unlink()

Removes the plugin's module from the loaded ones.

Should not be called on loaded plugins.

_unload()

Unloads the module and returns it. If it is already unloaded returns None.

Returns

module : None, ModuleType

Raises

SyntaxError

If check_for_syntax and the file's syntax is incorrect.

__getattr__()

Drops a rich attribute error.

__gt__()

Returns whether self is greater than other.

__hash__()

Returns the plugin's ._spec 's .origin 's hash.

__lt__()

Returns whether self is less than other.

__repr__()

Returns the plugin's representation.