Plugin API

All complex custom content in Imprint is generated by the plugins. Plugins are implemented by special configurable callable objects called handlers that follow a specific interface, which allows them to be referenced by the appropriate tags in the XML Template.

Three types of content are supported out of the box: Figures, Tables and Strings. Each type of plugin accepts a mapping of keywords from the IPC File (and the <expr> tags in the XML Template), and a dictionary of data configuration values from the IDC File that defines the behavior of the plugin. Beyond that, each type of handler has a different interface.

In fact, any custom TagDescriptor may define its own plugin interface. What makes a tag pluggable is its reliance on a function that accepts a data configuration. This technically makes the plugin API an implementation of a very distinct part of the XML Tag API.

Data Configuration

The data configuration is the second argument to every handler. The data configuration is a mapping set for every plugin in the IDC File. The name of the configuration dictionary is in the id attribute of the corresponding <figure>, <table> or <string> placeholder tag in the XML Template. Custom tags may be registered as configurable plugins by setting the data_config attribute of their TagDescriptor.

Data configuration values can contain any type of values, as long as they are meaningful to the plugin. Plugins may require some keys to be present in the configuration, and should raise a KnownError, optionally caused by a KeyError in response to missing keys. Most plugins will require some sort of data source, such as a file name, but again, this is not required.

Some values are special, in that they can override XML attibutes used by the TagDescriptor. In particular, the handler attribute can be overridden by a key with the similar name in the IDC File. Overridable values are noted for each builtin tag in the XML Template Specification.

Handlers

Handlers are named by the handler attribute of the corresponding <figure>, <table> or <string> placeholder tag in the XML Template. The exact class name (including package) is searched for the handler. If not found, a prefix of imprint.handlers is prepended to the nominal package name.

The handler can be overridden in the Data Configuration dictionary. Normally, all configuration keys are interpreted directly by the handler. However, a special handler key will processed before a handler is found, and can override the setting in the XML. This mechanism is provided by each of the Tag Descriptors for Figures, Tables and Strings. It allows for more flexible debugging, and modification of existing templates. New Tag Descriptors can use the get_handler function to implement the same functionality, although it is not stritcly required.

Figures

Some built-in figure handler examples can be found in imprint.handlers.figure.

Handler Signature

handler(config, kwds[, output])

Generate an image based on the Data Configuration. If an output is specified, it will be a string or file-like. A string indicates an output file name, which the handler may modify and return. A file-like can be assumed to be open for binary writing, with random access enabled. It should be rewound before being returned.

Parameters:
  • config (dict) – The Data Configuration for the figure.
  • kwds (dict) – The keyword dictionary for the figure.
  • output (str or file-like or None) – The name of the output file, or the output file to save the figure to. If omitted, the output must go to an in-memory file-like object like io.BytesIO. The handler may determine the output format based on the file extension, but this is not required. Each handler should have a default format for extensionless files and omitted output.
Returns:

Either the actual output file name, or an in-memory file-like object, rewound to the beginning, containing the image. A string output will not necessarily be the input file name. It may, for example, have an extension appended to it. A None return value indicates an internal non-fatal error.

Return type:

str or file-like

Tables

Some built-in table handler examples can be found in imprint.handlers.table.

Handler Signature

handler(config, kwds, doc, style, *, image_log_name=None)

Generate a table based on the Data Configuration. The handler is responsible for generating a table of the correct size and styling it properly based on the style parameter.

This type of plugin is expected to have no return value.

Parameters:
  • config (dict) – The Data Configuration for the table.
  • kwds (dict) – The keyword dictionary for the table.
  • doc (docx.document.Document) – The document to insert the table into. The handler is responsible for invoking the add_table method.
  • style (str) – The name of the style to apply to the generated object.
  • image_log_name (str, Path-like or None) – The name of the image log to use if table data is to be logged. If log_images is off, this will be None. May be completely ignored by the handler if impractical or inappropriate to implement. The file name, if supplied, is provided without any extension.

Strings

Some built-in string handler examples can be found in imprint.handlers.string.

Handler Signature

handler(config, kwds)

Generate a string based on Data Configuration.

Parameters:
Returns:

The newly created string. A None return value indicates an internal non-fatal error.

Return type:

str

Errors

Since plugins implement a subset of the tag-processing functionality, the same rules apply to plugin errors at to generic tag errors. See Errors in the XML Tag API section.

Builtin Plugins

Imprint is packaged with a small number of pre-defined builtin plugin Handlers for general purpose use. In addition to being useful on their own, these plugins provide a starting point for advanced users wishing to write their own. Handlers are grouped into sub-packages according to the tag they support.

Figures

imprint.handlers.figure is the root package for built-in Handlers for inserting figures into a document.

All the handlers in this module are compatible with the plugin interface used by the <figure> tag. This package exposes all the handlers defined in its submodules.

imprint.handlers.figure.ImageFile(config, kwds, output=None)

Generate python-docx compatible images from image files.

Copy image files as-is, or load them into memory. Output must be to a file of the same type as the input (except for PDFs): no conversion is done, only direct copy. PDFs (identified by the '.pdf' extension) get special handling to convert them into usable images.

The following Data Configuration keys are used:

file
The (mandatory) file name containing the image.
formatted
Whether or not file is a format string that has keyword replacements in it. Defaults to truthy. Set to falsy if the name contains random opening braces.

Notes

Using this plugin with PDF files requires the poppler library mentioned in the External Programs.

Submodules

imprint.handlers.figure.images contains basic built-in Handlers for inserting images into a document. All the handlers in this module are compatible with the plugin interface used by the <figure> tag.

Tables

Submodules

Strings

imprint.handlers.string is the root package for built-in Handlers for inserting strings into a document.

All the handlers in this module are compatible with the plugin interface used by the <string> tag. This package exposes all the handlers defined in its submodules.

imprint.handlers.string.TextFile(config, kwds)

Generate a string directly from the contents of a text file.

Text files are inserted literally, with no styling information beyond that of the <string> tag that triggered the plugin. Newlines are not preserved.

The following Data Configuration keys are used:

file
The (mandatory) file name.
formatted
Whether or not file is a format string that has keyword replacements in it. Defaults to truthy. Set to falsy if the name contains random opening braces.

Submodules

imprint.handlers.string.strings contains the basic built-in Handlers for inserting strings into a document. All the handlers in this module are compatible with the plugin interface used by the <string> tag.

Utilities

imprint.handlers.utilities contains common utilities for handlers. Users wishing to write their own handlers may want to use these functions to facilitate a uniform interface. Existing handlers in this package use these functions as well.

imprint.handlers.utilities.get_key(config, kwds, key, default=None, formatted='formatted', missing_ok=True)

Retreive the value of key from the mapping config.

If key does not exist in config, return default instead.

If formatted is a string, it determines the key name that determines whether key is a format string or not (default is yes). Otherwise, it is interpreted as a boolean directly.

Parameters:
  • config (dict) – The Data Configuration dictionary to search.
  • kwds (dict) – The Keywords dictionary to use for replacements if formatted turns out to be truthy.
  • key (str) – The name of the key in config containing the required value.
  • default – The value to return if key is missing from config.
  • formatted (str or bool) – Either the name of the key to get the formatted flag from (if a string), or the flag itself. In either case, ignored if the value is not a string.
  • missing_ok (bool) – If truthy, missing values are replaced by default. Otherwise a KeyError is raised.
Returns:

  • The value in config associated with key, optionally formatted
  • with kwds.

imprint.handlers.utilities.get_file(config, kwds, key='file', default=None, formatted='formatted', missing_ok=False)

A wrapper around get_key that sets the default key to 'file' and forbids missing keys.

imprint.handlers.utilities.normalize_descriptor(descriptor, key, copy=False)

If descriptor is a mapping, return it as-is; otherwise, turn it into a value in a mapping keyed by key.

If the descriptor is returned as-is, it can optionally be copied by setting copy to True.