Skip to content

Paragraph

Paragraph class for “text:p” tag and PageBreak().

Classes:

Name Description
LineBreak

Representation of a line break, “text:line-break”.
Paragraph

An ODF paragraph, “text:p”.
Spacer

Representation of several spaces, “text:s”.
Span

A span tag (styled text in paragraph), “text:span”.
Tab

Representation of a tabulation, “text:tab”.

Functions:

Name Description
PageBreak

Create an empty paragraph configured for a manual page break.

__all__ module-attribute 

__all__ = [
    "LineBreak",
    "PageBreak",
    "Paragraph",
    "Spacer",
    "Span",
    "Tab",
]

LineBreak

Bases: MDLineBreak, Element

Representation of a line break, “text:line-break”.

Methods:

Name Description
__init__

Initialize the LineBreak element.
__str__

Attributes:

Name Type Description
text str

Get the textual representation of the line break.
Source code in odfdo/line_break.py 
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
class LineBreak(MDLineBreak, Element):
    """Representation of a line break, "text:line-break"."""

    _tag = "text:line-break"

    def __init__(self, **kwargs: Any) -> None:
        """Initialize the LineBreak element.

        Args:
            **kwargs: Additional keyword arguments for the parent `Element` class.
        """
        super().__init__(**kwargs)

    def __str__(self) -> str:
        return "\n"

    @property
    def text(self) -> str:
        """Get the textual representation of the line break.

        Returns:
            str: Always returns a newline character ("\\n").
        """
        return "\n"

    @text.setter
    def text(self, text: str | None) -> None:
        pass

_tag class-attribute instance-attribute 

_tag = 'text:line-break'

text property writable 

text: str

Get the textual representation of the line break.

Returns:

Name Type Description
str str

Always returns a newline character (“\n”).

__init__ 

__init__(**kwargs: Any) -> None

Initialize the LineBreak element.

Parameters:

Name Type Description Default
**kwargs Any

Additional keyword arguments for the parent Element class.

 {}
Source code in odfdo/line_break.py 
39
40
41
42
43
44
45
def __init__(self, **kwargs: Any) -> None:
    """Initialize the LineBreak element.

    Args:
        **kwargs: Additional keyword arguments for the parent `Element` class.
    """
    super().__init__(**kwargs)

__str__ 

__str__() -> str
Source code in odfdo/line_break.py 
47
48
def __str__(self) -> str:
    return "\n"

Paragraph

Bases: MDParagraph, UserDefinedMixin, LinkMixin, ParaFormattedTextMixin, ParaMixin, NoteMixin, Element

An ODF paragraph, “text:p”.

The “text:p” element represents a paragraph, which is the basic unit of text in an OpenDocument file.

Methods:

Name Description
__init__

Initialize a Paragraph element (text:p).
__str__

Attributes:

Name Type Description
style
text
Source code in odfdo/paragraph.py 
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
class Paragraph(
    MDParagraph,
    UserDefinedMixin,
    LinkMixin,
    ParaFormattedTextMixin,
    ParaMixin,
    NoteMixin,
    Element,
):
    """An ODF paragraph, "text:p".

    The "text:p" element represents a paragraph, which is the basic unit of
    text in an OpenDocument file.
    """

    _tag = "text:p"
    _properties: tuple[PropDef | PropDefBool, ...] = (
        PropDef("style", "text:style-name"),
    )

    def __init__(
        self,
        text_or_element: str | bytes | Element | None = None,
        style: str | None = None,
        formatted: bool = True,
        **kwargs: Any,
    ):
        """Initialize a Paragraph element (`text:p`).

        Args:
            text_or_element: Initial content for the paragraph.
                If a string/bytes, it's treated as plain text. If an `Element`, it's appended.
            style: The name of the style to apply to the paragraph.
            formatted: If True (default), special characters (`\\n`, `\\t`, multiple spaces)
                in `text_or_element` are converted to their ODF tag equivalents.
                If False, only extra whitespace is removed.
            **kwargs: Additional keyword arguments for the parent `Element` class.
        """
        super().__init__(**kwargs)
        if self._do_init:
            if isinstance(text_or_element, Element):
                self.append(text_or_element)
            else:
                self.text = ""
                if formatted:
                    self.append_plain_text(text_or_element)
                else:
                    self.append_plain_text(self._unformatted(text_or_element))
            if style is not None:
                self.style = style

    def __str__(self) -> str:
        return self.inner_text + "\n"

_properties class-attribute instance-attribute 

_properties: tuple[PropDef | PropDefBool, ...] = (
    PropDef("style", "text:style-name"),
)

_tag class-attribute instance-attribute 

_tag = 'text:p'

style instance-attribute 

style = style

text instance-attribute 

text = ''

__init__ 

__init__(
    text_or_element: str | bytes | Element | None = None,
    style: str | None = None,
    formatted: bool = True,
    **kwargs: Any,
)

Initialize a Paragraph element (text:p).

Parameters:

Name Type Description Default
text_or_element str | bytes | Element | None

Initial content for the paragraph. If a string/bytes, it’s treated as plain text. If an Element, it’s appended.

 None
style str | None

The name of the style to apply to the paragraph.

 None
formatted bool

If True (default), special characters (\n, \t, multiple spaces) in text_or_element are converted to their ODF tag equivalents. If False, only extra whitespace is removed.

 True
**kwargs Any

Additional keyword arguments for the parent Element class.

 {}
Source code in odfdo/paragraph.py 
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def __init__(
    self,
    text_or_element: str | bytes | Element | None = None,
    style: str | None = None,
    formatted: bool = True,
    **kwargs: Any,
):
    """Initialize a Paragraph element (`text:p`).

    Args:
        text_or_element: Initial content for the paragraph.
            If a string/bytes, it's treated as plain text. If an `Element`, it's appended.
        style: The name of the style to apply to the paragraph.
        formatted: If True (default), special characters (`\\n`, `\\t`, multiple spaces)
            in `text_or_element` are converted to their ODF tag equivalents.
            If False, only extra whitespace is removed.
        **kwargs: Additional keyword arguments for the parent `Element` class.
    """
    super().__init__(**kwargs)
    if self._do_init:
        if isinstance(text_or_element, Element):
            self.append(text_or_element)
        else:
            self.text = ""
            if formatted:
                self.append_plain_text(text_or_element)
            else:
                self.append_plain_text(self._unformatted(text_or_element))
        if style is not None:
            self.style = style

__str__ 

__str__() -> str
Source code in odfdo/paragraph.py 
108
109
def __str__(self) -> str:
    return self.inner_text + "\n"

Spacer

Bases: MDSpacer, Element

Representation of several spaces, “text:s”.

This element shall be used to represent the second and all following ” ” (U+0020, SPACE) characters in a sequence of ” ” (U+0020, SPACE) characters. It’s good practice to use this element only for the second and all following SPACE characters in a sequence, though it’s not an error if the preceding character is not a white space.

Methods:

Name Description
__init__

Create a Spacer element, “text:s”, representing several spaces.
__str__

Attributes:

Name Type Description
length int

Get the number of spaces represented by the spacer.
number str | None
text str

Get the string representation of the spacer.
Source code in odfdo/spacer.py 
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
class Spacer(MDSpacer, Element):
    """Representation of several spaces, "text:s".

    This element shall be used to represent the second and all following " "
    (U+0020, SPACE) characters in a sequence of " " (U+0020, SPACE) characters.
    It's good practice to use this element only for the second and all
    following SPACE characters in a sequence, though it's not an error if
    the preceding character is not a white space.
    """

    _tag = "text:s"
    _properties: tuple[PropDef | PropDefBool, ...] = (PropDef("number", "text:c"),)

    def __init__(self, number: int | None = 1, **kwargs: Any) -> None:
        """Create a Spacer element, "text:s", representing several spaces.

        Args:
            number: The number of spaces. Defaults to 1.
        """
        super().__init__(**kwargs)
        if self._do_init:
            if number and number >= 2:
                self.number: str | None = str(number)
            else:
                self.number = None

    def __str__(self) -> str:
        return self.text

    @property
    def text(self) -> str:
        """Get the string representation of the spacer.

        Returns:
            str: A string composed of spaces, e.g., "   ".
        """
        return " " * self.length

    @text.setter
    def text(self, text: str | None) -> None:
        """Set the string value of the spacer, which updates its length.

        Args:
            text: The string to set.
        """
        if text is None:
            text = ""
        self.length = len(text)

    @property
    def length(self) -> int:
        """Get the number of spaces represented by the spacer.

        Returns:
            int: The number of spaces.
        """
        value = self._base_attrib_getter("text:c")
        if value is None:
            return 1  # minimum 1 space
        return int(value)

    @length.setter
    def length(self, value: int | None) -> None:
        """Set the number of spaces represented by the spacer.

        Args:
            value: The number of spaces to set. If None or less
                than 2, the `text:c` attribute is removed, defaulting to 1 space.
        """
        if value is None or int(value) < 2:
            self._base_attrib_setter("text:c", None)
        else:
            self._base_attrib_setter("text:c", int(value))

_properties class-attribute instance-attribute 

_properties: tuple[PropDef | PropDefBool, ...] = (
    PropDef("number", "text:c"),
)

_tag class-attribute instance-attribute 

_tag = 'text:s'

length property writable 

length: int

Get the number of spaces represented by the spacer.

Returns:

Name Type Description
int int

The number of spaces.

number instance-attribute 

number: str | None = str(number)

text property writable 

text: str

Get the string representation of the spacer.

Returns:

Name Type Description
str str

A string composed of spaces, e.g., ” “.

__init__ 

__init__(number: int | None = 1, **kwargs: Any) -> None

Create a Spacer element, “text:s”, representing several spaces.

Parameters:

Name Type Description Default
number int | None

The number of spaces. Defaults to 1.

 1
Source code in odfdo/spacer.py 
47
48
49
50
51
52
53
54
55
56
57
58
def __init__(self, number: int | None = 1, **kwargs: Any) -> None:
    """Create a Spacer element, "text:s", representing several spaces.

    Args:
        number: The number of spaces. Defaults to 1.
    """
    super().__init__(**kwargs)
    if self._do_init:
        if number and number >= 2:
            self.number: str | None = str(number)
        else:
            self.number = None

__str__ 

__str__() -> str
Source code in odfdo/spacer.py 
60
61
def __str__(self) -> str:
    return self.text

Span

Bases: MDSpan, MDParagraph, UserDefinedMixin, LinkMixin, ParaFormattedTextMixin, ParaMixin, NoteMixin, Element

A span tag (styled text in paragraph), “text:span”.

This element is used for inline text styling within a paragraph. It can contain text content and is often associated with a text style.

Inherits from various mixins to provide markdown, paragraph, and note functionalities.

Methods:

Name Description
__init__

Create a span element “text:span” of the given style containing the
__str__

Attributes:

Name Type Description
style
text
Source code in odfdo/span.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
class Span(
    MDSpan,
    MDParagraph,
    UserDefinedMixin,
    LinkMixin,
    ParaFormattedTextMixin,
    ParaMixin,
    NoteMixin,
    Element,
):
    """A span tag (styled text in paragraph), "text:span".

    This element is used for inline text styling within a paragraph. It can
    contain text content and is often associated with a text style.

    Inherits from various mixins to provide markdown, paragraph, and note
    functionalities.
    """

    _tag = "text:span"
    _properties = (
        PropDef("style", "text:style-name"),
        PropDef("class_names", "text:class-names"),
    )

    def __init__(
        self,
        text: str | None = None,
        style: str | None = None,
        formatted: bool = True,
        **kwargs: Any,
    ) -> None:
        """Create a span element "text:span" of the given style containing the
        optional given text.

        If "formatted" is True (the default), the given text is appended with <CR>,
        <TAB> and multiple spaces replaced by ODF corresponding tags.

        Args:
            text: The text content for the span.
            style: The style name for the span.
            formatted: If True, special characters in `text` are
                replaced by ODF corresponding tags. Defaults to True.
        """
        super().__init__(**kwargs)
        if self._do_init:
            if text:
                if formatted:
                    self.text = ""
                    self.append_plain_text(text)
                else:
                    self.text = self._unformatted(text)
            if style:
                self.style = style

    def __str__(self) -> str:
        return self.inner_text

_properties class-attribute instance-attribute 

_properties = (
    PropDef("style", "text:style-name"),
    PropDef("class_names", "text:class-names"),
)

_tag class-attribute instance-attribute 

_tag = 'text:span'

style instance-attribute 

style = style

text instance-attribute 

text = ''

__init__ 

__init__(
    text: str | None = None,
    style: str | None = None,
    formatted: bool = True,
    **kwargs: Any,
) -> None

Create a span element “text:span” of the given style containing the optional given text.

If “formatted” is True (the default), the given text is appended with , and multiple spaces replaced by ODF corresponding tags.

Parameters:

Name Type Description Default
text str | None

The text content for the span.

 None
style str | None

The style name for the span.

 None
formatted bool

If True, special characters in text are replaced by ODF corresponding tags. Defaults to True.

 True
Source code in odfdo/span.py 
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
def __init__(
    self,
    text: str | None = None,
    style: str | None = None,
    formatted: bool = True,
    **kwargs: Any,
) -> None:
    """Create a span element "text:span" of the given style containing the
    optional given text.

    If "formatted" is True (the default), the given text is appended with <CR>,
    <TAB> and multiple spaces replaced by ODF corresponding tags.

    Args:
        text: The text content for the span.
        style: The style name for the span.
        formatted: If True, special characters in `text` are
            replaced by ODF corresponding tags. Defaults to True.
    """
    super().__init__(**kwargs)
    if self._do_init:
        if text:
            if formatted:
                self.text = ""
                self.append_plain_text(text)
            else:
                self.text = self._unformatted(text)
        if style:
            self.style = style

__str__ 

__str__() -> str
Source code in odfdo/span.py 
98
99
def __str__(self) -> str:
    return self.inner_text

Tab

Bases: MDTab, Element

Representation of a tabulation, “text:tab”.

This element represents the [UNICODE] tab character (HORIZONTAL TABULATION, U+0009). The position attribute indicates the number of the tab-stop to which a tab character refers, where position 0 marks the start margin of a paragraph. Layout-oriented consumers should determine tab positions based on style information.

Methods:

Name Description
__init__

Create a tabulation element “text:tab”.
__str__

Attributes:

Name Type Description
position
text str

Get the text content, which is always a tab character.
Source code in odfdo/tab.py 
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
class Tab(MDTab, Element):
    """Representation of a tabulation, "text:tab".

    This element represents the [UNICODE] tab character (HORIZONTAL TABULATION,
    U+0009). The position attribute indicates the number of the tab-stop to
    which a tab character refers, where position 0 marks the start margin of
    a paragraph. Layout-oriented consumers should determine tab positions based
    on style information.
    """

    _tag = "text:tab"
    _properties: tuple[PropDef | PropDefBool, ...] = (
        PropDef("position", "text:tab-ref"),
    )

    def __init__(self, position: int | None = None, **kwargs: Any) -> None:
        """Create a tabulation element "text:tab".

        Args:
            position: The position of the tab-stop. If provided,
                must be a non-negative integer.
        """
        super().__init__(**kwargs)
        if self._do_init and position is not None and position >= 0:
            self.position = str(position)

    def __str__(self) -> str:
        return "\t"

    @property
    def text(self) -> str:
        """Get the text content, which is always a tab character.

        Returns:
            str: The tab character ("\t").
        """
        return "\t"

    @text.setter
    def text(self, text: str | None) -> None:
        """Setting text for a tab is a no-op as it always represents a tab character."""
        pass

_properties class-attribute instance-attribute 

_properties: tuple[PropDef | PropDefBool, ...] = (
    PropDef("position", "text:tab-ref"),
)

_tag class-attribute instance-attribute 

_tag = 'text:tab'

position instance-attribute 

position = str(position)

text property writable 

text: str

Get the text content, which is always a tab character.

Returns:

Name Type Description
str str

The tab character (” “).

__init__ 

__init__(
    position: int | None = None, **kwargs: Any
) -> None

Create a tabulation element “text:tab”.

Parameters:

Name Type Description Default
position int | None

The position of the tab-stop. If provided, must be a non-negative integer.

 None
Source code in odfdo/tab.py 
49
50
51
52
53
54
55
56
57
58
def __init__(self, position: int | None = None, **kwargs: Any) -> None:
    """Create a tabulation element "text:tab".

    Args:
        position: The position of the tab-stop. If provided,
            must be a non-negative integer.
    """
    super().__init__(**kwargs)
    if self._do_init and position is not None and position >= 0:
        self.position = str(position)

__str__ 

__str__() -> str
Source code in odfdo/tab.py 
60
61
def __str__(self) -> str:
    return "\t"

PageBreak 

PageBreak() -> Paragraph

Create an empty paragraph configured for a manual page break.

To properly render this page break, the document must have the “odfdopagebreak” style registered using document.add_page_break_style().

Returns:

Name Type Description
Paragraph Paragraph

An empty Paragraph element with the “odfdopagebreak” style.
Source code in odfdo/paragraph.py 
115
116
117
118
119
120
121
122
123
124
def PageBreak() -> Paragraph:
    """Create an empty paragraph configured for a manual page break.

    To properly render this page break, the document must have the
    "odfdopagebreak" style registered using `document.add_page_break_style()`.

    Returns:
        Paragraph: An empty `Paragraph` element with the "odfdopagebreak" style.
    """
    return Paragraph("", style="odfdopagebreak")