msl-odt

The methods provided by the msl-odt package are listed below.

A module to help write ODT documents with Python.

Document ¤

Document(filename, reopen=False)

Bases: object

A class to create and manipulate Open Document Text (ODT) files.

This class provides methods to add various elements to an ODT document, including headings, paragraphs, figures, equations, tables, and lists. It supports features such as converting URLs into hyperlinks, managing styles, and handling tables with optional formatting and captions.

Attributes:

Name	Type	Description
`filename`	`Union[str, Path]`	The name of the file to create or open.
`doc`	`OpenDocumentText`	The OpenDocumentText object representing the ODT document.

Methods:

Name	Description
`addheading1`	Adds a Level 1 heading to the document.
`addheading2`	Adds a Level 2 heading to the document.
`addtext`	Adds a new paragraph to the document and converts URLs to hyperlinks.
`addfigure`	Adds an image to the document with an optional caption.
`addequation`	Adds a mathematical equation to the document.
`addpagebreak`	Adds a page break to the document.
`initialize_table_count`	Updates the table count if there are existing tables.
`maketabledata`	Merges multiple columns of data into a row-major list of lists for table creation.
`addtable`	Adds a table to the document with optional formatting.
`addlist`	Adds a hierarchical list to the document.
`addbulletedlist`	Adds a bulleted list to the document.
`addnumberedlist`	Adds a numbered list to the document.

addbulletedlist ¤

addbulletedlist(item_list)

Add a bulleted list to .odt document.

See addlist for further options.

Parameters:

Name	Type	Description	Default
`item_list`	`List[Any]`	A list of objects representing the items to be included in the list.	required

Returns:

Type	Description
`None`

addequation ¤

addequation(
    math_text, math_width=None, math_height=None, wrap=False
)

Add some math as a separate paragraph.

Create an annotation using the Star Math 5.0 notation used by Open Office and others. See: wiki.openoffice.org/wiki/Documentation/ OOoAuthors_User_Manual/Writer_Guide/Math_commands_-_Reference for details on the command set.

The annotation is put into a frame which is attached to a paragraph. The width and height arguments can be used to ensure the math displays correctly. Values for math_width and math_height can be found by creating the math in a Open Document editor and then inspecting the created .xml If no sizing is given the equation can still be manually resized by opening and editing the .odt file.

Parameters:

Name	Type	Description	Default
`math_text`	`str`	A string containing the equation in Star Math 5.0 notation. Example '"Area" = %pi R^2'	required
`math_width`	`str`	Width of the math text frame. Example: "5.3cm"	`None`
`math_height`	`str`	Height of the math text frame. Example: "3.5cm"	`None`
`wrap`	`bool`	Whether or not the surrounding text is wrapped. Default is False. Example 'wrap=True'	`False`

Returns:

Type	Description
`None.`

addfigure ¤

addfigure(
    image_filename,
    image_width,
    image_height,
    caption_text=None,
)

Add an image to document as a separate paragraph, with optional caption.

The image needs to be added to the .odt document and then as an element to a frame which is added to a paragraph, which is added to the doc. The name of the frame is set to the image filename.

Optional caption text can be added. No auto-numbering is done so to obtain numbered figures use, e.g., caption_text='Figure 123: Desired caption text'.

If the file does not exist text to that effect is added to the document as a placeholder.

Parameters:

Name	Type	Description	Default
`image_filename`	`str`	The image file to add to the ODT file. File name as a string, not a file handle.	required
`image_width`	`str`	Width of the image in the document. Example: "8cm"	required
`image_height`	`str`	Height of the image in the document. Example: "5cm"	required
`caption_text`	`Optional[str]`	Optional text added to a second paragraph as plain text. There is no auto-numbering so to obtain numbered figures use, e.g., caption_text='Figure 123: Desired caption text'.	`None`

Returns:

Type	Description
`None.`

addheading1 ¤

addheading1(heading_text)

Add a Level 1 Heading to document.

Parameters:

Name	Type	Description	Default
`heading_text`	`str`	The heading text to add.	required

Returns:

Type	Description
`None.`

addheading2 ¤

addheading2(heading_text)

Add a Level 2 heading to document.

Parameters:

Name	Type	Description	Default
`heading_text`	`str`	The heading text to add.	required

Returns:

Type	Description
`None.`

addlist ¤

addlist(item_list, item_level=None, list_style=None)

Add a hierarchical list (bulleted or numbered) to .odt document.

Parameters:

Name	Type	Description	Default
`item_list`	`List[Any]`	A list of objects representing the items to be included in the list.	required
`item_level`	`Optional[List[int]]`	A list of integers representing the hierarchical level for each item. If not provided, all items are at the top level (level 1).	`None`
`list_style`	`str`	The style of the list, either bulleted or numbered. Must be one of the two valid values: 'bullet' or 'number'. If no list_style is provided, 'bullet' is used.	`None`

Raises:

Type	Description
`ValueError`	If `item_level` has fewer elements than `item_list` or if an invalid list structure is detected.
`ValueError`	If `list_style` is not 'bullet' or 'number'.

addnumberedlist ¤

addnumberedlist(item_list)

Add a numbered list to .odt document.

See addlist for further options.

Parameters:

Name	Type	Description	Default
`item_list`	`List[Any]`	A list of objects representing the items to be included in the list.	required

Returns:

Type	Description
`None`

addpagebreak ¤

addpagebreak()

Add a pagebreak to the document.

Add a page break by adding an empty paragraph of style afterbreakstyle, which is a paragraph with specific properties (specifically a pagebreak after it).

Returns:

Type	Description
`None.`

addtable ¤

addtable(
    table_data,
    column_width=None,
    table_width=None,
    decimal_tab=None,
    caption_text=None,
    border_style=None,
)

Add table with optional column or table width/s and header row.

Table data is row-major form (rows then columns) and widths can be specified either individually or a single value for all columns or just a single table width. If no widths are specified the columns are all made as wide as possible. Additionally, numerical values (as str) can be aligned on the decimal point character by specifying a tab stop for that column.

The optional caption is added to a second paragraph as plain text. There is no auto-numbering so to obtain numbered tables use, e.g., caption_text='Table 123: Desired caption text'.

Optional border styles can be applied to the table. The default is no borders.

See also: companion function maketable_data which combines multiple arguments (columns) and merges them into a row-major list of lists suitable for input to addtable. A header row can either be a separate argument or pre-pended as required. E.g.: 1) addtable(maketabledata(column1data, column2data, header_row=header_row)) or 2) addtable([header_row] + maketabledata(column1data, column2data))

Parameters:

Name	Type	Description	Default
`table_data`	`List[List[str]]`	A list of lists containing text for each row of the table. Example `[['User', 'Cost ($)'] ['Alice', '1.23'] ['Bob', '12.3']]`	required
`column_width`	`Optional[Union[List[Union[int, float]], Union[int, float]]]`	Optional list of ints or floats specifying widths of columns (cm). If a single value is provided, it is used for all columns. Example: `[1, 2.3]` or `4`, or `None`.	`None`
`table_width`	`Optional[Union[int, float]]`	Optional total width of table (cm). If specified and column_width is not provided, column widths will be calculated as `table_width / number of columns`. If both column_width and table_width are provided column_width will be used and a warning generated. Example: `3.2`	`None`
`decimal_tab`	`Optional[List[Optional[Union[float, int]]]]`	Optional list of floats specifying the position (cm) of the decimal tab stop for each column from the left column margin. If a column does not require a tab stop, use None. Example: `[None, 1.23, 2]`	`None`
`caption_text`	`Optional[str]`	Optional text added to a second paragraph as plain text. There is no auto-numbering so to obtain numbered figures use, e.g., `caption_text='Figure 123: Desired caption text'`.	`None`
`border_style`	`Optional[str]`	Optional text specifying what borders to draw on the table. Currently, "None", "Header Row" or "All". Default is None. Note: The `MSL Style Manual` prefers "Header Row".	`None`

Returns:

Type	Description
`None.`

addtext ¤

addtext(text)

Add a new paragraph to document.

Parameters:

Name	Type	Description	Default
`text`	`str`	Text to add. The use of `\t` and `\n` are supported. Uses ODFPY `teletype` function to handle whitespace. Detects URLs starting with `http://` or `https://` and converts them to hyperlinks.	required

Returns:

Type	Description
`None.`

close ¤

close()

Save and close file

Returns:

Type	Description
`None.`

define_styles ¤

define_styles()

Define styles for odt document.

initialize_table_count ¤

initialize_table_count()

Update table_count if there are any existing tables.

Each table has a unique style named based on the table count. When appending to a document it is necessary to first count existing tables to ensure styles of any new tables do not overwrite previous table styles.

Returns:

Type	Description
`None.`

maketabledata ¤

maketabledata(*args, header_row=None)

Merge variables (columns) into row-major list of lists for table creation.

Each column (variable) is provided as a separate argument, which can be a list, numpy array, or any iterable. Formats float or int items to str.

For more precise formatting, convert data to str before calling e.g.: [f'{i:0.2f} for i in my_variable] [f'{i:0.4E} for i in my_variable] etc.

An optional header row can be supplied as the last argument. It must be supplied as a keyword argument e.g.: maketabledata(col1, col2, header_row=['Name', 'Age'])

Parameters:

Name	Type	Description	Default
`*args`	`Iterable[Any]`	Variable number of iterables (e.g., `list`s, `numpy` arrays etc.), each representing a column. Raises error if iterables have different lengths.	`()`
`header_row`	`Optional[List[str]]`	Optional list of labels for header row. Must be given as a keyword argument e.g. `table_data = maketabledata(column1data, column2data, header_row=headerrowdata)` Default is `None`, which means only column data are provided. In this case the header row can be prepended e.g.: `table_data = [headerrowdata] + maketabledata(column1data, column2data)`	`None`

Returns:

Type	Description
`list of list : Row-major data where each inner list represents a row of the table.`

save ¤

save()

Save file

Returns:

Type	Description
`None.`