152 lines
3.6 KiB
ReStructuredText
152 lines
3.6 KiB
ReStructuredText
Writing a Plugin
|
|
================
|
|
|
|
**The plugin interface is a work in progress.**
|
|
|
|
Several interfaces exist for extending Lemur:
|
|
|
|
* Issuers (lemur.issuers)
|
|
|
|
Structure
|
|
---------
|
|
|
|
A plugins layout generally looks like the following::
|
|
|
|
setup.py
|
|
lemur_pluginname/
|
|
lemur_pluginname/__init__.py
|
|
lemur_pluginname/plugin.py
|
|
|
|
The ``__init__.py`` file should contain no plugin logic, and at most, a VERSION = 'x.x.x' line. For example,
|
|
if you want to pull the version using pkg_resources (which is what we recommend), your file might contain::
|
|
|
|
try:
|
|
VERSION = __import__('pkg_resources') \
|
|
.get_distribution(__name__).version
|
|
except Exception, e:
|
|
VERSION = 'unknown'
|
|
|
|
Inside of ``plugin.py``, you'll declare your Plugin class::
|
|
|
|
import lemur_pluginname
|
|
from lemur.common.services.issuers.plugins import Issuer
|
|
|
|
class PluginName(Plugin):
|
|
title = 'Plugin Name'
|
|
slug = 'pluginname'
|
|
description = 'My awesome plugin!'
|
|
version = lemur_pluginname.VERSION
|
|
|
|
author = 'Your Name'
|
|
author_url = 'https://github.com/yourname/lemur_pluginname'
|
|
|
|
def widget(self, request, group, **kwargs):
|
|
return "<p>Absolutely useless widget</p>"
|
|
|
|
And you'll register it via ``entry_points`` in your ``setup.py``::
|
|
|
|
setup(
|
|
# ...
|
|
entry_points={
|
|
'lemur.plugins': [
|
|
'pluginname = lemur_pluginname.issuers:PluginName'
|
|
],
|
|
},
|
|
)
|
|
|
|
|
|
That's it! Users will be able to install your plugin via ``pip install <package name>`` and configure it
|
|
via the web interface based on the hooks you enabled.
|
|
|
|
|
|
Permissions
|
|
===========
|
|
|
|
As described in the plugin interface, Lemur provides a suite of permissions.
|
|
|
|
In most cases, a admin (that is, if User.is_admin is ``True``), will be granted implicit permissions
|
|
on everything.
|
|
|
|
This page attempts to describe those permissions, and the contextual objects along with them.
|
|
|
|
.. data:: add_project
|
|
|
|
Controls whether a user can create a new project.
|
|
|
|
::
|
|
|
|
>>> has_perm('add_project', user)
|
|
|
|
|
|
Testing
|
|
=======
|
|
|
|
Lemur provides a basic py.test-based testing framework for extensions.
|
|
|
|
In a simple project, you'll need to do a few things to get it working:
|
|
|
|
setup.py
|
|
--------
|
|
|
|
Augment your setup.py to ensure at least the following:
|
|
|
|
.. code-block:: python
|
|
|
|
setup(
|
|
# ...
|
|
install_requires=[
|
|
'lemur',
|
|
]
|
|
)
|
|
|
|
|
|
conftest.py
|
|
-----------
|
|
|
|
The ``conftest.py`` file is our main entry-point for py.test. We need to configure it to load the Lemur pytest configuration:
|
|
|
|
.. code-block:: python
|
|
|
|
from __future__ import absolute_import
|
|
|
|
pytest_plugins = [
|
|
'lemur.utils.pytest'
|
|
]
|
|
|
|
|
|
Test Cases
|
|
----------
|
|
|
|
You can now inherit from Lemur's core test classes. These are Django-based and ensure the database and other basic utilities are in a clean state:
|
|
|
|
.. code-block:: python
|
|
|
|
# test_myextension.py
|
|
from __future__ import absolute_import
|
|
|
|
from lemur.testutils import TestCase
|
|
|
|
class MyExtensionTest(TestCase):
|
|
def test_simple(self):
|
|
assert 1 != 2
|
|
|
|
|
|
Running Tests
|
|
-------------
|
|
|
|
Running tests follows the py.test standard. As long as your test files and methods are named appropriately (``test_filename.py`` and ``test_function()``) you can simply call out to py.test:
|
|
|
|
::
|
|
|
|
$ py.test -v
|
|
============================== test session starts ==============================
|
|
platform darwin -- Python 2.7.9 -- py-1.4.26 -- pytest-2.6.4/python2.7
|
|
plugins: django
|
|
collected 1 items
|
|
|
|
tests/test_myextension.py::MyExtensionTest::test_simple PASSED
|
|
|
|
=========================== 1 passed in 0.35 seconds ============================
|
|
|
|
|