API¶
Interfaces/Implementations¶
-
gdaps.
Interface
(cls)¶ Decorator for classes that are interfaces.
Declare an interface using the
@Interface
decorator, optionally add add attributes/methods to that class:@Interface class IFooInterface: def do_something(self): pass
You can choose whatever name you want for your interfaces, but we recommend you start the name with a capital “I”. Read more about interfaces in the Interfaces section.
-
gdaps.
require_app
(appconfig: django.apps.AppConfig, required_app_name: str) → None¶ Helper function for AppConfig.ready - checks if an app is installed.
An
ImproperlyConfigured
Exception is raised if the required app is not present.- Parameters
appconfig – the AppConfig which requires another app. usually use
self
here.required_app_name – the required app name.
Plugin configuration and metadata¶
-
class
gdaps.apps.
PluginMeta
¶ Inner class of GDAPS plugins.
All GDAPS plugin AppConfig classes need to have an inner class named
PluginMeta
. This PluginMeta provides some basic attributes and methods that are needed when interacting with a plugin during its life cycle.from django.utils.translation import gettext_lazy as _ from django.apps import AppConfig class FooPluginConfig(AppConfig): class PluginMeta: # the plugin machine "name" is taken from the Appconfig, so no name here verbose_name = _('Foo Plugin') author = 'Me Personally' description = _('A foo plugin') visible = True version = '1.0.0' compatibility = "myproject.core>=2.3.0"
Note
If
PluginMeta
is missing, the plugin is not recognized by GDAPS.The author of the plugin. Not translatable.
The email address of the author
-
category
= 'GDAPS'¶ A freetext category where your plugin belongs to. This can be used in your application to group plugins.
-
description
= ''¶ A longer text to describe the plugin.
A boolean value whether the plugin should be hidden, or visible. False by default.
-
initialize
()¶ Callback to initialize the plugin.
If your plugin needs to install some data into the database at the first run, you can provide this method to
PluginMeta
. It will be called whenmanage.py syncplugins
is called and the plugin is run the first time.An example would be installing some fixtures, providing a message to the user etc.
-
version
= '0.0.0'¶ The version of the plugin, following Semantic Versioning. This is used for dependency checking as well, see
compatibility
.
-
visible
= True¶ A boolean value whether the plugin should be visible, or hidden.
Deprecated since version 0.4.2: Use hidden instead.
PluginManager¶
-
class
gdaps.pluginmanager.
PluginManager
¶ A Generic Django Plugin Manager that finds Django app plugins in a plugins folder or setuptools entry points and loads them dynamically.
It provides a couple of methods to interaft with plugins, load submodules of all available plugins dynamically, or get a list of enabled plugins. Don’t instantiate a
PluginManager
directly, just use its static and class methods directly.-
classmethod
find_plugins
(group: str) → List[str]¶ Finds plugins from setuptools entry points.
This function is supposed to be called in settings.py after the INSTALLED_APPS variable. Therefore it can not use global variables from settings, to prevent circle imports.
- Parameters
group – a dotted path where to find plugin apps. This is used as ‘group’ for setuptools’ entry points.
- Returns
A list of dotted app_names, which can be appended to INSTALLED_APPS.
-
classmethod
load_plugin_submodule
(submodule: str, mandatory=False) → list¶ Search plugin apps for specific submodules and load them.
- Parameters
submodule – the dotted name of the Django app’s submodule to import. This package must be a submodule of the plugin’s namespace, e.g. “schema” - then [“<main>.core.schema”, “<main>.laboratory.schema”] etc. will be found and imported.
mandatory – If set to True, each found plugin _must_ contain the given submodule. If any installed plugin doesn’t have it, a PluginError is raised.
- Returns
a list of module objects that have been successfully imported.
-
static
orphaned_plugins
() → django.db.models.QuerySet¶ Returns a list of GdapsPlugin models that have no disk representance any more.
Note
This method needs Django’s ORM to be running.
-
classmethod
plugin_path
()¶ Returns the absolute path where application plugins live.
This is basically the Django root + the dotted entry point. CAVE: this is not callable from within the settings.py file.
-
static
plugins
(skip_disabled: bool = False) → List[django.apps.AppConfig]¶ Returns a list of AppConfig classes that are GDAPS plugins.
This method basically checks for the presence of a
PluginMeta
attribute within the AppConfig of all apps and returns a list of apps containing it. :param skip_disabled: If True, skips disabled plugins and only returns enabled ones. Defaults toFalse
.
-
static
urlpatterns
() → list¶ Loads all plugins’ urls.py and collects their urlpatterns.
This is maybe not the best approach, but it allows plugins to have “global” URLs, and not only namespaced, and it is flexible
- Returns
a list of urlpatterns that can be merged with the global urls.urlpattern.
-
classmethod