Skip to main content
Version: 14

viktor.external.word

WordFileComponent​

class viktor.external.word.WordFileComponent(identifier)

Bases: ABC

Abstract base class for specific word file components, such as tags, images…

WordFileImage​

class viktor.external.word.WordFileImage(file, identifier, width=None, height=None)

Bases: WordFileComponent

Add an image in a Word file template. When neither width or height is provided, the original size is used. When only one is provided, the other is scaled. When both are provided, both are used and the original aspect ratio might be changed.

Parameters:

  • file (BinaryIO) – image to be placed at the tag location

  • identifier (str) – used to find the location in the template

  • width (int) – optional parameter for sizing. in Pt

  • height (int) – optional parameter for sizing. in Pt

classmethod from_path(file_path, identifier, width=None, height=None)

Create a WordFileImage from an image defined by its file path.

Return type:

WordFileImage

WordFileResult​

class viktor.external.word.WordFileResult(*, file_content=None)
property file_content: bytes

WordFileTag​

class viktor.external.word.WordFileTag(identifier, value)

Bases: WordFileComponent

Add a value in a Word file template by tag.

Parameters:

  • identifier (str) – used to find the location in the template

  • value (object) – what needs to be placed at tag location

WordFileTemplate​

class viktor.external.word.WordFileTemplate(file, components)

Note

Prefer to use the function render_word_file() instead.

Fill wordfile template with components (e.g. text, image).

Note that the template file should be a BytesIO object of a .docx file (not .doc).

Example usage:

>>> file = BytesIO(b'file')
>>> image = BytesIO(b'image')
>>>
>>> tags = [
>>>    WordFileTag('x', 1),
>>>    WordFileTag('y', 2),
>>>    WordFileImage(image, 'fig_tag', width=300),
>>> ]
>>> word_file_template = WordFileTemplate(file, tags)
>>> result = word_file_template.render()
>>> word_file = result.file_content
Parameters:

  • file (BytesIO) – BytesIO object of the Word template

  • components (List[WordFileComponent]) – items that need to be inserted in the template

classmethod from_path(file_path, components)
Parameters:

  • file_path (Union[str, bytes, PathLike]) – Complete path including extension

  • components (List[WordFileComponent]) – items that need to be inserted in the template

Return type:

WordFileTemplate

render()

This function renders the docx template and returns the resulting file. :rtype: WordFileResult

Note

This method needs to be mocked in (automated) unit and integration tests.

property result: WordFileResult

render_word_file​

viktor.external.word.render_word_file(template, components)

Fill Word file with components (e.g. text, image).

Example usage:

components = [
   WordFileTag('x', 1),
   WordFileImage(image, 'fig_tag', width=300),
]

template_path = Path(__file__).parent / 'my' / 'relative' / 'path' / 'template.docx'
with open(template_path, 'rb') as template:
    word_file = render_word_file(template, components)

Note

This method needs to be mocked in (automated) unit and integration tests.

Parameters:

  • template (BinaryIO) – Word file template of type .docx (not .doc)

  • components (List[WordFileComponent]) – components to fill the template with

Return type:

File

Returns:

File object containing the rendered Word file

Raises:

viktor.errors.WordFileError when rendering fails