Keywords

The engine is configured through the IPC File and the IIF Files it includes. These files supply a set of keywords associated with values. There are two types of keywords: System Keywords and User-Defined Keywords.

System Keywords

System keywords configure the behavior of the engine and plugins. System keywords are conventionally identified by the lowercase_with_underscore naming scheme.

Most system keywords are optional, with sensible defaults used in case they are omitted. There are a few mandatory keywords that will result in an error if they are not supplied:

The following is a complete listing of known system keywords. Custom tags and plugins may define additional keywords (or use existing ones for their own purposes).

caption_counter_depth

The number of elements to include in the caption of a generated figure, table or heading reference before the object number. For example, say we have a figure that is the second figure under heading 1.2.3. Let’s also say that it is the fifth figure under heading 1.2 and the 10th in the first section. In that case, the following table shows the resulting reference captions for different values of this keyword:

caption_counter_depth caption
None 1.2.3-2
0 10
1 1-10
2 1.2-5
3+ 1.2.3-2

This keyword is optional. It defaults to 1.

data_config

The name of the IDC File that configures the entire Plugins Layer.

This keyword is mandatory if the XML Template specifies content generated by plugins, and completely ignored otherwise.

date

This keyword has no special meaning. However, it is implicitly set to the result of datetime.datetime.now when headers and footers are processed, if not set explicitly to something else. This makes it simpler to include information about the time of generation into the Headers and Footers. The implicitly-defined value is not available at any point besides the final keyword replacement step for Headers and Footers.

This keyword is optional.

file_level

The minimum cutoff level to dump to the file. To dump everything to the file use logging.NOTSET, 0, or 1. The value can be a (case insensitive) string level name, a number or one of the constants in the logging module.

If log_file is missing, this level will be ignored and nothing will be written to a file.

This keyword is optional. It defaults to logging.NOTSET.

includes

A sequence of include file names. Include files can only add new keywords to the existing configuration. They do not overwrite any keywords that are already set. It is therefore important that include files are loaded in breadth-first order in the order that they appear in the sequence.

This keyword is optional.

input_docx

The name of the DOCX Stub to use as a style and formatting template in the Templates Layer. All the styles referenced explicitly by the XML Template and implicitly in the User Defaults File must be present in this file. This file must also contain all the required formatting for Headers and Footers.

This keyword is optional. The default is the empty document provided by python-docx.

input_xml

The name of the XML Template file to use a content and layout template in the Templates Layer. This template must follow the specification laid out in XML Template Specification. It may contain additional tags, loaded through the tags mapping.

This keyword is mandatory.

log_file

The name of the output file to write to. All messages with level greater than or equal to file_level will be written to the named file.

If boolean True, a file with the same name as output_docx, but with a .log extension will be created.

This keyword is optional. If omitted, a log file will not be written, and file_level is ignored.

log_format

A string that determines the contents of each line of the log file. The format of this string is the same as for the fmt attribute of a logging.Formatter. It uses % interpolation syntax, with all the logging.LogRecord attributes as valid keyword replacements.

This keyword is optional. If omitted, the log message will be formatted according to '%(asctime)s - %(name)s - %(levelname)s - %(message)s'.

log_images

Whether or not to log images in separate files, in addition to inserting them into the document. Evaluated as a boolean, regardless of the actual type of the value. It is up to individual tag handlers to respect this setting. This setting is independent of the other logger settings.

This keyword is optional. If omitted, it normally defaults to falsy, but custom tags may chose to interpret it differently.

See also

Image Logging

log_stderr

Whether or not to print log output to the standard error stream. Evaluated as a boolean, regardless of the actual type of the value. If truthy, all messages with level greater than or equal to stderr_level are written to standard error.

This keyword is optional. If omitted, it defaults to falsy, and stderr_level is ignored.

log_stdout

Whether or not to print log output to the standard output stream. Evaluated as a boolean, regardless of the actual type of the value. If truthy, all messages with level greater than or equal to stdout_level are written to standard error.

If falsy, stdout_level is ignored.

If log_stderr is set to truthy along with this keyword, then messages with a logging level greater than or equal to stderr_level will not be sent to standard output.

This keyword is optional. It defaults to truthy.

output_docx

The name of the generated document. If a file with the same name already exists, the program’s behavior is determined by the overwrite_output keyword.

This keyword is mandatory.

overwrite_output

Determines how to handle the case where the file named by output_docx already exists. The following options are recognized:

'raise'
Raise an error and abort.
'rename'
Keep prompting the user for a new file name until they select one that does not already exist. A default suggestion is generated, which can be selected automatically.
'silent'
Overwrite the existing file without further comment.
'warn'
Overwrite the existing file, but with a warning.

Any other value will trigger a fatal error.

This keyword is optional. It defaults to 'raise'.

stderr_level

The minimum threshold for messages that go to the standard error stream. This acts as an (exclusive) upper threshold for messages sent to the standard output stream as well. This level does not affect the level being logged to the file. The value can be a (case insensitive) string level name, a number or one of the constants in the logging module.

If log_stderr is missing or falsy, this level will be ignored.

This keyword is optional. It defaults to logging.ERROR.

stdout_level

The minimum threshold for messages that go to the standard output stream. This level does not affect the level being logged to the file. The value can be a (case insensitive) string level name, a number or one of the constants in the logging module.

If log_stderr is truthy, stderr_level provides the exclusive upper threshold for messages sent to standard output.

If log_stdout is falsy, this level will be ignored.

This keyword is optional. It defaults to logging.WARNING.

tags

Sets up user-defined tags for the XML Template. This is a mapping of tag names to user-defined Tag Descriptors. Values may be strings containing the fully-qualified names of the object to import, or the objects themselves. Both of the values in the following example are valid:

import my.custom.module

tags = {
    'tag1': my.cusom.module.descriptor,
    'tag2': 'my.custom.module.descriptor',
}

This keyword is optional.

User-Defined Keywords

User-defined keywords provide the data used to perform keyword replacements for the <kwd> tags in the XML Template. They provide the per-report configuration of the basic content. User-defined keywords are conventionally identified by a CamelCase naming scheme. While the naming is not strictly a requirement, any lowercase_and_underscore name is automatically reserved for use as a system keyword.

Computed Keywords

In addition to direct definition in the IPC File / IIF Files and insertion via the <kwd> tag, keywords can be computed through the <expr> tag in the XML Template. The namespace in which an <expr> tag is evaluated is the existing mapping of keywords defined up to that point. The result is a new user-defined keyword. System keywords placed in an <expr> tag are not guaranteed to work correctly. This form of computation is provided to de-clutter the IPC File, and avoid information redundancy in the frequently edited file.