Skip to content
Browse files

Merge pull request #2644 from avaris/namespace

Namespace plugin implementation
  • Loading branch information
justinmayer committed Dec 1, 2019
2 parents 772005f + 8a56e1f commit 48f62751346fcddfad7968ea768d1048af2a73dd
@@ -9,16 +9,31 @@ features to Pelican without having to directly modify the Pelican core.
How to use plugins

To load plugins, you have to specify them in your settings file. There are two
ways to do so. The first method is to specify strings with the path to the
Starting with version 5.0, Pelican moved to a new plugin structure utilizing
namespace packages. Plugins supporting this structure will install under the
namespace package ``pelican.plugins`` and can be automatically discovered
by Pelican.

PLUGINS = ['package.myplugin',]
If you leave the ``PLUGINS`` setting as default (``None``), Pelican will then
collect the namespace plugins and register them. If on the other hand you
specify a ``PLUGINS`` settings as a list of plugins, this autodiscovery will
be disabled and only listed plugins will be registered and you will have to
explicitly list the namespace plugins as well.

Alternatively, another method is to import them and add them to the list::
If you are using ``PLUGINS`` setting, you can specify plugins in two ways.
The first method specifies plugins as a list of strings. Namespace plugins can
be specified either by their full names (``pelican.plugins.myplugin``) or by
their short names (``myplugin``)::

PLUGINS = ['package.myplugin',

Alternatively, you can import them in your settings file and pass the modules::

from package import myplugin
PLUGINS = [myplugin,]
from pelican.plugins import namespace_plugin1, namespace_plugin2
PLUGINS = [myplugin, namespace_plugin1, namespace_plugin2]

.. note::

@@ -36,11 +51,13 @@ the ``PLUGIN_PATHS`` list can be absolute or relative to the settings file::

Where to find plugins
Namespace plugins can be found in the `pelican-plugins organization`_ as
individual repositories. Legacy plugins are collected in the `pelican-plugins
repository`_ and they will be slowly phased out in favor of the namespace

We maintain a separate repository of plugins for people to share and use.
Please visit the `pelican-plugins`_ repository for a list of available plugins.

.. _pelican-plugins:
.. _pelican-plugins organization:
.. _pelican-plugins repository:

Please note that while we do our best to review and maintain these plugins,
they are submitted by the Pelican community and thus may have varying levels of
@@ -70,6 +87,33 @@ which you map the signals to your plugin logic. Let's take a simple example::
your ``register`` callable or they will be garbage-collected before the
signal is emitted.

Namespace plugin structure

Namespace plugins must adhere to a certain structure in order to function
properly. They need to be installable (i.e. contain ```` or equivalent)
and have a folder structure as follows::

├── pelican
│   └── plugins
│   └── myplugin
│   ├──
│   └── ...
├── ...

It is crucial that ``pelican`` or ``pelican/plugins`` folder **not**
contain an ```` file. In fact, it is best to have those folders
empty besides the listed folders in the above structure and keep your
plugin related files contained solely in the ``pelican/plugins/myplugin``
folder to avoid any issues.

For easily setting up the proper structure, a `cookiecutter template for
plugins`_ is provided. Refer to the README in the link for how to use it.

.. _cookiecutter template for plugins:

List of signals

@@ -194,7 +194,7 @@ Basic settings
Controls the extension that will be used by the SourcesGenerator. Defaults
to ``.text``. If not a valid string the default value will be used.

.. data:: PLUGINS = []
.. data:: PLUGINS = None

The list of plugins to load. See :ref:`plugins`.

@@ -9,14 +9,20 @@
import time
import traceback
from import Iterable
# Combines all paths to `pelican` package accessible from `sys.path`
# Makes it possible to install `pelican` and namespace plugins into different
# locations in the file system (e.g. pip with `-e` or `--user`)
from pkgutil import extend_path
__path__ = extend_path(__path__, __name__)

# pelican.log has to be the first pelican module to be loaded
# because logging.setLoggerClass has to be called before logging.getLogger
from pelican.log import init as init_logging
from pelican import signals # noqa
from pelican.generators import (ArticlesGenerator, PagesGenerator,
SourceFileGenerator, StaticGenerator,
from pelican.generators import (ArticlesGenerator, # noqa: I100
PagesGenerator, SourceFileGenerator,
StaticGenerator, TemplatePagesGenerator)
from pelican.plugins import signals
from pelican.plugins._utils import load_plugins
from pelican.readers import Readers
from pelican.server import ComplexHTTPRequestHandler, RootedHTTPServer
from pelican.settings import read_settings
@@ -62,27 +68,14 @@ def init_path(self):
sys.path.insert(0, '')

def init_plugins(self):
self.plugins = []
logger.debug('Temporarily adding PLUGIN_PATHS to system path')
_sys_path = sys.path[:]
for pluginpath in self.settings['PLUGIN_PATHS']:
sys.path.insert(0, pluginpath)
for plugin in self.settings['PLUGINS']:
# if it's a string, then import it
if isinstance(plugin, str):
logger.debug("Loading plugin `%s`", plugin)
plugin = __import__(plugin, globals(), locals(), 'module')
except ImportError as e:
"Cannot load plugin `%s`\n%s", plugin, e)

logger.debug("Registering plugin `%s`", plugin.__name__)
logger.debug('Restoring system path')
sys.path = _sys_path
self.plugins = load_plugins(self.settings)
for plugin in self.plugins:
logger.debug('Registering plugin `%s`', plugin.__name__)
except Exception as e:
logger.error('Cannot register plugin `%s`\n%s',
plugin.__name__, e)

def run(self):
"""Run the generators and return"""
@@ -10,7 +10,7 @@

import pytz

from pelican import signals
from pelican.plugins import signals
from pelican.settings import DEFAULT_CONFIG
from pelican.utils import (deprecated_attribute, memoized, path_to_url,
posixize_path, sanitised_join, set_date_tzinfo,
@@ -13,9 +13,9 @@
from jinja2 import (BaseLoader, ChoiceLoader, Environment, FileSystemLoader,
PrefixLoader, TemplateNotFound)

from pelican import signals
from pelican.cache import FileStampDataCacher
from pelican.contents import Article, Page, Static
from pelican.plugins import signals
from pelican.readers import Readers
from pelican.utils import (DateFormatter, copy, mkdir_p, order_content,
posixize_path, process_translations)
@@ -0,0 +1,85 @@
import importlib
import importlib.machinery
import importlib.util
import logging
import pkgutil

logger = logging.getLogger(__name__)

def iter_namespace(ns_pkg):
# Specifying the second argument (prefix) to iter_modules makes the
# returned name an absolute name instead of a relative one. This allows
# import_module to work without having to do additional modification to
# the name.
return pkgutil.iter_modules(ns_pkg.__path__, ns_pkg.__name__ + ".")

def get_namespace_plugins(ns_pkg=None):
if ns_pkg is None:
import pelican.plugins as ns_pkg

return {
name: importlib.import_module(name)
for finder, name, ispkg
in iter_namespace(ns_pkg)
if ispkg

def list_plugins(ns_pkg=None):
from pelican.log import init as init_logging
ns_plugins = get_namespace_plugins(ns_pkg)
if ns_plugins:'Plugins found:\n' + '\n'.join(ns_plugins))
else:'No plugins are installed')

def load_legacy_plugin(plugin, plugin_paths):
# Try to find plugin in PLUGIN_PATHS
spec = importlib.machinery.PathFinder.find_spec(plugin, plugin_paths)
if spec is None:
# If failed, try to find it in normal importable locations
spec = importlib.util.find_spec(plugin)
if spec is None:
raise ImportError('Cannot import plugin `{}`'.format(plugin))
mod = importlib.util.module_from_spec(spec)
return mod

def load_plugins(settings):
logger.debug('Finding namespace plugins')
namespace_plugins = get_namespace_plugins()
if namespace_plugins:
logger.debug('Namespace plugins found:\n' +
plugins = []
if settings.get('PLUGINS') is not None:
for plugin in settings['PLUGINS']:
if isinstance(plugin, str):
logger.debug('Loading plugin `%s`', plugin)
# try to find in namespace plugins
if plugin in namespace_plugins:
plugin = namespace_plugins[plugin]
elif 'pelican.plugins.{}'.format(plugin) in namespace_plugins:
plugin = namespace_plugins['pelican.plugins.{}'.format(
# try to import it
plugin = load_legacy_plugin(
settings.get('PLUGIN_PATHS', []))
except ImportError as e:
logger.error('Cannot load plugin `%s`\n%s', plugin, e)
plugins = list(namespace_plugins.values())

return plugins
@@ -1,4 +1,5 @@
# -*- coding: utf-8 -*-
from __future__ import print_function, unicode_literals

from blinker import signal

@@ -16,9 +16,9 @@
from docutils.writers.html4css1 import HTMLTranslator, Writer

from pelican import rstdirectives # NOQA
from pelican import signals
from pelican.cache import FileStampDataCacher
from pelican.contents import Author, Category, Page, Tag
from pelican.plugins import signals
from pelican.utils import get_date, pelican_open, posixize_path

@@ -138,7 +138,7 @@ def load_source(name, path):
'PLUGINS': [],
'PLUGINS': None,
@@ -0,0 +1,5 @@
NAME = 'namespace plugin'

def register():
@@ -0,0 +1,5 @@
NAME = 'normal plugin'

def register():
@@ -10,8 +10,8 @@
from jinja2.utils import generate_lorem_ipsum

from pelican.contents import Article, Author, Category, Page, Static
from pelican.plugins.signals import content_object_init
from pelican.settings import DEFAULT_CONFIG
from pelican.signals import content_object_init
from import (LoggedTestCase, get_context, get_settings,
from pelican.utils import (path_to_url, posixize_path, truncate_html_words)

0 comments on commit 48f6275

Please sign in to comment.
You can’t perform that action at this time.