Source code for engineer.plugins.core

# coding=utf-8
import logging

__author__ = 'Tyler Butler <>'

# Adapted from Marty Alchin:

def find_plugins(entrypoint):
        import pkg_resources
    except ImportError:
        pkg_resources = None

    if pkg_resources is None:
    for entrypoint in pkg_resources.iter_entry_points(entrypoint):
        yield, entrypoint.load()

#noinspection PyUnresolvedReferences,PyUnusedLocal
def load_plugins():
    """Load all plugins."""

    # Ensure the built-in plugins are loaded by importing the module
    from engineer.plugins import bundled

    # Load registered plugin modules
    for name, module in find_plugins('engineer.plugins'):
        # No need to import the module manually because find_plugins will do that.

def get_all_plugin_types():
    return ThemeProvider, PostProcessor, CommandPlugin, JinjaEnvironmentPlugin

#noinspection PyMissingConstructor,PyUnusedLocal
class PluginMount(type):
    """A metaclass used to identify :ref:`plugins`."""

    def __init__(cls, name, bases, attrs):
        if not hasattr(cls, 'plugins'):
            # This branch only executes when processing the mount point itself.
            # So, since this is a new plugin type, not an implementation, this
            # class shouldn't be registered as a plugin. Instead, it sets up a
            # list where plugins can be registered later.
            cls.plugins = []
            # This must be a plugin implementation, which should be registered.
            # Simply appending it to the list is all that's needed to keep
            # track of it later.

class PluginMixin(object):
    def get_name(cls):
        return '.'.join([cls.__module__, cls.__name__])

    def get_logger(cls):
        """Returns a logger for the plugin."""
        return logging.getLogger(cls.get_name())

    def handle_settings(cls, config_dict, settings):
        If a plugin defines its own settings, it may also need to handle those settings in some unique way when the
        Engineer configuration files are being read. By overriding this method,
        plugins can ensure such unique handling of their settings is done.

        Note that a plugin does not have to handle its own settings unless there is unique processing that must be
        done. Any settings that are unknown to Engineer will automatically be added as attributes on the
        :class:`~engineer.conf.EngineerConfiguration` object. This method should only be implemented if the settings
        must be processed in some more complicated way prior to being added to the global configuration object.

        Implementations of this method should check for the plugin-specific settings in ``config_dict`` and set
        appropriate attributes/properties on the ``settings`` object. In addition, settings that
        have been handled should be removed from ``config_dict``. This ensures they are not handled by
        other plugins or the default Engineer code.

        :param config_dict: The dict of as-yet unhandled settings in the current settings file.

        :param settings: The global :class:`~engineer.conf.EngineerConfiguration` object that contains all the
            settings for the current Engineer process. Any custom settings should be added to this object.

        :returns: The modified ``config_dict`` object.
        return config_dict

[docs]class ThemeProvider(PluginMixin): """ Base class for Theme :ref:`plugins`. ThemeProvider subclasses must provide a value for :attr:`~engineer.plugins.ThemeProvider.paths`. .. versionchanged:: 0.3.0 """ __metaclass__ = PluginMount paths = () # empty tuple """An iterable of absolute paths containing one or more :ref:`theme manifests <theme manifest>`."""
[docs]class PostProcessor(PluginMixin): """ Base class for Post Processor :ref:`plugins`. PostProcessor subclasses should provide implementations for :meth:`~engineer.plugins.PostProcessor.preprocess` or :meth:`~engineer.plugins.PostProcessor.postprocess` (or both) as appropriate. """ __metaclass__ = PluginMount @classmethod
[docs] def preprocess(cls, post, metadata): """ The ``preprocess`` method is called during the Post import process, before any post metadata defaults have been set. The preprocess method should use the ``content_preprocessed`` attribute to get/modify the content of *post*. This ensures that preprocessors from other plugins can be chained together. By default, the ``content_preprocessed`` value is used only for generating post HTML. It is not written back to the source post file. However, sometimes you may want to make a permanent change to the post content that is written out. In this case, you should call the :meth:`~engineer.models.Post.set_finalized_content` method, passing it the modified content. This method will ensure the data is written back to the source file by the :ref:`metadata finalization` plugin. This means that in order for a plugin to write preprocessed data back to the post file, the :attr:`~engineer.conf.EngineerConfiguration.FINALIZE_METADATA` setting must be enabled. Your plugin will also need to be explicitly granted the ``MODIFY_RAW_POST`` permission. See more detail in :ref:`plugin permissions`. In addition, the preprocess method can add/remove/update properties on the *post* object itself as needed. .. tip:: Since the :attr:`~engineer.conf.EngineerConfiguration.FINALIZE_METADATA` setting must be enabled for plugins to write back to source post files, you should check this setting in addition to any other settings you may be using. :param post: The post being currently processed by Engineer. :param metadata: A dict of the post metadata contained in the post source file. It contains no default values - only the values contained within the post source file itself. The preprocess method can add, update, or otherwise manipulate metadata prior to it being processed by Engineer manipulating this parameter. :return: The *post* and *metadata* values should be returned (as a 2-tuple) by the method. """ return post, metadata
[docs] def postprocess(cls, post): """ The ``postprocess`` method is called after the post has been imported and processed as well as converted to HTML and output. :param post: The post being currently processed by Engineer. :return: The *post* parameter should be returned. """ return post
[docs]class CommandPlugin(PluginMixin): """ Base class for Command :ref:`plugins`. Command plugins add new commands to the :ref:`cmdline`. CommandPlugin subclasses must provide an implementation for :meth:`~engineer.plugins.CommandPlugin.add_command`, and can optionally override the :meth:`` classmethod to determine whether or not the plugin should actually be loaded. .. note:: Because Engineer uses :mod:`argparse` for parsing out its commands, you should be somewhat familiar with it in order to implement a Command plugin. .. seealso:: :ref:`command plugin examples` """ __metaclass__ = PluginMount @classmethod
[docs] def active(cls): """ If this method returns ``False``, the plugin will not run and any commands added by the plugin will not be available. This method can be overridden to make commands available only if certain criteria are met (for example, a custom :ref:`setting<settings>`). :return: A boolean value indicating whether or not the plugin is active and should run. Default implementation always returns ``True``. """ return True
[docs] def add_command(cls, subparser, main_parser, common_parser): """ This method is called by Engineer while it is building its :class:`~argparse.ArgumentParser`, allowing one to add addition parsers and subparsers to supplement the core :ref:`Engineer commands<cmdline>`. :param subparser: Since Engineer's built-in commands are subparsers, :meth:`~argparse.ArgumentParser.add_subparsers` is called to generate a subparser. :mod:`argparse` only supports calling :meth:`~argparse.ArgumentParser.add_subparsers` once, so the subparser object itself (the result of the initial :meth:`~argparse.ArgumentParser.add_subparsers` call Engineer made when building its parser) is passed in this parameter. This allows you to add either another top-level command by calling ``add_parser()`` then adding arguments directly, or to create further nested commands by adding a parser with additional subparsers within it. :param main_parser: The top level :class:`~argparse.ArgumentParser` used by Engineer. This is generally only useful if you're using an :mod:`argparse` wrapper library such as `argh <>`_ in your plugin. Most wrapper libraries require the root :class:`~argparse.ArgumentParser` object to add their subparsers to. If you're using :mod:`argparse` directly, you can ignore this parameter and work with the ``subparser`` parameter exclusively. :param common_parser: Engineer provides several :ref:`common arguments<engineer>` for its commands. If you wish to makes these arguments available for your custom commands, you should pass ``common_parser`` in to ``add_parser()`` via the ``parents`` parameter. """ raise NotImplementedError()
[docs]class JinjaEnvironmentPlugin(PluginMixin): """ Base class for JinjaEnvironment :ref:`plugins`. JinjaEnvironment plugins can supplement the Jinja 2 environment with things like filters and global functions. These additions can then be used in your Jinja templates. .. versionadded:: 0.5.0 """ __metaclass__ = PluginMount filters = {} """ A dict of filters to add to the Jinja environment. The key of each entry should be the name of the filter (as it will be used inside templates), while the value should be the filter function. If you require more custom logic to build the dict of filters, override the :meth:`~engineer.plugins.JinjaEnvironmentPlugin.get_filters` method. """ globals = {} """ A dict of functions to add to the Jinja environment globally. The key of each entry should be the name of the function (as it will be used inside templates), while the value should be the function itself. If you require more custom logic to build this dict, override the :meth:`~engineer.plugins.JinjaEnvironmentPlugin.get_globals` method. """ @classmethod def _add_filters(cls, jinja_env): logger = cls.get_logger() filters = cls.get_filters() for filter_name, filter_function in filters.iteritems(): if filter_name in jinja_env.filters: logger.warning("Jinja filter name conflict. " "A plugin is trying to add a filter with a name that conflicts with an existing filter. " "Filter name: %s" % filter_name) else: jinja_env.filters[filter_name] = filter_function logger.debug("Registered Jinja filter: %s" % filter_name) @classmethod def _add_globals(cls, jinja_env): logger = cls.get_logger() global_list = cls.get_globals() for global_name, the_global in global_list.iteritems(): if global_name in jinja_env.globals: logger.warning("Jinja global name conflict. " "A plugin is trying to add a global with a name that conflicts with an existing global. " "Global name: %s" % global_name) else: jinja_env.globals[global_name] = the_global logger.debug("Registered Jinja global: %s" % global_name) @classmethod
[docs] def update_environment(cls, jinja_env): """ For complete customization of the Jinja environment, subclasses can override this method. Subclasses should ensure that the base implementation is called first in their overridden implementation. For example: .. code-block:: python @classmethod def update_environment(cls, jinja_env): super(BundledFilters, cls).update_environment(jinja_env) # some other code here... :param jinja_env: The Jinja environment. """ cls._add_filters(jinja_env) cls._add_globals(jinja_env)
[docs] def get_filters(cls): """ If required, subclasses can override this method to return a dict of filters to add to the Jinja environment. The default implementation simply returns :attr:`~engineer.plugins.JinjaEnvironmentPlugin.filters`. """ return cls.filters
[docs] def get_globals(cls): """ If required, subclasses can override this method to return a dict of functions to add to the Jinja environment globally. The default implementation simply returns :attr:`~engineer.plugins.JinjaEnvironmentPlugin.globals`. """ return cls.globals