Skip to content

Header

Header class for “text:h” tag.

Classes:

Name Description
Header

A title, a specialized paragraph, “text:h”.

Header

Bases: Paragraph, MDHeader

A title, a specialized paragraph, “text:h”.

Attributes:

Name Type Description
level int

The outline level of the header. Level count begins at 1.
text str or None

The content of the header.
restart_numbering bool

If True, numbering restarts at this header level.
start_value int or None

The value at which to start numbering.
suppress_numbering bool

If True, no numbering for this header.
style str or None

The style name of the header.

Methods:

Name Description
__init__

Create a header element “text:h” of the given style and level, containing the
get_formatted_text

Return the formatted text content of the header.
Source code in odfdo/header.py 
 33
 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
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
class Header(Paragraph, MDHeader):
    """A title, a specialized paragraph, "text:h".

    Attributes:
        level (int): The outline level of the header. Level count begins at 1.
        text (str or None): The content of the header.
        restart_numbering (bool): If True, numbering restarts at this header level.
        start_value (int or None): The value at which to start numbering.
        suppress_numbering (bool): If True, no numbering for this header.
        style (str or None): The style name of the header.
    """

    _tag = "text:h"
    _properties = (
        PropDef("level", "text:outline-level"),
        PropDef("restart_numbering", "text:restart-numbering"),
        PropDef("start_value", "text:start-value"),
        PropDef("suppress_numbering", "text:suppress-numbering"),
    )

    def __init__(
        self,
        level: int = 1,
        text: str | None = None,
        restart_numbering: bool = False,
        start_value: int | None = None,
        suppress_numbering: bool = False,
        style: str | None = None,
        formatted: bool = True,
        **kwargs: Any,
    ) -> None:
        """Create a header element "text:h" of the given style and level, 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:
            level: The outline level of the header (starts at 1).
            text: The initial text content of the header.
            restart_numbering: If True, restart numbering at this level.
            start_value: The value at which to start numbering.
            suppress_numbering: If True, suppresses numbering for this header.
            style: The style name for the header.
            formatted: If True, replace special characters in `text` with ODF tags.
        """
        super().__init__(**kwargs)
        if self._do_init:
            self.level = int(level)
            if text:
                if formatted:
                    self.text = ""
                    self.append_plain_text(text)
                else:
                    self.text = self._unformatted(text)
            if restart_numbering:
                self.restart_numbering = True
            if start_value is not None:
                self.start_value = start_value
            if suppress_numbering:
                self.suppress_numbering = True
            # if style:
            #     self.style = style

    def get_formatted_text(
        self,
        context: dict | None = None,
        simple: bool = False,
    ) -> str:
        """Return the formatted text content of the header.

        In reStructuredText mode (when ``rst_mode`` is True in the
        context), the header is formatted with an underline appropriate
        to its outline level.

        Args:
            context: A dictionary providing context for formatting. If
                None, a default context is created.
            simple: Present for API compatibility with paragraph-like
                elements; ignored by this method.

        Returns:
            str: The formatted text content of the header.
        """
        if not context:
            context = {
                "document": None,
                "footnotes": [],
                "endnotes": [],
                "annotations": [],
                "rst_mode": False,
                "img_counter": 0,
                "images": [],
                "no_img_level": 0,
            }
        context["no_img_level"] += 1
        title = super().get_formatted_text(context)
        context["no_img_level"] -= 1
        title = title.strip()
        title = sub(r"\s+", " ", title)

        # No rst_mode ?
        if not context["rst_mode"]:
            return title
        # If here in rst_mode!

        # Get the level, max 5!
        LEVEL_STYLES = "#=-~`+^°'."
        level = int(self.level)
        if level > len(LEVEL_STYLES):
            raise ValueError("Too many levels of heading")

        # And return the result
        result = ["\n", title, "\n", LEVEL_STYLES[level - 1] * len(title), "\n"]
        return "".join(result)

_properties class-attribute instance-attribute 

_properties = (
    PropDef("level", "text:outline-level"),
    PropDef("restart_numbering", "text:restart-numbering"),
    PropDef("start_value", "text:start-value"),
    PropDef(
        "suppress_numbering", "text:suppress-numbering"
    ),
)

_tag class-attribute instance-attribute 

_tag = 'text:h'

level instance-attribute 

level = int(level)

restart_numbering instance-attribute 

restart_numbering = True

start_value instance-attribute 

start_value = start_value

suppress_numbering instance-attribute 

suppress_numbering = True

text instance-attribute 

text = ''

__init__ 

__init__(
    level: int = 1,
    text: str | None = None,
    restart_numbering: bool = False,
    start_value: int | None = None,
    suppress_numbering: bool = False,
    style: str | None = None,
    formatted: bool = True,
    **kwargs: Any,
) -> None

Create a header element “text:h” of the given style and level, 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
level int

The outline level of the header (starts at 1).

 1
text str | None

The initial text content of the header.

 None
restart_numbering bool

If True, restart numbering at this level.

 False
start_value int | None

The value at which to start numbering.

 None
suppress_numbering bool

If True, suppresses numbering for this header.

 False
style str | None

The style name for the header.

 None
formatted bool

If True, replace special characters in text with ODF tags.

 True
Source code in odfdo/header.py 
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
def __init__(
    self,
    level: int = 1,
    text: str | None = None,
    restart_numbering: bool = False,
    start_value: int | None = None,
    suppress_numbering: bool = False,
    style: str | None = None,
    formatted: bool = True,
    **kwargs: Any,
) -> None:
    """Create a header element "text:h" of the given style and level, 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:
        level: The outline level of the header (starts at 1).
        text: The initial text content of the header.
        restart_numbering: If True, restart numbering at this level.
        start_value: The value at which to start numbering.
        suppress_numbering: If True, suppresses numbering for this header.
        style: The style name for the header.
        formatted: If True, replace special characters in `text` with ODF tags.
    """
    super().__init__(**kwargs)
    if self._do_init:
        self.level = int(level)
        if text:
            if formatted:
                self.text = ""
                self.append_plain_text(text)
            else:
                self.text = self._unformatted(text)
        if restart_numbering:
            self.restart_numbering = True
        if start_value is not None:
            self.start_value = start_value
        if suppress_numbering:
            self.suppress_numbering = True

get_formatted_text 

get_formatted_text(
    context: dict | None = None, simple: bool = False
) -> str

Return the formatted text content of the header.

In reStructuredText mode (when rst_mode is True in the context), the header is formatted with an underline appropriate to its outline level.

Parameters:

Name Type Description Default
context dict | None

A dictionary providing context for formatting. If None, a default context is created.

 None
simple bool

Present for API compatibility with paragraph-like elements; ignored by this method.

 False

Returns:

Name Type Description
str str

The formatted text content of the header.
Source code in odfdo/header.py 
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
def get_formatted_text(
    self,
    context: dict | None = None,
    simple: bool = False,
) -> str:
    """Return the formatted text content of the header.

    In reStructuredText mode (when ``rst_mode`` is True in the
    context), the header is formatted with an underline appropriate
    to its outline level.

    Args:
        context: A dictionary providing context for formatting. If
            None, a default context is created.
        simple: Present for API compatibility with paragraph-like
            elements; ignored by this method.

    Returns:
        str: The formatted text content of the header.
    """
    if not context:
        context = {
            "document": None,
            "footnotes": [],
            "endnotes": [],
            "annotations": [],
            "rst_mode": False,
            "img_counter": 0,
            "images": [],
            "no_img_level": 0,
        }
    context["no_img_level"] += 1
    title = super().get_formatted_text(context)
    context["no_img_level"] -= 1
    title = title.strip()
    title = sub(r"\s+", " ", title)

    # No rst_mode ?
    if not context["rst_mode"]:
        return title
    # If here in rst_mode!

    # Get the level, max 5!
    LEVEL_STYLES = "#=-~`+^°'."
    level = int(self.level)
    if level > len(LEVEL_STYLES):
        raise ValueError("Too many levels of heading")

    # And return the result
    result = ["\n", title, "\n", LEVEL_STYLES[level - 1] * len(title), "\n"]
    return "".join(result)