PluginFileLocator

Role

The PluginFileLocator locates plugins when they are accessible via the filesystem.

It’s default behaviour is to look for text files with the ‘.yapsy-plugin’ extensions and to read the plugin’s decription in them.

Customization

The behaviour of a PluginFileLocator can be customized by instanciating it with a specific ‘analyzer’.

Two analyzers are already implemented and provided here:

PluginFileAnalyzerWithInfoFile

the default ‘analyzer’ that looks for plugin ‘info files’ as text file with a predefined extension. This implements the way yapsy looks for plugin since version 1.

PluginFileAnalyzerMathingRegex

look for files matching a regex and considers them as being the plugin itself.

All analyzers must enforce the

It enforces the plugin locator policy as defined by IPluginLocator and used by PluginManager.

info_ext

expects a plugin to be discovered through its plugin info file. User just needs to provide an extension (without ‘.’) to look for plugin_info_file.

regexp

looks for file matching the given regular pattern expression. User just needs to provide the regular pattern expression.

All analyzers must enforce the policy represented by the IPluginFileAnalyzer interface.

API

class yapsy.PluginFileLocator.IPluginFileAnalyzer(name)

Define the methods expected by PluginFileLocator for its ‘analyzer’.

getInfosDictFromPlugin(dirpath, filename)

Returns the extracted plugin informations as a dictionary. This function ensures that “name” and “path” are provided.

dirpath is the full path to the directory where the plugin file is

filename is the name (ie the basename) of the plugin file.

If callback function has not been provided for this strategy, we use the filename alone to extract minimal informations.

isValidPlugin(filename)

Check if the resource found at filename is a valid plugin.

class yapsy.PluginFileLocator.PluginFileAnalyzerMathingRegex(name, regexp)

An analyzer that targets plugins decribed by files whose name match a given regex.

getInfosDictFromPlugin(dirpath, filename)

Returns the extracted plugin informations as a dictionary. This function ensures that “name” and “path” are provided.

isValidPlugin(filename)

Checks if the given filename is a valid plugin for this Strategy

class yapsy.PluginFileLocator.PluginFileAnalyzerWithInfoFile(name, extensions='yapsy-plugin')

Consider plugins described by a textual description file.

A plugin is expected to be described by a text file (‘ini’ format) with a specific extension (.yapsy-plugin by default).

This file must contain at least the following information:

[Core]
Name = name of the module
Module = relative_path/to/python_file_or_directory

Optionnally the description file may also contain the following section (in addition to the above one):

[Documentation]
Author = Author Name
Version = Major.minor
Website = url_for_plugin
Description = A simple one-sentence description

Ctor Arguments:

name name of the analyzer.

extensions the expected extensions for the plugin info file. May be a string or a tuple of strings if several extensions are expected.

getInfosDictFromPlugin(dirpath, filename)

Returns the extracted plugin informations as a dictionary. This function ensures that “name” and “path” are provided.

If callback function has not been provided for this strategy, we use the filename alone to extract minimal informations.

getPluginNameAndModuleFromStream(infoFileObject, candidate_infofile=None)

Extract the name and module of a plugin from the content of the info file that describes it and which is stored in infoFileObject.

Note

Prefer using _extractCorePluginInfo instead, whenever possible…

Warning

infoFileObject must be a file-like object: either an opened file for instance or a string buffer wrapped in a StringIO instance as another example.

Note

candidate_infofile must be provided whenever possible to get better error messages.

Return a 3-uple with the name of the plugin, its module and the config_parser used to gather the core data in a tuple, if the required info could be localised, else return (None,None,None).

Note

This is supposed to be used internally by subclasses and decorators.

isValidPlugin(filename)

Check if it is a valid plugin based on the given plugin info file extension(s). If several extensions are provided, the first matching will cause the function to exit successfully.

setPluginInfoExtension(extensions)

Set the extension that will identify a plugin info file.

extensions May be a string or a tuple of strings if several extensions are expected.

class yapsy.PluginFileLocator.PluginFileLocator(analyzers=None, plugin_info_cls=<class 'yapsy.PluginInfo.PluginInfo'>)

Locates plugins on the file system using a set of analyzers to determine what files actually corresponds to plugins.

If more than one analyzer is being used, the first that will discover a new plugin will avoid other strategies to find it too.

By default each directory set as a “plugin place” is scanned recursively. You can change that by a call to disableRecursiveScan.

appendAnalyzer(analyzer)

Append an analyzer to the existing list.

disableRecursiveScan()

Disable recursive scan of the directories given as plugin places.

gatherCorePluginInfo(directory, filename)

Return a PluginInfo as well as the ConfigParser used to build it.

If filename is a valid plugin discovered by any of the known strategy in use. Returns None,None otherwise.

getPluginNameAndModuleFromStream(infoFileObject, candidate_infofile=None)

DEPRECATED(>1.9): kept for backward compatibility with existing PluginManager child classes.

Return a 3-uple with the name of the plugin, its module and the config_parser used to gather the core data in a tuple, if the required info could be localised, else return (None,None,None).

locatePlugins()

Walk through the plugins’ places and look for plugins.

Return the candidates and number of plugins found.

removeAllAnalyzer()

Remove all analyzers.

removeAnalyzers(name)

Removes analyzers of a given name.

setAnalyzers(analyzers)

Sets a new set of analyzers.

Warning

the new analyzers won’t be aware of the plugin info class that may have been set via a previous call to setPluginInfoClass.

setPluginInfoClass(picls, name=None)

Set the class that holds PluginInfo. The class should inherit from PluginInfo.

If name is given, then the class will be used only by the corresponding analyzer.

If name is None, the class will be set for all analyzers.

setPluginInfoExtension(ext)

DEPRECATED(>1.9): for backward compatibility. Directly configure the IPluginLocator instance instead !

This will only work if the strategy “info_ext” is active for locating plugins.

setPluginPlaces(directories_list)

Set the list of directories where to look for plugin places.

updatePluginPlaces(directories_list)

Updates the list of directories where to look for plugin places.