Usage
Creating plugins
If you use git in your project, install the gitpython
module (pip install gitpython
). startplugin
will determine your git user/email automatically and use it.
Create a plugin using a Django management command:
./manage.py startplugin fooplugin
This command asks a few questions, creates a basic Django app in the plugin path chosen in PluginManager.find_plugins()
. It provides useful defaults as well as a setup.py/setup.cfg file.
You now have two choices for this plugin:
add it statically to
INSTALLED_APPS
: see Static plugins.make use of the dynamic loading feature: see Dynamic plugins.
Static plugins
In most of the cases, you will ship your application with a few
“standard” plugins that are statically installed. These plugins must be
loaded after the gdaps
app.
# ...
INSTALLED_APPS = [
# ... standard Django apps and GDAPS
"gdaps",
# put "static" plugins here too:
"myproject.plugins.fooplugin",
]
This plugin app is loaded as usual, but your GDAPS enhanced Django application can make use of it’s GDAPS features.
Dynamic plugins
By installing a plugin with pip, you can make your application aware of that plugin too:
pip install -e myproject/plugins/fooplugin
This installs the plugin as python module into the site-packages and
makes it discoverable using setuptools. From this moment on it should be
already registered and loaded after a Django server restart. Of course
this also works when plugins are installed from PyPi, they don’t have to
be in the project’s plugins
folder. You can conveniently start
developing plugins in there, and later move them to the PyPi repository.
The plugin AppConfig
Plugins’ AppConfigs must provide an inner class named PluginMeta
, or a so named attribute pointing to an external class. For more information see gdaps.apps.PluginMeta
.
Interfaces
Plugins can define interfaces, which can then be implemented by other
plugins. The cookiecutter template contains a <app_name>/api/interfaces.py
file automatically.
It’s not obligatory to put all Interface definitions in api.interfaces
, but it is a recommended coding style for GDAPS plugins:
from gdaps import Interface
@Interface
class ITextRenderer:
"""Documentation of the interface"""
__service__ = True # is the default
text_type = None
def render(self):
pass
Predefined attributes are:
- __service__
If
__service__ = True
is set (which is the default), then all implementations are instantiated directly at loading time, having a full class instance available. Iterations over Interfaces return instances:for plugin in ITextRenderer: compiled_text = plugin.render()
If you use
__service__ = False
, the plugins are not instantiated, and iterations over Instances will return classes, not instances. This may be desired for reducing memory footprint, for data classes, or classes that just contain static or class methods.for plugin in INonServiceInterface: print(plugin.name) # class attribute plugin.some_classmethod() # if you need instances, you have to instantiate the plugin here. # this is not recommended. p = plugin() p.do_something()
Implementations
You can then easily implement this interface in any other file (in this plugin or in another plugin) by subclassing the interface:
from myproject.plugins.fooplugin.api.interfaces import IFooInterface
class OtherPluginClass(IFooInterface):
def do_something(self):
print('I did something!')
Using Implementations
You can straight-forwardly use implementations that are bound to an interface by iterating over that interface, anywhere in your code.
from myproject.plugins.fooplugin.api.interfaces import IFooInterface
class MyPlugin:
def foo_method(self):
for plugin in IFooInterface:
print plugin.do_domething()
Depending on the __service__ Meta flag, iterating over an Interface
returns either a class (__service__ = False
) or an instance (__service__ = True
), which is the default.
Extending Django’s URL patterns
To let your plugin define some URLs that are automatically detected by your Django application, you have to add a code fragment to your global urls.py file:
from gdaps.pluginmanager import PluginManager
urlpatterns = PluginManager.urlpatterns() + [
# add your fixed, non-plugin paths here.
]
GDAPS then loads and imports all available plugins’ urls.py files,
collects their urlpatterns
variables and includes them into merges them into the global urlpattern, using the app_name
namespace defined in the plugin’s urls.py:
from .views import MyUrlView, SomeViewSet
from django.views.generic import TemplateView
# fooplugin/urls.py
app_name = "fooplugin"
# This will be merged into the "fooplugin/" namespace
urlpatterns = [
path("", TemplateView("foo/index.html").as_view(), name="index"),
path("detail/", MyUrlView.as_view(), name="detail"),
# ...
]
GDAPS also lets your plugin create global, root URLs (not namespaced) by using root_urlpatterns
. This is because some plugins need to create global (e.g. API) URLS for frameworks like DRF, etc.
# This will be merged into the global urlpattern
root_urlpatterns = [
path("api/foo/", SomeViewSet.as_view(), name="api")
]
- Beware:
Plugins are responsible for their URLs and namespaces, and that they don’t collide with others.
DRF API Routers
DRF offers great router classes, but implementations always assume that your main urls.py knows about all of your apps. GDAPS lets you define one SimpleRouter for each of your apps, and automatically collects them into one global DefaultRouter.
In your global urls.py add:
router = PluginManager.router()
urlpatterns = [
# ...
path("api/", include(router.urls)),
]
In your apps’ urls.py, similar to urlpatterns, create a router variable:
from rest_framework.routers import SimpleRouter
router = SimpleRouter()
router.register(r"app", AppListViewSet)
…where AppListViewSet is your DRF ViewSet. That’s all, GDAPS takes care of the merging.
Per-plugin Settings
GDAPS allows your application to have own settings for each plugin
easily, which provide defaults, and can be overridden in the global
settings.py
file. Look at the example conf.py file (created by
./manage.py startplugin fooplugin
), and adapt to your needs:
from django.test.signals import setting_changed
from gdaps.conf import PluginSettings
NAMESPACE = "FOOPLUGIN"
# Optional defaults. Leave empty if not needed.
DEFAULTS = {
"MY_SETTING": "somevalue",
"FOO_PATH": "django.blah.foo",
"BAR": [
"baz",
"buh",
],
}
# Optional list of settings that are allowed to be in "string import" notation. Leave empty if not needed.
IMPORT_STRINGS = (
"FOO_PATH"
)
# Optional list of settings that have been removed. Leave empty if not needed.
REMOVED_SETTINGS = ( "FOO_SETTING" )
fooplugin_settings = PluginSettings("FOOPLUGIN", None, DEFAULTS, IMPORT_STRINGS)
Detailed explanation:
- DEFAULTS
The
DEFAULTS
are, as the name says, a default array of settings. Iffooplugin_setting.BLAH
is not set by the user in settings.py, this default value is used.- IMPORT_STRINGS
Settings in a dotted notation are evaluated, they return not the string, but the object they point to. If it does not exist, an
ImportError
is raised.- REMOVED_SETTINGS
A list of settings that are forbidden to use. If accessed, an
RuntimeError
is raised.This allows very flexible settings - as dependant plugins can easily import the
fooplugin_settings
from yourconf.py
.However, the created conf.py file is not needed, so if you don’t use custom settings at all, just delete the file.
Admin site
GDAPS provides support for the Django admin site. The built-in GdapsPlugin
model automatically
are added to Django’s admin site, and can be administered there.
Note
As GdapsPlugin database entries must not be edited directly, they are shown read-only in the admin. Please use the ‘syncplugins’ management command to update the fields from the file system. However, you can enable/disable or hide/show plugins via the admin interface.
If you want to disable the built-in admin site for GDAPS, or provide a custom GDAPS ModelAdmin, you can do this using:
GDAPS = {
"ADMIN": False
}
Frontend plugins
The GDAPS frontend module can be extended via plugins, each providing a pluggable frontend for your Django application. See
Signals
If you are using Django signals in your plugin, we recommend to put them into a signals
submodule. Import it then from the AppConfig.ready()
method.
def ready(self):
# Import signals if necessary:
from . import signals # NOQA
See also
Don’t overuse the ready
method. Have a look at the Django documentation of ready().