mformat-ext

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)

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, this 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

API 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

Output file formats

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

Test summary

• Test result: 2831 passed in 48s
• No flake8 warnings.
• No mypy errors found.
• Python layout report not available.
• Built version(s): 0.7
• Build and test using Python 3.14.6