mformat 0.5

Uniform way to write simple text to different file formats

mformat

The mformat package contains a number of classes providing a uniform way for a python program to write to a number of different file formats.

The primary intended use is for text output from a python program, where the programmer would like the user to be able to select the output file formats. Some users may want the text as a Microsoft Word file, others as a LibreOffice Open Document Text file, while still others might want it as Markdown. By using the uniform way of writing provided by mformat the same python code can produce output in a number of different formats.

This is intended to provide an easy and uniform way to produce information in different formats. The emphasis is on getting the same information into the different formats. This will allow you to get a correct (but perhaps rudimentary) document in several formats. If you want to produce the most esthetically pleasing document in a particular format, this is not the correct library to use.

Installing mformat (base package, this package)

The base package contains support for the output formats that are supported with a minimum of dependencies. Use this if you for some reason want to avoid extra dependencies.

If you want to use it, install it using pip from https://pypi.org/project/mformat . There is no need to download anything from Bitbucket to write Python programs that use the library.

Installing base mformat on mac and Linux

pip3 install --upgrade mformat

Installing base mformat on Microsoft Windows

pip install --upgrade mformat

Installing mformat-ext (extended package)

The extended package contains support also for output formats that require some additional dependencies. Use this if you want the full selection of output formats.

If you want to use it, install it using pip from https://pypi.org/project/mformat-ext . There is no need to download anything from Bitbucket to write Python programs that use the library.

Installing extended mformat on mac and Linux

pip3 install --upgrade mformat-ext

Installing extended mformat on Microsoft Windows

pip install --upgrade mformat-ext

What it does

The main features supported in a uniform way for all supported output file formats are:

• Factory function that takes file format and output file name as arguments

• It opens and closes a file in the selected format, with protection against accidentically overwriting an existing file

• The recommended way to use it is as a context manager in a with-clause, opening and closing the file

• Headings (several levels)

• Paragraphs

• Nested bullet point lists

• Nested numbered point lists

• Mixed nested numbered point and bullet point lists

• Tables

• URLs in paragraphs, headings, numbered point list items and in bullet point list items

Design of program that uses mformat

It is recommended that the ouput function(s) of the a Python program using mformat should have a with-clause getting the formatting object from the factory (easiest with with create_mf(file_format=fmt, file_name=output_file_name) as ).

In the context of the with-clause the programmer just calls a minimum of member functions:

• new_paragraph to start a new paragraph with some provided text content.

• new_heading to start a new heading with some provided text content.

• new_bullet_item to start a new bullet point list item with some provided text content, and if needed to start the bullet point list with the bullet point item.

• new_numbered_point_item to start a new numbered point list item with some provided text content, and if needed to start the numbered point list with the number point list item.

• new_block_quote to start a new block quote with some provided text content.

• add_text to add more text to an already started paragraph, heading, block quote, numbered point list item, bullet point list item or numbered point list item.

• add_url to add a URL (link) to an already started paragraph, heading, block quote, numbered point list item, bullet point list item or numbered point list item.

• add_code_in_text to add some short text (function name, variable name, etc.) as code to an already started paragraph, heading, block quote, bullet point list item or numbered point list item.

• new_table to start a new table with the provided first row.

• add_table_row to add another row to an already started table.

• write_complete_table to write a table all at once.

• write_code_block to write some preformatted text as a code block

There are no member functions to end or close any document item. Each document item is automatically closed as another docuemnt item is started (or when closing the file at the end of the context manager scope). new_bullet_item and new_numbered_point_item take an optional level argument, that is used to change to another nesting level.

Example programs

A number of minimal but complete example programs are provided to help the programmer new to mformat. See list of examples .

API documentation

PI documentation automatically extracted from the Python code and docstrings are available here for the public API for programmers using the API and here for the protected API for programmers that want to extend the API by adding their own derived class that provide some other output format.

Even though some may like reading API documentation, the example programs probably provide a better introduction.

Version history

Version	Date	Python version	Description
0.5	07 Mar 2026	3.12 or newer	Added RTF, TXT and reST formats
0.4	21 Feb 2026	3.12 or newer	Added block quote support
0.3	18 Feb 2026	3.12 or newer	Improved API and fixes
0.2.2	31 Jan 2026	3.12 or newer	Dependency corrected
0.2.1	30 Jan 2026	3.12 or newer	Minor documentation fix
0.2	30 Jan 2026	3.12 or newer	First released version

Output file formats

The following table provides information about in which version support for a format was introduced.

Format	Full name of format	Which package	Starting at version
docx	Microsoft Word	mformat-ext	0.2
html	HTML Web page	mformat	0.2
md	Markdown	mformat	0.2
odt	Open Document Text	mformat-ext	0.2
reST	reStructured Text	mformat	0.5
rtf	Rich Text Format	mformat-ext	0.5
txt	Plain text	mformat	0.5

API changes in version 0.3 (deprecated methods)

In version 0.2.x the public API was build around methods that started document items, like start_paragraph. However, experience showed that this was not intuitive for the user. Many users were trying to use end or stop methods (that do not exist) in pair with the start methods. To address this, the public API was changed in version 0.3.0 to use methods named new something, like new_paragraph. With this naming the intuition should hopefully not tell users to look for end or stop methods (that do not exist). People have also pointed out that phrases like "new paragraph" are commonly used in dictation.

The old methods are still available, but are deprecated and will be removed in some future version.

New method	Deprecated method
new_paragraph	start_paragraph
new_heading	start_heading
new_bullet_item	start_bullet_item
new_numbered_point_item	start_numbered_point_item
new_table	start_table

Test summary

• Test result: 2578 passed in 26s
• No Flake8 warnings.
• No mypy errors found.
• Built version(s): 0.5
• Build and test using Python 3.14.3