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
62
63
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
46
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 
48
49
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 str | None
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
110
111
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"),
    )
    style: str | None

    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: str | None

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 
 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
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 
110
111
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
107
108
109
110
111
112
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.
            kwargs: Arbitrary keyword arguments for the Element base class.

        """
        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
kwargs Any

Arbitrary keyword arguments for the Element base class.

 {}
Source code in odfdo/spacer.py 
47
48
49
50
51
52
53
54
55
56
57
58
59
60
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.
        kwargs: Arbitrary keyword arguments for the Element base class.

    """
    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 
62
63
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
100
101
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.
            kwargs: Arbitrary keyword arguments for the Element base class.

        """
        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
kwargs Any

Arbitrary keyword arguments for the Element base class.

 {}
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
97
98
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.
        kwargs: Arbitrary keyword arguments for the Element base class.

    """
    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 
100
101
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
76
77
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.
            kwargs: Arbitrary keyword arguments for the Element base class.

        """
        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:
        """Ignore text setting as a tab always represents a tab character."""

_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
kwargs Any

Arbitrary keyword arguments for the Element base class.

 {}
Source code in odfdo/tab.py 
49
50
51
52
53
54
55
56
57
58
59
60
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.
        kwargs: Arbitrary keyword arguments for the Element base class.

    """
    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 
62
63
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 
117
118
119
120
121
122
123
124
125
126
127
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")