Peas.Engine¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37), Gio.ListModel (4)
Structs:: GObject.ObjectClass (5)

class	`get_default` ()
class	`new` ()
class	`new_with_nonglobal_loaders` ()
	`add_search_path` (module_dir, data_dir)
	`create_extension` (info, extension_type, prop_names, prop_values)
	`dup_loaded_plugins` ()
	`enable_loader` (loader_name)
	`garbage_collect` ()
	`get_plugin_info` (plugin_name)
	`load_plugin` (info)
	`provides_extension` (info, extension_type)
	`rescan_plugins` ()
	`set_loaded_plugins` (plugin_names)
	`unload_plugin` (info)

Virtual Methods¶

Inherited:: GObject.Object (7), Gio.ListModel (3)

Properties¶

Name	Type	Flags	Short Description
`loaded-plugins`	[`str`]	r/w	The list of loaded plugins
`nonglobal-loaders`	`bool`	r/w/co	Use non-global plugin loaders

Signals¶

Inherited:: GObject.Object (1), Gio.ListModel (1)

Name	Short Description
`load-plugin`	The load-plugin signal is emitted when a plugin is being loaded.
`unload-plugin`	The unload-plugin signal is emitted when a plugin is being unloaded.

Fields¶

Inherited:: GObject.Object (1), Gio.ListModel (1)

Class Details¶

class Peas.Engine(**kwargs)¶

Bases:: GObject.Object, Gio.ListModel
Abstract:: No
Structure:: Peas.EngineClass

The Peas.Engine is the object which manages the plugins.

Its role is twofold:

it will fetch all the information about the available plugins from all the registered plugin directories;
it will provide you an API to load, control and unload your plugins and their extensions from within your application.

classmethod get_default()¶

Returns:: the existing instance of Peas.Engine.
Return type:: Peas.Engine

Return the existing instance of Peas.Engine or a subclass of it.

If no Peas.Engine subclass has been instantiated yet, the first call of this function will return a new instance of Peas.Engine.

Note: this function should never be used when multiple threads are using libpeas API as it is not thread-safe.

classmethod new()¶

Returns:: a new instance of Peas.Engine.
Return type:: Peas.Engine

Return a new instance of Peas.Engine.

If no default Peas.Engine has been instantiated yet, the first call of this function will set the default engine as the new instance of Peas.Engine.

classmethod new_with_nonglobal_loaders()¶

Returns:: a new instance of Peas.Engine that uses non-global loaders.
Return type:: Peas.Engine

Return a new instance of Peas.Engine which will use non-global plugin loaders instead of the default global ones.

This allows multiple threads to each have a Peas.Engine and be used without internal locking.

Note: due to CPython’s GIL the python and python3 plugin loaders are always global.

add_search_path(module_dir, data_dir)¶

Parameters:

module_dir (str) – the plugin module directory.
data_dir (str or None) – the plugin data directory.

Appends a search path to the list of paths where to look for plugins.

A so-called “search path” actually consists of both a module directory (where the shared libraries or language modules lie) and a data directory (where the plugin data is).

The plugin will be able to use a correct data dir depending on where it is installed, hence allowing to keep the plugin agnostic when it comes to installation location: the same plugin can be installed either in the system path or in the user’s home directory, without taking other special care than using [method`PluginInfo`.get_data_dir] when looking for its data files.

If data_dir is None, then it is set to the same value as module_dir.

create_extension(info, extension_type, prop_names, prop_values)¶

Parameters:

info (Peas.PluginInfo) – A loaded Peas.PluginInfo.
extension_type (GObject.GType) – The implemented extension GObject.GType.
prop_names ([str]) – an array of property names.
prop_values ([GObject.Value]) – an array of property values.

Returns:

a new instance of GObject.Object which meets the prerequisites of extension_type, or None.

Return type:

GObject.Object

If the plugin identified by info implements the extension_type, then this function will return a new instance of this implementation.

See [method`Engine`.create_extension] for more information.

dup_loaded_plugins()¶

Returns:: A newly-allocated None-terminated array of strings.
Return type:: [str]

Returns the list of the names of all the loaded plugins.

If there is no plugin currently loaded, it will return an array containing a single None element.

Please note that the returned array is a newly allocated one: you will need to free it using [func`GLib`.strfreev].

enable_loader(loader_name)¶

Parameters:: loader_name (str) – The name of the loader to enable.

Enable a loader, enables a loader for plugins.

The C plugin loader is always enabled. The other plugin loaders are: gjs, lua5.1, python and python3.

For instance, the following code will enable Python 2 plugins to be loaded:

``c peas_engine_enable_loader (engine, “python”); ``

Note: plugin loaders used to be shared across ``PeasEngine``s so enabling a loader on one Peas.Engine would enable it on all Peas.Engines. This behavior has been kept to avoid breaking applications, however a warning has been added to help applications transition.

garbage_collect()¶

Triggers garbage collection on all the loaders currently owned by the Peas.Engine.

This can be used to force the loaders to destroy managed objects that still hold references to objects that are about to disappear.

get_plugin_info(plugin_name)¶

Parameters:: plugin_name (str) – A plugin name.
Returns:: the Peas.PluginInfo corresponding with a given plugin module name.
Return type:: Peas.PluginInfo

Gets the [class`PluginInfo`] corresponding with plugin_name, or None if plugin_name was not found.

load_plugin(info)¶

Parameters:: info (Peas.PluginInfo) – A Peas.PluginInfo.
Returns:: whether the plugin has been successfully loaded.
Return type:: bool

Loads the plugin corresponding to info if it’s not currently loaded.

Emits the [signal`Engine`:py:func:::load-plugin<Peas.Engine.signals.load_plugin>] signal; loading the plugin actually occurs in the default signal handler.

provides_extension(info, extension_type)¶

Parameters:

info (Peas.PluginInfo) – A Peas.PluginInfo.
extension_type (GObject.GType) – The extension GObject.GType.

Returns:

if info provides an extension for extension_type.

Return type:

bool

Returns if info provides an extension for extension_type.

If the info is not loaded than False will always be returned.

rescan_plugins()¶

Rescan all the registered directories to find new or updated plugins.

Calling this function will make the newly installed plugin infos be loaded by the engine, so the new plugins can be used without restarting the application.

set_loaded_plugins(plugin_names)¶

Parameters:: plugin_names ([str] or None) – A None-terminated array of plugin names, or None.

Sets the list of loaded plugins for self.

When this function is called, the Peas.Engine will load all the plugins whose names are in plugin_names, and ensures all other active plugins are unloaded.

If plugin_names is None, all plugins will be unloaded.

unload_plugin(info)¶

Parameters:: info (Peas.PluginInfo) – A Peas.PluginInfo.
Returns:: whether the plugin has been successfully unloaded.
Return type:: bool

Unloads the plugin corresponding to info.

Emits the [signal`Engine`:py:func:::unload-plugin<Peas.Engine.signals.unload_plugin>] signal; unloading the plugin actually occurs in the default signal handler.

Signal Details¶

Peas.Engine.signals.load_plugin(engine, info)¶

Signal Name:

load-plugin

Flags:

RUN_LAST

Parameters:

engine (Peas.Engine) – The object which received the signal
info (Peas.PluginInfo) – A Peas.PluginInfo.

The load-plugin signal is emitted when a plugin is being loaded.

The plugin is being loaded in the default handler. Hence, if you want to perform some action before the plugin is loaded, you should use [func`GObject`.signal_connect], but if you want to perform some action *after* the plugin is loaded (the most common case), you should use [func`GObject`.signal_connect_after].

Peas.Engine.signals.unload_plugin(engine, info)¶

Signal Name:

unload-plugin

Flags:

RUN_LAST

Parameters:

engine (Peas.Engine) – The object which received the signal
info (Peas.PluginInfo) – A Peas.PluginInfo.

The unload-plugin signal is emitted when a plugin is being unloaded.

The plugin is being unloaded in the default handler. Hence, if you want to perform some action before the plugin is unloaded (the most common case), you should use [func`GObject`.signal_connect], but if you want to perform some action after the plugin is unloaded (the most common case), you should use [func`GObject`.signal_connect_after].

Property Details¶

Peas.Engine.props.loaded_plugins¶

Name:: loaded-plugins
Type:: [str]
Default Value:: []
Flags:: READABLE, WRITABLE

The list of loaded plugins.

This will be modified when [method`Engine`.load_plugin] or [method`Engine`.unload_plugin] is called.

This can be used with [class`Gio`.Settings] to save the loaded plugins by binding to this property after instantiating the engine by doing:

``c

g_settings_bind (gsettings_object,: LOADED_PLUGINS_KEY, engine, “loaded-plugins”, G_SETTINGS_BIND_DEFAULT);

``

Note: notify will not be called when the engine is being destroyed.

Peas.Engine.props.nonglobal_loaders¶

Name:: nonglobal-loaders
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

If non-global plugin loaders should be used.

See [ctor`Engine`.new_with_nonglobal_loaders] for more information.