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.
Contents
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:
- data_config Required for all documents that use plugins.
- input_xml
- output_docx
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).
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
.
See also
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.
See also
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'
.
See also
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
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.
See also
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.
See also
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
.
See also
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
.
See also
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.