calingen.interfaces.plugin_api

Provides the API for plugins.

Module Contents

Classes

CompilerProvider	Mount point for plugins that provide means to compile layouts to documents.
EventProvider	Mount point for plugins that provide events.
LayoutProvider	Mount point for plugins that provide layouts.
PluginMount	Core of the plugin api.

Functions

fully_qualified_classname(class_or_instance)

Get the fully qualified Python path of a class (or instance).

class calingen.interfaces.plugin_api.CompilerProvider

Mount point for plugins that provide means to compile layouts to documents.

Plugins implementing this reference must provide the following attributes and methods:

• title (str): The title of the provider.

• get_response() : A classmethod that accepts a str, which will be the rendered layout source as provided by LayoutProvider.render(). The method must return a valid Django Response object.

abstract classmethod get_response(source, *args, **kwargs)

Get the compiler’s HTTP response.

This is the compiler’s main interface to other components of the app.

It should be used to actually trigger the compilation of the provided source and then return a valid Django Response object.

Parameters:

source (str) – The source as provided by LayoutProvider.render().

Return type:

Django Response object

Notes

This method is called from CompilerView's get() method with an additional keyword argument layout_type, exposing the layout_type attribute of the layout.

classmethod list_available_plugins()

Return the available plugins.

Returns:

The resulting set contains a 2-tuple for every plugin, including its qualified classname and its title attribute. The qualified classname is determined by fully_qualified_classname().

Return type:

set

class calingen.interfaces.plugin_api.EventProvider

Mount point for plugins that provide events.

Plugins implementing this reference must provide the following attribute:

• title (str): The title of the provider, provided as a class attribute.

Plugins implementing this reference can provide the following attributes and/or methods:

• entries (list): A list of calingen.interfaces.data_exchange.CalendarEntry instances.

  The default implementation of resolve() will work on this list. Alternatively resolve() may be re-implemented (see below).

• resolve(year) : A classmethod that accepts a year (int) as parameter and returns an instance of calingen.interfaces.data_exchange.CalendarEntryList containing the Events of the requested year with their corresponding meta information as specified by calingen.interfaces.data_exchange.CalendarEntry.

classmethod list_available_plugins()

Return the available plugins.

Returns:

The resulting set contains a 2-tuple for every plugin, including its qualified classname and its title attribute. The qualified classname is determined by fully_qualified_classname().

Return type:

set

Notes

Primary use case for this method is the usage in a Django view, specifically ProfileForm uses this method to provide the choices of its field. That Form is then used in the app’s views, e.g. calingen.views.profile.ProfileUpdateView.

classmethod resolve(year)

Return a list of events.

Parameters:

year (int) – The year to retrieve the list of events for.

Returns:

Wraps the actual events, provided as calingen.interfaces.data_exchange.CalendarEntry into one single object.

Return type:

calingen.interfaces.data_exchange.CalendarEntryList

Notes

This is the default implementation of the resolve() method. It makes some assumptions about the internal structure of an actual implementation of EventProvider:

• A class variable entries provides a list of tuple instances with the following structure: (title, category, recurrence):

  • title: str

  • category: str, but it is recommended to rely on a predefined value from calingen.constants.EventCategory

  • recurrence: dateutil.rrule.rrule

• A class variable title (str). This is already a required parameter of the EventProvider implementation itsself and is used to populate the source attribute of the returned CalenderEntry instances.

class calingen.interfaces.plugin_api.LayoutProvider

Mount point for plugins that provide layouts.

Plugins implementing this reference must provide the following attributes:

• title (str): The title will be used to represent the plugin in the app’s views. It must be provided as a class attribute resolving to a str. However, it is recommended to provide the following class attributes instead:

  • name (str): A descriptive name of the layout.

  • paper_size (str): The size of the paper, e.g. "a4", "a5", etc.

  • orientation (str): The orientation, e.g. "landscape" or "portrait".

  By providing these attributes, the title can be provided automatically by title() in a unified way throughout the application.

• layout_type (str): This required class attribute specifies the source language of the rendered result and is used in calingen.views.generation.CompilerView to determine which compiler is to be used to actually compile the rendered source to its final product.

  The actual mapping of layout_type to compiler is done in the app-specific setting CALINGEN_COMPILER.

  layout_type may not be "default", as this is a special key used internally in CompilerView and specifies the fallback compiler for the case that there is no dedicated compiler available for the layout_type of a layout.

Plugins implementing this reference can provide implementations of the following methods:

• prepare_context(context) (dict): This method performs pre-processing of the context. If an actual layout needs data in a different structure than provided by calingen.views.generation.CompilerView, this method may be re-implemented by the actual layout. See prepare_context() for additional details.

• render(year, entries) (str): Actually renders the layout’s templates with the given context. This method may be re-implemented by actual layouts, though it is pretty generic as it is and should work for most use cases. It calls prepare_context() for pre-processing of the context. It is recommended to rely on prepare_context() in actual layout implementations.

configuration_form

Layouts may provide a custom form to fetch configuration values.

The specified form should be a subclass of calingen.forms.generation.LayoutConfigurationForm and may implement custom validation / cleaning logic.

classmethod list_available_plugins()

Return the available plugins.

Returns:

The resulting set contains a 2-tuple for every plugin, including its qualified classname and its title attribute. The qualified classname is determined by fully_qualified_classname().

Return type:

set

Notes

Primary use case for this method is the usage in a Django view, specifically ProfileForm uses this method to provide the choices of its field. That Form is then used in the app’s views, e.g. ProfileUpdateView.

classmethod prepare_context(context)

Pre-process the context before rendering.

Parameters:

context (dict) – The context, as provided by calingen.views.generation.CompilerView.get().

Returns:

The updated context.

Return type:

dict

Notes

This default implementation does nothing. LayoutProvider implementations may override this method to apply necessary modifications of the context.

classmethod render(context, *args, **kwargs)

Return the rendered source.

Returns:

The rendered source.

Return type:

str

Notes

This is a very basic implementation of the (required) render() method.

title()

Return the plugin’s human-readable title.

Returns:

The plugin’s title is constructed from class attributes.

Return type:

str

Notes

The title is provided as a classproperty.

If an actual layout implementation wishes to provide its title in a different way, it may provide a specific implementation of this method or provide a plain title class attribute, resolving to a str (TODO: NEEDS VERIFICATION!).

The classproperty decorator is provided by Django, so B902 is disabled on this.

class calingen.interfaces.plugin_api.PluginMount(name, bases, attrs)

Bases: type

Core of the plugin api.

Notes

Searching Google with any Django-related term usually results in at least five StackOverflow threads with similar issues. This failed for “django plugin system” (ok, there are SO threads, without providing any real solution).

However, there is a blog post by Marty Alchin, dating back to 2008 [1], describing some sort of weird Python sorcery. Digging deeper, while trying to understand the purpose and possible application of metaclass in this context, this SO thread [2] was found (easily one of the best SO threads on a general programming technique).

Obviously, [1] was ported to Python3 syntax (getting rid of __metaclass__ and apply it in the class definition of the actual mount point).

References

[1] (1,2)

http://martyalchin.com/2008/jan/10/simple-plugin-framework/

[2]

https://stackoverflow.com/questions/100003/what-are-metaclasses-in-python

calingen.interfaces.plugin_api.fully_qualified_classname(class_or_instance)

Get the fully qualified Python path of a class (or instance).

Parameters:

class_or_instance (any) – The class (or instance of a class) to work on

Returns:

The fully qualified, dotted Python path of that class or instance.

Return type:

str