PythonPluginSystem Class Reference

Loads Python Packages, using entry point discovery or from a custom search path. More...

Inheritance diagram for PythonPluginSystem:

Public Member Functions
def	__init__ (self, logger)
def	reset (self)
	Clears any previously loaded plugins. More...
def	scan (self, paths, pathsEnvVar, entryPointName, disableEntryPointsEnvVar, disableEntryPoints, moduleHookName)
	Searches the supplied paths and/or entry points for modules that define a PythonPluginSystemPlugin through a supplied top-level variable. More...
def	scan_paths (self, paths, moduleHookName)
	Searches the supplied paths for modules that define a PythonPluginSystemPlugin through a supplied top-level variable. More...
def	scan_entry_points (self, entryPointName, moduleHookName)
	Searches packages for entry points that define a PythonPluginSystemPlugin through a given top-level variable. More...
def	identifiers (self)
	Returns the identifiers known to the plugin system. More...
def	plugin (self, identifier)
	Retrieves the plugin that provides the given identifier. More...
def	register (self, cls, path="<unknown>")
	Allows manual registration of a PythonPluginSystemPlugin derived class. More...

Detailed Description

Loads Python Packages, using entry point discovery or from a custom search path.

If they contain a top-level 'plugin' attribute, that holds a class derived from PythonPluginSystemPlugin, it will be registered with its identifier. Once a plug-in has registered an identifier, any subsequent registrations with that id will be skipped.

Constructor & Destructor Documentation

def __init__	(		self,
			logger
	)

Member Function Documentation

def identifiers

(

self

)

Returns the identifiers known to the plugin system.

If scan has not been called, then this will be empty.

Returns

List[str]

def plugin	(		self,
			identifier
	)

Retrieves the plugin that provides the given identifier.

Returns

PythonPluginSystemPlugin

Exceptions

errors.InputValidationException

Raised if no plugin provides the specified identifier.

def register	(		self,
			cls,
			path = "<unknown>"
	)

Allows manual registration of a PythonPluginSystemPlugin derived class.

This can be used to register plugins using means other than the built-in file system scanning.

Parameters

cls	PythonPluginSystemPlugin
path	str Some reference to where this plugin originated, used for debug messaging when duplicate registrations of the same identifier are encountered.

def reset

(

self

)

Clears any previously loaded plugins.

def scan	(		self,
			paths,
			pathsEnvVar,
			entryPointName,
			disableEntryPointsEnvVar,
			disableEntryPoints,
			moduleHookName
	)

Searches the supplied paths and/or entry points for modules that define a PythonPluginSystemPlugin through a supplied top-level variable.

Parameters

paths	str A list of paths to search, delimited by os.pathsep. Set to blank (or otherwise falsey) to use the environment variable given by pathsEnvVar instead.
pathsEnvVar	str The name of the environment variable that contains paths to search, formatted as given in paths. If paths is set then this environment variable is unused.
entryPointName	str The name of the entry point group to search for plugins.
disableEntryPointsEnvVar	str An environment variable that, if set, will disable scanning for entry point plugins, unless overridden by disableEntryPoints.
disableEntryPoints	Optional[bool] Set to True or False to force disabling or enabling of entry point plugins, respectively. Set to None to enable unless disableEntryPointsEnvVar is set.
moduleHookName	str The name of the top-level variable that contains the plugin class.

def scan_entry_points	(		self,
			entryPointName,
			moduleHookName
	)

Searches packages for entry points that define a PythonPluginSystemPlugin through a given top-level variable.

Note

The order of discovery is determined by importlib, only the first plugin with any given identifier will be registered.

Parameters

entryPointName	str The entry point name to search for (see: importlib.metadata.entry_points group).
moduleHookName	str The name of the top-level variable that contains the plugin class.

Returns

True if entry point discovery is possible, False if there was a problem loading importlib.metadata.

def scan_paths	(		self,
			paths,
			moduleHookName
	)

Searches the supplied paths for modules that define a PythonPluginSystemPlugin through a supplied top-level variable.

Paths are searched left-to-right, but only the first instance of any given plugin identifier will be used, and subsequent registrations ignored. This means entries to the left of the paths list take precedence over ones to the right.

Note

Precedence order is undefined for plugins sharing the same identifier within the same directory.

Parameters

paths	str A list of paths to search, delimited by os.pathsep.
moduleHookName	str The name of the top-level variable that contains the plugin class.

---

The documentation for this class was generated from the following file:

• /src/src/openassetio-python/package/openassetio/pluginSystem/PythonPluginSystem.py