Skip to main content
Version: 12.9.0

viktor.external.word

WordFileComponent

class viktor.external.word.WordFileComponent(identifier)

Bases: abc.ABC

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

WordFileTag

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

Bases: viktor.external.word.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

WordFileImage

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

Bases: viktor.external.word.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 (Optional[int]) – optional parameter for sizing. in Pt

  • height (Optional[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

WordFileError

exception viktor.external.word.WordFileError

Bases: Exception

WordFileResult

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

bytes

WordFileTemplate

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

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.

Return type

WordFileResult

property result: viktor.external.word.WordFileResult
Return type

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)
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

WordFileError – when duplicate tags are defined