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.
Contents
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: - config (dict) – The Data Configuration for the string.
- kwds (dict) – The keyword dictionary for the string.
Returns: The newly created string. A
None
return value indicates an internal non-fatal error.Return type:
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.
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.