mformat-ext 0.2__py3-none-any.whl

mformat_ext/__init__.py

@@ -0,0 +1,6 @@
+#! /usr/local/bin/python3
+"""Initialize the mformat_ext package."""
+
+# Copyright (c) 2025 - 2026 Tom Björkholm
+# MIT License
+#

mformat_ext/mformat_docx.py

@@ -0,0 +1,428 @@
+#! /usr/local/bin/python3
+"""Extension of the MultiFormat class for DOCX files."""
+
+# Copyright (c) 2025 - 2026 Tom Björkholm
+# MIT License
+#
+
+from typing import Optional, Callable
+from docx import Document
+from docx.document import Document as DocumentObject
+from docx.text.paragraph import Paragraph
+from docx.shared import Inches, Twips
+from docx.oxml.ns import qn
+from docx.oxml import OxmlElement
+from mformat.mformat import FormatterDescriptor, MultiFormat
+from mformat.mformat_state import MultiFormatState, Formatting
+
+
+class MultiFormatDocx(MultiFormat):
+    """Extension of the MultiFormat class for DOCX files."""
+
+    def __init__(self, file_name: str, url_as_text: bool = False,
+                 file_exists_callback: Optional[Callable[[str], None]] = None):
+        """Initialize the MultiFormatDocx class.
+
+        Args:
+            file_name: The name of the file to write to.
+            url_as_text: Format URLs as text not clickable URLs.
+            file_exists_callback: A callback function to call if the file
+                                  already exists. Return to allow the file to
+                                  be overwritten. Raise an exception to prevent
+                                  the file from being overwritten.
+                                  (May for instance save existing file as
+                                  backup.)
+                                  (Default is to raise an exception.)
+        """
+        self.doc: DocumentObject = Document()
+        self.current_paragraph: Optional[Paragraph] = None
+        super().__init__(file_name=file_name, url_as_text=url_as_text,
+                         file_exists_callback=file_exists_callback)
+
+    @classmethod
+    def file_name_extension(cls) -> str:
+        """Get the file name extension for the formatter."""
+        return '.docx'
+
+    @classmethod
+    def get_arg_desciption(cls) -> FormatterDescriptor:
+        """Get the description of the arguments for the formatter."""
+        return FormatterDescriptor(name='docx', mandatory_args=[],
+                                   optional_args=[])
+
+    def open(self) -> None:
+        """Open the file.
+
+        Avoid using this method directly.
+        Use as a context manager instead, using a with statement.
+        """
+        self.doc.save(self.file_name)
+
+    def _close(self) -> None:
+        """Close the file.
+
+        Avoid using this method directly.
+        Use as a context manager instead, using a with statement.
+        """
+        if self.state == MultiFormatState.EMPTY:
+            return
+        self.doc.save(self.file_name)
+
+    def _write_file_prefix(self) -> None:
+        """Write the file prefix.
+
+        For DOCX files, this is a no-op since the document
+        structure is handled by python-docx.
+        """
+
+    def _write_file_suffix(self) -> None:
+        """Write the file suffix.
+
+        For DOCX files, this is a no-op since the document
+        structure is handled by python-docx.
+        """
+
+    def _start_paragraph(self) -> None:
+        """Start a paragraph."""
+        self.current_paragraph = self.doc.add_paragraph()
+
+    def _end_paragraph(self) -> None:
+        """End a paragraph."""
+        self.current_paragraph = None
+
+    def _start_heading(self, level: int) -> None:
+        """Start a heading.
+
+        Args:
+            level: The level of the heading (1-9).
+        """
+        self.current_paragraph = self.doc.add_heading(level=level)
+
+    def _end_heading(self, level: int) -> None:
+        """End a heading.
+
+        Args:
+            level: The level of the heading (1-9).
+        """
+        self.current_paragraph = None
+
+    def _write_text(self, text: str, state: MultiFormatState,
+                    formatting: Formatting) -> None:
+        """Write text into current item (paragraph, bullet list item, etc.).
+
+        Args:
+            text: The text to write into the current item.
+            state: The state of the current item.
+            formatting: The formatting of the text.
+        """
+        if self.current_paragraph is None:
+            raise RuntimeError('No current paragraph to write text into')
+        run = self.current_paragraph.add_run(text)
+        if formatting.bold:
+            run.bold = True
+        if formatting.italic:
+            run.italic = True
+
+    def _write_url(self, url: str, text: Optional[str],
+                   state: MultiFormatState,
+                   formatting: Formatting) -> None:
+        """Write a URL into current item (paragraph, bullet list item, etc.).
+
+        Args:
+            url: The URL to write into the current item.
+            text: The text to display for the URL.
+            state: The state of the current item.
+            formatting: The formatting of the text.
+        """  # pylint: disable=too-many-arguments,too-many-positional-arguments
+        if self.current_paragraph is None:
+            raise RuntimeError('No current paragraph to write URL into')
+        if not text:
+            text = url
+        self._add_hyperlink(self.current_paragraph, url, text, formatting)
+
+    def _add_hyperlink(self, paragraph: Paragraph, url: str,
+                       text: str, formatting: Formatting) -> None:
+        """Add a clickable hyperlink to a paragraph.
+
+        Args:
+            paragraph: The paragraph to add the hyperlink to.
+            url: The URL for the hyperlink.
+            text: The display text for the hyperlink.
+            formatting: The formatting (bold/italic) for the text.
+        """
+        # Create relationship for the hyperlink
+        # The relationship type for external hyperlinks
+        rel_type = ('http://schemas.openxmlformats.org/officeDocument/'
+                    '2006/relationships/hyperlink')
+        r_id = self.doc.part.relate_to(url, rel_type, is_external=True)
+        # Create hyperlink element
+        hyperlink = OxmlElement('w:hyperlink')
+        hyperlink.set(qn('r:id'), r_id)
+        # Create run inside hyperlink
+        run_element = OxmlElement('w:r')
+        run_props = OxmlElement('w:rPr')
+        # Add blue color for link appearance
+        color = OxmlElement('w:color')
+        color.set(qn('w:val'), '0000FF')
+        run_props.append(color)
+        # Add underline for link appearance
+        underline = OxmlElement('w:u')
+        underline.set(qn('w:val'), 'single')
+        run_props.append(underline)
+        # Add bold if requested
+        if formatting.bold:
+            bold = OxmlElement('w:b')
+            run_props.append(bold)
+        # Add italic if requested
+        if formatting.italic:
+            italic = OxmlElement('w:i')
+            run_props.append(italic)
+        run_element.append(run_props)
+        # Add text element
+        text_element = OxmlElement('w:t')
+        text_element.text = text
+        run_element.append(text_element)
+        hyperlink.append(run_element)
+        # Append hyperlink to paragraph
+        # pylint: disable=protected-access
+        paragraph._p.append(hyperlink)
+
+    def _start_bullet_list(self, level: int) -> None:
+        """Start a bullet list.
+
+        Args:
+            level: The level of the bullet list (1-9).
+        """
+        assert isinstance(level, int)
+        # In python-docx, lists are created by setting paragraph styles
+        # No explicit list start/end is needed
+
+    def _end_bullet_list(self, level: int) -> None:
+        """End a bullet list.
+
+        Args:
+            level: The level of the bullet list (1-9).
+        """
+        assert isinstance(level, int)
+        # In python-docx, lists are created by setting paragraph styles
+        # No explicit list start/end is needed
+
+    def _start_bullet_item(self, level: int) -> None:
+        """Start a bullet item.
+
+        Args:
+            level: The level of the bullet item (1-9).
+        """
+        assert isinstance(level, int)
+        self.current_paragraph = self.doc.add_paragraph(style='List Bullet')
+        # Set the indentation level for nested lists
+        if level > 1:
+            self.current_paragraph.paragraph_format.left_indent = \
+                Inches(0.5 * (level - 1))
+
+    def _end_bullet_item(self, level: int) -> None:
+        """End a bullet item.
+
+        Args:
+            level: The level of the bullet item (1-9).
+        """
+        assert isinstance(level, int)
+        self.current_paragraph = None
+
+    def _start_numbered_list(self, level: int) -> None:
+        """Start a numbered list.
+
+        Args:
+            level: The level of the numbered list (1-9).
+        """
+        assert isinstance(level, int)
+        # In python-docx, lists are created by setting paragraph styles
+        # No explicit list start/end is needed
+
+    def _end_numbered_list(self, level: int) -> None:
+        """End a numbered list.
+
+        Args:
+            level: The level of the numbered list (1-9).
+        """
+        assert isinstance(level, int)
+        # In python-docx, lists are created by setting paragraph styles
+        # No explicit list start/end is needed
+
+    def _start_numbered_item(self, level: int, num: int,
+                             full_number: str) -> None:
+        """Start a numbered item.
+
+        Args:
+            level: The level of the numbered item (1-9).
+            num: The number of the item.
+            full_number: The full number of the item including all levels.
+        """
+        assert isinstance(level, int)
+        assert isinstance(num, int)
+        assert isinstance(full_number, str)
+        # Use regular paragraph with manual numbering for hierarchical numbers
+        # The 'List Number' style only supports simple sequential numbering
+        self.current_paragraph = self.doc.add_paragraph()
+        # Set up hanging indent with tab stop for proper text alignment
+        # Using twips: 720 twips = 0.5 inches
+        number_width_twips = 720  # Space reserved for the number
+        base_indent_twips = 720 * (level - 1)  # Additional indent per level
+        text_position_twips = base_indent_twips + number_width_twips
+        self.current_paragraph.paragraph_format.left_indent = \
+            Twips(text_position_twips)
+        self.current_paragraph.paragraph_format.first_line_indent = \
+            Twips(-number_width_twips)
+        # Add tab stop at text position so text after number aligns with
+        # wrapped lines (both start at the same position)
+        self._add_tab_stop(self.current_paragraph, text_position_twips)
+        # Add the hierarchical number followed by tab (not space)
+        self.current_paragraph.add_run(full_number)
+        self.current_paragraph.add_run('\t')
+
+    @staticmethod
+    def _add_tab_stop(paragraph: Paragraph, position_twips: int) -> None:
+        """Add a left-aligned tab stop to a paragraph.
+
+        Args:
+            paragraph: The paragraph to add the tab stop to.
+            position_twips: The position of the tab stop in twips.
+        """
+        # pylint: disable=protected-access
+        p_pr = paragraph._p.get_or_add_pPr()
+        tabs = OxmlElement('w:tabs')
+        tab = OxmlElement('w:tab')
+        tab.set(qn('w:val'), 'left')
+        tab.set(qn('w:pos'), str(position_twips))
+        tabs.append(tab)
+        p_pr.append(tabs)
+
+    def _end_numbered_item(self, level: int, num: int) -> None:
+        """End a numbered item.
+
+        Args:
+            level: The level of the numbered item (1-9).
+            num: The number of the item.
+        """
+        assert isinstance(level, int)
+        assert isinstance(num, int)
+        self.current_paragraph = None
+
+    def _start_table(self, num_columns: int) -> None:
+        """Start a table.
+
+        Args:
+            num_columns: The number of columns in the table.
+        """
+        assert isinstance(num_columns, int)
+        # Add an empty paragraph before the table for spacing
+        # This separates the table from previous content
+        self.doc.add_paragraph()
+        # Note: Actual table creation happens in _write_table_first_row
+
+    def _end_table(self, num_columns: int, num_rows: int) -> None:
+        """End a table.
+
+        Args:
+            num_columns: The number of columns in the table.
+            num_rows: The number of rows in the table.
+        """
+        assert isinstance(num_columns, int)
+        assert isinstance(num_rows, int)
+        # Add an empty paragraph after the table for spacing
+        self.doc.add_paragraph()
+
+    def _write_table_first_row(self, first_row: list[str],
+                               formatting: Formatting) -> None:
+        """Write the first row of a table.
+
+        Args:
+            first_row: The first row of the table.
+            formatting: The formatting of the text in each cell.
+        """
+        assert isinstance(first_row, list)
+        assert isinstance(formatting, Formatting)
+        # Create the table with the first row
+        table = self.doc.add_table(rows=1, cols=len(first_row))
+        table.style = 'Table Grid'
+        # Fill in the first row
+        for idx, cell_text in enumerate(first_row):
+            cell = table.rows[0].cells[idx]
+            para = cell.paragraphs[0]
+            run = para.add_run(cell_text)
+            if formatting.bold:
+                run.bold = True
+            if formatting.italic:
+                run.italic = True
+
+    def _write_table_row(self, row: list[str], formatting: Formatting,
+                         row_number: int) -> None:
+        """Write a row of a table.
+
+        Args:
+            row: The row to add to the table.
+            formatting: The formatting of the text in each cell.
+            row_number: The row number (0-based).
+        """
+        assert isinstance(row, list)
+        assert isinstance(formatting, Formatting)
+        assert isinstance(row_number, int)
+        # Get the last table in the document
+        table = self.doc.tables[-1]
+        # Add a new row
+        new_row = table.add_row()  # type: ignore[no-untyped-call]
+        # Fill in the row
+        for idx, cell_text in enumerate(row):
+            cell = new_row.cells[idx]
+            para = cell.paragraphs[0]
+            run = para.add_run(cell_text)
+            if formatting.bold:
+                run.bold = True
+            if formatting.italic:
+                run.italic = True
+
+    def _start_code_block(self, programming_language: Optional[str]) -> None:
+        """Start a code block.
+
+        Args:
+            programming_language: The programming language of the code block.
+        """
+        assert programming_language is None or \
+            isinstance(programming_language, str)
+        # Create a paragraph with a code/verbatim style
+        # python-docx doesn't have a built-in code style,
+        # so we'll use 'No Spacing' style and monospace font
+        self.current_paragraph = self.doc.add_paragraph()
+        self.current_paragraph.style = 'No Spacing'
+
+    def _end_code_block(self, programming_language: Optional[str]) -> None:
+        """End a code block.
+
+        Args:
+            programming_language: The programming language of the code block.
+        """
+        assert programming_language is None or \
+            isinstance(programming_language, str)
+        self.current_paragraph = None
+
+    def _write_code_block(self, text: str,
+                          programming_language: Optional[str]) -> None:
+        """Write a code block.
+
+        Args:
+            text: The text to add to the code block.
+            programming_language: The programming language of the code block.
+        """
+        assert isinstance(text, str)
+        assert programming_language is None or \
+            isinstance(programming_language, str)
+        if self.current_paragraph is None:
+            raise RuntimeError('No current paragraph to write code into')
+        run = self.current_paragraph.add_run(text)
+        # Set monospace font
+        run.font.name = 'Courier New'
+
+    def _encode_text(self, text: str) -> str:
+        """Encode text (escape special characters)."""
+        # No encoding needed for DOCX
+        return text

mformat_ext/mformat_odt.py

@@ -0,0 +1,666 @@
+#! /usr/local/bin/python3
+"""Extension of the MultiFormat class for DOCX files."""
+
+# Copyright (c) 2025 - 2026 Tom Björkholm
+# MIT License
+#
+
+from typing import Optional, Callable, NamedTuple
+from odfdo import Document, Paragraph, Header, Table, Row, Cell, \
+    Link, List, ListItem, Style, Span, Element
+from mformat.mformat import FormatterDescriptor, MultiFormat
+from mformat.mformat_state import MultiFormatState, Formatting
+
+
+class OdtStyles(NamedTuple):
+    """Styles for ODT files."""
+
+    text_styles: dict[str, Style]
+    font_styles: dict[str, Style]
+    paragraph_styles: dict[str, Style]
+    bold: Style
+    italic: Style
+    bold_italic: Style
+    code: Style
+
+
+class MultiFormatOdt(MultiFormat):
+    """Extension of the MultiFormat class for ODT files."""
+
+    def __init__(self, file_name: str, url_as_text: bool = False,
+                 file_exists_callback: Optional[Callable[[str], None]] = None,
+                 lang: str = 'en-UK'):
+        """Initialize the MultiFormatOdt class.
+
+        Args:
+            file_name: The name of the file to write to.
+            url_as_text: Format URLs as text not clickable URLs.
+            file_exists_callback: A callback function to call if the file
+                                  already exists. Return to allow the file to
+                                  be overwritten. Raise an exception to prevent
+                                  the file from being overwritten.
+                                  (May for instance save existing file as
+                                  backup.)
+                                  (Default is to raise an exception.)
+            lang: The language of the document.
+        """
+        self.doc: Document = Document('text')
+        self.doc.set_language(lang)
+        self.current_paragraph: Optional[Paragraph] = None
+        self.odt_table: Optional[Table] = None
+        self.odt_tablenumber: int = 1
+        self.odt_list: list[List] = []
+        self.odt_listitem: Optional[ListItem] = None
+        self.odt_styles: OdtStyles = self._create_odt_styles()
+        self._insert_odt_styles()
+        super().__init__(file_name=file_name, url_as_text=url_as_text,
+                         file_exists_callback=file_exists_callback)
+
+    def _insert_odt_styles(self) -> None:
+        """Insert the ODT styles into the document."""
+        for style in self.odt_styles.text_styles.values():
+            self.doc.insert_style(style)
+        for style in self.odt_styles.font_styles.values():
+            self.doc.insert_style(style)
+        for style in self.odt_styles.paragraph_styles.values():
+            self.doc.insert_style(style)
+        # Insert list styles (Element type for list styles, not StyleBase)
+        self.doc.insert_style(
+            self._create_numbered_list_style())  # type: ignore[arg-type]
+        self.doc.insert_style(
+            self._create_bullet_list_style())  # type: ignore[arg-type]
+
+    @staticmethod
+    def _create_list_level_properties(level_num: int) -> Element:
+        """Create list-level-properties element for indentation.
+
+        Args:
+            level_num: The list level number (1-9).
+
+        Returns:
+            An Element representing style:list-level-properties.
+        """
+        # Base indentation values (in cm)
+        base_indent = 0.635  # text indent (negative, for hanging indent)
+        base_margin = 1.27   # margin left per level
+
+        props = Element.from_tag('style:list-level-properties')
+        props.set_attribute('text:list-level-position-and-space-mode',
+                            'label-alignment')
+
+        # Add label alignment with indentation
+        label_align = Element.from_tag('style:list-level-label-alignment')
+        label_align.set_attribute('text:label-followed-by', 'listtab')
+        margin_left = base_margin * level_num
+        label_align.set_attribute('text:list-tab-stop-position',
+                                  f'{margin_left:.2f}cm')
+        label_align.set_attribute('fo:text-indent', f'-{base_indent:.3f}cm')
+        label_align.set_attribute('fo:margin-left', f'{margin_left:.2f}cm')
+
+        props.append(label_align)
+        return props
+
+    @staticmethod
+    def _create_numbered_list_style() -> Element:
+        """Create a numbered list style for ODF documents.
+
+        Returns:
+            An Element representing a text:list-style for numbered lists.
+        """
+        list_style = Element.from_tag('text:list-style')
+        list_style.set_attribute('style:name', 'numbered-list')
+        # Add levels 1-9 for nested numbered lists
+        for level_num in range(1, 10):
+            level = Element.from_tag('text:list-level-style-number')
+            level.set_attribute('text:level', str(level_num))
+            level.set_attribute('style:num-suffix', '.')
+            level.set_attribute('style:num-format', '1')
+            # Add indentation properties
+            level.append(
+                MultiFormatOdt._create_list_level_properties(level_num))
+            list_style.append(level)
+        return list_style
+
+    @staticmethod
+    def _create_bullet_list_style() -> Element:
+        """Create a bullet list style for ODF documents.
+
+        Returns:
+            An Element representing a text:list-style for bullet lists.
+        """
+        list_style = Element.from_tag('text:list-style')
+        list_style.set_attribute('style:name', 'bullet-list')
+        # Bullet characters for different levels (bullet, white bullet, square)
+        bullets = ['\u2022', '\u25e6', '\u25aa',
+                   '\u2022', '\u25e6', '\u25aa',
+                   '\u2022', '\u25e6', '\u25aa']
+        # Add levels 1-9 for nested bullet lists
+        for level_num in range(1, 10):
+            level = Element.from_tag('text:list-level-style-bullet')
+            level.set_attribute('text:level', str(level_num))
+            level.set_attribute('text:bullet-char', bullets[level_num - 1])
+            # Add indentation properties
+            level.append(
+                MultiFormatOdt._create_list_level_properties(level_num))
+            list_style.append(level)
+        return list_style
+
+    @staticmethod
+    def _create_code_paragraph_style() -> Style:
+        """Create a code paragraph style with monospace font.
+
+        Returns:
+            A Style object for code blocks with monospace font.
+        """
+        style = Style(
+            name='code',
+            family='paragraph',
+            display_name='code'
+        )
+        # Add text properties for monospace font
+        text_props = Element.from_tag('style:text-properties')
+        text_props.set_attribute('style:font-name', 'Liberation Mono')
+        text_props.set_attribute('fo:font-family', "'Liberation Mono'")
+        text_props.set_attribute('style:font-family-generic', 'modern')
+        text_props.set_attribute('style:font-pitch', 'fixed')
+        # Also set for Asian and Complex text
+        text_props.set_attribute('style:font-name-asian', 'Liberation Mono')
+        text_props.set_attribute('style:font-name-complex', 'Liberation Mono')
+        style.append(text_props)
+        # Add paragraph properties for light gray background
+        para_props = Element.from_tag('style:paragraph-properties')
+        para_props.set_attribute('fo:background-color', '#f0f0f0')
+        para_props.set_attribute('fo:padding', '0.1cm')
+        style.append(para_props)
+        return style
+
+    @staticmethod
+    def _create_link_style(name: str, bold: bool = False,
+                           italic: bool = False) -> Style:
+        """Create a link style with blue color and underline.
+
+        Args:
+            name: The name of the style.
+            bold: Whether the link text should be bold.
+            italic: Whether the link text should be italic.
+
+        Returns:
+            A Style object for links with the specified formatting.
+        """
+        link_color = '#0000ff'  # Blue color for links
+        style = Style(
+            name=name,
+            family='text',
+            display_name=name,
+            area='text',
+            color=link_color,
+            bold=bold,
+            italic=italic
+        )
+        # Add underline to text-properties
+        text_props = style.get_element('style:text-properties')
+        if text_props:
+            text_props.set_attribute('style:text-underline-style', 'solid')
+            text_props.set_attribute('style:text-underline-width', 'auto')
+            text_props.set_attribute('style:text-underline-color', link_color)
+        return style
+
+    def _create_odt_styles(self) -> OdtStyles:
+        """Create the ODT styles needed for documents."""
+        text_styles: dict[str, Style] = {}
+        font_styles: dict[str, Style] = {}
+        paragraph_styles: dict[str, Style] = {}
+        bold_style = Style(name='bold', family='text',
+                           display_name='bold', area='text',
+                           bold=True, italic=False)
+        text_styles['bold'] = bold_style
+        italic_style = Style(name='italic', family='text',
+                             display_name='italic', area='text',
+                             italic=True, bold=False)
+        text_styles['italic'] = italic_style
+        bold_italic_style = Style(name='bold-italic', family='text',
+                                  display_name='bold-italic', area='text',
+                                  bold=True, italic=True)
+        text_styles['bold-italic'] = bold_italic_style
+        # Create code paragraph style with monospace font and background
+        code_style = self._create_code_paragraph_style()
+        paragraph_styles['code'] = code_style
+        # Create link styles with blue color and underline
+        text_styles['link'] = self._create_link_style('link')
+        text_styles['link-bold'] = self._create_link_style(
+            'link-bold', bold=True)
+        text_styles['link-italic'] = self._create_link_style(
+            'link-italic', italic=True)
+        text_styles['link-bold-italic'] = self._create_link_style(
+            'link-bold-italic', bold=True, italic=True)
+        return OdtStyles(text_styles=text_styles, font_styles=font_styles,
+                         paragraph_styles=paragraph_styles, bold=bold_style,
+                         italic=italic_style, bold_italic=bold_italic_style,
+                         code=code_style)
+
+    @staticmethod
+    def _style_name_from_formatting(formatting: Formatting) -> str:
+        """Get the style name from the formatting."""
+        assert isinstance(formatting, Formatting)
+        style_name = ''
+        if formatting.bold:
+            style_name = 'bold'
+            if formatting.italic:
+                style_name += '-italic'
+        elif formatting.italic:
+            style_name = 'italic'
+        return style_name
+
+    @staticmethod
+    def _link_style_name_from_formatting(formatting: Formatting) -> str:
+        """Get the link style name from the formatting.
+
+        Link styles include blue color and underline to be visible as links.
+        """
+        assert isinstance(formatting, Formatting)
+        style_name = 'link'
+        if formatting.bold:
+            style_name += '-bold'
+        if formatting.italic:
+            style_name += '-italic'
+        return style_name
+
+    @classmethod
+    def file_name_extension(cls) -> str:
+        """Get the file name extension for the formatter."""
+        return '.odt'
+
+    @classmethod
+    def get_arg_desciption(cls) -> FormatterDescriptor:
+        """Get the description of the arguments for the formatter."""
+        return FormatterDescriptor(name='odt', mandatory_args=[],
+                                   optional_args=['lang'])
+
+    def open(self) -> None:
+        """Open the file.
+
+        Avoid using this method directly.
+        Use as a context manager instead, using a with statement.
+        """
+        # No need to open the file - it is created when the document is saved
+
+    def _close(self) -> None:
+        """Close the file.
+
+        Avoid using this method directly.
+        Use as a context manager instead, using a with statement.
+        """
+        if self.state == MultiFormatState.EMPTY:
+            return
+        self.doc.save(self.file_name, pretty=True)
+
+    def _write_file_prefix(self) -> None:
+        """Write the file prefix.
+
+        For ODT files, this is a no-op since the document
+        structure is handled by odfdo.
+        """
+
+    def _write_file_suffix(self) -> None:
+        """Write the file suffix.
+
+        For ODT files, this is a no-op since the document
+        structure is handled by odfdo.
+        """
+
+    def _start_paragraph(self) -> None:
+        """Start a paragraph."""
+        self.current_paragraph = Paragraph()
+
+    def _end_paragraph(self) -> None:
+        """End a paragraph."""
+        if self.current_paragraph is not None:
+            self.doc.body.append(self.current_paragraph)
+        self.current_paragraph = None
+
+    def _start_heading(self, level: int) -> None:
+        """Start a heading.
+
+        Args:
+            level: The level of the heading (1-9).
+        """
+        self.current_paragraph = Header(level=level)
+
+    def _end_heading(self, level: int) -> None:
+        """End a heading.
+
+        Args:
+            level: The level of the heading (1-9).
+        """
+        if self.current_paragraph is not None:
+            self.doc.body.append(self.current_paragraph)
+        self.current_paragraph = None
+
+    def _formatted_write(self, paragraph: Paragraph,
+                         formatting: Formatting, text: str) -> None:
+        """Apply formatting to a paragraph or list item.
+
+        In ODF/XML, paragraph.text holds text before any child elements,
+        and each element's tail holds text after that element. To maintain
+        correct text order when mixing formatted and unformatted text, we:
+        - Use Span elements for formatted text (appended as children)
+        - For unformatted text: add to paragraph.text if no children exist,
+          otherwise add to the tail of the last child element.
+        """
+        assert paragraph is not None
+        assert isinstance(paragraph, Paragraph)
+        style = self._style_name_from_formatting(formatting)
+        if style:
+            # Formatted text: create a span with the style and append it
+            span = Span(text=text, style=style)
+            paragraph.append(span)
+        else:
+            # Unformatted text: add to correct position
+            if len(paragraph.children) == 0:
+                # No children yet, add to paragraph.text
+                if paragraph.text:
+                    paragraph.text += text
+                else:
+                    paragraph.text = text
+            else:
+                # Has children, add to the tail of the last child
+                last_child = paragraph.children[-1]
+                if last_child.tail:
+                    last_child.tail += text
+                else:
+                    last_child.tail = text
+
+    def _write_text(self, text: str, state: MultiFormatState,
+                    formatting: Formatting) -> None:
+        """Write text into current item (paragraph, bullet list item, etc.).
+
+        Args:
+            text: The text to write into the current item.
+            state: The state of the current item.
+            formatting: The formatting of the text.
+        """
+        if self.state in (MultiFormatState.PARAGRAPH,
+                          MultiFormatState.HEADING):
+            assert self.current_paragraph is not None
+            self._formatted_write(self.current_paragraph, formatting, text)
+        elif self.state in (MultiFormatState.BULLET_LIST_ITEM,
+                            MultiFormatState.NUMBERED_LIST_ITEM):
+            assert self.odt_listitem is not None
+            assert isinstance(self.odt_listitem.children[-1], Paragraph)
+            self._formatted_write(self.odt_listitem.children[-1],
+                                  formatting, text)
+        else:
+            raise RuntimeError(f'Unexpected state: {self.state.name} for '
+                               f'writing text: {text}')
+
+    def _impl_write_url(self, paragraph: Paragraph,
+                        url: str, text: Optional[str],
+                        formatting: Formatting) -> None:
+        """Implement the writing of a URL into a paragraph or list item."""
+        assert paragraph is not None
+        assert isinstance(paragraph, Paragraph)
+        assert isinstance(formatting, Formatting)
+        if not text:
+            text = url
+        lnk = Link(url=url, text=text)
+        # Use link styles that include blue color and underline
+        lnk.style = self._link_style_name_from_formatting(formatting)
+        paragraph.append(lnk)
+
+    def _write_url(self, url: str, text: Optional[str],
+                   state: MultiFormatState,
+                   formatting: Formatting) -> None:
+        """Write a URL into current item (paragraph, bullet list item, etc.).
+
+        Args:
+            url: The URL to write into the current item.
+            text: The text to display for the URL.
+            state: The state of the current item.
+            formatting: The formatting of the text.
+        """
+        assert state == self.state
+        if self.state in (MultiFormatState.PARAGRAPH,
+                          MultiFormatState.HEADING):
+            assert self.current_paragraph is not None
+            self._impl_write_url(self.current_paragraph, url, text, formatting)
+        elif self.state in (MultiFormatState.BULLET_LIST_ITEM,
+                            MultiFormatState.NUMBERED_LIST_ITEM):
+            assert self.odt_listitem is not None
+            assert isinstance(self.odt_listitem.children[-1], Paragraph)
+            self._impl_write_url(self.odt_listitem.children[-1],
+                                 url, text, formatting)
+        else:
+            raise RuntimeError(f'Unexpected state: {self.state.name} for '
+                               f'writing url: {url} text: {text}')
+
+    def _start_bullet_list(self, level: int) -> None:
+        """Start a bullet list.
+
+        Args:
+            level: The level of the bullet list (1-9).
+        """
+        assert isinstance(level, int)
+        self.odt_list.append(List(style='bullet-list'))
+        self.current_paragraph = None
+
+    def _end_bullet_list(self, level: int) -> None:
+        """End a bullet list.
+
+        Args:
+            level: The level of the bullet list (1-9).
+        """
+        assert isinstance(level, int)
+        if not self.odt_list or len(self.odt_list) != level:
+            print(f'len(odt_list) = {len(self.odt_list)} for bullet list '
+                  f'level = {level} state: {self.state.name}')
+        assert self.odt_list and len(self.odt_list) == level
+        if len(self.odt_list) > 1:
+            # Nested list: append to the last list item of the parent list
+            # In ODF, nested lists must be inside the parent's list item
+            parent_list = self.odt_list[-2]
+            parent_list_item = parent_list.children[-1]
+            parent_list_item.append(self.odt_list[-1])
+        else:
+            self.doc.body.append(self.odt_list[-1])
+        self.odt_list.pop()
+
+    def _start_bullet_item(self, level: int) -> None:
+        """Start a bullet item.
+
+        Args:
+            level: The level of the bullet item (1-9).
+        """
+        assert isinstance(level, int)
+        self.odt_listitem = ListItem()
+        self.odt_listitem.text_content = Paragraph(text_or_element=Paragraph())
+        assert self.odt_listitem is not None
+        self.current_paragraph = None
+
+    def _end_bullet_item(self, level: int) -> None:
+        """End a bullet item.
+
+        Args:
+            level: The level of the bullet item (1-9).
+        """
+        assert isinstance(level, int)
+        assert self.odt_listitem is not None
+        self.odt_list[-1].append(self.odt_listitem)
+        self.odt_listitem = None
+        self.current_paragraph = None
+
+    def _start_numbered_list(self, level: int) -> None:
+        """Start a numbered list.
+
+        Args:
+            level: The level of the numbered list (1-9).
+        """
+        assert isinstance(level, int)
+        self.odt_list.append(List(style='numbered-list'))
+        self.current_paragraph = None
+
+    def _end_numbered_list(self, level: int) -> None:
+        """End a numbered list.
+
+        Args:
+            level: The level of the numbered list (1-9).
+        """
+        assert isinstance(level, int)
+        if not self.odt_list or len(self.odt_list) != level:
+            print(f'len(odt_list) = {len(self.odt_list)} for numbered list '
+                  f'level = {level} state: {self.state.name}')
+        assert self.odt_list and len(self.odt_list) == level
+        if len(self.odt_list) > 1:
+            # Nested list: append to the last list item of the parent list
+            # In ODF, nested lists must be inside the parent's list item
+            parent_list = self.odt_list[-2]
+            parent_list_item = parent_list.children[-1]
+            parent_list_item.append(self.odt_list[-1])
+        else:
+            self.doc.body.append(self.odt_list[-1])
+        self.odt_list.pop()
+
+    def _start_numbered_item(self, level: int, num: int,
+                             full_number: str) -> None:
+        """Start a numbered item.
+
+        Args:
+            level: The level of the numbered item (1-9).
+            num: The number of the item.
+            full_number: The full number of the item including all levels.
+        """
+        assert isinstance(level, int)
+        assert isinstance(num, int)
+        assert isinstance(full_number, str)
+        self.odt_listitem = ListItem(text_or_element=Paragraph())
+        self.current_paragraph = None
+
+    def _end_numbered_item(self, level: int, num: int) -> None:
+        """End a numbered item.
+
+        Args:
+            level: The level of the numbered item (1-9).
+            num: The number of the item.
+        """
+        assert isinstance(level, int)
+        assert isinstance(num, int)
+        assert self.odt_listitem is not None
+        if not self.odt_list or len(self.odt_list) != level:
+            print(f'len(odt_list) = {len(self.odt_list)} for numbered item '
+                  f'level = {level} {num} state: {self.state.name}')
+        assert self.odt_list and len(self.odt_list) == level
+        self.odt_list[-1].append(self.odt_listitem)
+        self.odt_listitem = None
+        self.current_paragraph = None
+
+    def _start_table(self, num_columns: int) -> None:
+        """Start a table.
+
+        Args:
+            num_columns: The number of columns in the table.
+        """
+        assert isinstance(num_columns, int)
+        assert num_columns > 0
+        # Add an empty paragraph before the table for spacing
+        self.doc.body.append(Paragraph())
+        self.odt_table = Table(name=f'Table{self.odt_tablenumber}',
+                               width=num_columns)
+        self.odt_tablenumber += 1
+
+    def _end_table(self, num_columns: int, num_rows: int) -> None:
+        """End a table.
+
+        Args:
+            num_columns: The number of columns in the table.
+            num_rows: The number of rows in the table.
+        """
+        assert isinstance(num_columns, int)
+        assert isinstance(num_rows, int)
+        assert self.odt_table is not None
+        self.doc.body.append(self.odt_table)
+        # Add an empty paragraph after the table for spacing
+        self.doc.body.append(Paragraph())
+        self.odt_table = None
+
+    def _write_table_first_row(self, first_row: list[str],
+                               formatting: Formatting) -> None:
+        """Write the first row of a table.
+
+        Args:
+            first_row: The first row of the table.
+            formatting: The formatting of the text in each cell.
+        """
+        assert isinstance(first_row, list)
+        assert isinstance(formatting, Formatting)
+        assert self.odt_table is not None
+        self._write_table_row(first_row, formatting, 0)
+        self.odt_table.delete_row(0)
+
+    def _write_table_row(self, row: list[str], formatting: Formatting,
+                         row_number: int) -> None:
+        """Write a row of a table.
+
+        Args:
+            row: The row to add to the table.
+            formatting: The formatting of the text in each cell.
+            row_number: The row number (0-based).
+        """
+        assert isinstance(row, list)
+        assert isinstance(formatting, Formatting)
+        assert isinstance(row_number, int)
+        assert self.odt_table is not None
+        table_row = Row()
+        for cell_text in row:
+            cell = Cell()
+            # Create a paragraph inside the cell with formatted text
+            para = Paragraph()
+            style = self._style_name_from_formatting(formatting)
+            if style:
+                # Use a span with the style for formatted text
+                span = Span(text=cell_text, style=style)
+                para.append(span)
+            else:
+                # No formatting, just set the text directly
+                para.text = cell_text
+            cell.append(para)
+            table_row.append(cell)
+        self.odt_table.append(table_row)
+
+    def _start_code_block(self, programming_language: Optional[str]) -> None:
+        """Start a code block.
+
+        Args:
+            programming_language: The programming language of the code block.
+        """
+        assert programming_language is None or \
+            isinstance(programming_language, str)
+        # No-op. Everything is done in _write_code_block.
+
+    def _end_code_block(self, programming_language: Optional[str]) -> None:
+        """End a code block.
+
+        Args:
+            programming_language: The programming language of the code block.
+        """
+        assert programming_language is None or \
+            isinstance(programming_language, str)
+        # No-op. Everyhing is done in _write_code_block.
+
+    def _write_code_block(self, text: str,
+                          programming_language: Optional[str]) -> None:
+        """Write a code block.
+
+        Args:
+            text: The text to add to the code block.
+            programming_language: The programming language of the code block.
+        """
+        assert isinstance(text, str)
+        assert programming_language is None or \
+            isinstance(programming_language, str)
+        for line in text.split('\n'):
+            para = Paragraph(text_or_element=line, style='code')
+            self.doc.body.append(para)
+
+    def _encode_text(self, text: str) -> str:
+        """Encode text (escape special characters)."""
+        # No encoding needed for DOCX
+        return text

mformat_ext/reg_extpkg_formats.py

@@ -0,0 +1,16 @@
+#! /usr/local/bin/python3
+"""Register the formats defined in the ext package with the factory."""
+
+# Copyright (c) 2025 - 2026 Tom Björkholm
+# MIT License
+#
+
+from mformat_ext.mformat_docx import MultiFormatDocx
+from mformat_ext.mformat_odt import MultiFormatOdt
+from mformat.mformat import MultiFormat
+
+
+def register_formats_in_ext_pkg() -> list[type[MultiFormat]]:
+    """Get formats defined in the ext package to register with the factory."""
+    ret: list[type[MultiFormat]] = [MultiFormatDocx, MultiFormatOdt]
+    return ret

mformat_ext-0.2.dist-info/METADATA

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: mformat_ext
+Version: 0.2
+Summary: Uniform way to write simple text extended with DOCX and ODT files
+Author: Tom Björkholm
+Author-email: Tom Björkholm <klausuler_linnet0q@icloud.com>
+License-Expression: MIT
+Project-URL: Source code, https://bitbucket.org/tom-bjorkholm/mformat
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: mformat>=0.0.1
+Requires-Dist: python-docx>=1.2.0
+Requires-Dist: odfpy>=1.4.1
+Requires-Dist: msl-odt>=1.0
+Requires-Dist: pip>=25.3
+Requires-Dist: setuptools>=80.9.0
+Requires-Dist: build>=1.3.0
+Requires-Dist: wheel>=0.45.1
+Dynamic: author
+Dynamic: requires-dist
+Dynamic: requires-python
+
+# 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 estetically 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](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, 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](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:
+
+* `start_paragraph` to start a new paragraph with some provided text content.
+* `start_heading`to start a new heading with some provided text content.
+* `start_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.
+* `start_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.
+* `start_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). `start_bullet_item`and `start_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
+
+API 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.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   | Web page            | mformat       | 0.2                 |
+| md     | Markdown            | mformat       | 0.2                 |
+| odt    | Open Document Text  | mformat-ext   | 0.2                 |
+
+## Test summary
+
+* Test result: 916 passed in 10s
+* No Flake8 warnings.
+* No mypy errors found.
+* 0.2 built and tested using python version: Python 3.14.2

mformat_ext-0.2.dist-info/RECORD

@@ -0,0 +1,9 @@
+mformat_ext/__init__.py,sha256=p3sK092CiwBQdLl5533lOh37j8luVu-wNiGFKBWgfjg,128
+mformat_ext/mformat_docx.py,sha256=_tDyMM2m5-zrn20KusQT6gowsqb3QEMDAAjtlpx4XUQ,16032
+mformat_ext/mformat_odt.py,sha256=jrah1JH4juXAY6HE9XyqVH3P8b8-OxMQzBvBVxxnXw4,26706
+mformat_ext/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mformat_ext/reg_extpkg_formats.py,sha256=wJXv5rsWgTYSHFo9BYBZn_8tV4pun3aXDUpZFUxI9os,530
+mformat_ext-0.2.dist-info/METADATA,sha256=J1AOdeHm9vbnCeuEA4R9ivHodVbKVaHpYzDzeSNJV-Y,7247
+mformat_ext-0.2.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+mformat_ext-0.2.dist-info/top_level.txt,sha256=Qvx4UfVay6UsRei0fsuXp1CH3aLvozKFBJWrw-O5dLU,12
+mformat_ext-0.2.dist-info/RECORD,,

mformat_ext-0.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mformat_ext-0.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+mformat_ext