mformat 0.3
Uniform way to write simple text to different file formats
Requires Python: >=3.12

# 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](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

````sh
pip3 install --upgrade mformat
````

### Installing base mformat on Microsoft Windows

````sh
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](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

````sh
pip3 install --upgrade mformat-ext
````

### Installing extended mformat on Microsoft Windows

````sh
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.

- `add_text` to add more text to an already started paragraph, heading, bullet
  point list item or numbered point list item.

- `add_url` to add a URL (link) to an already started paragraph, heading, 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, 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](https://bitbucket.org/tom-bjorkholm/mformat/src/master/example/README.md)
.

## API documentation

PI documentation automatically extracted from the Python code and docstrings are
available
[here for the public API](https://bitbucket.org/tom-bjorkholm/mformat/src/master/doc/api.md)
for programmers using the API and
[here for the protected API](https://bitbucket.org/tom-bjorkholm/mformat/src/master/doc/protected_api.md)
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](https://bitbucket.org/tom-bjorkholm/mformat/src/master/example/README.md)
probably provide a better introduction.

## Version history

| Version | Date        | Python version | Description             |
|---------|-------------|----------------|-------------------------|
| 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                 |

## 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: 1480 passed in 15s
- No Flake8 warnings.
- No mypy errors found.
- 0.3 built and tested using python version: Python 3.14.3