Reference

Classes:

Name	Description
AnimPar	Container for SMIL animations, “anim:par”.
AnimSeq	Container for SMIL Presentation Animations, “anim:seq”.
AnimTransFilter	Transition between two frames, “anim:transitionFilter”.
Annotation	An annotation (private note), “text:annotation”.
AnnotationEnd	End of annotation marker, “office:annotation-end”.
BackgroundImage	Style for a background image, “style:background-image”.
Body	Root of the document content, “office:body”.
Bookmark	Bookmark class, “text:bookmark” tag.
BookmarkEnd	Bookmark end marker, “text:bookmark-end”.
BookmarkStart	Bookmark start marker, “text:bookmark-start”.
Cell	A cell of a table, “table:table-cell” and “table:covered-table-cell”.
ChangeInfo	Representation of information of a change, “office:change-info”.
Chart	Root of the Chart document content, “office:chart”.
Column	A Column of a table, “table:table-column”.
ConnectorShape	A connector shape, “draw:connector”.
Container	Storage of the ODF document, as zip or other format.
Content	Representation of the “content.xml” part.
Database	Root of the Database document content, “office:database”.
DcCreatorMixin	Creator of the document, “dc:creator”.
DcDateMixin	Date of the document, “dc:date”.
Document	Abstraction of the ODF document.
DrawFillImage	A link to a bitmap resource, “draw:fill-image”.
DrawGroup	Representation of a group of drawing shapes, “draw:g”.
DrawImage	An ODF image, “draw:image”.
DrawPage	ODF draw page for presentations and drawings, “draw:page”.
Drawing	Root of the Drawing document content, “office:drawing”.
EText	Representation of an XML text node (internal).
Element	Base class of all ODF classes, abstraction of the underlying XML.
ElementTyped	Subclass of Element for classes managing typed values.
EllipseShape	An ellipse shape, “draw:ellipse”.
Frame	ODF Frame, “draw:frame”.
Header	A title, a specialized paragraph, “text:h”.
HeaderRows	A header row of a table, “table:table-header-rows”.
Image	Root of the Image document content, “office:image”.
IndexTitle	The title of an index, “text:index-title”.
IndexTitleTemplate	Template style for title, “text:index-title-template”.
LineBreak	Representation of a line break, “text:line-break”.
LineShape	A line shape, “draw:line”.
Link	Representation of a link (URL), “text:a”.
List	A list of elements, “text:list”.
ListItem	An item of a list, “text:list-item”.
Manifest	Representation of the “manifest.xml” part.
Meta	Representation of the “meta.xml” part.
MetaAutoReload	Container for auto-reload properties, “meta:auto-reload”.
MetaHyperlinkBehaviour	Container for hyperlink-behaviour properties, “meta:hyperlink-
MetaTemplate	Container for the meta template properties, “meta:template”.
Metadata	Root of the Meta document content, “office:meta”.
NamedRange	Named range of cells in a table, “table:named-range”.
Note	A note (footnote or endnote), “text:note”.
OfficeAutomaticStyles	Container for automatic styles used in the document, “office:automatic-
OfficeMasterStyles	Container for master styles used in the document, “office:master-
ParaMixin	Mixin for Paragraph methods.
Paragraph	An ODF paragraph, “text:p”.
Presentation	Root of the Presentation document content, “office:presentation”.
RectangleShape	A rectangle shape, “draw:rect”.
Reference	A reference to a content marked by a reference mark, “text:reference-
ReferenceMark	A point reference, “text:reference-mark”.
ReferenceMarkEnd	End of a range reference, “text:reference-mark-end”.
ReferenceMarkStart	Start of a range reference, “text:reference-mark-start”.
Row	A row of a table, “table:table-row”.
RowGroup	A group of rows with common properties, “table:table-row-group”.
Section	Section of the text document, “text:section”.
Spacer	Representation of several spaces, “text:s”.
Span	A span tag (syled text in paragraph), “text:span”.
Spreadsheet	Root of the Spreadsheet document content, “office:spreadsheet”.
Style	Style class for many ODF tags, “style:style”, “number:date-style”,…
StyleFooter	Content of a footer in a StyleMasterPage, tag “style:footer”.
StyleFooterLeft	Content of a left page footer in a StyleMasterPage, tag “style:footer-
StyleHeader	Content of a header in a StyleMasterPage, tag “style:header”.
StyleHeaderLeft	Content of a left page header in a StyleMasterPage, tag “style:header-
StyleMasterPage	Container of headers and footers, “style:master-page”.
StylePageLayout	The “style:page-layout” element represents the styles that specify the
Styles	Representation of the “styles.xml” part.
TOC	A table of content, “text:table-of-content”.
Tab	Representation of a tabulation, “text:tab”.
TabStopStyle	Base style for a TOC entryBase style for a TOC entry, “style:tab-
Table	A table, in a spreadsheet or other document, “table:table”.
Text	Root of the Text document content, “office:text”.
TextChange	A text change position, “text:change”.
TextChangeEnd	End of a changed region, “text:change-end”.
TextChangeStart	Start of a changed region, “text:change-start”.
TextChangedRegion	A changed region of text, “text:changed-region”.
TextDeletion	Information on a text deletion, “text:deletion”.
TextFormatChange	A change in text formatting, “text:format-change”.
TextInsertion	Information on a text insertion, “text:insertion”.
TocEntryTemplate	Template for entry of TOC, “text:table-of-content-entry-template”.
TrackedChanges	A tracked change, “text:tracked-changes”.
UserDefined	A user defined field, “text:user-defined”.
UserFieldDecl	Declaration of a user field, “text:user-field-decl”.
UserFieldDecls	Container of user fields declarations, “text:user-field-decls”.
UserFieldGet	Representation of user field getter, “text:user-field-get”.
UserFieldInput	Representation of user field input, “text:user-field-input”.
VarChapter	Variable for a chapter, “text:chapter”.
VarCreationDate	Variable for the creation date, “text:creation-date”.
VarCreationTime	Variable for the creation time, “text:creation-time”.
VarDate	Variable for a date, “text:date”.
VarDecl	A variable declaration, “text:variable-decl”.
VarDecls	Container of variables declarations, “text:variable-decls”.
VarDescription	Variable for the text description, “text:description”.
VarFileName	Variable for the file name, “text:file-name”.
VarGet	Representation of a variable getter, “text:variable-get”.
VarInitialCreator	Variable for the initial creator, “text:initial-creator”.
VarKeywords	Variable for the keywords, “text:keywords”.
VarPageCount	Variable for page count, “text:page-count”.
VarPageNumber	Variable for page number, “text:page-number”.
VarSet	Representation of a variable setter, “text:variable-set”.
VarSubject	Variable for the subject, “text:subject”.
VarTime	Variable for a time, “text:time”.
VarTitle	Variable for the title, “text:title”.
XmlPart	Representation of an XML part.

Functions:

Name	Description
PageBreak	Return an empty paragraph with a manual page break.
create_table_cell_style	Return a cell style.
default_boolean_style	Return a default boolean style.
default_currency_style	Return a default currency style (€).
default_date_style	Return a default time style Y-M-D.
default_frame_position_style	Generate a style for positioning frames in desktop applications.
default_number_style	Return a default number style with two decimals.
default_percentage_style	Return a default percentage style with two decimals.
default_time_style	Return a default time style.
default_toc_level_style	Generate an automatic default style for the given TOC level.
hex2rgb	Convert “#RRGGBB” hexadecimal representation into (R, G, B) tuple.
hexa_color	Safe conversion from color tuple or string to hexadecimal
make_table_cell_border_string	Returns a string for “style:table-cell-properties” “fo:border”.
rgb2hex	Convert color name or (R, G, B) tuple into “#RRGGBB” hexadecimal.

Attributes:

Name	Type	Description
FIRST_CHILD
LAST_CHILD
NEXT_SIBLING
PREV_SIBLING

FIRST_CHILD module-attribute

FIRST_CHILD = 0

LAST_CHILD module-attribute

LAST_CHILD = 1

NEXT_SIBLING module-attribute

NEXT_SIBLING = 2

PREV_SIBLING module-attribute

PREV_SIBLING = 3

AnimPar

Bases: Element

Container for SMIL animations, “anim:par”.

Methods:

Name	Description
__init__	Create a container for SMIL presentation animations “anim:par”.

Attributes:

Name	Type	Description
presentation_node_type
smil_begin

Source code in odfdo/smil.py

class AnimPar(Element):
    """Container for SMIL animations, "anim:par"."""

    _tag = "anim:par"
    _properties = (
        PropDef("presentation_node_type", "presentation:node-type"),
        PropDef("smil_begin", "smil:begin"),
    )

    def __init__(
        self,
        presentation_node_type: str | None = None,
        smil_begin: str | None = None,
        **kwargs: Any,
    ) -> None:
        """Create a container for SMIL presentation animations "anim:par".

        Args:

            presentation_node_type -- default, on-click, with-previous,
                                      after-previous, timing-root, main-sequence
                                      and interactive-sequence

            smil_begin -- indefinite, 10s, [id].click, [id].begin
        """
        super().__init__(**kwargs)
        if self._do_init:
            if presentation_node_type:
                self.presentation_node_type = presentation_node_type
            if smil_begin:
                self.smil_begin = smil_begin

presentation_node_type instance-attribute

presentation_node_type = presentation_node_type

smil_begin instance-attribute

smil_begin = smil_begin

__init__

__init__(
    presentation_node_type: str | None = None,
    smil_begin: str | None = None,
    **kwargs: Any,
) -> None

Create a container for SMIL presentation animations “anim:par”.

Args:

presentation_node_type -- default, on-click, with-previous,
                          after-previous, timing-root, main-sequence
                          and interactive-sequence

smil_begin -- indefinite, 10s, [id].click, [id].begin

Source code in odfdo/smil.py

def __init__(
    self,
    presentation_node_type: str | None = None,
    smil_begin: str | None = None,
    **kwargs: Any,
) -> None:
    """Create a container for SMIL presentation animations "anim:par".

    Args:

        presentation_node_type -- default, on-click, with-previous,
                                  after-previous, timing-root, main-sequence
                                  and interactive-sequence

        smil_begin -- indefinite, 10s, [id].click, [id].begin
    """
    super().__init__(**kwargs)
    if self._do_init:
        if presentation_node_type:
            self.presentation_node_type = presentation_node_type
        if smil_begin:
            self.smil_begin = smil_begin

AnimSeq

Bases: Element

Container for SMIL Presentation Animations, “anim:seq”.

Animations inside this block are executed after the slide has executed its initial transition.

Methods:

Name	Description
__init__	Create a container for SMIL Presentation Animations “anim:seq”.

Attributes:

Name	Type	Description
presentation_node_type

Source code in odfdo/smil.py

class AnimSeq(Element):
    """Container for SMIL Presentation Animations, "anim:seq".

    Animations inside this block are executed after the slide has executed its
    initial transition.
    """

    _tag = "anim:seq"
    _properties = (PropDef("presentation_node_type", "presentation:node-type"),)

    def __init__(
        self,
        presentation_node_type: str | None = None,
        **kwargs: Any,
    ) -> None:
        """Create a container for SMIL Presentation Animations "anim:seq".

        Animations inside this block are executed after the slide
        has executed its initial transition.

        Args:

            presentation_node_type -- default, on-click, with-previous,
                                      after-previous, timing-root, main-sequence
                                      and interactive-sequence
        """
        super().__init__(**kwargs)
        if self._do_init and presentation_node_type:
            self.presentation_node_type = presentation_node_type

presentation_node_type instance-attribute

presentation_node_type = presentation_node_type

__init__

__init__(
    presentation_node_type: str | None = None, **kwargs: Any
) -> None

Create a container for SMIL Presentation Animations “anim:seq”.

Animations inside this block are executed after the slide has executed its initial transition.

Args:

presentation_node_type -- default, on-click, with-previous,
                          after-previous, timing-root, main-sequence
                          and interactive-sequence

Source code in odfdo/smil.py

def __init__(
    self,
    presentation_node_type: str | None = None,
    **kwargs: Any,
) -> None:
    """Create a container for SMIL Presentation Animations "anim:seq".

    Animations inside this block are executed after the slide
    has executed its initial transition.

    Args:

        presentation_node_type -- default, on-click, with-previous,
                                  after-previous, timing-root, main-sequence
                                  and interactive-sequence
    """
    super().__init__(**kwargs)
    if self._do_init and presentation_node_type:
        self.presentation_node_type = presentation_node_type

AnimTransFilter

Bases: Element

Transition between two frames, “anim:transitionFilter”.

Methods:

Name	Description
__init__	Create a transition between two frames “anim:transitionFilter”.

Attributes:

Name	Type	Description
smil_direction
smil_dur
smil_fadeColor
smil_mode
smil_subtype
smil_type

Source code in odfdo/smil.py

class AnimTransFilter(Element):
    """Transition between two frames, "anim:transitionFilter"."""

    _tag = "anim:transitionFilter"
    _properties = (
        PropDef("smil_dur", "smil:dur"),
        PropDef("smil_type", "smil:type"),
        PropDef("smil_subtype", "smil:subtype"),
        PropDef("smil_direction", "smil:direction"),
        PropDef("smil_fadeColor", "smil:fadeColor"),
        PropDef("smil_mode", "smil:mode"),
    )

    def __init__(
        self,
        smil_dur: str | None = None,
        smil_type: str | None = None,
        smil_subtype: str | None = None,
        smil_direction: str | None = None,
        smil_fadeColor: str | None = None,
        smil_mode: str | None = None,
        **kwargs: Any,
    ) -> None:
        """Create a transition between two frames "anim:transitionFilter".

        Args:

          smil_dur -- str, duration

          smil_type and smil_subtype -- see http://www.w3.org/TR/SMIL20/
                        smil-transitions.html#TransitionEffects-Appendix
                                        to get a list of all types/subtypes

          smil_direction -- forward, reverse

          smil_fadeColor -- forward, reverse

          smil_mode -- in, out
        """
        super().__init__(**kwargs)
        if self._do_init:
            if smil_dur:
                self.smil_dur = smil_dur
            if smil_type:
                self.smil_type = smil_type
            if smil_subtype:
                self.smil_subtype = smil_subtype
            if smil_direction:
                self.smil_direction = smil_direction
            if smil_fadeColor:
                self.smil_fadeColor = smil_fadeColor
            if smil_mode:
                self.smil_mode = smil_mode

smil_direction instance-attribute

smil_direction = smil_direction

smil_dur instance-attribute

smil_dur = smil_dur

smil_fadeColor instance-attribute

smil_fadeColor = smil_fadeColor

smil_mode instance-attribute

smil_mode = smil_mode

smil_subtype instance-attribute

smil_subtype = smil_subtype

smil_type instance-attribute

smil_type = smil_type

__init__

__init__(
    smil_dur: str | None = None,
    smil_type: str | None = None,
    smil_subtype: str | None = None,
    smil_direction: str | None = None,
    smil_fadeColor: str | None = None,
    smil_mode: str | None = None,
    **kwargs: Any,
) -> None

Create a transition between two frames “anim:transitionFilter”.

Args:

smil_dur – str, duration

smil_type and smil_subtype – see http://www.w3.org/TR/SMIL20/ smil-transitions.html#TransitionEffects-Appendix to get a list of all types/subtypes

smil_direction – forward, reverse

smil_fadeColor – forward, reverse

smil_mode – in, out

Source code in odfdo/smil.py

def __init__(
    self,
    smil_dur: str | None = None,
    smil_type: str | None = None,
    smil_subtype: str | None = None,
    smil_direction: str | None = None,
    smil_fadeColor: str | None = None,
    smil_mode: str | None = None,
    **kwargs: Any,
) -> None:
    """Create a transition between two frames "anim:transitionFilter".

    Args:

      smil_dur -- str, duration

      smil_type and smil_subtype -- see http://www.w3.org/TR/SMIL20/
                    smil-transitions.html#TransitionEffects-Appendix
                                    to get a list of all types/subtypes

      smil_direction -- forward, reverse

      smil_fadeColor -- forward, reverse

      smil_mode -- in, out
    """
    super().__init__(**kwargs)
    if self._do_init:
        if smil_dur:
            self.smil_dur = smil_dur
        if smil_type:
            self.smil_type = smil_type
        if smil_subtype:
            self.smil_subtype = smil_subtype
        if smil_direction:
            self.smil_direction = smil_direction
        if smil_fadeColor:
            self.smil_fadeColor = smil_fadeColor
        if smil_mode:
            self.smil_mode = smil_mode

Annotation

Bases: MDTail, Element, DcCreatorMixin, DcDateMixin

An annotation (private note), “text:annotation”.

Methods:

Name	Description
__init__	An annotation (private note), “text:annotation”.
check_validity
delete	Delete the given element from the XML tree. If no element is given,
get_annotated	Returns the annotated content from an annotation.

Attributes:

Name	Type	Description
creator
date
dc_creator	str | None	Alias for self.creator property.
dc_date	datetime | None	Alias for self.date property.
end	AnnotationEnd | None	Return the corresponding annotation-end tag or None.
name
note_body	str
start	Annotation	Return self.

Source code in odfdo/annotation.py

class Annotation(MDTail, Element, DcCreatorMixin, DcDateMixin):
    """An annotation (private note), "text:annotation"."""

    _tag = "office:annotation"
    _properties = (
        PropDef("name", "office:name"),
        PropDef("note_id", "text:id"),
    )

    def __init__(
        self,
        text_or_element: Element | str | None = None,
        creator: str | None = None,
        date: datetime | None = None,
        name: str | None = None,
        parent: Element | None = None,
        **kwargs: Any,
    ) -> None:
        """An annotation (private note), "text:annotation".

        Annotation element credited to the given creator with the
        given text, optionally dated (current date by default).
        If name not provided and some parent is provided, the name is
        autogenerated.

        Args:

            text -- str or odf_element

            creator -- str

            date -- datetime

            name -- str

            parent -- Element
        """
        # fixme : use offset
        # TODO allow paragraph and text styles
        super().__init__(**kwargs)

        if self._do_init:
            self.note_body = text_or_element
            if creator:
                self.creator = creator
            if date is None:
                date = datetime.now()
            self.date = date
            if not name:
                name = get_unique_office_name(parent)
            self.name = name

    @property
    def dc_creator(self) -> str | None:
        """Alias for self.creator property."""
        return self.creator

    @dc_creator.setter
    def dc_creator(self, creator: str) -> None:
        self.creator = creator

    @property
    def dc_date(self) -> datetime | None:
        """Alias for self.date property."""
        return self.date

    @dc_date.setter
    def dc_date(self, dtdate: datetime) -> None:
        self.date = dtdate

    @property
    def note_body(self) -> str:
        return self.text_content

    @note_body.setter
    def note_body(self, text_or_element: Element | str | None) -> None:
        if text_or_element is None:
            self.text_content = ""
        elif isinstance(text_or_element, str):
            self.text_content = text_or_element
        elif isinstance(text_or_element, Element):
            self.clear()
            self.append(text_or_element)
        else:
            raise TypeError(f'Unexpected type for body: "{type(text_or_element)}"')

    @property
    def start(self) -> Annotation:
        """Return self."""
        return self

    @property
    def end(self) -> AnnotationEnd | None:
        """Return the corresponding annotation-end tag or None."""
        name = self.name
        parent = self.parent
        if parent is None:  # pragma: nocover
            raise ValueError("Can't find end tag: no parent available")
        body: Body | Element = self.document_body or parent
        return body.get_annotation_end(name=name)

    def get_annotated(
        self,
        as_text: bool = False,
        no_header: bool = True,
        clean: bool = True,
    ) -> Element | list | str | None:
        """Returns the annotated content from an annotation.

        If no content exists (single position annotation or annotation-end not
        found), returns [] (or "" if text flag is True).
        If as_text is True: returns the text content.
        If clean is True: suppress unwanted tags (deletions marks, ...)
        If no_header is True: existing text:h are changed in text:p
        By default: returns a list of odf_element, cleaned and without headers.

        Args:

            as_text -- boolean

            clean -- boolean

            no_header -- boolean

        Returns: list or Element or text or None
        """
        end = self.end
        if end is None:
            if as_text:
                return ""
            return None
        body: Body | Element = self.document_body or self.root
        return elements_between(
            body, self, end, as_text=as_text, no_header=no_header, clean=clean
        )

    def delete(self, child: Element | None = None, keep_tail: bool = True) -> None:
        """Delete the given element from the XML tree. If no element is given,
        "self" is deleted. The XML library may allow to continue to use an
        element now "orphan" as long as you have a reference to it.

        For Annotation : delete the annotation-end tag if exists.

        Args:

            child -- Element or None
        """
        if child is not None:  # act like normal delete
            super().delete(child)
            return
        end = self.end
        if end:
            end.delete()
        # act like normal delete
        super().delete()

    def check_validity(self) -> None:
        if not self.note_body:
            raise ValueError("Annotation must have a body")
        if not self.dc_creator:
            raise ValueError("Annotation must have a creator")
        if not self.dc_date:
            self.dc_date = datetime.now()

    def __str__(self) -> str:
        return f"{self.note_body}\n{self.dc_creator} {self.dc_date}"

creator instance-attribute

creator = creator

date instance-attribute

date = date

dc_creator property writable

dc_creator: str | None

Alias for self.creator property.

dc_date property writable

dc_date: datetime | None

Alias for self.date property.

end property

end: AnnotationEnd | None

Return the corresponding annotation-end tag or None.

name instance-attribute

name = name

note_body property writable

note_body: str

start property

start: Annotation

Return self.

__init__

__init__(
    text_or_element: Element | str | None = None,
    creator: str | None = None,
    date: datetime | None = None,
    name: str | None = None,
    parent: Element | None = None,
    **kwargs: Any,
) -> None

An annotation (private note), “text:annotation”.

Annotation element credited to the given creator with the given text, optionally dated (current date by default). If name not provided and some parent is provided, the name is autogenerated.

Args:

text -- str or odf_element

creator -- str

date -- datetime

name -- str

parent -- Element

Source code in odfdo/annotation.py

def __init__(
    self,
    text_or_element: Element | str | None = None,
    creator: str | None = None,
    date: datetime | None = None,
    name: str | None = None,
    parent: Element | None = None,
    **kwargs: Any,
) -> None:
    """An annotation (private note), "text:annotation".

    Annotation element credited to the given creator with the
    given text, optionally dated (current date by default).
    If name not provided and some parent is provided, the name is
    autogenerated.

    Args:

        text -- str or odf_element

        creator -- str

        date -- datetime

        name -- str

        parent -- Element
    """
    # fixme : use offset
    # TODO allow paragraph and text styles
    super().__init__(**kwargs)

    if self._do_init:
        self.note_body = text_or_element
        if creator:
            self.creator = creator
        if date is None:
            date = datetime.now()
        self.date = date
        if not name:
            name = get_unique_office_name(parent)
        self.name = name

check_validity

check_validity() -> None

Source code in odfdo/annotation.py

def check_validity(self) -> None:
    if not self.note_body:
        raise ValueError("Annotation must have a body")
    if not self.dc_creator:
        raise ValueError("Annotation must have a creator")
    if not self.dc_date:
        self.dc_date = datetime.now()

delete

delete(
    child: Element | None = None, keep_tail: bool = True
) -> None

Delete the given element from the XML tree. If no element is given, “self” is deleted. The XML library may allow to continue to use an element now “orphan” as long as you have a reference to it.

For Annotation : delete the annotation-end tag if exists.

Args:

child -- Element or None

Source code in odfdo/annotation.py

def delete(self, child: Element | None = None, keep_tail: bool = True) -> None:
    """Delete the given element from the XML tree. If no element is given,
    "self" is deleted. The XML library may allow to continue to use an
    element now "orphan" as long as you have a reference to it.

    For Annotation : delete the annotation-end tag if exists.

    Args:

        child -- Element or None
    """
    if child is not None:  # act like normal delete
        super().delete(child)
        return
    end = self.end
    if end:
        end.delete()
    # act like normal delete
    super().delete()

get_annotated

get_annotated(
    as_text: bool = False,
    no_header: bool = True,
    clean: bool = True,
) -> Element | list | str | None

Returns the annotated content from an annotation.

If no content exists (single position annotation or annotation-end not found), returns [] (or “” if text flag is True). If as_text is True: returns the text content. If clean is True: suppress unwanted tags (deletions marks, …) If no_header is True: existing text:h are changed in text:p By default: returns a list of odf_element, cleaned and without headers.

Args:

as_text -- boolean

clean -- boolean

no_header -- boolean

Returns: list or Element or text or None

Source code in odfdo/annotation.py

def get_annotated(
    self,
    as_text: bool = False,
    no_header: bool = True,
    clean: bool = True,
) -> Element | list | str | None:
    """Returns the annotated content from an annotation.

    If no content exists (single position annotation or annotation-end not
    found), returns [] (or "" if text flag is True).
    If as_text is True: returns the text content.
    If clean is True: suppress unwanted tags (deletions marks, ...)
    If no_header is True: existing text:h are changed in text:p
    By default: returns a list of odf_element, cleaned and without headers.

    Args:

        as_text -- boolean

        clean -- boolean

        no_header -- boolean

    Returns: list or Element or text or None
    """
    end = self.end
    if end is None:
        if as_text:
            return ""
        return None
    body: Body | Element = self.document_body or self.root
    return elements_between(
        body, self, end, as_text=as_text, no_header=no_header, clean=clean
    )

AnnotationEnd

Bases: MDTail, Element

End of annotation marker, “office:annotation-end”.

AnnotationEnd: the “office:annotation-end” element may be used to define the end of a text range of document content that spans element boundaries. In that case, an “office:annotation” element shall precede the “office:annotation-end” element. Both elements shall have the same value for their office:name attribute. The “office:annotation-end” element shall be preceded by an “office:annotation” element that has the same value for its office:name attribute as the “office:annotation-end” element. An “office:annotation-end” element without a preceding “office:annotation” element that has the same name assigned is ignored.

Methods:

Name	Description
__init__	An annotation (private note), “text:annotation”.

Attributes:

Name	Type	Description
end	AnnotationEnd	Return self.
name
start	Annotation | None	Return the corresponding annotation starting tag or None.

Source code in odfdo/annotation.py

class AnnotationEnd(MDTail, Element):
    """End of annotation marker, "office:annotation-end".

    AnnotationEnd: the "office:annotation-end" element may be used to
    define the end of a text range of document content that spans element
    boundaries. In that case, an "office:annotation" element shall precede
    the "office:annotation-end" element. Both elements shall have the same
    value for their office:name attribute. The "office:annotation-end" element
    shall be preceded by an "office:annotation" element that has the same
    value for its office:name attribute as the "office:annotation-end"
    element. An "office:annotation-end" element without a preceding
    "office:annotation" element that has the same name assigned is ignored.
    """

    _tag = "office:annotation-end"
    _properties = (PropDef("name", "office:name"),)

    def __init__(
        self,
        annotation: Annotation | None = None,
        name: str | None = None,
        **kwargs: Any,
    ) -> None:
        """An annotation (private note), "text:annotation".

        Annotation element credited to the given creator with the
        given text, optionally dated (current date by default).
        If name not provided and some parent is provided, the name is
        autogenerated.

        Args:

            text -- str or odf_element

            creator -- str

            date -- datetime

            name -- str

            parent -- Element
        """
        # fixme : use offset
        # TODO allow paragraph and text styles
        super().__init__(**kwargs)
        if self._do_init:
            if annotation:
                name = annotation.name
            if not name:
                raise ValueError("Annotation-end must have a name")
            self.name = name

    @property
    def start(self) -> Annotation | None:
        """Return the corresponding annotation starting tag or None."""
        name = self.name
        parent = self.parent
        if parent is None:
            raise ValueError(
                "Can't find start tag: no parent available"
            )  # pragma:nocover
        body: Body | Element = self.document_body or parent
        return body.get_annotation(name=name)

    @property
    def end(self) -> AnnotationEnd:
        """Return self."""
        return self

end property

end: AnnotationEnd

Return self.

name instance-attribute

name = name

start property

start: Annotation | None

Return the corresponding annotation starting tag or None.

__init__

__init__(
    annotation: Annotation | None = None,
    name: str | None = None,
    **kwargs: Any,
) -> None

An annotation (private note), “text:annotation”.

Annotation element credited to the given creator with the given text, optionally dated (current date by default). If name not provided and some parent is provided, the name is autogenerated.

Args:

text -- str or odf_element

creator -- str

date -- datetime

name -- str

parent -- Element

Source code in odfdo/annotation.py

def __init__(
    self,
    annotation: Annotation | None = None,
    name: str | None = None,
    **kwargs: Any,
) -> None:
    """An annotation (private note), "text:annotation".

    Annotation element credited to the given creator with the
    given text, optionally dated (current date by default).
    If name not provided and some parent is provided, the name is
    autogenerated.

    Args:

        text -- str or odf_element

        creator -- str

        date -- datetime

        name -- str

        parent -- Element
    """
    # fixme : use offset
    # TODO allow paragraph and text styles
    super().__init__(**kwargs)
    if self._do_init:
        if annotation:
            name = annotation.name
        if not name:
            raise ValueError("Annotation-end must have a name")
        self.name = name

BackgroundImage

Bases: Style, DrawImage

Style for a background image, “style:background-image”.

Methods:

Name	Description
__init__	Create style for a background image “style:background-image”.

Attributes:

Name	Type	Description
display_name
family
name
position

Source code in odfdo/style.py

class BackgroundImage(Style, DrawImage):
    """Style for a background image, "style:background-image"."""

    _tag = "style:background-image"
    _properties: tuple[PropDef, ...] = (
        PropDef("name", "style:name"),
        PropDef("display_name", "style:display-name"),
        PropDef("svg_font_family", "svg:font-family"),
        PropDef("font_family_generic", "style:font-family-generic"),
        PropDef("font_pitch", "style:font-pitch"),
        PropDef("position", "style:position", "background-image"),
        PropDef("repeat", "style:repeat", "background-image"),
        PropDef("opacity", "draw:opacity", "background-image"),
        PropDef("filter", "style:filter-name", "background-image"),
        PropDef("text_style", "text:style-name"),
    )

    def __init__(
        self,
        name: str | None = None,
        display_name: str | None = None,
        position: str | None = None,
        repeat: str | None = None,
        opacity: str | None = None,
        filter: str | None = None,  # noqa: A002
        # Every other property
        **kwargs: Any,
    ) -> None:
        """Create style for a background image "style:background-image"."""
        kwargs["family"] = "background-image"
        super().__init__(**kwargs)
        if self._do_init:
            kwargs.pop("tag", None)
            kwargs.pop("tag_or_elem", None)
            self.family = "background-image"
            if name:
                self.name = name
            if display_name:
                self.display_name = display_name
            if position:
                self.position = position
            if repeat:
                self.position = repeat
            if opacity:
                self.position = opacity
            if filter:
                self.position = filter
            # Every other properties
            for prop in BackgroundImage._properties:
                if prop.name in kwargs:
                    self.set_style_attribute(prop.attr, kwargs[prop.name])

display_name instance-attribute

display_name = display_name

family instance-attribute

family = 'background-image'

name instance-attribute

name = name

position instance-attribute

position = position

__init__

__init__(
    name: str | None = None,
    display_name: str | None = None,
    position: str | None = None,
    repeat: str | None = None,
    opacity: str | None = None,
    filter: str | None = None,
    **kwargs: Any,
) -> None

Create style for a background image “style:background-image”.

Source code in odfdo/style.py

def __init__(
    self,
    name: str | None = None,
    display_name: str | None = None,
    position: str | None = None,
    repeat: str | None = None,
    opacity: str | None = None,
    filter: str | None = None,  # noqa: A002
    # Every other property
    **kwargs: Any,
) -> None:
    """Create style for a background image "style:background-image"."""
    kwargs["family"] = "background-image"
    super().__init__(**kwargs)
    if self._do_init:
        kwargs.pop("tag", None)
        kwargs.pop("tag_or_elem", None)
        self.family = "background-image"
        if name:
            self.name = name
        if display_name:
            self.display_name = display_name
        if position:
            self.position = position
        if repeat:
            self.position = repeat
        if opacity:
            self.position = opacity
        if filter:
            self.position = filter
        # Every other properties
        for prop in BackgroundImage._properties:
            if prop.name in kwargs:
                self.set_style_attribute(prop.attr, kwargs[prop.name])

Body

Bases: Element

Root of the document content, “office:body”.

Methods:

Name	Description
get_table	Return the table that matches the criteria.
get_tables	Return all the tables that match the criteria.

Attributes:

Name	Type	Description
get_sheet
get_sheets
sheets
tables	list[Table]	Return all the tables.

Source code in odfdo/body.py

class Body(Element):
    """Root of the document content, "office:body"."""

    _tag: str = "office:body"
    _properties: tuple[PropDef, ...] = ()

    def get_tables(
        self,
        style: str | None = None,
        content: str | None = None,
    ) -> list[Table]:
        """Return all the tables that match the criteria.

        The method is also accessible via the alias
        get_sheets()

        Args:

            style -- str

            content -- str regex

        Returns: list of Table
        """
        return self._filtered_elements(  # type: ignore[return-value]
            "descendant::table:table",
            table_style=style,
            content=content,
        )

    get_sheets = get_tables

    @property
    def tables(self) -> list[Table]:
        """Return all the tables.

        The property is also accessible via the alias sheets.

        Returns: list of Table
        """
        return self.get_elements("descendant::table:table")  # type: ignore[return-value]

    sheets = tables

    def get_table(
        self,
        position: int = 0,
        name: str | None = None,
        content: str | None = None,
    ) -> Table | None:
        """Return the table that matches the criteria.

        The method is also accessible via the alias
        get_sheet()

        Args:

            position -- int

            name -- str

            content -- str regex

        Returns: Table or None if not found
        """
        if name is None and content is None:
            result = self._filtered_element("descendant::table:table", position)
        else:
            result = self._filtered_element(
                "descendant::table:table",
                position,
                table_name=name,
                content=content,
            )
        return result  # type: ignore[return-value]

    get_sheet = get_table

get_sheet class-attribute instance-attribute

get_sheet = get_table

get_sheets class-attribute instance-attribute

get_sheets = get_tables

sheets class-attribute instance-attribute

sheets = tables

tables property

tables: list[Table]

Return all the tables.

The property is also accessible via the alias sheets.

Returns: list of Table

get_table

get_table(
    position: int = 0,
    name: str | None = None,
    content: str | None = None,
) -> Table | None

Return the table that matches the criteria.

The method is also accessible via the alias get_sheet()

Args:

position -- int

name -- str

content -- str regex

Returns: Table or None if not found

Source code in odfdo/body.py

def get_table(
    self,
    position: int = 0,
    name: str | None = None,
    content: str | None = None,
) -> Table | None:
    """Return the table that matches the criteria.

    The method is also accessible via the alias
    get_sheet()

    Args:

        position -- int

        name -- str

        content -- str regex

    Returns: Table or None if not found
    """
    if name is None and content is None:
        result = self._filtered_element("descendant::table:table", position)
    else:
        result = self._filtered_element(
            "descendant::table:table",
            position,
            table_name=name,
            content=content,
        )
    return result  # type: ignore[return-value]

get_tables

get_tables(
    style: str | None = None, content: str | None = None
) -> list[Table]

Return all the tables that match the criteria.

The method is also accessible via the alias get_sheets()

Args:

style -- str

content -- str regex

Returns: list of Table

Source code in odfdo/body.py

def get_tables(
    self,
    style: str | None = None,
    content: str | None = None,
) -> list[Table]:
    """Return all the tables that match the criteria.

    The method is also accessible via the alias
    get_sheets()

    Args:

        style -- str

        content -- str regex

    Returns: list of Table
    """
    return self._filtered_elements(  # type: ignore[return-value]
        "descendant::table:table",
        table_style=style,
        content=content,
    )

Bookmark

Bases: Element

Bookmark class, “text:bookmark” tag.

Methods:

Name	Description
__init__	Bookmark class, “text:bookmark” tag.

Attributes:

Name	Type	Description
name

Source code in odfdo/bookmark.py

class Bookmark(Element):
    """Bookmark class, "text:bookmark" tag."""

    _tag = "text:bookmark"
    _properties = (PropDef("name", "text:name"),)

    def __init__(self, name: str = "", **kwargs: Any) -> None:
        """Bookmark class, "text:bookmark" tag.

        Args:

            name -- str
        """
        super().__init__(**kwargs)
        if self._do_init:
            self.name = name

name instance-attribute

name = name

__init__

__init__(name: str = '', **kwargs: Any) -> None

Bookmark class, “text:bookmark” tag.

Args:

name -- str

Source code in odfdo/bookmark.py

def __init__(self, name: str = "", **kwargs: Any) -> None:
    """Bookmark class, "text:bookmark" tag.

    Args:

        name -- str
    """
    super().__init__(**kwargs)
    if self._do_init:
        self.name = name

BookmarkEnd

Bases: Element

Bookmark end marker, “text:bookmark-end”.

Args:

name -- str

Methods:

Name	Description
__init__

Attributes:

Name	Type	Description
name

Source code in odfdo/bookmark.py

class BookmarkEnd(Element):
    """Bookmark end marker, "text:bookmark-end".

    Args:

        name -- str
    """

    _tag = "text:bookmark-end"
    _properties = (PropDef("name", "text:name"),)

    def __init__(self, name: str = "", **kwargs: Any) -> None:
        super().__init__(**kwargs)
        if self._do_init:
            self.name = name

name instance-attribute

name = name

__init__

__init__(name: str = '', **kwargs: Any) -> None

Source code in odfdo/bookmark.py

def __init__(self, name: str = "", **kwargs: Any) -> None:
    super().__init__(**kwargs)
    if self._do_init:
        self.name = name

BookmarkStart

Bases: Element

Bookmark start marker, “text:bookmark-start”.

Methods:

Name	Description
__init__	Bookmark start marker, “text:bookmark-start”.

Attributes:

Name	Type	Description
name

Source code in odfdo/bookmark.py

class BookmarkStart(Element):
    """Bookmark start marker, "text:bookmark-start"."""

    _tag = "text:bookmark-start"
    _properties = (PropDef("name", "text:name"),)

    def __init__(self, name: str = "", **kwargs: Any) -> None:
        """Bookmark start marker, "text:bookmark-start"."""
        super().__init__(**kwargs)
        if self._do_init:
            self.name = name

name instance-attribute

name = name

__init__

__init__(name: str = '', **kwargs: Any) -> None

Bookmark start marker, “text:bookmark-start”.

Source code in odfdo/bookmark.py

def __init__(self, name: str = "", **kwargs: Any) -> None:
    """Bookmark start marker, "text:bookmark-start"."""
    super().__init__(**kwargs)
    if self._do_init:
        self.name = name

Cell

Bases: ElementTyped

A cell of a table, “table:table-cell” and “table:covered-table-cell”.

Methods:

Name	Description
__init__	Cell of a Table, “table:table-cell”.
is_covered	Return whether the cell is covered (tag table:covered-table-cell).
is_empty	Return whether the cell has no value or the value evaluates to False
is_spanned	Return whether the cell is spanned over several cells.
set_value	Set the cell state from the Python value type.
span_area	Return the tuple (nb_columns, nb_rows) of the zone covered by a

Attributes:

Name	Type	Description
bool	_bool	Set / get the value of the cell as a boolean.
clone	Cell
currency	str | None	Get / set the currency used for monetary values.
date	date	Set / get the value of the cell as a date.
datetime	datetime	Set / get the value of the cell as a datetime.
decimal	Decimal	Set / get the value of the cell as a Decimal (or 0.0).
duration	timedelta	Set / get the value of the cell as a duration (Python timedelta).
float	_float	Set / get the value of the cell as a float (or 0.0).
formula	str | None	Get / set the formula of the cell, or None if undefined.
int	_int	Set / get the value of the cell as a integer (or 0).
repeated	_int | None	Get / set the number of times the cell is repeated.
string	str	Set / get the value of the cell as a string (or ‘’).
style	str | None	Get / set the style of the cell itself.
type	str | None	Get / set the type of the cell: boolean, float, date, string or
value	str | _bool | _int | _float | Decimal | date | datetime | timedelta | None	Set / get the value of the cell. The type is read from the
x	int | None
y	int | None

Source code in odfdo/cell.py

class Cell(ElementTyped):
    """A cell of a table, "table:table-cell" and "table:covered-table-cell"."""

    _tag = "table:table-cell"

    def __init__(
        self,
        value: Any = None,
        text: str | None = None,
        cell_type: str | None = None,
        currency: str | None = None,
        formula: str | None = None,
        repeated: _int | None = None,
        style: str | None = None,
        **kwargs: Any,
    ) -> None:
        """Cell of a Table, "table:table-cell".

        Create a cell element containing the given value. The textual
        representation is automatically formatted but can be provided. Cell
        type can be deduced as well, unless the number is a percentage or
        currency. If cell type is "currency", the currency must be given.
        The cell can be repeated on the given number of columns.

        Args:

            value -- bool, int, float, Decimal, date, datetime, str,
                     timedelta

            text -- str

            cell_type -- 'boolean', 'currency', 'date', 'float', 'percentage',
                         'string' or 'time'

            currency -- three-letter str

            repeated -- int

            style -- str
        """
        super().__init__(**kwargs)
        self.x: int | None = None
        self.y: int | None = None
        if self._do_init:
            self.set_value(
                value,
                text=text,
                cell_type=cell_type,
                currency=currency,
                formula=formula,
            )
            if repeated and repeated > 1:
                self.repeated = repeated
            if style is not None:
                self.style = style

    def __repr__(self) -> str:
        return f"<{self.__class__.__name__} x={self.x} y={self.y}>"

    @property
    def clone(self) -> Cell:
        clone = Element.clone.fget(self)  # type: ignore
        clone.y = self.y
        clone.x = self.x
        return clone  # type: ignore[no-any-return]

    @property
    def value(
        self,
    ) -> str | _bool | _int | _float | Decimal | _date | _datetime | timedelta | None:
        """Set / get the value of the cell. The type is read from the
        'office:value-type' attribute of the cell. When setting the value, the
        type of the value will determine the new value_type of the cell.

        Warning:
            - for date, datetime and timedelta, a default text value is generated.
            - for boolean type, the text value is either 'True' or 'False'.
            - for numeric types, the return value is either Decimal or in, use
              the float, decimal or int properties to force the type.
            - Use the method Cell.set_value() to customize the text value.
        """
        value_type = self.get_attribute_string("office:value-type")
        if value_type == "boolean":
            return self.bool
        if value_type in {"float", "percentage", "currency"}:
            value_decimal = Decimal(str(self.get_attribute_string("office:value")))
            # Return 3 instead of 3.0 if possible
            if int(value_decimal) == value_decimal:
                return int(value_decimal)
            return value_decimal
        if value_type == "date":
            value_str = str(self.get_attribute_string("office:date-value"))
            if "T" in value_str:
                return DateTime.decode(value_str)
            return Date.decode(value_str)
        if value_type == "time":
            return Duration.decode(str(self.get_attribute_string("office:time-value")))
        if value_type == "string":
            value = self.get_attribute_string("office:string-value")
            if value is not None:
                return value
            value_list = []
            for para in self.get_elements("text:p"):
                value_list.append(para.inner_text)
            return "\n".join(value_list)
        return None

    @value.setter
    def value(
        self,
        value: (
            str
            | bytes
            | _bool
            | _int
            | _float
            | Decimal
            | timedelta
            | _datetime
            | _date
            | None
        ),
    ) -> None:
        if value is None:
            self.clear()
        elif isinstance(value, (str, bytes)):
            self.string = value
        elif isinstance(value, _bool):
            self.bool = value
        elif isinstance(value, _float):
            self.float = value
        elif isinstance(value, Decimal):
            self.decimal = value
        elif isinstance(value, _int):
            self.int = value
        elif isinstance(value, timedelta):
            self.duration = value
        elif isinstance(value, _datetime):
            self.datetime = value
        elif isinstance(value, _date):
            self.date = value
        else:
            raise TypeError(f"Unknown value type, try with set_value() : {value!r}")

    @property
    def _bool_string(self) -> str:
        value = self.get_attribute_string("office:boolean-value")
        if not isinstance(value, str):
            return "0"
        return "1" if value == "true" else "0"

    @property
    def float(self) -> _float:
        """Set / get the value of the cell as a float (or 0.0)."""
        for tag in ("office:value", "office:string-value"):
            read_attr = self.get_attribute(tag)
            if isinstance(read_attr, str):
                with contextlib.suppress(ValueError, TypeError):
                    return _float(read_attr)
        return _float(self._bool_string)

    @float.setter
    def float(self, value: str | _float | _int | Decimal | None) -> None:
        try:
            value_float = _float(value)  # type: ignore[arg-type]
        except (ValueError, TypeError, ConversionSyntax):
            value_float = 0.0
        value_str = str(value_float)
        self.clear()
        self.set_attribute("office:value", value_str)
        self.set_attribute("office:value-type", "float")
        self.text = value_str

    @property
    def decimal(self) -> Decimal:
        """Set / get the value of the cell as a Decimal (or 0.0)."""
        for tag in ("office:value", "office:string-value"):
            read_attr = self.get_attribute(tag)
            if isinstance(read_attr, str):
                with contextlib.suppress(ValueError, TypeError, ConversionSyntax):
                    return Decimal(read_attr)
        return Decimal(self._bool_string)

    @decimal.setter
    def decimal(self, value: str | _float | _int | Decimal | None) -> None:
        try:
            value_decimal = Decimal(value)  # type: ignore[arg-type]
        except (ValueError, TypeError, ConversionSyntax, InvalidOperation):
            value_decimal = Decimal("0.0")
        value_str = str(value_decimal)
        self.clear()
        self.set_attribute("office:value", value_str)
        self.set_attribute("office:value-type", "float")
        self.text = value_str

    @property
    def int(self) -> _int:
        """Set / get the value of the cell as a integer (or 0)."""
        for tag in ("office:value", "office:string-value"):
            read_attr = self.get_attribute(tag)
            if isinstance(read_attr, str):
                with contextlib.suppress(ValueError, TypeError):
                    return int(float(read_attr))
        return _int(self._bool_string)

    @int.setter
    def int(self, value: str | _float | _int | Decimal | None) -> None:
        try:
            value_int = _int(value)  # type:ignore
        except (ValueError, TypeError, ConversionSyntax):
            value_int = 0
        value_str = str(value_int)
        self.clear()
        self.set_attribute("office:value", value_str)
        self.set_attribute("office:value-type", "float")
        self.text = value_str

    @property
    def string(self) -> str:
        """Set / get the value of the cell as a string (or '')."""
        value = self.get_attribute_string("office:string-value")
        if isinstance(value, str):
            return value
        return ""

    @string.setter
    def string(
        self,
        value: str | bytes | _int | _float | Decimal | _bool | None,
    ) -> None:
        self.clear()
        if value is None:
            value_str = ""
        elif isinstance(value, bytes):
            value_str = value.decode()
        else:
            value_str = str(value)
        self.set_attribute("office:value-type", "string")
        self.set_attribute("office:string-value", value_str)
        self.text = value_str

    @property
    def bool(self) -> _bool:
        """Set / get the value of the cell as a boolean."""
        value = self.get_attribute_string("office:boolean-value")
        if isinstance(value, str):
            return value == "true"
        return _bool(self.int)

    @bool.setter
    def bool(
        self,
        value: str | bytes | _int | _float | Decimal | _bool | None,
    ) -> None:
        self.clear()
        self.set_attribute("office:value-type", "boolean")
        if isinstance(value, (_bool, str, bytes)):
            bvalue = Boolean.encode(value)
        else:
            bvalue = Boolean.encode(bool(value))
        self.set_attribute("office:boolean-value", bvalue)
        self.text = bvalue

    @property
    def duration(self) -> timedelta:
        """Set / get the value of the cell as a duration (Python timedelta)."""
        value = self.get_attribute("office:time-value")
        if isinstance(value, str):
            return Duration.decode(value)
        return timedelta(0)

    @duration.setter
    def duration(self, value: timedelta) -> None:
        self.clear()
        self.set_attribute("office:value-type", "time")
        dvalue = Duration.encode(value)
        self.set_attribute("office:time-value", dvalue)
        self.text = dvalue

    @property
    def datetime(self) -> _datetime:
        """Set / get the value of the cell as a datetime."""
        value = self.get_attribute("office:date-value")
        if isinstance(value, str):
            return DateTime.decode(value)
        return _datetime.fromtimestamp(0)

    @datetime.setter
    def datetime(self, value: _datetime) -> None:
        self.clear()
        self.set_attribute("office:value-type", "date")
        dvalue = DateTime.encode(value)
        self.set_attribute("office:date-value", dvalue)
        self.text = dvalue

    @property
    def date(self) -> _date:
        """Set / get the value of the cell as a date."""
        value = self.get_attribute("office:date-value")
        if isinstance(value, str):
            return Date.decode(value).date()
        return _date.fromtimestamp(0)

    @date.setter
    def date(self, value: _date) -> None:
        self.clear()
        self.set_attribute("office:value-type", "date")
        dvalue = Date.encode(value)
        self.set_attribute("office:date-value", dvalue)
        self.text = dvalue

    def set_value(
        self,
        value: (
            str
            | bytes
            | _float
            | _int
            | Decimal
            | _bool
            | _datetime
            | _date
            | timedelta
            | None
        ),
        text: str | None = None,
        cell_type: str | None = None,
        currency: str | None = None,
        formula: str | None = None,
    ) -> None:
        """Set the cell state from the Python value type.

        Text is how the cell is displayed. Cell type is guessed,
        unless provided.

        For monetary values, provide the name of the currency.

        Args:

            value -- Python type

            text -- str

            cell_type -- 'boolean', 'float', 'date', 'string', 'time',
                        'currency' or 'percentage'

            currency -- str
        """
        self.clear()
        text = self.set_value_and_type(
            value=value,
            text=text,
            value_type=cell_type,
            currency=currency,
        )
        if text is not None:
            self.text_content = text
        if formula is not None:
            self.formula = formula

    @property
    def type(self) -> str | None:
        """Get / set the type of the cell: boolean, float, date, string or
        time.

        Returns: str | None
        """
        return self.get_attribute_string("office:value-type")

    @type.setter
    def type(self, cell_type: str) -> None:
        self.set_attribute("office:value-type", cell_type)

    @property
    def currency(self) -> str | None:
        """Get / set the currency used for monetary values.

        Returns: str | None
        """
        return self.get_attribute_string("office:currency")

    @currency.setter
    def currency(self, currency: str) -> None:
        self.set_attribute("office:currency", currency)

    def _set_repeated(self, repeated: _int | None) -> None:
        """Internal only.

        Set the number of times the cell is repeated, or None to delete.
        Without changing cache.
        """
        if repeated is None or repeated < 2:
            with contextlib.suppress(KeyError):
                self.del_attribute("table:number-columns-repeated")
            return
        self.set_attribute("table:number-columns-repeated", str(repeated))

    @property
    def repeated(self) -> _int | None:
        """Get / set the number of times the cell is repeated.

        Always None when using the table API.

        Returns: int or None
        """
        repeated = self.get_attribute("table:number-columns-repeated")
        if repeated is None:
            return None
        return _int(repeated)

    @repeated.setter
    def repeated(self, repeated: _int | None) -> None:
        self._set_repeated(repeated)
        # update cache
        child: Element = self
        while True:
            # look for Row, parent may be group of rows
            upper = child.parent
            if not upper:
                # lonely cell
                return
            # parent may be group of rows, not table
            if isinstance(upper, Element) and upper._tag == "table:table-row":
                upper._compute_row_cache()  # type:ignore[attr-defined]
                return
            child = upper

    @property
    def style(self) -> str | None:
        """Get / set the style of the cell itself.

        Returns: str | None
        """
        return self.get_attribute_string("table:style-name")

    @style.setter
    def style(self, style: str | Style) -> None:
        self.set_style_attribute("table:style-name", style)

    @property
    def formula(self) -> str | None:
        """Get / set the formula of the cell, or None if undefined.

        The formula is not interpreted in any way.

        Returns: str | None
        """
        return self.get_attribute_string("table:formula")

    @formula.setter
    def formula(self, formula: str | None) -> None:
        self.set_attribute("table:formula", formula)

    def is_empty(self, aggressive: _bool = False) -> _bool:
        """Return whether the cell has no value or the value evaluates to False
        (empty string), and no style.

        If aggressive is True, empty cells with style are considered empty.

        Args:

            aggressive -- bool

        Returns: bool
        """
        if (
            self.value is not None
            or self.children
            or self.is_covered()
            or self.is_spanned()
        ):
            return False
        if not aggressive and self.style is not None:  # noqa: SIM103
            return False
        return True

    def is_covered(self) -> _bool:
        """Return whether the cell is covered (tag table:covered-table-cell).

        Returns: True | False
        """
        return self.tag == "table:covered-table-cell"

    def is_spanned(self, covered: _bool = True) -> _bool:
        """Return whether the cell is spanned over several cells.

        If covered is True (the default), covered cells are considered as
        spanned, else only the top left cell. The top left contains the
        attributes "table:number-columns-spanned" and
        "table:number-rows-spanned".

        Args:

            covered -- bool

        Returns: True | False
        """
        if self.is_covered():
            return covered
        if self.get_attribute("table:number-columns-spanned") is not None:
            return True
        if self.get_attribute("table:number-rows-spanned") is not None:  # noqa: SIM103
            return True
        return False

    _is_spanned = is_spanned  # compatibility

    def span_area(self) -> tuple[_int, _int]:
        """Return the tuple (nb_columns, nb_rows) of the zone covered by a
        spanned cell.

        If the cell is not spanned, return (0,0).

        Returns: tuple[int, int]
        """
        columns = self.get_attribute_integer("table:number-columns-spanned") or 0
        rows = self.get_attribute_integer("table:number-rows-spanned") or 0
        return (columns, rows)

bool property writable

bool: _bool

Set / get the value of the cell as a boolean.

clone property

clone: Cell

currency property writable

currency: str | None

Get / set the currency used for monetary values.

Returns: str | None

date property writable

date: date

Set / get the value of the cell as a date.

datetime property writable

datetime: datetime

Set / get the value of the cell as a datetime.

decimal property writable

decimal: Decimal

Set / get the value of the cell as a Decimal (or 0.0).

duration property writable

duration: timedelta

Set / get the value of the cell as a duration (Python timedelta).

float property writable

float: _float

Set / get the value of the cell as a float (or 0.0).

formula property writable

formula: str | None

Get / set the formula of the cell, or None if undefined.

The formula is not interpreted in any way.

Returns: str | None

int property writable

int: _int

Set / get the value of the cell as a integer (or 0).

repeated property writable

repeated: _int | None

Get / set the number of times the cell is repeated.

Always None when using the table API.

Returns: int or None

string property writable

string: str

Set / get the value of the cell as a string (or ‘’).

style property writable

style: str | None

Get / set the style of the cell itself.

Returns: str | None

type property writable

type: str | None

Get / set the type of the cell: boolean, float, date, string or time.

Returns: str | None

value property writable

value: (
    str
    | _bool
    | _int
    | _float
    | Decimal
    | date
    | datetime
    | timedelta
    | None
)

Set / get the value of the cell. The type is read from the ‘office:value-type’ attribute of the cell. When setting the value, the type of the value will determine the new value_type of the cell.

Warning

• for date, datetime and timedelta, a default text value is generated.
• for boolean type, the text value is either ‘True’ or ‘False’.
• for numeric types, the return value is either Decimal or in, use the float, decimal or int properties to force the type.
• Use the method Cell.set_value() to customize the text value.

x instance-attribute

x: int | None = None

y instance-attribute

y: int | None = None

__init__

__init__(
    value: Any = None,
    text: str | None = None,
    cell_type: str | None = None,
    currency: str | None = None,
    formula: str | None = None,
    repeated: _int | None = None,
    style: str | None = None,
    **kwargs: Any,
) -> None

Cell of a Table, “table:table-cell”.

Create a cell element containing the given value. The textual representation is automatically formatted but can be provided. Cell type can be deduced as well, unless the number is a percentage or currency. If cell type is “currency”, the currency must be given. The cell can be repeated on the given number of columns.

Args:

value -- bool, int, float, Decimal, date, datetime, str,
         timedelta

text -- str

cell_type -- 'boolean', 'currency', 'date', 'float', 'percentage',
             'string' or 'time'

currency -- three-letter str

repeated -- int

style -- str

Source code in odfdo/cell.py

def __init__(
    self,
    value: Any = None,
    text: str | None = None,
    cell_type: str | None = None,
    currency: str | None = None,
    formula: str | None = None,
    repeated: _int | None = None,
    style: str | None = None,
    **kwargs: Any,
) -> None:
    """Cell of a Table, "table:table-cell".

    Create a cell element containing the given value. The textual
    representation is automatically formatted but can be provided. Cell
    type can be deduced as well, unless the number is a percentage or
    currency. If cell type is "currency", the currency must be given.
    The cell can be repeated on the given number of columns.

    Args:

        value -- bool, int, float, Decimal, date, datetime, str,
                 timedelta

        text -- str

        cell_type -- 'boolean', 'currency', 'date', 'float', 'percentage',
                     'string' or 'time'

        currency -- three-letter str

        repeated -- int

        style -- str
    """
    super().__init__(**kwargs)
    self.x: int | None = None
    self.y: int | None = None
    if self._do_init:
        self.set_value(
            value,
            text=text,
            cell_type=cell_type,
            currency=currency,
            formula=formula,
        )
        if repeated and repeated > 1:
            self.repeated = repeated
        if style is not None:
            self.style = style

is_covered

is_covered() -> _bool

Return whether the cell is covered (tag table:covered-table-cell).

Returns: True | False

Source code in odfdo/cell.py

def is_covered(self) -> _bool:
    """Return whether the cell is covered (tag table:covered-table-cell).

    Returns: True | False
    """
    return self.tag == "table:covered-table-cell"

is_empty

is_empty(aggressive: _bool = False) -> _bool

Return whether the cell has no value or the value evaluates to False (empty string), and no style.

If aggressive is True, empty cells with style are considered empty.

Args:

aggressive -- bool

Returns: bool

Source code in odfdo/cell.py

def is_empty(self, aggressive: _bool = False) -> _bool:
    """Return whether the cell has no value or the value evaluates to False
    (empty string), and no style.

    If aggressive is True, empty cells with style are considered empty.

    Args:

        aggressive -- bool

    Returns: bool
    """
    if (
        self.value is not None
        or self.children
        or self.is_covered()
        or self.is_spanned()
    ):
        return False
    if not aggressive and self.style is not None:  # noqa: SIM103
        return False
    return True

is_spanned

is_spanned(covered: _bool = True) -> _bool

Return whether the cell is spanned over several cells.

If covered is True (the default), covered cells are considered as spanned, else only the top left cell. The top left contains the attributes “table:number-columns-spanned” and “table:number-rows-spanned”.

Args:

covered -- bool

Returns: True | False

Source code in odfdo/cell.py

def is_spanned(self, covered: _bool = True) -> _bool:
    """Return whether the cell is spanned over several cells.

    If covered is True (the default), covered cells are considered as
    spanned, else only the top left cell. The top left contains the
    attributes "table:number-columns-spanned" and
    "table:number-rows-spanned".

    Args:

        covered -- bool

    Returns: True | False
    """
    if self.is_covered():
        return covered
    if self.get_attribute("table:number-columns-spanned") is not None:
        return True
    if self.get_attribute("table:number-rows-spanned") is not None:  # noqa: SIM103
        return True
    return False

set_value

set_value(
    value: str
    | bytes
    | _float
    | _int
    | Decimal
    | _bool
    | datetime
    | date
    | timedelta
    | None,
    text: str | None = None,
    cell_type: str | None = None,
    currency: str | None = None,
    formula: str | None = None,
) -> None

Set the cell state from the Python value type.

Text is how the cell is displayed. Cell type is guessed, unless provided.

For monetary values, provide the name of the currency.

Args:

value -- Python type

text -- str

cell_type -- 'boolean', 'float', 'date', 'string', 'time',
            'currency' or 'percentage'

currency -- str

Source code in odfdo/cell.py

def set_value(
    self,
    value: (
        str
        | bytes
        | _float
        | _int
        | Decimal
        | _bool
        | _datetime
        | _date
        | timedelta
        | None
    ),
    text: str | None = None,
    cell_type: str | None = None,
    currency: str | None = None,
    formula: str | None = None,
) -> None:
    """Set the cell state from the Python value type.

    Text is how the cell is displayed. Cell type is guessed,
    unless provided.

    For monetary values, provide the name of the currency.

    Args:

        value -- Python type

        text -- str

        cell_type -- 'boolean', 'float', 'date', 'string', 'time',
                    'currency' or 'percentage'

        currency -- str
    """
    self.clear()
    text = self.set_value_and_type(
        value=value,
        text=text,
        value_type=cell_type,
        currency=currency,
    )
    if text is not None:
        self.text_content = text
    if formula is not None:
        self.formula = formula

span_area

span_area() -> tuple[_int, _int]

Return the tuple (nb_columns, nb_rows) of the zone covered by a spanned cell.

If the cell is not spanned, return (0,0).

Returns: tuple[int, int]

Source code in odfdo/cell.py

def span_area(self) -> tuple[_int, _int]:
    """Return the tuple (nb_columns, nb_rows) of the zone covered by a
    spanned cell.

    If the cell is not spanned, return (0,0).

    Returns: tuple[int, int]
    """
    columns = self.get_attribute_integer("table:number-columns-spanned") or 0
    rows = self.get_attribute_integer("table:number-rows-spanned") or 0
    return (columns, rows)

ChangeInfo

Bases: Element, DcCreatorMixin, DcDateMixin

Representation of information of a change, “office:change-info”.

The “office:change-info” element represents who made a change and when. It may also contain a comment (one or more Paragraph “text:p” elements) on the change.

The comments available in the ChangeInfo are available through:

• paragraphs property, get_paragraphs and get_paragraph methods for actual Paragraph.

• get_comments for a plain text version

Methods:

Name	Description
__init__	Create information of a change “office:change-info”.
get_comments	Get text content of the comments. If joined is True (default), the
set_comments	Set the text content of the comments. If replace is True (default),

Attributes:

Name	Type	Description
creator
date

Source code in odfdo/tracked_changes.py

class ChangeInfo(Element, DcCreatorMixin, DcDateMixin):
    """Representation of information of a change, "office:change-info".

    The "office:change-info" element represents who made a change and when.
    It may also contain a comment (one or more Paragraph "text:p" elements)
    on the change.

    The comments available in the ChangeInfo are available through:

       - paragraphs property, get_paragraphs and get_paragraph methods for actual Paragraph.

       - get_comments for a plain text version
    """

    _tag = "office:change-info"

    def __init__(
        self,
        creator: str | None = None,
        date: datetime | None = None,
        **kwargs: Any,
    ) -> None:
        """Create information of a change "office:change-info".

        Args:

           creator -- str (or None)

           date -- datetime (or None)
        """
        super().__init__(**kwargs)
        if self._do_init:
            self.creator = creator or "Unknown"
            self.date = date

    def get_comments(self, joined: bool = True) -> str | list[str]:
        """Get text content of the comments. If joined is True (default), the
        text of different paragraphs is concatenated, else a list of strings,
        one per paragraph, is returned.

        Args:

            joined -- boolean (default is True)

        Returns: str or list of str.
        """
        content = self.paragraphs
        text = [para.get_formatted_text(simple=True) for para in content]
        if joined:
            return "\n".join(text)
        return text

    def set_comments(self, text: str = "", replace: bool = True) -> None:
        """Set the text content of the comments. If replace is True (default),
        the new text replace old comments, else it is added at the end.

        Args:

            text -- str

            replace -- boolean
        """
        if replace:
            for para in self.paragraphs:
                self.delete(para)
        para = Paragraph()
        para.append_plain_text(text)
        self.insert(para, xmlposition=LAST_CHILD)

creator instance-attribute

creator = creator or 'Unknown'

date instance-attribute

date = date

__init__

__init__(
    creator: str | None = None,
    date: datetime | None = None,
    **kwargs: Any,
) -> None

Create information of a change “office:change-info”.

Args:

creator – str (or None)

date – datetime (or None)

Source code in odfdo/tracked_changes.py

def __init__(
    self,
    creator: str | None = None,
    date: datetime | None = None,
    **kwargs: Any,
) -> None:
    """Create information of a change "office:change-info".

    Args:

       creator -- str (or None)

       date -- datetime (or None)
    """
    super().__init__(**kwargs)
    if self._do_init:
        self.creator = creator or "Unknown"
        self.date = date

get_comments

get_comments(joined: bool = True) -> str | list[str]

Get text content of the comments. If joined is True (default), the text of different paragraphs is concatenated, else a list of strings, one per paragraph, is returned.

Args:

joined -- boolean (default is True)

Returns: str or list of str.

Source code in odfdo/tracked_changes.py

def get_comments(self, joined: bool = True) -> str | list[str]:
    """Get text content of the comments. If joined is True (default), the
    text of different paragraphs is concatenated, else a list of strings,
    one per paragraph, is returned.

    Args:

        joined -- boolean (default is True)

    Returns: str or list of str.
    """
    content = self.paragraphs
    text = [para.get_formatted_text(simple=True) for para in content]
    if joined:
        return "\n".join(text)
    return text

set_comments

set_comments(text: str = '', replace: bool = True) -> None

Set the text content of the comments. If replace is True (default), the new text replace old comments, else it is added at the end.

Args:

text -- str

replace -- boolean

Source code in odfdo/tracked_changes.py

def set_comments(self, text: str = "", replace: bool = True) -> None:
    """Set the text content of the comments. If replace is True (default),
    the new text replace old comments, else it is added at the end.

    Args:

        text -- str

        replace -- boolean
    """
    if replace:
        for para in self.paragraphs:
            self.delete(para)
    para = Paragraph()
    para.append_plain_text(text)
    self.insert(para, xmlposition=LAST_CHILD)

Chart

Bases: NRMixin, Body

Root of the Chart document content, “office:chart”.

Source code in odfdo/body.py

class Chart(NRMixin, Body):
    """Root of the Chart document content, "office:chart"."""

    _tag: str = "office:chart"
    _properties: tuple[PropDef, ...] = ()

Column

Bases: Element

A Column of a table, “table:table-column”.

Methods:

Name	Description
__init__	A Column of a table, “table:table-column”.
get_default_cell_style	Get or set the default cell style for column.
set_default_cell_style	Get or set the default cell style for column.

Attributes:

Name	Type	Description
clone	Column
default_cell_style	str | None	Get or set the default cell style for column.
repeated	int | None	Get /set the number of times the column is repeated.
style	str | None	Get /set the style of the column itself.
x	int | None

Source code in odfdo/column.py

class Column(Element):
    """A Column of a table, "table:table-column"."""

    _tag = "table:table-column"

    def __init__(
        self,
        default_cell_style: str | None = None,
        repeated: int | None = None,
        style: str | None = None,
        **kwargs: Any,
    ) -> None:
        """A Column of a table, "table:table-column".

        Create a column group element of the optionally given style. Cell
        style can be set for the whole column. If the properties apply to
        several columns, give the number of repeated columns.

        Columns don't contain cells, just style information.

        You don't generally have to create columns by hand, use the Table API.

        Args:

            default_cell_style -- str or None

            repeated -- int or None

            style -- str or None
        """
        super().__init__(**kwargs)
        self.x: int | None = None
        if self._do_init:
            if default_cell_style:
                self.default_cell_style = default_cell_style
            if repeated and repeated > 1:
                self.repeated = repeated
            if style:
                self.style = style

    def __repr__(self) -> str:
        return f"<{self.__class__.__name__} x={self.x}>"

    @property
    def clone(self) -> Column:
        clone: Column = Element.clone.fget(self)  # type: ignore[attr-defined]
        clone.x = self.x
        return clone

    def get_default_cell_style(self) -> str | None:
        """Get or set the default cell style for column.

        (See also self.default_cell_style property.)
        """
        return self.get_attribute_string("table:default-cell-style-name")

    def set_default_cell_style(self, style: Style | str | None) -> None:
        """Get or set the default cell style for column.

        (See also self.default_cell_style property.)
        """
        self.set_style_attribute("table:default-cell-style-name", style)

    @property
    def default_cell_style(self) -> str | None:
        """Get or set the default cell style for column."""
        return self.get_attribute_string("table:default-cell-style-name")

    @default_cell_style.setter
    def default_cell_style(self, style: Style | str | None) -> None:
        self.set_style_attribute("table:default-cell-style-name", style)

    def _set_repeated(self, repeated: int | None) -> None:
        """Internal only. Set the number of times the column is repeated, or
        None to delete it. Without changing cache.

        Args:

            repeated -- int or None
        """
        if repeated is None or repeated < 2:
            with contextlib.suppress(KeyError):
                self.del_attribute("table:number-columns-repeated")
            return
        self.set_attribute("table:number-columns-repeated", str(repeated))

    @property
    def repeated(self) -> int | None:
        """Get /set the number of times the column is repeated.

        Always None when using the table API.

        Returns: int or None
        """
        repeated = self.get_attribute("table:number-columns-repeated")
        if repeated is None:
            return None
        return int(repeated)

    @repeated.setter
    def repeated(self, repeated: int | None) -> None:
        self._set_repeated(repeated)
        # update cache
        current: Element = self
        while True:
            # look for Table, parent may be group of rows
            upper = current.parent
            if not upper:
                # lonely column
                return
            # parent may be group of rows, not table
            if upper.tag == "table:table":
                break
            current = upper

    @property
    def style(self) -> str | None:
        """Get /set the style of the column itself.

        Returns: str or None
        """
        return self.get_attribute_string("table:style-name")

    @style.setter
    def style(self, style: str | Style | None) -> None:
        self.set_style_attribute("table:style-name", style)

clone property

clone: Column

default_cell_style property writable

default_cell_style: str | None

Get or set the default cell style for column.

repeated property writable

repeated: int | None

Get /set the number of times the column is repeated.

Always None when using the table API.

Returns: int or None

style property writable

style: str | None

Get /set the style of the column itself.

Returns: str or None

x instance-attribute

x: int | None = None

__init__

__init__(
    default_cell_style: str | None = None,
    repeated: int | None = None,
    style: str | None = None,
    **kwargs: Any,
) -> None

A Column of a table, “table:table-column”.

Create a column group element of the optionally given style. Cell style can be set for the whole column. If the properties apply to several columns, give the number of repeated columns.

Columns don’t contain cells, just style information.

You don’t generally have to create columns by hand, use the Table API.

Args:

default_cell_style -- str or None

repeated -- int or None

style -- str or None

Source code in odfdo/column.py

def __init__(
    self,
    default_cell_style: str | None = None,
    repeated: int | None = None,
    style: str | None = None,
    **kwargs: Any,
) -> None:
    """A Column of a table, "table:table-column".

    Create a column group element of the optionally given style. Cell
    style can be set for the whole column. If the properties apply to
    several columns, give the number of repeated columns.

    Columns don't contain cells, just style information.

    You don't generally have to create columns by hand, use the Table API.

    Args:

        default_cell_style -- str or None

        repeated -- int or None

        style -- str or None
    """
    super().__init__(**kwargs)
    self.x: int | None = None
    if self._do_init:
        if default_cell_style:
            self.default_cell_style = default_cell_style
        if repeated and repeated > 1:
            self.repeated = repeated
        if style:
            self.style = style

get_default_cell_style

get_default_cell_style() -> str | None

Get or set the default cell style for column.

(See also self.default_cell_style property.)

Source code in odfdo/column.py

def get_default_cell_style(self) -> str | None:
    """Get or set the default cell style for column.

    (See also self.default_cell_style property.)
    """
    return self.get_attribute_string("table:default-cell-style-name")

set_default_cell_style

set_default_cell_style(style: Style | str | None) -> None

Get or set the default cell style for column.

(See also self.default_cell_style property.)

Source code in odfdo/column.py

def set_default_cell_style(self, style: Style | str | None) -> None:
    """Get or set the default cell style for column.

    (See also self.default_cell_style property.)
    """
    self.set_style_attribute("table:default-cell-style-name", style)

ConnectorShape

Bases: ShapeBase

A connector shape, “draw:connector”.

Methods:

Name	Description
__init__	Create a Connector shape “draw:connector”.

Attributes:

Name	Type	Description
end_glue_point
end_shape
start_glue_point
start_shape
x1
x2
y1
y2

Source code in odfdo/shapes.py

class ConnectorShape(ShapeBase):
    """A connector shape, "draw:connector"."""

    _tag = "draw:connector"
    _properties: tuple[PropDef, ...] = (
        PropDef("start_shape", "draw:start-shape"),
        PropDef("end_shape", "draw:end-shape"),
        PropDef("start_glue_point", "draw:start-glue-point"),
        PropDef("end_glue_point", "draw:end-glue-point"),
        PropDef("x1", "svg:x1"),
        PropDef("y1", "svg:y1"),
        PropDef("x2", "svg:x2"),
        PropDef("y2", "svg:y2"),
    )

    def __init__(
        self,
        style: str | None = None,
        text_style: str | None = None,
        draw_id: str | None = None,
        layer: str | None = None,
        connected_shapes: tuple | None = None,
        glue_points: tuple | None = None,
        p1: tuple | None = None,
        p2: tuple | None = None,
        **kwargs: Any,
    ) -> None:
        """Create a Connector shape "draw:connector".

        Args:

            style -- str

            text_style -- str

            draw_id -- str

            layer -- str

            connected_shapes -- (shape, shape)

            glue_points -- (point, point)

            p1 -- (str, str)

            p2 -- (str, str)
        """
        kwargs.update(
            {
                "style": style,
                "text_style": text_style,
                "draw_id": draw_id,
                "layer": layer,
            }
        )
        super().__init__(**kwargs)
        if self._do_init:
            if connected_shapes:
                self.start_shape = connected_shapes[0].draw_id
                self.end_shape = connected_shapes[1].draw_id
            if glue_points:
                self.start_glue_point = glue_points[0]
                self.end_glue_point = glue_points[1]
            if p1:
                self.x1 = p1[0]
                self.y1 = p1[1]
            if p2:
                self.x2 = p2[0]
                self.y2 = p2[1]

end_glue_point instance-attribute

end_glue_point = glue_points[1]

end_shape instance-attribute

end_shape = draw_id

start_glue_point instance-attribute

start_glue_point = glue_points[0]

start_shape instance-attribute

start_shape = draw_id

x1 instance-attribute

x1 = p1[0]

x2 instance-attribute

x2 = p2[0]

y1 instance-attribute

y1 = p1[1]

y2 instance-attribute

y2 = p2[1]

__init__

__init__(
    style: str | None = None,
    text_style: str | None = None,
    draw_id: str | None = None,
    layer: str | None = None,
    connected_shapes: tuple | None = None,
    glue_points: tuple | None = None,
    p1: tuple | None = None,
    p2: tuple | None = None,
    **kwargs: Any,
) -> None

Create a Connector shape “draw:connector”.

Args:

style -- str

text_style -- str

draw_id -- str

layer -- str

connected_shapes -- (shape, shape)

glue_points -- (point, point)

p1 -- (str, str)

p2 -- (str, str)

Source code in odfdo/shapes.py

def __init__(
    self,
    style: str | None = None,
    text_style: str | None = None,
    draw_id: str | None = None,
    layer: str | None = None,
    connected_shapes: tuple | None = None,
    glue_points: tuple | None = None,
    p1: tuple | None = None,
    p2: tuple | None = None,
    **kwargs: Any,
) -> None:
    """Create a Connector shape "draw:connector".

    Args:

        style -- str

        text_style -- str

        draw_id -- str

        layer -- str

        connected_shapes -- (shape, shape)

        glue_points -- (point, point)

        p1 -- (str, str)

        p2 -- (str, str)
    """
    kwargs.update(
        {
            "style": style,
            "text_style": text_style,
            "draw_id": draw_id,
            "layer": layer,
        }
    )
    super().__init__(**kwargs)
    if self._do_init:
        if connected_shapes:
            self.start_shape = connected_shapes[0].draw_id
            self.end_shape = connected_shapes[1].draw_id
        if glue_points:
            self.start_glue_point = glue_points[0]
            self.end_glue_point = glue_points[1]
        if p1:
            self.x1 = p1[0]
            self.y1 = p1[1]
        if p2:
            self.x2 = p2[0]
            self.y2 = p2[1]

Container

Storage of the ODF document, as zip or other format.

Methods:

Name	Description
__init__	Storage of the ODF document, as zip or other format.
del_part	Mark a part for deletion.
get_part	Get the bytes of a part of the ODF.
get_parts	Get the list of members.
open	Load the content of an ODF file.
save	Save the container to the given target, a path or a file-like
set_part	Replace or add a new part.

Attributes:

Name	Type	Description
clone	Container	Make a copy of this container with no path.
default_manifest_rdf	str
mimetype	str	Return str value of mimetype of the document.
parts	list[str]	Get the list of members.
path	Path | None

Source code in odfdo/container.py

class Container:
    """Storage of the ODF document, as zip or other format."""

    def __init__(self, path: Path | str | io.BytesIO | None = None) -> None:
        """Storage of the ODF document, as zip or other format.

        Args:

        path -- path like, io.BytesIO or None
        """
        self.__parts: dict[str, bytes | None] = {}
        self.__parts_ts: dict[str, int] = {}
        self.__path_like: Path | str | io.BytesIO | None = None
        self.__packaging: str = ZIP
        self.path: Path | None = None  # or Path
        if path:
            self.open(path)

    def __repr__(self) -> str:
        return f"<{self.__class__.__name__} type={self.mimetype} path={self.path}>"

    def open(self, path_or_file: Path | str | io.BytesIO) -> None:
        """Load the content of an ODF file."""
        self.__path_like = path_or_file
        if isinstance(path_or_file, (str, Path)):
            self.path = Path(path_or_file).expanduser()
            if not self.path.exists():
                raise FileNotFoundError(str(self.path))
            self.__path_like = self.path
        if (self.path or isinstance(self.__path_like, io.BytesIO)) and is_zipfile(
            self.__path_like
        ):
            self.__packaging = ZIP
            return self._read_zip()
        if self.path:
            is_folder = False
            with contextlib.suppress(OSError):
                is_folder = self.path.is_dir()
            if is_folder:
                self.__packaging = FOLDER
                return self._read_folder()
        msg = f"Document format not managed by odfdo: {type(path_or_file)}."
        raise TypeError(msg)

    def _read_zip(self) -> None:
        if isinstance(self.__path_like, io.BytesIO):
            self.__path_like.seek(0)
        with ZipFile(self.__path_like) as zf:  # type: ignore
            mimetype = bytes_to_str(zf.read("mimetype"))
            if mimetype not in ODF_MIMETYPES:
                raise ValueError(f"Document of unknown type {mimetype}")
            self.__parts["mimetype"] = str_to_bytes(mimetype)
        if self.path is None:
            if isinstance(self.__path_like, io.BytesIO):
                self.__path_like.seek(0)
            # read the full file at once and forget file
            with ZipFile(self.__path_like) as zf:  # type: ignore
                for name in zf.namelist():
                    upath = normalize_path(name)
                    self.__parts[upath] = zf.read(name)
            self.__path_like = None

    def _read_folder(self) -> None:
        try:
            mimetype, timestamp = self._get_folder_part("mimetype")
        except OSError:
            msg = "Corrupted or not an OpenDocument folder (missing mimetype)"
            printwarn(msg)
            mimetype = b""
            timestamp = int(time.time())
        if bytes_to_str(mimetype) not in ODF_MIMETYPES:
            msg = f"Document of unknown type {mimetype!r}, try with ODF Text."
            printwarn(msg)
            self.__parts["mimetype"] = str_to_bytes(ODF_EXTENSIONS["odt"])
            self.__parts_ts["mimetype"] = timestamp

    def _parse_folder(self, folder: str) -> list[str]:
        parts = []
        if self.path is None:
            raise ValueError("Document path is not defined")
        root = self.path / folder
        for path in root.iterdir():
            if path.name.startswith("."):  # no hidden files
                continue
            relative_path = path.relative_to(self.path)
            if path.is_file():
                parts.append(relative_path.as_posix())
            if path.is_dir():
                sub_parts = self._parse_folder(str(relative_path))
                if sub_parts:
                    parts.extend(sub_parts)
                else:
                    # store leaf directories
                    parts.append(relative_path.as_posix() + "/")
        return parts

    def _get_folder_parts(self) -> list[str]:
        """Get the list of members in the ODF folder."""
        return self._parse_folder("")

    def _get_folder_part(self, name: str) -> tuple[bytes, int]:
        """Get bytes of a part from the ODF folder, with timestamp."""
        if self.path is None:
            raise ValueError("Document path is not defined")
        path = self.path / name
        timestamp = int(path.stat().st_mtime)
        if path.is_dir():
            return (b"", timestamp)
        return (path.read_bytes(), timestamp)

    def _get_folder_part_timestamp(self, name: str) -> int:
        if self.path is None:
            raise ValueError("Document path is not defined")
        path = self.path / name
        try:
            timestamp = int(path.stat().st_mtime)
        except OSError:
            timestamp = -1
        return timestamp

    def _get_zip_part(self, name: str) -> bytes | None:
        """Get bytes of a part from the Zip ODF file.

        No cache.
        """
        if self.path is None:
            raise ValueError("Document path is not defined")
        try:
            with ZipFile(self.path) as zf:
                upath = normalize_path(name)
                self.__parts[upath] = zf.read(name)
                return self.__parts[upath]
        except BadZipfile:
            return None

    def _get_all_zip_part(self) -> None:
        """Read all parts.

        No cache.
        """
        if self.path is None:
            raise ValueError("Document path is not defined")
        try:
            with ZipFile(self.path) as zf:
                for name in zf.namelist():
                    upath = normalize_path(name)
                    self.__parts[upath] = zf.read(name)
        except BadZipfile:
            pass

    def _save_zip(self, target: str | Path | io.BytesIO) -> None:
        """Save a Zip ODF from the available parts."""
        parts = self.__parts
        with ZipFile(target, "w", compression=ZIP_DEFLATED) as filezip:
            # Parts to save, except manifest at the end
            part_names = list(parts.keys())
            try:
                part_names.remove(ODF_MANIFEST)
            except ValueError:
                printwarn(f"Missing '{ODF_MANIFEST}'")
            # "Pretty-save" parts in some order
            # mimetype requires to be first and uncompressed
            mimetype = parts.get("mimetype")
            if mimetype is None:
                raise ValueError("Mimetype is not defined")
            try:
                filezip.writestr("mimetype", mimetype, ZIP_STORED)
                part_names.remove("mimetype")
            except (ValueError, KeyError):
                printwarn("Missing 'mimetype'")
            # XML parts
            for path in ODF_CONTENT, ODF_META, ODF_SETTINGS, ODF_STYLES:
                if path not in parts:
                    printwarn(f"Missing '{path}'")
                    continue
                part = parts[path]
                if part is None:
                    continue
                filezip.writestr(path, part)
                part_names.remove(path)
            # Everything else
            for path in part_names:
                data = parts[path]
                if data is None:
                    # Deleted
                    continue
                filezip.writestr(path, data)
            with contextlib.suppress(KeyError):
                part = parts[ODF_MANIFEST]
                if part is not None:
                    filezip.writestr(ODF_MANIFEST, part)

    def _save_folder(self, folder: Path | str) -> None:
        """Save a folder ODF from the available parts."""

        def dump(part_path: str, content: bytes) -> None:
            if part_path.endswith("/"):  # folder
                is_folder = True
                pure_path = PurePath(folder, part_path[:-1])
            else:
                is_folder = False
                pure_path = PurePath(folder, part_path)
            path = Path(pure_path)
            if is_folder:
                path.mkdir(parents=True, exist_ok=True)
            else:
                path.parent.mkdir(parents=True, exist_ok=True)
                path.write_bytes(content)
                path.chmod(0o666)

        for part_path, data in self.__parts.items():
            if data is None:
                # Deleted
                continue
            dump(part_path, data)

    def _encoded_image(self, elem: _Element) -> _Element | None:
        mime_type = elem.get(
            "{urn:oasis:names:tc:opendocument:xmlns:drawing:1.0}mime-type"
        )
        path = elem.get("{http://www.w3.org/1999/xlink}href")
        if not path:
            return None
        content = self.__parts[path]
        if not content:
            return None
        text = base64.standard_b64encode(content).decode()
        ebytes = (
            f'<draw:image draw:mime-type="{mime_type}">'
            f"<office:binary-data>{text}\n</office:binary-data></draw:image>"
        ).encode()
        root = fromstring(NAMESPACES_XML % ebytes)
        return root[0]

    def _xml_content(self, pretty: bool = True) -> bytes:
        mimetype_b = self.__parts["mimetype"]
        if mimetype_b is None:
            # use some default
            mimetype = "application/vnd.oasis.opendocument.text"
        else:
            mimetype = mimetype_b.decode("utf8")
        doc_xml = (
            OFFICE_PREFIX.decode("utf8")
            + f'office:version="{OFFICE_VERSION}"\n'
            + f'office:mimetype="{mimetype}">'
            + "</office:document>"
        )
        root = fromstring(doc_xml.encode("utf8"))
        for path in ODF_META, ODF_SETTINGS, ODF_STYLES, ODF_CONTENT:
            if path not in self.__parts:
                printwarn(f"Missing '{path}'")
                continue
            part = self.__parts[path]
            if part is None:
                continue
            if isinstance(part, bytes):
                xpart = fromstring(part)
            else:
                xpart = part
            if path == ODF_CONTENT:
                xpath = xpath_compile("descendant::draw:image")
                images = xpath(xpart)
                if images:
                    for elem in images:
                        encoded = self._encoded_image(elem)
                        elem.getparent().replace(elem, encoded)
            for child in xpart:
                root.append(child)
        if pretty:
            xml_header = b'<?xml version="1.0" encoding="UTF-8"?>\n'
            bytes_tree: bytes = tostring(
                pretty_indent(root),
                encoding="unicode",
            ).encode("utf8")
            return xml_header + bytes_tree
        else:
            return tostring(  # type: ignore[no-any-return]
                root,
                encoding="UTF-8",
                xml_declaration=True,
            )

    def _save_xml(
        self,
        target: Path | str | io.BytesIO,
        pretty: bool = True,
    ) -> None:
        """Save a XML flat ODF format from the available parts."""
        if isinstance(target, (Path, str)):
            target = Path(target).with_suffix(".xml")
            target.write_bytes(self._xml_content(pretty))
        else:
            target.write(self._xml_content(pretty))

    # Public API

    def get_parts(self) -> list[str]:
        """Get the list of members."""
        if not self.path:
            # maybe a file like zip archive
            return list(self.__parts.keys())
        if self.__packaging == ZIP:
            parts = []
            with ZipFile(self.path) as zf:
                for name in zf.namelist():
                    upath = normalize_path(name)
                    parts.append(upath)
            return parts
        elif self.__packaging == FOLDER:
            return self._get_folder_parts()
        else:
            raise ValueError("Unable to provide parts of the document")

    @property
    def parts(self) -> list[str]:
        """Get the list of members."""
        return self.get_parts()

    def get_part(self, path: str) -> str | bytes | None:
        """Get the bytes of a part of the ODF."""
        path = str(path)
        if path in self.__parts:
            part = self.__parts[path]
            if part is None:
                raise ValueError(f'Part "{path}" is deleted')
            if self.__packaging == FOLDER:
                cache_ts = self.__parts_ts.get(path, -1)
                current_ts = self._get_folder_part_timestamp(path)
                if current_ts != cache_ts:
                    part, timestamp = self._get_folder_part(path)
                    self.__parts[path] = part
                    self.__parts_ts[path] = timestamp
            return part
        if self.__packaging == ZIP:
            return self._get_zip_part(path)
        if self.__packaging == FOLDER:
            part, timestamp = self._get_folder_part(path)
            self.__parts[path] = part
            self.__parts_ts[path] = timestamp
            return part
        return None

    @property
    def default_manifest_rdf(self) -> str:
        return (
            '<?xml version="1.0" encoding="utf-8"?>\n'
            '<rdf:RDF xmlns:rdf="http://www.w3.org/'
            '1999/02/22-rdf-syntax-ns#">\n'
            '  <rdf:Description rdf:about="styles.xml">\n'
            '    <rdf:type rdf:resource="http://docs.oasis-open.org/'
            f'ns/office/{OFFICE_VERSION}/meta/odf#StylesFile"/>\n'
            "  </rdf:Description>\n"
            '  <rdf:Description rdf:about="">\n'
            '    <ns0:hasPart xmlns:ns0="http://docs.oasis-open.org/ns/'
            f'office/{OFFICE_VERSION}/meta/pkg#" rdf:resource="styles.xml"/>\n'
            "  </rdf:Description>\n"
            '  <rdf:Description rdf:about="content.xml">\n'
            '    <rdf:type rdf:resource="http://docs.oasis-open.org/'
            f'ns/office/{OFFICE_VERSION}/meta/odf#ContentFile"/>\n'
            "  </rdf:Description>\n"
            '  <rdf:Description rdf:about="">\n'
            '    <ns0:hasPart xmlns:ns0="http://docs.oasis-open.org/ns/office'
            f'/{OFFICE_VERSION}/meta/pkg#" rdf:resource="content.xml"/>\n'
            "  </rdf:Description>\n"
            '  <rdf:Description rdf:about="">\n'
            '    <rdf:type rdf:resource="http://docs.oasis-open.org/ns/office'
            f'/{OFFICE_VERSION}/meta/pkg#Document"/>\n'
            "  </rdf:Description>\n"
            "</rdf:RDF>\n"
        )

    @property
    def mimetype(self) -> str:
        """Return str value of mimetype of the document."""
        with contextlib.suppress(Exception):
            b_mimetype = self.get_part("mimetype")
            if isinstance(b_mimetype, bytes):
                return bytes_to_str(b_mimetype)
        return ""

    @mimetype.setter
    def mimetype(self, mimetype: str | bytes) -> None:
        """Set mimetype value of the document."""
        if isinstance(mimetype, str):
            self.__parts["mimetype"] = str_to_bytes(mimetype)
        elif isinstance(mimetype, bytes):
            self.__parts["mimetype"] = mimetype
        else:
            raise TypeError(f'Wrong mimetype "{mimetype!r}"')

    def set_part(self, path: str, data: bytes) -> None:
        """Replace or add a new part."""
        self.__parts[path] = data

    def del_part(self, path: str) -> None:
        """Mark a part for deletion."""
        self.__parts[path] = None

    @property
    def clone(self) -> Container:
        """Make a copy of this container with no path."""
        if self.path and self.__packaging == ZIP:
            self._get_all_zip_part()
        clone = deepcopy(self)
        clone.path = None
        return clone

    def _backup_or_unlink(self, backup: bool, target: str | Path) -> None:
        if backup:
            self._do_backup(target)
        else:
            self._do_unlink(target)

    @staticmethod
    def _do_backup(target: str | Path) -> None:
        path = Path(target)
        if not path.exists():
            return
        back_file = Path(path.stem + ".backup" + path.suffix)
        if back_file.is_dir():
            try:
                shutil.rmtree(back_file)
            except OSError as e:
                printwarn(str(e))
        try:
            shutil.move(target, back_file)
        except OSError as e:
            printwarn(str(e))

    @staticmethod
    def _do_unlink(target: str | Path) -> None:
        path = Path(target)
        if path.exists():
            try:
                shutil.rmtree(path)
            except OSError as e:
                printwarn(str(e))

    def _clean_save_packaging(self, packaging: str | None) -> str:
        if not packaging:
            packaging = self.__packaging if self.__packaging else ZIP
        packaging = packaging.strip().lower()
        if packaging not in PACKAGING:
            msg = f'Packaging of type "{packaging}" is not supported'
            raise ValueError(msg)
        return packaging

    def _clean_save_target(
        self,
        target: str | Path | io.BytesIO | None,
    ) -> str | io.BytesIO:
        if target is None:
            target = self.path
        if isinstance(target, Path):
            target = str(target)
        if isinstance(target, str):
            while target.endswith(os.sep):
                target = target[:-1]
            while target.endswith(".folder"):
                target = target.split(".folder", 1)[0]
        return target  # type: ignore

    def _save_as_zip(
        self,
        target: str | Path | io.BytesIO,
        backup: bool,
    ) -> None:
        if isinstance(target, (str, Path)) and backup:
            self._do_backup(target)
        self._save_zip(target)

    def _save_as_folder(self, target: str | Path, backup: bool) -> None:
        if not isinstance(target, (str, Path)):
            raise TypeError(
                f"Saving in folder format requires a folder name, not '{target!r}'"
            )
        if not str(target).endswith(".folder"):
            target = str(target) + ".folder"
        self._backup_or_unlink(backup, target)
        self._save_folder(target)

    def _save_as_xml(
        self,
        target: str | Path | io.BytesIO,
        backup: bool,
        pretty: bool = True,
    ) -> None:
        if not isinstance(target, (str, Path, io.BytesIO)):
            raise TypeError(
                f"Saving in XML format requires a path name, not '{target!r}'"
            )
        if isinstance(target, (str, Path)):
            if not str(target).endswith(".xml"):
                target = str(target) + ".xml"
            if backup:
                self._do_backup(target)
        self._save_xml(target, pretty)

    def save(
        self,
        target: str | Path | io.BytesIO | None,
        packaging: str | None = None,
        backup: bool = False,
        pretty: bool = False,
    ) -> None:
        """Save the container to the given target, a path or a file-like
        object.

        Package the output document in the same format than current document,
        unless "packaging" is different.

        Args:

            target -- str or file-like or Path

            packaging -- 'zip', or for debugging purpose 'xml' or 'folder'

            backup -- boolean
        """
        parts = self.__parts
        packaging = self._clean_save_packaging(packaging)
        # Load parts else they will be considered deleted
        for path in self.parts:
            if path not in parts:
                self.get_part(path)
        target = self._clean_save_target(target)
        if packaging == FOLDER:
            if isinstance(target, io.BytesIO):
                msg = "Impossible to save on io.BytesIO with 'folder' packaging"
                raise TypeError(msg)
            self._save_as_folder(target, backup)
        elif packaging == XML:
            self._save_as_xml(target, backup, pretty)
        else:
            # default:
            self._save_as_zip(target, backup)

clone property

clone: Container

Make a copy of this container with no path.

default_manifest_rdf property

default_manifest_rdf: str

mimetype property writable

mimetype: str

Return str value of mimetype of the document.

parts property

parts: list[str]

Get the list of members.

path instance-attribute

path: Path | None = None

__init__

__init__(path: Path | str | BytesIO | None = None) -> None

Storage of the ODF document, as zip or other format.

Args:

path – path like, io.BytesIO or None

Source code in odfdo/container.py

def __init__(self, path: Path | str | io.BytesIO | None = None) -> None:
    """Storage of the ODF document, as zip or other format.

    Args:

    path -- path like, io.BytesIO or None
    """
    self.__parts: dict[str, bytes | None] = {}
    self.__parts_ts: dict[str, int] = {}
    self.__path_like: Path | str | io.BytesIO | None = None
    self.__packaging: str = ZIP
    self.path: Path | None = None  # or Path
    if path:
        self.open(path)

del_part

del_part(path: str) -> None

Mark a part for deletion.

Source code in odfdo/container.py

def del_part(self, path: str) -> None:
    """Mark a part for deletion."""
    self.__parts[path] = None

get_part

get_part(path: str) -> str | bytes | None

Get the bytes of a part of the ODF.

Source code in odfdo/container.py

def get_part(self, path: str) -> str | bytes | None:
    """Get the bytes of a part of the ODF."""
    path = str(path)
    if path in self.__parts:
        part = self.__parts[path]
        if part is None:
            raise ValueError(f'Part "{path}" is deleted')
        if self.__packaging == FOLDER:
            cache_ts = self.__parts_ts.get(path, -1)
            current_ts = self._get_folder_part_timestamp(path)
            if current_ts != cache_ts:
                part, timestamp = self._get_folder_part(path)
                self.__parts[path] = part
                self.__parts_ts[path] = timestamp
        return part
    if self.__packaging == ZIP:
        return self._get_zip_part(path)
    if self.__packaging == FOLDER:
        part, timestamp = self._get_folder_part(path)
        self.__parts[path] = part
        self.__parts_ts[path] = timestamp
        return part
    return None

get_parts

get_parts() -> list[str]

Get the list of members.

Source code in odfdo/container.py

def get_parts(self) -> list[str]:
    """Get the list of members."""
    if not self.path:
        # maybe a file like zip archive
        return list(self.__parts.keys())
    if self.__packaging == ZIP:
        parts = []
        with ZipFile(self.path) as zf:
            for name in zf.namelist():
                upath = normalize_path(name)
                parts.append(upath)
        return parts
    elif self.__packaging == FOLDER:
        return self._get_folder_parts()
    else:
        raise ValueError("Unable to provide parts of the document")

open

open(path_or_file: Path | str | BytesIO) -> None

Load the content of an ODF file.

Source code in odfdo/container.py

def open(self, path_or_file: Path | str | io.BytesIO) -> None:
    """Load the content of an ODF file."""
    self.__path_like = path_or_file
    if isinstance(path_or_file, (str, Path)):
        self.path = Path(path_or_file).expanduser()
        if not self.path.exists():
            raise FileNotFoundError(str(self.path))
        self.__path_like = self.path
    if (self.path or isinstance(self.__path_like, io.BytesIO)) and is_zipfile(
        self.__path_like
    ):
        self.__packaging = ZIP
        return self._read_zip()
    if self.path:
        is_folder = False
        with contextlib.suppress(OSError):
            is_folder = self.path.is_dir()
        if is_folder:
            self.__packaging = FOLDER
            return self._read_folder()
    msg = f"Document format not managed by odfdo: {type(path_or_file)}."
    raise TypeError(msg)

save

save(
    target: str | Path | BytesIO | None,
    packaging: str | None = None,
    backup: bool = False,
    pretty: bool = False,
) -> None

Save the container to the given target, a path or a file-like object.

Package the output document in the same format than current document, unless “packaging” is different.

Args:

target -- str or file-like or Path

packaging -- 'zip', or for debugging purpose 'xml' or 'folder'

backup -- boolean

Source code in odfdo/container.py

def save(
    self,
    target: str | Path | io.BytesIO | None,
    packaging: str | None = None,
    backup: bool = False,
    pretty: bool = False,
) -> None:
    """Save the container to the given target, a path or a file-like
    object.

    Package the output document in the same format than current document,
    unless "packaging" is different.

    Args:

        target -- str or file-like or Path

        packaging -- 'zip', or for debugging purpose 'xml' or 'folder'

        backup -- boolean
    """
    parts = self.__parts
    packaging = self._clean_save_packaging(packaging)
    # Load parts else they will be considered deleted
    for path in self.parts:
        if path not in parts:
            self.get_part(path)
    target = self._clean_save_target(target)
    if packaging == FOLDER:
        if isinstance(target, io.BytesIO):
            msg = "Impossible to save on io.BytesIO with 'folder' packaging"
            raise TypeError(msg)
        self._save_as_folder(target, backup)
    elif packaging == XML:
        self._save_as_xml(target, backup, pretty)
    else:
        # default:
        self._save_as_zip(target, backup)

set_part

set_part(path: str, data: bytes) -> None

Replace or add a new part.

Source code in odfdo/container.py

def set_part(self, path: str, data: bytes) -> None:
    """Replace or add a new part."""
    self.__parts[path] = data

Content

Bases: XmlPart

Representation of the “content.xml” part.

Methods:

Name	Description
get_style	Return the style uniquely identified by the name/family pair. If the
get_styles	Return the list of styles in the Content part, optionally limited to

Source code in odfdo/content.py

class Content(XmlPart):
    """Representation of the "content.xml" part."""

    def _get_style_contexts(self, family: str | None) -> tuple:
        if family == "font-face":
            return (self.get_element("//office:font-face-decls"),)
        return (
            self.get_element("//office:font-face-decls"),
            self.get_element("//office:automatic-styles"),
        )

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

    # Public API

    def get_styles(self, family: str | None = None) -> list[StyleBase]:
        """Return the list of styles in the Content part, optionally limited to
        the given family.

        Args:

            family -- str or None

        Returns: list of Style
        """
        result: list[StyleBase] = []
        for context in self._get_style_contexts(family):
            if context is None:
                continue
            result.extend(context.get_styles(family=family))
        return result

    def get_style(
        self,
        family: str,
        name_or_element: str | Element | None = None,
        display_name: str | None = None,
    ) -> StyleBase | None:
        """Return the style uniquely identified by the name/family pair. If the
        argument is already a style object, it will return it.

        If the name is None, the default style is fetched.

        If the name is not the internal name but the name you gave in the
        desktop application, use display_name instead.

        Args:

            family -- 'paragraph', 'text', 'graphic', 'table', 'list',
                      'number', ...
            name_or_element -- str or Style

            display_name -- str

        Returns: Style or None if not found
        """
        for context in self._get_style_contexts(family):
            if context is None:
                continue
            style: StyleBase | None = context.get_style(
                family,
                name_or_element=name_or_element,
                display_name=display_name,
            )
            if style is not None:
                return style
        return None

get_style

get_style(
    family: str,
    name_or_element: str | Element | None = None,
    display_name: str | None = None,
) -> StyleBase | None

Return the style uniquely identified by the name/family pair. If the argument is already a style object, it will return it.

If the name is None, the default style is fetched.

If the name is not the internal name but the name you gave in the desktop application, use display_name instead.

Args:

family -- 'paragraph', 'text', 'graphic', 'table', 'list',
          'number', ...
name_or_element -- str or Style

display_name -- str

Returns: Style or None if not found

Source code in odfdo/content.py

def get_style(
    self,
    family: str,
    name_or_element: str | Element | None = None,
    display_name: str | None = None,
) -> StyleBase | None:
    """Return the style uniquely identified by the name/family pair. If the
    argument is already a style object, it will return it.

    If the name is None, the default style is fetched.

    If the name is not the internal name but the name you gave in the
    desktop application, use display_name instead.

    Args:

        family -- 'paragraph', 'text', 'graphic', 'table', 'list',
                  'number', ...
        name_or_element -- str or Style

        display_name -- str

    Returns: Style or None if not found
    """
    for context in self._get_style_contexts(family):
        if context is None:
            continue
        style: StyleBase | None = context.get_style(
            family,
            name_or_element=name_or_element,
            display_name=display_name,
        )
        if style is not None:
            return style
    return None

get_styles

get_styles(family: str | None = None) -> list[StyleBase]

Return the list of styles in the Content part, optionally limited to the given family.

Args:

family -- str or None

Returns: list of Style

Source code in odfdo/content.py

def get_styles(self, family: str | None = None) -> list[StyleBase]:
    """Return the list of styles in the Content part, optionally limited to
    the given family.

    Args:

        family -- str or None

    Returns: list of Style
    """
    result: list[StyleBase] = []
    for context in self._get_style_contexts(family):
        if context is None:
            continue
        result.extend(context.get_styles(family=family))
    return result

Database

Bases: Body

Root of the Database document content, “office:database”.

Source code in odfdo/body.py

class Database(Body):
    """Root of the Database document content, "office:database"."""

    _tag: str = "office:database"
    _properties: tuple[PropDef, ...] = ()

DcCreatorMixin

Creator of the document, “dc:creator”.

Methods:

Name	Description
get_creator	Get the creator of the document.
set_creator	Set the creator of the document.

Attributes:

Name	Type	Description
creator	str | None	Get or set the element.

Source code in odfdo/mixin_dc_creator.py

class DcCreatorMixin:
    """Creator of the document, "dc:creator"."""

    def get_creator(self) -> str | None:
        """Get the creator of the document.

        (Also available as "self.creator" property.)

        Returns: str (or None if inexistent)

        Example::

            >>> document.meta.get_creator()
            Unknown
        """
        element = self.clone.get_element("//dc:creator")
        if element is None:
            return None
        return element.text  # type: ignore[no-any-return]

    def set_creator(self, creator: str) -> None:
        """Set the creator of the document.

        (Also available as "self.creator" property.)

        Args:

            creator -- str

        Example::

            >>> document.meta.set_creator("Plato")
        """
        element = self.get_element("//dc:creator")
        if element is None:
            element = Element.from_tag("dc:creator")
            if hasattr(self, "get_meta_body"):
                self.get_meta_body().append(element)
            else:
                self.append(element)
        element.text = creator

    @property
    def creator(self) -> str | None:
        """Get or set the <dc:creator> element.

        The <dc:creator> element specifies the name of the person who last
        modified a document (<office:meta>), who created an annotation
        (<office:annotation>), who authored a change (<office:change-info>).

        The <dc:creator> element is usable within the following elements:
        <office:annotation>, <office:change-info> and <office:meta>.
        """
        return self.get_creator()

    @creator.setter
    def creator(self, creator: str) -> None:
        self.set_creator(creator)

creator property writable

creator: str | None

Get or set the element.

The element specifies the name of the person who last modified a document (), who created an annotation (), who authored a change ().

The element is usable within the following elements: , and .

get_creator

get_creator() -> str | None

Get the creator of the document.

(Also available as “self.creator” property.)

Returns: str (or None if inexistent)

Example::

>>> document.meta.get_creator()
Unknown

Source code in odfdo/mixin_dc_creator.py

def get_creator(self) -> str | None:
    """Get the creator of the document.

    (Also available as "self.creator" property.)

    Returns: str (or None if inexistent)

    Example::

        >>> document.meta.get_creator()
        Unknown
    """
    element = self.clone.get_element("//dc:creator")
    if element is None:
        return None
    return element.text  # type: ignore[no-any-return]

set_creator

set_creator(creator: str) -> None

Set the creator of the document.

(Also available as “self.creator” property.)

Args:

creator -- str

Example::

>>> document.meta.set_creator("Plato")

Source code in odfdo/mixin_dc_creator.py

def set_creator(self, creator: str) -> None:
    """Set the creator of the document.

    (Also available as "self.creator" property.)

    Args:

        creator -- str

    Example::

        >>> document.meta.set_creator("Plato")
    """
    element = self.get_element("//dc:creator")
    if element is None:
        element = Element.from_tag("dc:creator")
        if hasattr(self, "get_meta_body"):
            self.get_meta_body().append(element)
        else:
            self.append(element)
    element.text = creator

DcDateMixin

Date of the document, “dc:date”.

Methods:

Name	Description
get_modification_date	Get the last modified date of the document.
set_modification_date	Set the last modified date of the document.

Attributes:

Name	Type	Description
date	datetime | None	Get or set the element.
set_dc_date

Source code in odfdo/mixin_dc_date.py

class DcDateMixin:
    """Date of the document, "dc:date"."""

    def get_modification_date(self) -> datetime | None:
        """Get the last modified date of the document.

        (Also available as "self.date" property.)

        Returns: datetime (or None if inexistent)
        """
        element = self.clone.get_element("//dc:date")
        if element is None:
            return None
        dtdate = element.text
        return DateTime.decode(dtdate)

    def set_modification_date(self, date: datetime | None = None) -> None:
        """Set the last modified date of the document.

        If provided datetime is None, use current time.

        (Also available as "self.date" property.)

        Args:

            dtdate -- datetime
        """
        element = self.get_element("//dc:date")
        if element is None:
            element = Element.from_tag("dc:date")
            if hasattr(self, "get_meta_body"):
                self.get_meta_body().append(element)
            else:
                self.append(element)
        if date is None:
            date = datetime.now()
        element.text = DateTime.encode(date)

    # alias for ChangeInfo class
    set_dc_date = set_modification_date

    @property
    def date(self) -> datetime | None:
        """Get or set the <dc:date> element.

        If provided datetime is None, use current time.

        The <dc:date> element specifies the date and time when the document was
        last modified (<office:meta>), when an annotation was created
        (<office:annotation>), when a change was made (<office:change-info>).
        """
        return self.get_modification_date()

    @date.setter
    def date(self, date: datetime | None = None) -> None:
        self.set_modification_date(date)

date property writable

date: datetime | None

Get or set the element.

If provided datetime is None, use current time.

The element specifies the date and time when the document was last modified (), when an annotation was created (), when a change was made ().

set_dc_date class-attribute instance-attribute

set_dc_date = set_modification_date

get_modification_date

get_modification_date() -> datetime | None

Get the last modified date of the document.

(Also available as “self.date” property.)

Returns: datetime (or None if inexistent)

Source code in odfdo/mixin_dc_date.py

def get_modification_date(self) -> datetime | None:
    """Get the last modified date of the document.

    (Also available as "self.date" property.)

    Returns: datetime (or None if inexistent)
    """
    element = self.clone.get_element("//dc:date")
    if element is None:
        return None
    dtdate = element.text
    return DateTime.decode(dtdate)

set_modification_date

set_modification_date(date: datetime | None = None) -> None

Set the last modified date of the document.

If provided datetime is None, use current time.

(Also available as “self.date” property.)

Args:

dtdate -- datetime

Source code in odfdo/mixin_dc_date.py

def set_modification_date(self, date: datetime | None = None) -> None:
    """Set the last modified date of the document.

    If provided datetime is None, use current time.

    (Also available as "self.date" property.)

    Args:

        dtdate -- datetime
    """
    element = self.get_element("//dc:date")
    if element is None:
        element = Element.from_tag("dc:date")
        if hasattr(self, "get_meta_body"):
            self.get_meta_body().append(element)
        else:
            self.append(element)
    if date is None:
        date = datetime.now()
    element.text = DateTime.encode(date)

Document

Bases: MDDocument

Abstraction of the ODF document.

Methods:

Name	Description
__init__	Abstraction of the ODF document.
add_file	Insert a file from a path or a file-like object in the container.
add_page_break_style	Ensure that the document contains the style required for a manual
del_part	Mark a part for deletion.
delete_styles	Remove all style information from content and all styles.
get_cell_background_color	Return the background color of a table cell of a .ods document, from
get_cell_style_properties	Return the style properties of a table cell of a .ods document, from
get_formated_meta	Return meta information as text, with some formatting.
get_formatted_text	Return content as text, with some formatting.
get_language	Get the default language of the document from default styles.
get_list_style
get_parent_style
get_part	Return the bytes of the given part. The path is relative to the
get_parts	Return available part names with path inside the archive, e.g.
get_style	Return the style uniquely identified by the name/family pair. If the
get_style_properties	Return the properties of the required style as a dict.
get_styled_elements	Brute-force to find paragraphs, tables, etc. using the given style
get_styles
get_table_displayed	Return the table:display property of the style of the table, ie if
get_table_style	Return the Style instance the table.
get_type	Get the ODF type (also called class) of this document.
insert_style	Insert the given style object in the document, as required by the
merge_styles_from	Copy all the styles of a document into ourself.
new	Create a Document from a template.
save	Save the document, at the same place it was opened or at the given
set_language	Set the default language of the document, both in styles and
set_part	Set the bytes of the given part. The path is relative to the
set_table_displayed	Set the table:display property of the style of the table, ie if the
show_styles
to_markdown

Attributes:

Name	Type	Description
body	Body	Return the body element of the content part, where actual content is
clone	Document	Return an exact copy of the document.
container	Container | None
content	Content
language	str | None	Get or set the default language of the document, both in styles and
manifest	Manifest	Return the manifest part (manifest.xml) of the document.
meta	Meta	Return the meta part (meta.xml) of the document, where meta data are
mimetype	str
parts	list[str]	Return available part names with path inside the archive, e.g.
path	Path | None	Shortcut to Document.Container.path.
styles	Styles

Source code in odfdo/document.py

class Document(MDDocument):
    """Abstraction of the ODF document."""

    def __init__(
        self,
        target: str | bytes | Path | Container | io.BytesIO | None = "text",
    ) -> None:
        """Abstraction of the ODF document.

        To create a new Document, several possibilities:

            - Document() or Document("text") or Document("odt")
                -> an "empty" document of type text

            - Document("spreadsheet") or Document("ods")
                -> an "empty" document of type spreadsheet

            - Document("presentation") or Document("odp")
                -> an "empty" document of type presentation

            - Document("drawing") or Document("odg")
                -> an "empty" document of type drawing

            Meaning of “empty”: these documents are copies of the default
            templates documents provided with this library, which, as templates,
            are not really empty. It may be useful to clear the newly created
            document: document.body.clear(), or adjust meta information like
            description or default language: document.meta.language = 'fr-FR'

        If the argument is not a known template type, or is a Path,
        Document(file) will load the content of the ODF file.

        To explicitly create a document from a custom template, use the
        Document.new(path) method whose argument is the path to the template file.
        """
        # Cache of XML parts
        self.__xmlparts: dict[str, XmlPart] = {}
        # Cache of the body
        self.__body: Element | None = None
        self.container: Container | None = None
        if isinstance(target, bytes):
            # eager conversion
            target = bytes_to_str(target)
        if target is None:
            # empty document, you probably don't want this.
            self.container = Container()
            return
        if isinstance(target, Path):
            # let's assume we open a container on existing file
            self.container = Container(target)
            return
        if isinstance(target, Container):
            # special internal case, use an existing container
            self.container = target
            return
        if isinstance(target, str):
            if target in ODF_TEMPLATES:
                # assuming a new document from templates
                self.container = container_from_template(target)
                return
            # let's assume we open a container on existing file
            self.container = Container(target)
            return
        if isinstance(target, io.BytesIO):
            self.container = Container(target)
            return
        raise TypeError(f"Unknown Document source type: '{target!r}'")

    def __repr__(self) -> str:
        return f"<{self.__class__.__name__} type={self.get_type()} path={self.path}>"

    def __str__(self) -> str:
        try:
            return str(self.get_formatted_text())
        except NotImplementedError:
            return str(self.body)

    @classmethod
    def new(cls, template: str | Path | io.BytesIO = "text") -> Document:
        """Create a Document from a template.

        The template argument is expected to be the path to a ODF template.

        Args:

            template -- str or Path or file-like (io.BytesIO)

        Return : ODF document -- Document
        """
        container = container_from_template(template)
        return cls(container)

    # Public API

    @property
    def path(self) -> Path | None:
        """Shortcut to Document.Container.path."""
        if not self.container:
            return None
        return self.container.path

    @path.setter
    def path(self, path_or_str: str | Path) -> None:
        """Shortcut to Document.Container.path.

        Only accepting str or Path.
        """
        if not self.container:
            return
        self.container.path = Path(path_or_str)

    def get_parts(self) -> list[str]:
        """Return available part names with path inside the archive, e.g.
        ['content.xml', ...,
        'Pictures/100000000000032000000258912EB1C3.jpg']
        """
        if not self.container:
            raise ValueError("Empty Container")
        return self.container.parts

    @property
    def parts(self) -> list[str]:
        """Return available part names with path inside the archive, e.g.
        ['content.xml', ...,
        'Pictures/100000000000032000000258912EB1C3.jpg']
        """
        return self.get_parts()

    def get_part(self, path: str) -> XmlPart | str | bytes | None:
        """Return the bytes of the given part. The path is relative to the
        archive, e.g. "Pictures/1003200258912EB1C3.jpg".

        'content', 'meta', 'settings', 'styles' and 'manifest' are shortcuts to
        the real path, e.g. content.xml, and return a dedicated object with its
        own API.

        path formatted as URI, so always use '/' separator
        """
        if not self.container:
            raise ValueError("Empty Container")
        # "./ObjectReplacements/Object 1"
        path = path.lstrip("./")
        path = _get_part_path(path)
        cls = _get_part_class(path)
        # Raw bytes
        if cls is None:
            return self.container.get_part(path)
        # XML part
        part = self.__xmlparts.get(path)
        if part is None:
            self.__xmlparts[path] = part = cls(path, self.container)
        return part

    def set_part(self, path: str, data: bytes) -> None:
        """Set the bytes of the given part. The path is relative to the
        archive, e.g. "Pictures/1003200258912EB1C3.jpg".

        path formatted as URI, so always use '/' separator
        """
        if not self.container:
            raise ValueError("Empty Container")
        # "./ObjectReplacements/Object 1"
        path = path.lstrip("./")
        path = _get_part_path(path)
        cls = _get_part_class(path)
        # XML part overwritten
        if cls is not None:
            with suppress(KeyError):
                self.__xmlparts[path]
        self.container.set_part(path, data)

    def del_part(self, path: str) -> None:
        """Mark a part for deletion.

        The path is relative to the archive, e.g.
        "Pictures/1003200258912EB1C3.jpg"
        """
        if not self.container:
            raise ValueError("Empty Container")
        path = _get_part_path(path)
        cls = _get_part_class(path)
        if path == ODF_MANIFEST or cls is not None:
            raise ValueError(f"part '{path}' is mandatory")
        self.container.del_part(path)

    @property
    def mimetype(self) -> str:
        if not self.container:
            raise ValueError("Empty Container")
        return self.container.mimetype

    @mimetype.setter
    def mimetype(self, mimetype: str) -> None:
        if not self.container:
            raise ValueError("Empty Container")
        self.container.mimetype = mimetype

    def get_type(self) -> str:
        """Get the ODF type (also called class) of this document.

        Returns: 'chart', 'database', 'formula', 'graphics',
            'graphics-template', 'image', 'presentation',
            'presentation-template', 'spreadsheet', 'spreadsheet-template',
            'text', 'text-master', 'text-template' or 'text-web'
        """
        # The mimetype must be with the form:
        # application/vnd.oasis.opendocument.text

        # Isolate and return the last part
        return self.mimetype.rsplit(".", 1)[-1]

    @property
    def body(self) -> Body:
        """Return the body element of the content part, where actual content is
        stored.
        """
        if self.__body is None:
            self.__body = self.content.body
        return self.__body  # type: ignore[return-value]

    @property
    def meta(self) -> Meta:
        """Return the meta part (meta.xml) of the document, where meta data are
        stored.
        """
        metadata = self.get_part(ODF_META)
        if metadata is None or not isinstance(metadata, Meta):
            raise ValueError("Empty Meta")
        return metadata

    @property
    def manifest(self) -> Manifest:
        """Return the manifest part (manifest.xml) of the document."""
        manifest = self.get_part(ODF_MANIFEST)
        if manifest is None or not isinstance(manifest, Manifest):
            raise ValueError("Empty Manifest")
        return manifest

    def _get_formatted_text_footnotes(
        self,
        result: list[str],
        context: dict,
        rst_mode: bool,
    ) -> None:
        # Separate text from notes
        if rst_mode:
            result.append("\n")
        else:
            result.append("----\n")
        for citation, body in context["footnotes"]:
            if rst_mode:
                result.append(f".. [#] {body}\n")
            else:
                result.append(f"[{citation}] {body}\n")
        # Append a \n after the notes
        result.append("\n")
        # Reset for the next paragraph
        context["footnotes"] = []

    def _get_formatted_text_annotations(
        self,
        result: list[str],
        context: dict,
        rst_mode: bool,
    ) -> None:
        # Insert the annotations
        # With a separation
        if rst_mode:
            result.append("\n")
        else:
            result.append("----\n")
        for annotation in context["annotations"]:
            if rst_mode:
                result.append(f".. [#] {annotation}\n")
            else:
                result.append(f"[*] {annotation}\n")
        context["annotations"] = []

    def _get_formatted_text_images(
        self,
        result: list[str],
        context: dict,
        rst_mode: bool,
    ) -> None:
        # Insert the images ref, only in rst mode
        result.append("\n")
        for ref, filename, (width, height) in context["images"]:
            result.append(f".. {ref} image:: {filename}\n")
            if width is not None:
                result.append(f"   :width: {width}\n")
            if height is not None:
                result.append(f"   :height: {height}\n")
        context["images"] = []

    def _get_formatted_text_endnotes(
        self,
        result: list[str],
        context: dict,
        rst_mode: bool,
    ) -> None:
        # Append the end notes
        if rst_mode:
            result.append("\n\n")
        else:
            result.append("\n========\n")
        for citation, body in context["endnotes"]:
            if rst_mode:
                result.append(f".. [*] {body}\n")
            else:
                result.append(f"({citation}) {body}\n")

    def get_formatted_text(self, rst_mode: bool = False) -> str:
        """Return content as text, with some formatting."""
        # For the moment, only "type='text'"
        doc_type = self.get_type()
        if doc_type == "spreadsheet":
            return self._tables_csv()
        if doc_type in {
            "text",
            "text-template",
            "presentation",
            "presentation-template",
        }:
            return self._formatted_text(rst_mode)
        raise NotImplementedError(f"Type of document '{doc_type}' not supported yet")

    def _tables_csv(self) -> str:
        return "\n\n".join(str(table) for table in self.body.tables)

    def _formatted_text(self, rst_mode: bool) -> str:
        # Initialize an empty context
        context = {
            "document": self,
            "footnotes": [],
            "endnotes": [],
            "annotations": [],
            "rst_mode": rst_mode,
            "img_counter": 0,
            "images": [],
            "no_img_level": 0,
        }
        body = self.body
        # Get the text
        result = []
        for child in body.children:
            # self._get_formatted_text_child(result, element, context, rst_mode)
            # if child.tag == "table:table":
            #     result.append(child.get_formatted_text(context))
            #     return
            result.append(child.get_formatted_text(context))
            if context["footnotes"]:
                self._get_formatted_text_footnotes(result, context, rst_mode)
            if context["annotations"]:
                self._get_formatted_text_annotations(result, context, rst_mode)
            # Insert the images ref, only in rst mode
            if context["images"]:
                self._get_formatted_text_images(result, context, rst_mode)
        if context["endnotes"]:
            self._get_formatted_text_endnotes(result, context, rst_mode)
        return "".join(result)

    def get_formated_meta(self) -> str:
        """Return meta information as text, with some formatting.

        (Redirection to new implementation for compatibility.)
        """
        return self.meta.as_text()

    def to_markdown(self) -> str:
        doc_type = self.get_type()
        if doc_type not in {
            "text",
        }:
            raise NotImplementedError(
                f"Type of document '{doc_type}' not supported yet"
            )
        return self._markdown_export()

    def _add_binary_part(self, blob: Blob) -> str:
        if not self.container:
            raise ValueError("Empty Container")
        manifest = self.manifest
        if manifest.get_media_type("Pictures/") is None:
            manifest.add_full_path("Pictures/")
        path = posixpath.join("Pictures", blob.name)
        self.container.set_part(path, blob.content)
        manifest.add_full_path(path, blob.mime_type)
        return path

    def add_file(self, path_or_file: str | Path | BinaryIO) -> str:
        """Insert a file from a path or a file-like object in the container.

        Return the full path to reference in the content. The internal name
        of the file in the Picture/ folder is generated by a hash function.

        Args:

            path_or_file -- str or Path or file-like

        Returns: str (URI)
        """
        if not self.container:
            raise ValueError("Empty Container")
        if isinstance(path_or_file, (str, Path)):
            blob = Blob.from_path(path_or_file)
        else:
            blob = Blob.from_io(path_or_file)
        return self._add_binary_part(blob)

    @property
    def clone(self) -> Document:
        """Return an exact copy of the document.

        Returns: Document
        """
        clone = object.__new__(self.__class__)
        for name in self.__dict__:
            if name == "_Document__body":
                setattr(clone, name, None)
            elif name == "_Document__xmlparts":
                setattr(clone, name, {})
            elif name == "container":
                if not self.container:
                    raise ValueError("Empty Container")
                setattr(clone, name, self.container.clone)
            else:
                value = deepcopy(getattr(self, name))
                setattr(clone, name, value)
        return clone

    def _check_manifest_rdf(self) -> None:
        manifest = self.manifest
        if not self.container:
            return
        parts = self.container.parts
        if manifest.get_media_type(ODF_MANIFEST_RDF):
            if ODF_MANIFEST_RDF not in parts:
                self.container.set_part(
                    ODF_MANIFEST_RDF, self.container.default_manifest_rdf.encode("utf8")
                )
        else:
            if ODF_MANIFEST_RDF in parts:
                self.container.del_part(ODF_MANIFEST_RDF)

    def save(
        self,
        target: str | Path | io.BytesIO | None = None,
        packaging: str = ZIP,
        pretty: bool | None = None,
        backup: bool = False,
    ) -> None:
        """Save the document, at the same place it was opened or at the given
        target path. Target can also be a file-like object. It can be saved as
        a Zip file (default), flat XML format or as files in a folder (for
        debugging purpose). XML parts can be pretty printed (the default for
        'folder' and 'xml' packaging).

        Note: 'xml' packaging is an experimental work in progress.

        Args:

            target -- str or file-like object

            packaging -- 'zip', 'folder', 'xml'

            pretty -- bool | None

            backup -- bool
        """
        if not self.container:
            raise ValueError("Empty Container")
        if packaging not in PACKAGING:
            raise ValueError(f'Packaging of type "{packaging}" is not supported')
        # Some advertising
        self.meta.set_generator_default()
        # Synchronize data with container
        container = self.container
        if pretty is None:
            pretty = packaging in {"folder", "xml"}
        pretty = bool(pretty)
        backup = bool(backup)
        self._check_manifest_rdf()
        if pretty and packaging != XML:
            for path, part in self.__xmlparts.items():
                if part is not None:
                    container.set_part(path, part.pretty_serialize())
            for path in (ODF_CONTENT, ODF_META, ODF_SETTINGS, ODF_STYLES):
                if path in self.__xmlparts:
                    continue
                cls = _get_part_class(path)
                if cls is None:
                    raise RuntimeError("Should never happen")
                # XML part
                self.__xmlparts[path] = part = cls(path, container)
                container.set_part(path, part.pretty_serialize())
        else:
            for path, part in self.__xmlparts.items():
                if part is not None:
                    container.set_part(path, part.serialize())
        container.save(target, packaging=packaging, backup=backup, pretty=pretty)

    @property
    def content(self) -> Content:
        content: Content | None = self.get_part(ODF_CONTENT)  # type:ignore
        if content is None:
            raise ValueError("Empty Content")
        return content

    @property
    def styles(self) -> Styles:
        styles: Styles | None = self.get_part(ODF_STYLES)  # type:ignore
        if styles is None:
            raise ValueError("Empty Styles")
        return styles

    # Styles over several parts

    def get_styles(
        self,
        family: str | bytes = "",
        automatic: bool = False,
    ) -> list[StyleBase]:
        # compatibility with old versions:
        if isinstance(family, bytes):
            family = bytes_to_str(family)
        return self.content.get_styles(family=family) + self.styles.get_styles(
            family=family, automatic=automatic
        )

    def get_style(
        self,
        family: str,
        name_or_element: str | StyleBase | None = None,
        display_name: str | None = None,
    ) -> StyleBase | None:
        """Return the style uniquely identified by the name/family pair. If the
        argument is already a style object, it will return it.

        If the name is None, the default style is fetched.

        If the name is not the internal name but the name you gave in a
        desktop application, use display_name instead.

        Args:

            family -- 'paragraph', 'text',  'graphic', 'table', 'list',
                      'number', 'page-layout', 'master-page', ...

            name -- str or Element or None

            display_name -- str

        Returns: Style or None if not found.
        """
        # 1. content.xml
        element = self.content.get_style(
            family, name_or_element=name_or_element, display_name=display_name
        )
        if element is not None:
            return element
        # 2. styles.xml
        return self.styles.get_style(
            family,
            name_or_element=name_or_element,
            display_name=display_name,
        )

    def get_parent_style(self, style: StyleBase) -> StyleBase | None:
        family = style.family
        if family is None:
            return None
        parent_style_name = style.parent_style  # type: ignore [attr-defined]
        if not parent_style_name:
            return None
        return self.get_style(family, parent_style_name)

    def get_list_style(self, style: StyleBase) -> StyleBase | None:
        list_style_name = style.list_style_name  # type: ignore[attr-defined]
        if not list_style_name:
            return None
        return self.get_style("list", list_style_name)

    @staticmethod
    def _pseudo_style_attribute(
        style_element: StyleBase | Element, attribute: str
    ) -> Any:
        if hasattr(style_element, attribute):
            return getattr(style_element, attribute)
        return ""

    def _set_automatic_name(self, style: StyleBase, family: str) -> None:
        """Generate a name for the new automatic style."""
        if not hasattr(style, "name"):
            # do nothing
            return
        styles = self.get_styles(family=family, automatic=True)
        max_index = 0
        for existing_style in styles:
            if not hasattr(existing_style, "name"):
                continue
            if not existing_style.name.startswith(AUTOMATIC_PREFIX):
                continue
            try:
                index = int(existing_style.name[len(AUTOMATIC_PREFIX) :])
            except ValueError:
                continue
            max_index = max(max_index, index)

        style.name = f"{AUTOMATIC_PREFIX}{max_index + 1}"

    def _insert_style_get_common_styles(
        self,
        family: str,
        name: str,
    ) -> tuple[Any, Any]:
        style_container = self.styles.get_element("office:styles")
        existing = self.styles.get_style(family, name)
        return existing, style_container

    def _insert_style_get_automatic_styles(
        self,
        style: StyleBase,
        family: str,
        name: str,
    ) -> tuple[Any, Any]:
        style_container = self.content.get_element("office:automatic-styles")
        # A name ?
        if name:
            if hasattr(style, "name"):
                style.name = name
            existing = self.content.get_style(family, name)
        else:
            self._set_automatic_name(style, family)
            existing = None
        return existing, style_container

    def _insert_style_get_default_styles(
        self,
        style: StyleBase,
        family: str,
        name: str,
    ) -> tuple[Any, Any]:
        style_container = self.styles.get_element("office:styles")
        style.tag = "style:default-style"
        if name:
            with contextlib.suppress(KeyError):
                style.del_attribute("style:name")
        existing = self.styles.get_style(family)
        return existing, style_container

    def _insert_style_get_master_page(
        self,
        family: str,
        name: str,
    ) -> tuple[Any, Any]:
        style_container = self.styles.get_element("office:master-styles")
        existing = self.styles.get_style(family, name)
        return existing, style_container

    def _insert_style_get_font_face_default(
        self,
        family: str,
        name: str,
    ) -> tuple[Any, Any]:
        style_container = self.styles.get_element("office:font-face-decls")
        existing = self.styles.get_style(family, name)
        return existing, style_container

    def _insert_style_get_font_face(
        self,
        family: str,
        name: str,
    ) -> tuple[Any, Any]:
        style_container = self.content.get_element("office:font-face-decls")
        existing = self.content.get_style(family, name)
        return existing, style_container

    def _insert_style_get_page_layout(
        self,
        family: str,
        name: str,
    ) -> tuple[Any, Any]:
        # force to automatic
        style_container = self.styles.get_element("office:automatic-styles")
        existing = self.styles.get_style(family, name)
        return existing, style_container

    def _insert_style_get_draw_fill_image(
        self,
        name: str,
    ) -> tuple[Any, Any]:
        # special case for 'draw:fill-image' pseudo style
        # not family and style_element.__class__.__name__ == "DrawFillImage"
        style_container = self.styles.get_element("office:styles")
        existing = self.styles.get_style("", name)
        return existing, style_container

    def _insert_style_standard(
        self,
        style: StyleBase,
        name: str,
        family: str,
        automatic: bool,
        default: bool,
    ) -> tuple[Any, Any]:
        # Common style
        if name and automatic is False and default is False:
            return self._insert_style_get_common_styles(family, name)
        # Automatic style
        elif automatic is True and default is False:
            return self._insert_style_get_automatic_styles(style, family, name)
        # Default style
        elif automatic is False and default is True:
            return self._insert_style_get_default_styles(style, family, name)
        else:
            raise AttributeError("Invalid combination of arguments")

    def insert_style(
        self,
        style: StyleBase | str,
        name: str = "",
        automatic: bool = False,
        default: bool = False,
    ) -> Any:
        """Insert the given style object in the document, as required by the
        style family and type.

        The style is expected to be a common style with a name. In case it
        was created with no name, the given can be set on the fly.

        If automatic is True, the style will be inserted as an automatic
        style.

        If default is True, the style will be inserted as a default style and
        would replace any existing default style of the same family. Any name
        or display name would be ignored.

        Automatic and default arguments are mutually exclusive.

        All styles can't be used as default styles. Default styles are
        allowed for the following families: paragraph, text, section, table,
        table-column, table-row, table-cell, table-page, chart, drawing-page,
        graphic, presentation, control and ruby.

        Args:

            style -- Style or str

            name -- str

            automatic -- bool

            default -- bool

        Return : style name -- str
        """

        # if style is a str, assume it is the Style definition
        if isinstance(style, str):
            style_element: StyleBase = Element.from_tag(style)  # type: ignore
        else:
            style_element = style
        if not isinstance(style_element, Element):
            raise TypeError(f"Unknown Style type: '{style!r}'")

        # Get family and name
        family = style_element.family
        if not name:
            name = self._pseudo_style_attribute(style_element, "name")

        # Master page style
        if family == "master-page":
            existing, style_container = self._insert_style_get_master_page(family, name)
        # Font face declarations
        elif family == "font-face":
            if default:
                existing, style_container = self._insert_style_get_font_face_default(
                    family, name
                )
            else:
                existing, style_container = self._insert_style_get_font_face(
                    family, name
                )
        # page layout style
        elif family == "page-layout":
            existing, style_container = self._insert_style_get_page_layout(family, name)
        # Common style
        elif family in FAMILY_MAPPING:
            existing, style_container = self._insert_style_standard(
                style_element, name, family, automatic, default
            )
        elif not family and style_element.__class__.__name__ == "DrawFillImage":
            # special case for 'draw:fill-image' pseudo style
            existing, style_container = self._insert_style_get_draw_fill_image(name)
        # Invalid style
        else:
            raise ValueError(
                "Invalid style: "
                f"{style_element}, tag:{style_element.tag}, family:{family}"
            )

        # Insert it!
        if existing is not None:
            style_container.delete(existing)
        style_container.append(style_element)
        return self._pseudo_style_attribute(style_element, "name")

    def get_styled_elements(self, name: str = "") -> list[Element]:
        """Brute-force to find paragraphs, tables, etc. using the given style
        name (or all by default).

        Args:

            name -- str

        Returns: list
        """
        # Header, footer, etc. have styles too
        return self.content.root.get_styled_elements(
            name
        ) + self.styles.root.get_styled_elements(name)

    def show_styles(
        self,
        automatic: bool = True,
        common: bool = True,
        properties: bool = False,
    ) -> str:
        infos = []
        for style in self.get_styles():
            try:
                name = style.name  # type: ignore[attr-defined]
            except AttributeError:
                print("Style error:")
                print(style.__class__)
                print(style.serialize())
                raise
            if style.__class__.__name__ == "DrawFillImage":
                family = ""
            else:
                family = str(style.family)
            parent = style.parent
            is_auto = parent and parent.tag == "office:automatic-styles"
            if (is_auto and automatic is False) or (not is_auto and common is False):
                continue
            is_used = bool(self.get_styled_elements(name))
            infos.append(
                {
                    "type": "auto  " if is_auto else "common",
                    "used": "y" if is_used else "n",
                    "family": family,
                    "parent": self._pseudo_style_attribute(style, "parent_style") or "",
                    "name": name or "",
                    "display_name": self._pseudo_style_attribute(style, "display_name")
                    or "",
                    "properties": style.get_properties() if properties else None,
                }
            )
        if not infos:
            return ""
        # Sort by family and name
        infos.sort(key=itemgetter("family", "name"))
        # Show common and used first
        infos.sort(key=itemgetter("type", "used"), reverse=True)
        max_family = str(max(len(x["family"]) for x in infos))  # type: ignore
        max_parent = str(max(len(x["parent"]) for x in infos))  # type: ignore
        formater = (
            "%(type)s used:%(used)s family:%(family)-0"
            + max_family
            + "s parent:%(parent)-0"
            + max_parent
            + "s name:%(name)s"
        )
        output = []
        for info in infos:
            line = formater % info
            if info["display_name"]:
                line += " display_name:" + info["display_name"]  # type: ignore
            output.append(line)
            if info["properties"]:
                for name, value in info["properties"].items():  # type: ignore
                    output.append(f"   - {name}: {value}")
        output.append("")
        return "\n".join(output)

    def delete_styles(self) -> int:
        """Remove all style information from content and all styles.

        Returns: number of deleted styles
        """
        # First remove references to styles
        for element in self.get_styled_elements():
            for attribute in (
                "text:style-name",
                "draw:style-name",
                "draw:text-style-name",
                "table:style-name",
                "style:page-layout-name",
            ):
                with contextlib.suppress(KeyError):
                    element.del_attribute(attribute)
        # Then remove supposedly orphaned styles
        deleted = 0
        for style in self.get_styles():
            try:
                name = style.name  # type: ignore[attr-defined]
            except AttributeError:
                continue
                # Don't delete default styles
            if name is None:
                continue
            # elif type(style) is odf_master_page:
            #    # Don't suppress header and footer, just styling was removed
            #    continue
            style.delete()
            deleted += 1
        return deleted

    def merge_styles_from(self, document: Document) -> None:
        """Copy all the styles of a document into ourself.

        Styles with the same type and name will be replaced, so only unique
        styles will be preserved.
        """
        manifest = self.manifest
        document_manifest = document.manifest
        for style in document.get_styles():
            tagname = style.tag
            family = style.family
            try:
                stylename = style.name  # type: ignore[attr-defined]
            except AttributeError:
                stylename = None
            container = style.parent
            container_name = container.tag  # type: ignore
            partname = container.parent.tag  # type: ignore
            # The destination part
            if partname == "office:document-styles":
                part: Content | Styles = self.styles
            elif partname == "office:document-content":
                part = self.content
            else:
                raise NotImplementedError(partname)
            # Implemented containers
            if container_name not in {
                "office:styles",
                "office:automatic-styles",
                "office:master-styles",
                "office:font-face-decls",
            }:
                raise NotImplementedError(container_name)
            dest = part.get_element(f"//{container_name}")
            if not dest:
                continue
            # Implemented style types
            # if tagname not in registered_styles:
            #    raise NotImplementedError(tagname)
            duplicate = part.get_style(family, stylename)  # type: ignore[arg-type]
            if duplicate is not None:
                duplicate.delete()
            dest.append(style)
            # Copy images from the header/footer
            if tagname == "style:master-page":
                query = "descendant::draw:image"
                for image in style.get_elements(query):
                    url = image.url  # type: ignore
                    part_url = document.get_part(url)
                    # Manually add the part to keep the name
                    self.set_part(url, part_url)  # type: ignore
                    media_type = document_manifest.get_media_type(url)
                    manifest.add_full_path(url, media_type)  # type: ignore
            # Copy images from the fill-image
            elif tagname == "draw:fill-image":
                url = style.url  # type: ignore
                part_url = document.get_part(url)
                self.set_part(url, part_url)  # type: ignore
                media_type = document_manifest.get_media_type(url)
                manifest.add_full_path(url, media_type)  # type: ignore

    def add_page_break_style(self) -> None:
        """Ensure that the document contains the style required for a manual
        page break.

        Then a manual page break can be added to the document with:
            from paragraph import PageBreak
            ...
            document.body.append(PageBreak())

        Note: this style uses the property 'fo:break-after', another
        possibility could be the property 'fo:break-before'
        """
        if existing := self.get_style(  # noqa: SIM102
            family="paragraph",
            name_or_element="odfdopagebreak",
        ):
            if properties := existing.get_properties():  # noqa: SIM102
                if properties["fo:break-after"] == "page":
                    return
        style = (
            '<style:style style:family="paragraph" style:parent-style-name="Standard" '
            'style:name="odfdopagebreak">'
            '<style:paragraph-properties fo:break-after="page"/></style:style>'
        )
        self.insert_style(style, automatic=False)

    def get_style_properties(
        self, family: str, name: str, area: str | None = None
    ) -> dict[str, str] | None:
        """Return the properties of the required style as a dict."""
        style = self.get_style(family, name)
        if style is None:
            return None
        return style.get_properties(area=area)  # type: ignore

    def _get_table(self, table: int | str) -> Table | None:
        if not isinstance(table, (int, str)):
            raise TypeError(f"Table parameter must be int or str: {table!r}")
        if isinstance(table, int):
            return self.body.get_table(position=table)
        return self.body.get_table(name=table)

    def get_cell_style_properties(
        self, table: str | int, coord: tuple | list | str
    ) -> dict[str, str]:
        """Return the style properties of a table cell of a .ods document, from
        the cell style or from the row style.
        """

        if not (sheet := self._get_table(table)):
            return {}
        cell = sheet.get_cell(coord, clone=False)
        if cell.style:
            return (
                self.get_style_properties("table-cell", cell.style, "table-cell") or {}
            )
        try:
            row = sheet.get_row(cell.y, clone=False, create=False)  # type: ignore
            if row.style:  # noqa: SIM102
                if props := self.get_style_properties(
                    "table-row", row.style, "table-cell"
                ):
                    return props
            column = sheet.get_column(cell.x)  # type: ignore
            style = column.default_cell_style
            if style:  # noqa: SIM102
                if props := self.get_style_properties(
                    "table-cell", style, "table-cell"
                ):
                    return props
        except ValueError:
            pass
        return {}

    def get_cell_background_color(
        self,
        table: str | int,
        coord: tuple | list | str,
        default: str = "#ffffff",
    ) -> str:
        """Return the background color of a table cell of a .ods document, from
        the cell style, or from the row or column.

        If color is not defined, return default value.
        """
        found = self.get_cell_style_properties(table, coord).get("fo:background-color")
        return found or default

    def get_table_style(
        self,
        table: str | int,
    ) -> StyleBase | None:
        """Return the Style instance the table.

        Args:

            table -- name or index of the table
        """
        if not (sheet := self._get_table(table)):
            return None
        return self.get_style("table", sheet.style)

    def get_table_displayed(self, table: str | int) -> bool:
        """Return the table:display property of the style of the table, ie if
        the table should be displayed in a graphical interface.

        Note: that method replaces the broken Table.displayd() method from previous
        odfdo versions.

        Args:

            table -- name or index of the table
        """
        style = self.get_table_style(table)
        if not style:
            # should not happen, but assume that a table without style is
            # displayed by default
            return True
        properties = style.get_properties() or {}
        property_str = str(properties.get("table:display", "true"))
        return Boolean.decode(property_str)

    def _unique_style_name(self, base: str) -> str:
        current = {style.name for style in self.get_styles() if hasattr(style, "name")}
        idx = 0
        while True:
            name = f"{base}_{idx}"
            if name in current:
                idx += 1
                continue
            return name

    def set_table_displayed(self, table: str | int, displayed: bool) -> None:
        """Set the table:display property of the style of the table, ie if the
        table should be displayed in a graphical interface.

        Note: that method replaces the broken Table.displayd() method from previous
        odfdo versions.

        Args:

            table -- name or index of the table

            displayed -- boolean flag
        """
        orig_style = self.get_table_style(table)
        if not orig_style:
            name = self._unique_style_name("ta")
            orig_style = Element.from_tag(  # type:ignore[assignment]
                f'<style:style style:name="{name}" style:family="table" '
                'style:master-page-name="Default">'
                '<style:table-properties table:display="true" '
                'style:writing-mode="lr-tb"/></style:style>'
            )
            self.insert_style(orig_style, automatic=True)  # type:ignore
        new_style = orig_style.clone  # type: ignore[union-attr]
        new_name = self._unique_style_name("ta")
        new_style.name = new_name  # type:ignore
        self.insert_style(new_style, automatic=True)  # type:ignore
        sheet = self._get_table(table)
        sheet.style = new_name  # type: ignore
        properties = {"table:display": Boolean.encode(displayed)}
        new_style.set_properties(properties)  # type: ignore

    def get_language(self) -> str:
        """Get the default language of the document from default styles.

        (Note: the Metadata value may differ).

        Returns: str
        """
        return self.styles.default_language

    def set_language(self, language: str) -> None:
        """Set the default language of the document, both in styles and
        metadata.

        (Also available as "Document.language" property.)

        Args:

            language -- str

        Example::

            >>> document.set_language('fr-FR')
        """
        language = str(language)
        if not is_RFC3066(language):
            raise TypeError(
                'Language must be "xx" lang or "xx-YY" lang-COUNTRY code (RFC3066)'
            )
        self.styles.default_language = language
        self.meta.language = language

    @property
    def language(self) -> str | None:
        """Get or set the default language of the document, both in styles and
        metadata.

        Returns: str
        """
        return self.get_language()

    @language.setter
    def language(self, language: str) -> None:
        return self.set_language(language)

body property

body: Body

Return the body element of the content part, where actual content is stored.

clone property

clone: Document

Return an exact copy of the document.

Returns: Document

container instance-attribute

container: Container | None = None

content property

content: Content

language property writable

language: str | None

Get or set the default language of the document, both in styles and metadata.

Returns: str

manifest property

manifest: Manifest

Return the manifest part (manifest.xml) of the document.

meta property

meta: Meta

Return the meta part (meta.xml) of the document, where meta data are stored.

mimetype property writable

mimetype: str

parts property

parts: list[str]

Return available part names with path inside the archive, e.g. [‘content.xml’, …, ‘Pictures/100000000000032000000258912EB1C3.jpg’]

path property writable

path: Path | None

Shortcut to Document.Container.path.

styles property

styles: Styles

__init__

__init__(
    target: str
    | bytes
    | Path
    | Container
    | BytesIO
    | None = "text",
) -> None

Abstraction of the ODF document.

To create a new Document, several possibilities:

- Document() or Document("text") or Document("odt")
    -> an "empty" document of type text

- Document("spreadsheet") or Document("ods")
    -> an "empty" document of type spreadsheet

- Document("presentation") or Document("odp")
    -> an "empty" document of type presentation

- Document("drawing") or Document("odg")
    -> an "empty" document of type drawing

Meaning of “empty”: these documents are copies of the default
templates documents provided with this library, which, as templates,
are not really empty. It may be useful to clear the newly created
document: document.body.clear(), or adjust meta information like
description or default language: document.meta.language = 'fr-FR'

If the argument is not a known template type, or is a Path, Document(file) will load the content of the ODF file.

To explicitly create a document from a custom template, use the Document.new(path) method whose argument is the path to the template file.

Source code in odfdo/document.py

def __init__(
    self,
    target: str | bytes | Path | Container | io.BytesIO | None = "text",
) -> None:
    """Abstraction of the ODF document.

    To create a new Document, several possibilities:

        - Document() or Document("text") or Document("odt")
            -> an "empty" document of type text

        - Document("spreadsheet") or Document("ods")
            -> an "empty" document of type spreadsheet

        - Document("presentation") or Document("odp")
            -> an "empty" document of type presentation

        - Document("drawing") or Document("odg")
            -> an "empty" document of type drawing

        Meaning of “empty”: these documents are copies of the default
        templates documents provided with this library, which, as templates,
        are not really empty. It may be useful to clear the newly created
        document: document.body.clear(), or adjust meta information like
        description or default language: document.meta.language = 'fr-FR'

    If the argument is not a known template type, or is a Path,
    Document(file) will load the content of the ODF file.

    To explicitly create a document from a custom template, use the
    Document.new(path) method whose argument is the path to the template file.
    """
    # Cache of XML parts
    self.__xmlparts: dict[str, XmlPart] = {}
    # Cache of the body
    self.__body: Element | None = None
    self.container: Container | None = None
    if isinstance(target, bytes):
        # eager conversion
        target = bytes_to_str(target)
    if target is None:
        # empty document, you probably don't want this.
        self.container = Container()
        return
    if isinstance(target, Path):
        # let's assume we open a container on existing file
        self.container = Container(target)
        return
    if isinstance(target, Container):
        # special internal case, use an existing container
        self.container = target
        return
    if isinstance(target, str):
        if target in ODF_TEMPLATES:
            # assuming a new document from templates
            self.container = container_from_template(target)
            return
        # let's assume we open a container on existing file
        self.container = Container(target)
        return
    if isinstance(target, io.BytesIO):
        self.container = Container(target)
        return
    raise TypeError(f"Unknown Document source type: '{target!r}'")

add_file

add_file(path_or_file: str | Path | BinaryIO) -> str

Insert a file from a path or a file-like object in the container.

Return the full path to reference in the content. The internal name of the file in the Picture/ folder is generated by a hash function.

Args:

path_or_file -- str or Path or file-like

Returns: str (URI)

Source code in odfdo/document.py

def add_file(self, path_or_file: str | Path | BinaryIO) -> str:
    """Insert a file from a path or a file-like object in the container.

    Return the full path to reference in the content. The internal name
    of the file in the Picture/ folder is generated by a hash function.

    Args:

        path_or_file -- str or Path or file-like

    Returns: str (URI)
    """
    if not self.container:
        raise ValueError("Empty Container")
    if isinstance(path_or_file, (str, Path)):
        blob = Blob.from_path(path_or_file)
    else:
        blob = Blob.from_io(path_or_file)
    return self._add_binary_part(blob)

add_page_break_style

add_page_break_style() -> None

Ensure that the document contains the style required for a manual page break.

Then a manual page break can be added to the document with

from paragraph import PageBreak … document.body.append(PageBreak())

Note: this style uses the property ‘fo:break-after’, another possibility could be the property ‘fo:break-before’

Source code in odfdo/document.py

def add_page_break_style(self) -> None:
    """Ensure that the document contains the style required for a manual
    page break.

    Then a manual page break can be added to the document with:
        from paragraph import PageBreak
        ...
        document.body.append(PageBreak())

    Note: this style uses the property 'fo:break-after', another
    possibility could be the property 'fo:break-before'
    """
    if existing := self.get_style(  # noqa: SIM102
        family="paragraph",
        name_or_element="odfdopagebreak",
    ):
        if properties := existing.get_properties():  # noqa: SIM102
            if properties["fo:break-after"] == "page":
                return
    style = (
        '<style:style style:family="paragraph" style:parent-style-name="Standard" '
        'style:name="odfdopagebreak">'
        '<style:paragraph-properties fo:break-after="page"/></style:style>'
    )
    self.insert_style(style, automatic=False)

del_part

del_part(path: str) -> None

Mark a part for deletion.

The path is relative to the archive, e.g. “Pictures/1003200258912EB1C3.jpg”

Source code in odfdo/document.py

def del_part(self, path: str) -> None:
    """Mark a part for deletion.

    The path is relative to the archive, e.g.
    "Pictures/1003200258912EB1C3.jpg"
    """
    if not self.container:
        raise ValueError("Empty Container")
    path = _get_part_path(path)
    cls = _get_part_class(path)
    if path == ODF_MANIFEST or cls is not None:
        raise ValueError(f"part '{path}' is mandatory")
    self.container.del_part(path)

delete_styles

delete_styles() -> int

Remove all style information from content and all styles.

Returns: number of deleted styles

Source code in odfdo/document.py

def delete_styles(self) -> int:
    """Remove all style information from content and all styles.

    Returns: number of deleted styles
    """
    # First remove references to styles
    for element in self.get_styled_elements():
        for attribute in (
            "text:style-name",
            "draw:style-name",
            "draw:text-style-name",
            "table:style-name",
            "style:page-layout-name",
        ):
            with contextlib.suppress(KeyError):
                element.del_attribute(attribute)
    # Then remove supposedly orphaned styles
    deleted = 0
    for style in self.get_styles():
        try:
            name = style.name  # type: ignore[attr-defined]
        except AttributeError:
            continue
            # Don't delete default styles
        if name is None:
            continue
        # elif type(style) is odf_master_page:
        #    # Don't suppress header and footer, just styling was removed
        #    continue
        style.delete()
        deleted += 1
    return deleted

get_cell_background_color

get_cell_background_color(
    table: str | int,
    coord: tuple | list | str,
    default: str = "#ffffff",
) -> str

Return the background color of a table cell of a .ods document, from the cell style, or from the row or column.

If color is not defined, return default value.

Source code in odfdo/document.py

def get_cell_background_color(
    self,
    table: str | int,
    coord: tuple | list | str,
    default: str = "#ffffff",
) -> str:
    """Return the background color of a table cell of a .ods document, from
    the cell style, or from the row or column.

    If color is not defined, return default value.
    """
    found = self.get_cell_style_properties(table, coord).get("fo:background-color")
    return found or default

get_cell_style_properties

get_cell_style_properties(
    table: str | int, coord: tuple | list | str
) -> dict[str, str]

Return the style properties of a table cell of a .ods document, from the cell style or from the row style.

Source code in odfdo/document.py

def get_cell_style_properties(
    self, table: str | int, coord: tuple | list | str
) -> dict[str, str]:
    """Return the style properties of a table cell of a .ods document, from
    the cell style or from the row style.
    """

    if not (sheet := self._get_table(table)):
        return {}
    cell = sheet.get_cell(coord, clone=False)
    if cell.style:
        return (
            self.get_style_properties("table-cell", cell.style, "table-cell") or {}
        )
    try:
        row = sheet.get_row(cell.y, clone=False, create=False)  # type: ignore
        if row.style:  # noqa: SIM102
            if props := self.get_style_properties(
                "table-row", row.style, "table-cell"
            ):
                return props
        column = sheet.get_column(cell.x)  # type: ignore
        style = column.default_cell_style
        if style:  # noqa: SIM102
            if props := self.get_style_properties(
                "table-cell", style, "table-cell"
            ):
                return props
    except ValueError:
        pass
    return {}

get_formated_meta

get_formated_meta() -> str

Return meta information as text, with some formatting.

(Redirection to new implementation for compatibility.)

Source code in odfdo/document.py

def get_formated_meta(self) -> str:
    """Return meta information as text, with some formatting.

    (Redirection to new implementation for compatibility.)
    """
    return self.meta.as_text()

get_formatted_text

get_formatted_text(rst_mode: bool = False) -> str

Return content as text, with some formatting.

Source code in odfdo/document.py

def get_formatted_text(self, rst_mode: bool = False) -> str:
    """Return content as text, with some formatting."""
    # For the moment, only "type='text'"
    doc_type = self.get_type()
    if doc_type == "spreadsheet":
        return self._tables_csv()
    if doc_type in {
        "text",
        "text-template",
        "presentation",
        "presentation-template",
    }:
        return self._formatted_text(rst_mode)
    raise NotImplementedError(f"Type of document '{doc_type}' not supported yet")

get_language

get_language() -> str

Get the default language of the document from default styles.

(Note: the Metadata value may differ).

Returns: str

Source code in odfdo/document.py

def get_language(self) -> str:
    """Get the default language of the document from default styles.

    (Note: the Metadata value may differ).

    Returns: str
    """
    return self.styles.default_language

get_list_style

get_list_style(style: StyleBase) -> StyleBase | None

Source code in odfdo/document.py

def get_list_style(self, style: StyleBase) -> StyleBase | None:
    list_style_name = style.list_style_name  # type: ignore[attr-defined]
    if not list_style_name:
        return None
    return self.get_style("list", list_style_name)

get_parent_style

get_parent_style(style: StyleBase) -> StyleBase | None

Source code in odfdo/document.py

def get_parent_style(self, style: StyleBase) -> StyleBase | None:
    family = style.family
    if family is None:
        return None
    parent_style_name = style.parent_style  # type: ignore [attr-defined]
    if not parent_style_name:
        return None
    return self.get_style(family, parent_style_name)

get_part

get_part(path: str) -> XmlPart | str | bytes | None

Return the bytes of the given part. The path is relative to the archive, e.g. “Pictures/1003200258912EB1C3.jpg”.

‘content’, ‘meta’, ‘settings’, ‘styles’ and ‘manifest’ are shortcuts to the real path, e.g. content.xml, and return a dedicated object with its own API.

path formatted as URI, so always use ‘/’ separator

Source code in odfdo/document.py

def get_part(self, path: str) -> XmlPart | str | bytes | None:
    """Return the bytes of the given part. The path is relative to the
    archive, e.g. "Pictures/1003200258912EB1C3.jpg".

    'content', 'meta', 'settings', 'styles' and 'manifest' are shortcuts to
    the real path, e.g. content.xml, and return a dedicated object with its
    own API.

    path formatted as URI, so always use '/' separator
    """
    if not self.container:
        raise ValueError("Empty Container")
    # "./ObjectReplacements/Object 1"
    path = path.lstrip("./")
    path = _get_part_path(path)
    cls = _get_part_class(path)
    # Raw bytes
    if cls is None:
        return self.container.get_part(path)
    # XML part
    part = self.__xmlparts.get(path)
    if part is None:
        self.__xmlparts[path] = part = cls(path, self.container)
    return part

get_parts

get_parts() -> list[str]

Return available part names with path inside the archive, e.g. [‘content.xml’, …, ‘Pictures/100000000000032000000258912EB1C3.jpg’]

Source code in odfdo/document.py

def get_parts(self) -> list[str]:
    """Return available part names with path inside the archive, e.g.
    ['content.xml', ...,
    'Pictures/100000000000032000000258912EB1C3.jpg']
    """
    if not self.container:
        raise ValueError("Empty Container")
    return self.container.parts

get_style

get_style(
    family: str,
    name_or_element: str | StyleBase | None = None,
    display_name: str | None = None,
) -> StyleBase | None

Return the style uniquely identified by the name/family pair. If the argument is already a style object, it will return it.

If the name is None, the default style is fetched.

If the name is not the internal name but the name you gave in a desktop application, use display_name instead.

Args:

family -- 'paragraph', 'text',  'graphic', 'table', 'list',
          'number', 'page-layout', 'master-page', ...

name -- str or Element or None

display_name -- str

Returns: Style or None if not found.

Source code in odfdo/document.py

def get_style(
    self,
    family: str,
    name_or_element: str | StyleBase | None = None,
    display_name: str | None = None,
) -> StyleBase | None:
    """Return the style uniquely identified by the name/family pair. If the
    argument is already a style object, it will return it.

    If the name is None, the default style is fetched.

    If the name is not the internal name but the name you gave in a
    desktop application, use display_name instead.

    Args:

        family -- 'paragraph', 'text',  'graphic', 'table', 'list',
                  'number', 'page-layout', 'master-page', ...

        name -- str or Element or None

        display_name -- str

    Returns: Style or None if not found.
    """
    # 1. content.xml
    element = self.content.get_style(
        family, name_or_element=name_or_element, display_name=display_name
    )
    if element is not None:
        return element
    # 2. styles.xml
    return self.styles.get_style(
        family,
        name_or_element=name_or_element,
        display_name=display_name,
    )

get_style_properties

get_style_properties(
    family: str, name: str, area: str | None = None
) -> dict[str, str] | None

Return the properties of the required style as a dict.

Source code in odfdo/document.py

def get_style_properties(
    self, family: str, name: str, area: str | None = None
) -> dict[str, str] | None:
    """Return the properties of the required style as a dict."""
    style = self.get_style(family, name)
    if style is None:
        return None
    return style.get_properties(area=area)  # type: ignore

get_styled_elements

get_styled_elements(name: str = '') -> list[Element]

Brute-force to find paragraphs, tables, etc. using the given style name (or all by default).

Args:

name -- str

Returns: list

Source code in odfdo/document.py

def get_styled_elements(self, name: str = "") -> list[Element]:
    """Brute-force to find paragraphs, tables, etc. using the given style
    name (or all by default).

    Args:

        name -- str

    Returns: list
    """
    # Header, footer, etc. have styles too
    return self.content.root.get_styled_elements(
        name
    ) + self.styles.root.get_styled_elements(name)

get_styles

get_styles(
    family: str | bytes = "", automatic: bool = False
) -> list[StyleBase]

Source code in odfdo/document.py

def get_styles(
    self,
    family: str | bytes = "",
    automatic: bool = False,
) -> list[StyleBase]:
    # compatibility with old versions:
    if isinstance(family, bytes):
        family = bytes_to_str(family)
    return self.content.get_styles(family=family) + self.styles.get_styles(
        family=family, automatic=automatic
    )

get_table_displayed

get_table_displayed(table: str | int) -> bool

Return the table:display property of the style of the table, ie if the table should be displayed in a graphical interface.

Note: that method replaces the broken Table.displayd() method from previous odfdo versions.

Args:

table -- name or index of the table

Source code in odfdo/document.py

def get_table_displayed(self, table: str | int) -> bool:
    """Return the table:display property of the style of the table, ie if
    the table should be displayed in a graphical interface.

    Note: that method replaces the broken Table.displayd() method from previous
    odfdo versions.

    Args:

        table -- name or index of the table
    """
    style = self.get_table_style(table)
    if not style:
        # should not happen, but assume that a table without style is
        # displayed by default
        return True
    properties = style.get_properties() or {}
    property_str = str(properties.get("table:display", "true"))
    return Boolean.decode(property_str)

get_table_style

get_table_style(table: str | int) -> StyleBase | None

Return the Style instance the table.

Args:

table -- name or index of the table

Source code in odfdo/document.py

def get_table_style(
    self,
    table: str | int,
) -> StyleBase | None:
    """Return the Style instance the table.

    Args:

        table -- name or index of the table
    """
    if not (sheet := self._get_table(table)):
        return None
    return self.get_style("table", sheet.style)

get_type

get_type() -> str

Get the ODF type (also called class) of this document.

'chart', 'database', 'formula', 'graphics',

Type	Description
str	‘graphics-template’, ‘image’, ‘presentation’,
str	‘presentation-template’, ‘spreadsheet’, ‘spreadsheet-template’,
str	‘text’, ‘text-master’, ‘text-template’ or ‘text-web’

Source code in odfdo/document.py

def get_type(self) -> str:
    """Get the ODF type (also called class) of this document.

    Returns: 'chart', 'database', 'formula', 'graphics',
        'graphics-template', 'image', 'presentation',
        'presentation-template', 'spreadsheet', 'spreadsheet-template',
        'text', 'text-master', 'text-template' or 'text-web'
    """
    # The mimetype must be with the form:
    # application/vnd.oasis.opendocument.text

    # Isolate and return the last part
    return self.mimetype.rsplit(".", 1)[-1]

insert_style

insert_style(
    style: StyleBase | str,
    name: str = "",
    automatic: bool = False,
    default: bool = False,
) -> Any

Insert the given style object in the document, as required by the style family and type.

The style is expected to be a common style with a name. In case it was created with no name, the given can be set on the fly.

If automatic is True, the style will be inserted as an automatic style.

If default is True, the style will be inserted as a default style and would replace any existing default style of the same family. Any name or display name would be ignored.

Automatic and default arguments are mutually exclusive.

All styles can’t be used as default styles. Default styles are allowed for the following families: paragraph, text, section, table, table-column, table-row, table-cell, table-page, chart, drawing-page, graphic, presentation, control and ruby.

Args:

style -- Style or str

name -- str

automatic -- bool

default -- bool

Return : style name – str

Source code in odfdo/document.py

def insert_style(
    self,
    style: StyleBase | str,
    name: str = "",
    automatic: bool = False,
    default: bool = False,
) -> Any:
    """Insert the given style object in the document, as required by the
    style family and type.

    The style is expected to be a common style with a name. In case it
    was created with no name, the given can be set on the fly.

    If automatic is True, the style will be inserted as an automatic
    style.

    If default is True, the style will be inserted as a default style and
    would replace any existing default style of the same family. Any name
    or display name would be ignored.

    Automatic and default arguments are mutually exclusive.

    All styles can't be used as default styles. Default styles are
    allowed for the following families: paragraph, text, section, table,
    table-column, table-row, table-cell, table-page, chart, drawing-page,
    graphic, presentation, control and ruby.

    Args:

        style -- Style or str

        name -- str

        automatic -- bool

        default -- bool

    Return : style name -- str
    """

    # if style is a str, assume it is the Style definition
    if isinstance(style, str):
        style_element: StyleBase = Element.from_tag(style)  # type: ignore
    else:
        style_element = style
    if not isinstance(style_element, Element):
        raise TypeError(f"Unknown Style type: '{style!r}'")

    # Get family and name
    family = style_element.family
    if not name:
        name = self._pseudo_style_attribute(style_element, "name")

    # Master page style
    if family == "master-page":
        existing, style_container = self._insert_style_get_master_page(family, name)
    # Font face declarations
    elif family == "font-face":
        if default:
            existing, style_container = self._insert_style_get_font_face_default(
                family, name
            )
        else:
            existing, style_container = self._insert_style_get_font_face(
                family, name
            )
    # page layout style
    elif family == "page-layout":
        existing, style_container = self._insert_style_get_page_layout(family, name)
    # Common style
    elif family in FAMILY_MAPPING:
        existing, style_container = self._insert_style_standard(
            style_element, name, family, automatic, default
        )
    elif not family and style_element.__class__.__name__ == "DrawFillImage":
        # special case for 'draw:fill-image' pseudo style
        existing, style_container = self._insert_style_get_draw_fill_image(name)
    # Invalid style
    else:
        raise ValueError(
            "Invalid style: "
            f"{style_element}, tag:{style_element.tag}, family:{family}"
        )

    # Insert it!
    if existing is not None:
        style_container.delete(existing)
    style_container.append(style_element)
    return self._pseudo_style_attribute(style_element, "name")

merge_styles_from

merge_styles_from(document: Document) -> None

Copy all the styles of a document into ourself.

Styles with the same type and name will be replaced, so only unique styles will be preserved.

Source code in odfdo/document.py

def merge_styles_from(self, document: Document) -> None:
    """Copy all the styles of a document into ourself.

    Styles with the same type and name will be replaced, so only unique
    styles will be preserved.
    """
    manifest = self.manifest
    document_manifest = document.manifest
    for style in document.get_styles():
        tagname = style.tag
        family = style.family
        try:
            stylename = style.name  # type: ignore[attr-defined]
        except AttributeError:
            stylename = None
        container = style.parent
        container_name = container.tag  # type: ignore
        partname = container.parent.tag  # type: ignore
        # The destination part
        if partname == "office:document-styles":
            part: Content | Styles = self.styles
        elif partname == "office:document-content":
            part = self.content
        else:
            raise NotImplementedError(partname)
        # Implemented containers
        if container_name not in {
            "office:styles",
            "office:automatic-styles",
            "office:master-styles",
            "office:font-face-decls",
        }:
            raise NotImplementedError(container_name)
        dest = part.get_element(f"//{container_name}")
        if not dest:
            continue
        # Implemented style types
        # if tagname not in registered_styles:
        #    raise NotImplementedError(tagname)
        duplicate = part.get_style(family, stylename)  # type: ignore[arg-type]
        if duplicate is not None:
            duplicate.delete()
        dest.append(style)
        # Copy images from the header/footer
        if tagname == "style:master-page":
            query = "descendant::draw:image"
            for image in style.get_elements(query):
                url = image.url  # type: ignore
                part_url = document.get_part(url)
                # Manually add the part to keep the name
                self.set_part(url, part_url)  # type: ignore
                media_type = document_manifest.get_media_type(url)
                manifest.add_full_path(url, media_type)  # type: ignore
        # Copy images from the fill-image
        elif tagname == "draw:fill-image":
            url = style.url  # type: ignore
            part_url = document.get_part(url)
            self.set_part(url, part_url)  # type: ignore
            media_type = document_manifest.get_media_type(url)
            manifest.add_full_path(url, media_type)  # type: ignore

new classmethod

new(template: str | Path | BytesIO = 'text') -> Document

Create a Document from a template.

The template argument is expected to be the path to a ODF template.

Args:

template -- str or Path or file-like (io.BytesIO)

Return : ODF document – Document

Source code in odfdo/document.py

@classmethod
def new(cls, template: str | Path | io.BytesIO = "text") -> Document:
    """Create a Document from a template.

    The template argument is expected to be the path to a ODF template.

    Args:

        template -- str or Path or file-like (io.BytesIO)

    Return : ODF document -- Document
    """
    container = container_from_template(template)
    return cls(container)

save

save(
    target: str | Path | BytesIO | None = None,
    packaging: str = ZIP,
    pretty: bool | None = None,
    backup: bool = False,
) -> None

Save the document, at the same place it was opened or at the given target path. Target can also be a file-like object. It can be saved as a Zip file (default), flat XML format or as files in a folder (for debugging purpose). XML parts can be pretty printed (the default for ‘folder’ and ‘xml’ packaging).

Note: ‘xml’ packaging is an experimental work in progress.

Args:

target -- str or file-like object

packaging -- 'zip', 'folder', 'xml'

pretty -- bool | None

backup -- bool

Source code in odfdo/document.py

def save(
    self,
    target: str | Path | io.BytesIO | None = None,
    packaging: str = ZIP,
    pretty: bool | None = None,
    backup: bool = False,
) -> None:
    """Save the document, at the same place it was opened or at the given
    target path. Target can also be a file-like object. It can be saved as
    a Zip file (default), flat XML format or as files in a folder (for
    debugging purpose). XML parts can be pretty printed (the default for
    'folder' and 'xml' packaging).

    Note: 'xml' packaging is an experimental work in progress.

    Args:

        target -- str or file-like object

        packaging -- 'zip', 'folder', 'xml'

        pretty -- bool | None

        backup -- bool
    """
    if not self.container:
        raise ValueError("Empty Container")
    if packaging not in PACKAGING:
        raise ValueError(f'Packaging of type "{packaging}" is not supported')
    # Some advertising
    self.meta.set_generator_default()
    # Synchronize data with container
    container = self.container
    if pretty is None:
        pretty = packaging in {"folder", "xml"}
    pretty = bool(pretty)
    backup = bool(backup)
    self._check_manifest_rdf()
    if pretty and packaging != XML:
        for path, part in self.__xmlparts.items():
            if part is not None:
                container.set_part(path, part.pretty_serialize())
        for path in (ODF_CONTENT, ODF_META, ODF_SETTINGS, ODF_STYLES):
            if path in self.__xmlparts:
                continue
            cls = _get_part_class(path)
            if cls is None:
                raise RuntimeError("Should never happen")
            # XML part
            self.__xmlparts[path] = part = cls(path, container)
            container.set_part(path, part.pretty_serialize())
    else:
        for path, part in self.__xmlparts.items():
            if part is not None:
                container.set_part(path, part.serialize())
    container.save(target, packaging=packaging, backup=backup, pretty=pretty)

set_language

set_language(language: str) -> None

Set the default language of the document, both in styles and metadata.

(Also available as “Document.language” property.)

Args:

language -- str

Example::

>>> document.set_language('fr-FR')

Source code in odfdo/document.py

def set_language(self, language: str) -> None:
    """Set the default language of the document, both in styles and
    metadata.

    (Also available as "Document.language" property.)

    Args:

        language -- str

    Example::

        >>> document.set_language('fr-FR')
    """
    language = str(language)
    if not is_RFC3066(language):
        raise TypeError(
            'Language must be "xx" lang or "xx-YY" lang-COUNTRY code (RFC3066)'
        )
    self.styles.default_language = language
    self.meta.language = language

set_part

set_part(path: str, data: bytes) -> None

Set the bytes of the given part. The path is relative to the archive, e.g. “Pictures/1003200258912EB1C3.jpg”.

path formatted as URI, so always use ‘/’ separator

Source code in odfdo/document.py

def set_part(self, path: str, data: bytes) -> None:
    """Set the bytes of the given part. The path is relative to the
    archive, e.g. "Pictures/1003200258912EB1C3.jpg".

    path formatted as URI, so always use '/' separator
    """
    if not self.container:
        raise ValueError("Empty Container")
    # "./ObjectReplacements/Object 1"
    path = path.lstrip("./")
    path = _get_part_path(path)
    cls = _get_part_class(path)
    # XML part overwritten
    if cls is not None:
        with suppress(KeyError):
            self.__xmlparts[path]
    self.container.set_part(path, data)

set_table_displayed

set_table_displayed(
    table: str | int, displayed: bool
) -> None

Set the table:display property of the style of the table, ie if the table should be displayed in a graphical interface.

Note: that method replaces the broken Table.displayd() method from previous odfdo versions.

Args:

table -- name or index of the table

displayed -- boolean flag

Source code in odfdo/document.py

def set_table_displayed(self, table: str | int, displayed: bool) -> None:
    """Set the table:display property of the style of the table, ie if the
    table should be displayed in a graphical interface.

    Note: that method replaces the broken Table.displayd() method from previous
    odfdo versions.

    Args:

        table -- name or index of the table

        displayed -- boolean flag
    """
    orig_style = self.get_table_style(table)
    if not orig_style:
        name = self._unique_style_name("ta")
        orig_style = Element.from_tag(  # type:ignore[assignment]
            f'<style:style style:name="{name}" style:family="table" '
            'style:master-page-name="Default">'
            '<style:table-properties table:display="true" '
            'style:writing-mode="lr-tb"/></style:style>'
        )
        self.insert_style(orig_style, automatic=True)  # type:ignore
    new_style = orig_style.clone  # type: ignore[union-attr]
    new_name = self._unique_style_name("ta")
    new_style.name = new_name  # type:ignore
    self.insert_style(new_style, automatic=True)  # type:ignore
    sheet = self._get_table(table)
    sheet.style = new_name  # type: ignore
    properties = {"table:display": Boolean.encode(displayed)}
    new_style.set_properties(properties)  # type: ignore

show_styles

show_styles(
    automatic: bool = True,
    common: bool = True,
    properties: bool = False,
) -> str

Source code in odfdo/document.py

def show_styles(
    self,
    automatic: bool = True,
    common: bool = True,
    properties: bool = False,
) -> str:
    infos = []
    for style in self.get_styles():
        try:
            name = style.name  # type: ignore[attr-defined]
        except AttributeError:
            print("Style error:")
            print(style.__class__)
            print(style.serialize())
            raise
        if style.__class__.__name__ == "DrawFillImage":
            family = ""
        else:
            family = str(style.family)
        parent = style.parent
        is_auto = parent and parent.tag == "office:automatic-styles"
        if (is_auto and automatic is False) or (not is_auto and common is False):
            continue
        is_used = bool(self.get_styled_elements(name))
        infos.append(
            {
                "type": "auto  " if is_auto else "common",
                "used": "y" if is_used else "n",
                "family": family,
                "parent": self._pseudo_style_attribute(style, "parent_style") or "",
                "name": name or "",
                "display_name": self._pseudo_style_attribute(style, "display_name")
                or "",
                "properties": style.get_properties() if properties else None,
            }
        )
    if not infos:
        return ""
    # Sort by family and name
    infos.sort(key=itemgetter("family", "name"))
    # Show common and used first
    infos.sort(key=itemgetter("type", "used"), reverse=True)
    max_family = str(max(len(x["family"]) for x in infos))  # type: ignore
    max_parent = str(max(len(x["parent"]) for x in infos))  # type: ignore
    formater = (
        "%(type)s used:%(used)s family:%(family)-0"
        + max_family
        + "s parent:%(parent)-0"
        + max_parent
        + "s name:%(name)s"
    )
    output = []
    for info in infos:
        line = formater % info
        if info["display_name"]:
            line += " display_name:" + info["display_name"]  # type: ignore
        output.append(line)
        if info["properties"]:
            for name, value in info["properties"].items():  # type: ignore
                output.append(f"   - {name}: {value}")
    output.append("")
    return "\n".join(output)

to_markdown

to_markdown() -> str

Source code in odfdo/document.py

def to_markdown(self) -> str:
    doc_type = self.get_type()
    if doc_type not in {
        "text",
    }:
        raise NotImplementedError(
            f"Type of document '{doc_type}' not supported yet"
        )
    return self._markdown_export()

DrawFillImage

Bases: DrawImage

A link to a bitmap resource, “draw:fill-image”.

Methods:

Name	Description
__init__	A link to a bitmap resource, “draw:fill-image”.

Attributes:

Name	Type	Description
display_name
family
height
name
width

Source code in odfdo/image.py

class DrawFillImage(DrawImage):
    """A link to a bitmap resource, "draw:fill-image"."""

    _tag = "draw:fill-image"
    _properties: tuple[PropDef, ...] = (
        PropDef("display_name", "draw:display-name"),
        PropDef("name", "draw:name"),
        PropDef("height", "svg:height"),
        PropDef("width", "svg:width"),
    )

    def __init__(
        self,
        name: str | None = None,
        display_name: str | None = None,
        height: str | None = None,
        width: str | None = None,
        **kwargs: Any,
    ) -> None:
        """A link to a bitmap resource, "draw:fill-image".

        The "draw:fill-image" element specifies a link to a bitmap
        resource. Fill image are not available as automatic styles.
        The "draw:fill-image" element is usable within the following element:
        "office:styles"

        Args:

            name -- str

            display_name -- str

            height -- str

            width -- str
        """
        super().__init__(**kwargs)
        if self._do_init:
            self.name = name
            self.display_name = display_name
            self.height = height
            self.width = width
        self.family = ""

display_name instance-attribute

display_name = display_name

family instance-attribute

family = ''

height instance-attribute

height = height

name instance-attribute

name = name

width instance-attribute

width = width

__init__

__init__(
    name: str | None = None,
    display_name: str | None = None,
    height: str | None = None,
    width: str | None = None,
    **kwargs: Any,
) -> None

A link to a bitmap resource, “draw:fill-image”.

The “draw:fill-image” element specifies a link to a bitmap resource. Fill image are not available as automatic styles. The “draw:fill-image” element is usable within the following element: “office:styles”

Args:

name -- str

display_name -- str

height -- str

width -- str

Source code in odfdo/image.py

def __init__(
    self,
    name: str | None = None,
    display_name: str | None = None,
    height: str | None = None,
    width: str | None = None,
    **kwargs: Any,
) -> None:
    """A link to a bitmap resource, "draw:fill-image".

    The "draw:fill-image" element specifies a link to a bitmap
    resource. Fill image are not available as automatic styles.
    The "draw:fill-image" element is usable within the following element:
    "office:styles"

    Args:

        name -- str

        display_name -- str

        height -- str

        width -- str
    """
    super().__init__(**kwargs)
    if self._do_init:
        self.name = name
        self.display_name = display_name
        self.height = height
        self.width = width
    self.family = ""

DrawGroup

Bases: Element, AnchorMix, ZMix, PosMix

Representation of a group of drawing shapes, “draw:g”.

Warning: implementation is currently minimal.

Drawing shapes contained by a “draw:g” element that is itself contained by a “draw:a” element, act as hyperlinks using the xlink:href attribute of the containing “draw:a” element. If the included drawing shapes are themselves contained within “draw:a” elements, then the xlink:href attributes of those “draw:a” elements act as the hyperlink information for the shapes they contain.

The “draw:g” element has the following attributes: draw:caption-id, draw:class-names, draw:id, draw:name, draw:style-name, draw:z-index, presentation:class-names, presentation:style-name, svg:y, table:end-cell-address, table:end-x, table:end-y, table:table-background, text:anchor-page-number, text:anchor-type, and xml:id.

The “draw:g” element has the following child elements: “dr3d:scene”, “draw:a”, “draw:caption”, “draw:circle”, “draw:connector”, “draw:control”, “draw:custom-shape”, “draw:ellipse”, “draw:frame”, “draw:g”, “draw:glue-point”, “draw:line”, “draw:measure”, “draw:page-thumbnail”, “draw:path”, “draw:polygon”, “draw:polyline”, “draw:rect”, “draw:regular-polygon”, “office:event-listeners”, “svg:desc” and “svg:title”.

Methods:

Name	Description
__init__	Create a group of drawing shapes “draw:g”.

Attributes:

Name	Type	Description
anchor_page
anchor_type
draw_id
name
position
presentation_style
style
z_index

Source code in odfdo/shapes.py

class DrawGroup(Element, AnchorMix, ZMix, PosMix):
    """Representation of a group of drawing shapes, "draw:g".

    Warning: implementation is currently minimal.

    Drawing shapes contained by a "draw:g" element that is itself
    contained by a "draw:a" element, act as hyperlinks using the
    xlink:href attribute of the containing "draw:a" element. If the
    included drawing shapes are themselves contained within "draw:a"
    elements, then the xlink:href attributes of those "draw:a" elements
    act as the hyperlink information for the shapes they contain.

    The "draw:g" element has the following attributes: draw:caption-id,
    draw:class-names, draw:id, draw:name, draw:style-name, draw:z-index,
    presentation:class-names, presentation:style-name, svg:y,
    table:end-cell-address, table:end-x, table:end-y,
    table:table-background, text:anchor-page-number, text:anchor-type,
    and xml:id.

    The "draw:g" element has the following child elements: "dr3d:scene",
    "draw:a", "draw:caption", "draw:circle", "draw:connector",
    "draw:control", "draw:custom-shape", "draw:ellipse", "draw:frame",
    "draw:g", "draw:glue-point", "draw:line", "draw:measure",
    "draw:page-thumbnail", "draw:path", "draw:polygon", "draw:polyline",
    "draw:rect", "draw:regular-polygon", "office:event-listeners",
    "svg:desc" and "svg:title".
    """

    _tag = "draw:g"
    _properties: tuple[PropDef, ...] = (
        PropDef("draw_id", "draw:id"),
        PropDef("caption_id", "draw:caption-id"),
        PropDef("draw_class_names", "draw:class-names"),
        PropDef("name", "draw:name"),
        PropDef("style", "draw:style-name"),
        # ('z_index', 'draw:z-index'),
        PropDef("presentation_class_names", "presentation:class-names"),
        PropDef("presentation_style", "presentation:style-name"),
        PropDef("table_end_cell", "table:end-cell-address"),
        PropDef("table_end_x", "table:end-x"),
        PropDef("table_end_y", "table:end-y"),
        PropDef("table_background", "table:table-background"),
        # ('anchor_page', 'text:anchor-page-number'),
        # ('anchor_type', 'text:anchor-type'),
        PropDef("xml_id", "xml:id"),
        PropDef("pos_x", "svg:x"),
        PropDef("pos_y", "svg:y"),
    )

    def __init__(
        self,
        name: str | None = None,
        draw_id: str | None = None,
        style: str | None = None,
        position: tuple | None = None,
        z_index: int = 0,
        anchor_type: str | None = None,
        anchor_page: int | None = None,
        presentation_style: str | None = None,
        **kwargs: Any,
    ) -> None:
        """Create a group of drawing shapes "draw:g"."""
        super().__init__(**kwargs)
        if self._do_init:
            if z_index is not None:
                self.z_index = z_index
            if name:
                self.name = name
            if draw_id is not None:
                self.draw_id = draw_id
            if style is not None:
                self.style = style
            if position is not None:
                self.position = position
            if anchor_type:
                self.anchor_type = anchor_type
            if anchor_page is not None:
                self.anchor_page = anchor_page
            if presentation_style is not None:
                self.presentation_style = presentation_style

anchor_page instance-attribute

anchor_page = anchor_page

anchor_type instance-attribute

anchor_type = anchor_type

draw_id instance-attribute

draw_id = draw_id

name instance-attribute

name = name

position instance-attribute

position = position

presentation_style instance-attribute

presentation_style = presentation_style

style instance-attribute

style = style

z_index instance-attribute

z_index = z_index

__init__

__init__(
    name: str | None = None,
    draw_id: str | None = None,
    style: str | None = None,
    position: tuple | None = None,
    z_index: int = 0,
    anchor_type: str | None = None,
    anchor_page: int | None = None,
    presentation_style: str | None = None,
    **kwargs: Any,
) -> None

Create a group of drawing shapes “draw:g”.

Source code in odfdo/shapes.py

def __init__(
    self,
    name: str | None = None,
    draw_id: str | None = None,
    style: str | None = None,
    position: tuple | None = None,
    z_index: int = 0,
    anchor_type: str | None = None,
    anchor_page: int | None = None,
    presentation_style: str | None = None,
    **kwargs: Any,
) -> None:
    """Create a group of drawing shapes "draw:g"."""
    super().__init__(**kwargs)
    if self._do_init:
        if z_index is not None:
            self.z_index = z_index
        if name:
            self.name = name
        if draw_id is not None:
            self.draw_id = draw_id
        if style is not None:
            self.style = style
        if position is not None:
            self.position = position
        if anchor_type:
            self.anchor_type = anchor_type
        if anchor_page is not None:
            self.anchor_page = anchor_page
        if presentation_style is not None:
            self.presentation_style = presentation_style

DrawImage

Bases: Element

An ODF image, “draw:image”.

The “draw:image” element represents an image. An image can be either a link to an external resource or most often embedded into the document.

Methods:

Name	Description
__init__	An ODF image, “draw:image”.

Attributes:

Name	Type	Description
actuate
filter_name
show
type
url

Source code in odfdo/image.py

class DrawImage(Element):
    """An ODF image, "draw:image".

    The "draw:image" element represents an image. An image can be either a link
    to an external resource or most often embedded into the document.
    """

    _tag = "draw:image"
    _properties: tuple[PropDef, ...] = (
        PropDef("url", "xlink:href"),
        PropDef("type", "xlink:type"),
        PropDef("show", "xlink:show"),
        PropDef("actuate", "xlink:actuate"),
        PropDef("filter_name", "draw:filter-name"),
    )

    def __init__(
        self,
        url: str = "",
        xlink_type: str = "simple",
        show: str = "embed",
        actuate: str = "onLoad",
        filter_name: str | None = None,
        **kwargs: Any,
    ) -> None:
        """An ODF image, "draw:image".

        When image is embedded in the document, the url parameter is a
        reference to the local document obtained by copying the source
        image into the document, ie: url = document.add_file(image_path)

        Warning: image elements must be stored in a frame "draw:frame",
        see Frame().

        Initialization of an DrawImage.

        Args:

            url -- str

            type -- str

            show -- str

            actuate -- str

            filter_name -- str
        """
        super().__init__(**kwargs)
        if self._do_init:
            self.url = url
            self.type = xlink_type
            self.show = show
            self.actuate = actuate
            self.filter_name = filter_name

actuate instance-attribute

actuate = actuate

filter_name instance-attribute

filter_name = filter_name

show instance-attribute

show = show

type instance-attribute

type = xlink_type

url instance-attribute

url = url

__init__

__init__(
    url: str = "",
    xlink_type: str = "simple",
    show: str = "embed",
    actuate: str = "onLoad",
    filter_name: str | None = None,
    **kwargs: Any,
) -> None

An ODF image, “draw:image”.

When image is embedded in the document, the url parameter is a reference to the local document obtained by copying the source image into the document, ie: url = document.add_file(image_path)

Warning: image elements must be stored in a frame “draw:frame”, see Frame().

Initialization of an DrawImage.

Args:

url -- str

type -- str

show -- str

actuate -- str

filter_name -- str

Source code in odfdo/image.py

def __init__(
    self,
    url: str = "",
    xlink_type: str = "simple",
    show: str = "embed",
    actuate: str = "onLoad",
    filter_name: str | None = None,
    **kwargs: Any,
) -> None:
    """An ODF image, "draw:image".

    When image is embedded in the document, the url parameter is a
    reference to the local document obtained by copying the source
    image into the document, ie: url = document.add_file(image_path)

    Warning: image elements must be stored in a frame "draw:frame",
    see Frame().

    Initialization of an DrawImage.

    Args:

        url -- str

        type -- str

        show -- str

        actuate -- str

        filter_name -- str
    """
    super().__init__(**kwargs)
    if self._do_init:
        self.url = url
        self.type = xlink_type
        self.show = show
        self.actuate = actuate
        self.filter_name = filter_name

DrawPage

Bases: Element

ODF draw page for presentations and drawings, “draw:page”.

Methods:

Name	Description
__init__	ODF draw page for presentations and drawings, “draw:page”.
get_formatted_text
get_shapes
get_transition
set_transition

Attributes:

Name	Type	Description
draw_id
master_page
name
presentation_page_layout
style

Source code in odfdo/draw_page.py

class DrawPage(Element):
    """ODF draw page for presentations and drawings, "draw:page"."""

    _tag = "draw:page"
    _properties = (
        PropDef("name", "draw:name"),
        PropDef("draw_id", "draw:id"),
        PropDef("master_page", "draw:master-page-name"),
        PropDef(
            "presentation_page_layout", "presentation:presentation-page-layout-name"
        ),
        PropDef("style", "draw:style-name"),
    )

    def __init__(
        self,
        draw_id: str | None = None,
        name: str | None = None,
        master_page: str | None = None,
        presentation_page_layout: str | None = None,
        style: str | None = None,
        **kwargs: Any,
    ) -> None:
        """ODF draw page for presentations and drawings, "draw:page".

        Args:

            draw_id -- str

            name -- str

            master_page -- str

            presentation_page_layout -- str

            style -- str
        """
        super().__init__(**kwargs)
        if self._do_init:
            if draw_id:
                self.draw_id = draw_id
            if name:
                self.name = name
            if master_page:
                self.master_page = master_page
            if presentation_page_layout:
                self.presentation_page_layout = presentation_page_layout
            if style:
                self.style = style

    def get_transition(self) -> AnimPar | None:
        return self.get_element("anim:par")  # type: ignore

    def set_transition(
        self,
        smil_type: str,
        subtype: str | None = None,
        dur: str = "2s",
        node_type: str = "default",
    ) -> None:
        # Create the new animation
        anim_page = AnimPar(presentation_node_type=node_type)
        anim_begin = AnimPar(smil_begin=f"{self.draw_id}.begin")
        transition = AnimTransFilter(
            smil_dur=dur, smil_type=smil_type, smil_subtype=subtype
        )
        anim_page.append(anim_begin)
        anim_begin.append(transition)
        # Replace when already a transition:
        #   anim:seq => After the frame's transition
        #   cf page 349 of OpenDocument-v1.0-os.pdf
        #   Conclusion: We must delete the first child 'anim:par'
        previous_transition = self.get_transition()
        if previous_transition:
            self.delete(previous_transition)
        self.append(anim_page)

    def get_shapes(self) -> list[Element]:
        query = "(descendant::" + "|descendant::".join(registered_shapes) + ")"
        return self.get_elements(query)

    def get_formatted_text(self, context: dict | None = None) -> str:
        result: list[str] = []
        for child in self.children:
            if child.tag == "presentation:notes":
                # No need for an advanced odf_notes.get_formatted_text()
                # because the text seems to be only contained in paragraphs
                # and frames, that we already handle
                for sub_child in child.children:
                    result.append(sub_child.get_formatted_text(context))
                result.append("\n")
            result.append(child.get_formatted_text(context))
        result.append("\n")
        return "".join(result)

draw_id instance-attribute

draw_id = draw_id

master_page instance-attribute

master_page = master_page

name instance-attribute

name = name

presentation_page_layout instance-attribute

presentation_page_layout = presentation_page_layout

style instance-attribute

style = style

__init__

__init__(
    draw_id: str | None = None,
    name: str | None = None,
    master_page: str | None = None,
    presentation_page_layout: str | None = None,
    style: str | None = None,
    **kwargs: Any,
) -> None

ODF draw page for presentations and drawings, “draw:page”.

Args:

draw_id -- str

name -- str

master_page -- str

presentation_page_layout -- str

style -- str

Source code in odfdo/draw_page.py

def __init__(
    self,
    draw_id: str | None = None,
    name: str | None = None,
    master_page: str | None = None,
    presentation_page_layout: str | None = None,
    style: str | None = None,
    **kwargs: Any,
) -> None:
    """ODF draw page for presentations and drawings, "draw:page".

    Args:

        draw_id -- str

        name -- str

        master_page -- str

        presentation_page_layout -- str

        style -- str
    """
    super().__init__(**kwargs)
    if self._do_init:
        if draw_id:
            self.draw_id = draw_id
        if name:
            self.name = name
        if master_page:
            self.master_page = master_page
        if presentation_page_layout:
            self.presentation_page_layout = presentation_page_layout
        if style:
            self.style = style

get_formatted_text

get_formatted_text(context: dict | None = None) -> str

Source code in odfdo/draw_page.py

def get_formatted_text(self, context: dict | None = None) -> str:
    result: list[str] = []
    for child in self.children:
        if child.tag == "presentation:notes":
            # No need for an advanced odf_notes.get_formatted_text()
            # because the text seems to be only contained in paragraphs
            # and frames, that we already handle
            for sub_child in child.children:
                result.append(sub_child.get_formatted_text(context))
            result.append("\n")
        result.append(child.get_formatted_text(context))
    result.append("\n")
    return "".join(result)

get_shapes

get_shapes() -> list[Element]

Source code in odfdo/draw_page.py

def get_shapes(self) -> list[Element]:
    query = "(descendant::" + "|descendant::".join(registered_shapes) + ")"
    return self.get_elements(query)

get_transition

get_transition() -> AnimPar | None

Source code in odfdo/draw_page.py

def get_transition(self) -> AnimPar | None:
    return self.get_element("anim:par")  # type: ignore

set_transition

set_transition(
    smil_type: str,
    subtype: str | None = None,
    dur: str = "2s",
    node_type: str = "default",
) -> None

Source code in odfdo/draw_page.py

def set_transition(
    self,
    smil_type: str,
    subtype: str | None = None,
    dur: str = "2s",
    node_type: str = "default",
) -> None:
    # Create the new animation
    anim_page = AnimPar(presentation_node_type=node_type)
    anim_begin = AnimPar(smil_begin=f"{self.draw_id}.begin")
    transition = AnimTransFilter(
        smil_dur=dur, smil_type=smil_type, smil_subtype=subtype
    )
    anim_page.append(anim_begin)
    anim_begin.append(transition)
    # Replace when already a transition:
    #   anim:seq => After the frame's transition
    #   cf page 349 of OpenDocument-v1.0-os.pdf
    #   Conclusion: We must delete the first child 'anim:par'
    previous_transition = self.get_transition()
    if previous_transition:
        self.delete(previous_transition)
    self.append(anim_page)

Drawing

Bases: NRMixin, Body

Root of the Drawing document content, “office:drawing”.

Source code in odfdo/body.py

class Drawing(NRMixin, Body):
    """Root of the Drawing document content, "office:drawing"."""

    _tag: str = "office:drawing"
    _properties: tuple[PropDef, ...] = ()

EText

Bases: str

Representation of an XML text node (internal).

Created to hide the specifics of lxml in searching text nodes using XPath.

Constructed like any str object but only accepts lxml text objects.

Methods:

Name	Description
__init__
is_tail
is_text

Attributes:

Name	Type	Description
parent	Element | None

Source code in odfdo/element.py

class EText(str):
    """Representation of an XML text node (internal).

    Created to hide the specifics of lxml in searching text nodes using XPath.

    Constructed like any str object but only accepts lxml text objects.
    """

    # There's some black magic in inheriting from str
    def __init__(
        self,
        text_result: _Element,
    ) -> None:
        self.__parent = text_result.getparent()
        self.__is_text: bool = bool(text_result.is_text)
        self.__is_tail: bool = bool(text_result.is_tail)

    @property
    def parent(self) -> Element | None:
        parent = self.__parent
        # XXX happens just because of the unit test
        if parent is None:
            return None
        return Element.from_tag(tag_or_elem=parent)

    def is_text(self) -> bool:
        return self.__is_text

    def is_tail(self) -> bool:
        return self.__is_tail

parent property

parent: Element | None

__init__

__init__(text_result: _Element) -> None

Source code in odfdo/element.py

def __init__(
    self,
    text_result: _Element,
) -> None:
    self.__parent = text_result.getparent()
    self.__is_text: bool = bool(text_result.is_text)
    self.__is_tail: bool = bool(text_result.is_tail)

is_tail

is_tail() -> bool

Source code in odfdo/element.py

def is_tail(self) -> bool:
    return self.__is_tail

is_text

is_text() -> bool

Source code in odfdo/element.py

def is_text(self) -> bool:
    return self.__is_text

Element

Bases: MDBase

Base class of all ODF classes, abstraction of the underlying XML.

Methods:

Name	Description
__init__	Base class of all ODF classes, abstraction of the underlying XML.
clear	Remove text, children and attributes from the element.
del_attribute
delete	Delete the given element from the XML tree. If no element is given,
elements_repeated_sequence	Utility method for table module.
extend	Fast append elements at the end of ourself using extend.
from_tag	Element class and subclass factory.
from_tag_for_clone
get_annotation	Return the annotation that matches the criteria.
get_annotation_end	Return the annotation end that matches the criteria.
get_annotation_ends	Return all the annotation ends.
get_annotations	Return all the annotations that match the criteria.
get_attribute	Return the attribute value as type str | bool | None.
get_attribute_integer	Return either the attribute as type int, or None.
get_attribute_string	Return either the attribute as type str, or None.
get_bookmark	Return the bookmark that matches the criteria.
get_bookmark_end	Return the bookmark end that matches the criteria.
get_bookmark_ends	Return all the bookmark ends.
get_bookmark_start	Return the bookmark start that matches the criteria.
get_bookmark_starts	Return all the bookmark starts.
get_bookmarks	Return all the bookmarks.
get_changes_ids	Return a list of ids that refers to a change region in the tracked
get_draw_connector	Return the draw connector that matches the criteria.
get_draw_connectors	Return all the draw connectors that match the criteria.
get_draw_ellipse	Return the draw ellipse that matches the criteria.
get_draw_ellipses	Return all the draw ellipses that match the criteria.
get_draw_group	Return the draw group that matches the criteria.
get_draw_groups	Return all the draw groups that match the criteria.
get_draw_line	Return the draw line that matches the criteria.
get_draw_lines	Return all the draw lines that match the criteria.
get_draw_page	Return the draw page that matches the criteria.
get_draw_pages	Return all the draw pages that match the criteria.
get_draw_rectangle	Return the draw rectangle that matches the criteria.
get_draw_rectangles	Return all the draw rectangles that match the criteria.
get_element	Returns the first element obtained from the XPath query applied to
get_elements	Returns the elements obtained from the XPath query applied to the
get_formatted_text	This function should return a beautiful version of the text.
get_frame	Return the section that matches the criteria.
get_frames	Return all the frames that match the criteria.
get_header	Return the Header that matches the criteria.
get_headers	Return all the Headers that match the criteria.
get_image	Return the image matching the criteria.
get_images	Return all the images matching the criteria.
get_link	Return the link that matches the criteria.
get_links	Return all the links that match the criteria.
get_list	Return the list that matches the criteria.
get_lists	Return all the lists that match the criteria.
get_note	Return the note that matches the criteria.
get_notes	Return all the notes that match the criteria.
get_office_names	Return all the used office:name tags values of the element.
get_orphan_draw_connectors	Return a list of connectors which don’t have any shape connected to
get_paragraph	Return the paragraph that matches the criteria.
get_paragraphs	Return all the paragraphs that match the criteria.
get_reference_mark	Return the reference mark that match the criteria. Either single
get_reference_mark_end	Return the reference mark end that matches the criteria. Search only
get_reference_mark_ends	Return all the reference mark ends. Search only the tags
get_reference_mark_single	Return the reference mark that matches the criteria. Search only the
get_reference_mark_start	Return the reference mark start that matches the criteria. Search
get_reference_mark_starts	Return all the reference mark starts. Search only the tags
get_reference_marks	Return all the reference marks, either single position reference
get_reference_marks_single	Return all the reference marks. Search only the tags
get_references	Return all the references (text:reference-ref). If name is provided,
get_section	Return the section that matches the criteria.
get_sections	Return all the sections that match the criteria.
get_span	Return the span that matches the criteria.
get_spans	Return all the spans that match the criteria.
get_style	Return the style uniquely identified by the family/name pair. If the
get_styled_elements	Brute-force to find paragraphs, tables, etc. using the given style
get_styles
get_text_change	Return the text change that matches the criteria. Either single
get_text_change_deletion	Return the text change of deletion kind that matches the criteria.
get_text_change_deletions	Return all the text changes of deletion kind: the tags text:change.
get_text_change_end	Return the text change-end that matches the criteria. Search only
get_text_change_ends	Return all the text change-end. Search only the tags
get_text_change_start	Return the text change-start that matches the criteria. Search
get_text_change_starts	Return all the text change-start. Search only for the tags
get_text_changes	Return all the text changes, either single deletion (text:change) or
get_toc	Return the table of contents that matches the criteria.
get_tocs	Return all the tables of contents.
get_tracked_changes	Return the tracked-changes part in the text body.
get_user_defined	Return the user defined declaration for the given name.
get_user_defined_list	Return all the user defined field declarations.
get_user_defined_value	Return the value of the given user defined field name.
get_user_field_decl	Return the user field declaration for the given name.
get_user_field_decl_list	Return all the user field declarations.
get_user_field_decls	Return the container for user field declarations. Created if not
get_user_field_value	Return the value of the given user field name.
get_variable_decl	Return the variable declaration for the given name.
get_variable_decl_list	Return all the variable declarations.
get_variable_decls	Return the container for variable declarations. Created if not
get_variable_set	Return the variable set for the given name (last one by default).
get_variable_set_value	Return the last value of the given variable name.
get_variable_sets	Return all the variable sets that match the criteria.
index	Return the position of the child in this element.
insert	Insert an element relatively to ourself.
is_empty	Check if the element is empty : no text, no children, no tail.
match	Return True if the pattern is found one or more times anywhere in
replace	Replace the pattern with the given text, or delete if text is an
replace_element	Replaces in place a sub element with the element passed as second
search	Return the first position of the pattern in the text content of the
search_all	Return all start and end positions of the regex pattern in the text
search_first	Return the start and end position of the first occurrence of the
serialize	Return text serialization of XML element.
set_attribute
set_style_attribute	Shortcut to accept a style object as a value.
text_at	Return the text (recursive) content of the element between start and
xpath	Apply XPath query to the element and its subtree.

Attributes:

Name	Type	Description
append
attributes	dict[str, str]
children	list[Element]
clone	Element
document_body	Body | None	Return the first children of document body if any: ‘office:body/*[1]’
frames	list[Frame]	Return all the frames.
headers	list[Header]	Return all the Headers.
images	list[DrawImage]	Return all the images.
inner_text	str
is_bound	bool
lists	list[List]	Return all the lists.
paragraphs	list[Paragraph]	Return all the paragraphs.
parent	Element | None
root	Element
sections	list[Section]	Return all the sections.
spans	list[Span]	Return all the spans.
svg_description	str | None
svg_title	str | None
tag	str	Get/set the underlying xml tag with the given qualified name.
tail	str | None	Get / set the text immediately following the element.
text	str	Get / set the text content of the element.
text_changes	list[TextChange | TextChangeStart]	Return all the text changes, either single deletion (text:change) or
text_content	str	Get / set the text of the embedded paragraphs, including embeded
text_recursive	str
toc	TOC | None	Return the first table of contents.
tocs	list[TOC]	Return all the tables of contents.
tracked_changes	Element | None	Return the tracked-changes part in the text body.
user_defined_list	list[UserDefined]	Return all the user defined field declarations.

Source code in odfdo/element.py

class Element(MDBase):
    """Base class of all ODF classes, abstraction of the underlying XML."""

    _tag: str = ""
    _properties: tuple[PropDef, ...] = ()

    def __init__(self, **kwargs: Any) -> None:
        """Base class of all ODF classes, abstraction of the underlying XML."""
        tag_or_elem = kwargs.pop("tag_or_elem", None)
        if tag_or_elem is None:
            # Instance for newly created object: create new lxml element and
            # continue by subclass __init__
            # If the tag key word exists, make a custom element
            self._do_init = True
            tag = kwargs.pop("tag", self._tag)
            self.__element = self._make_etree_element(tag)
        else:
            # called with an existing lxml element, sould be a result of
            # from_tag() casting, do not execute the subclass __init__
            if not isinstance(tag_or_elem, _Element):
                raise TypeError(f'"{type(tag_or_elem)}" is not an element node')
            self._do_init = False
            self.__element = tag_or_elem

    def __repr__(self) -> str:
        return f"<{self.__class__.__name__} tag={self.tag}>"

    @classmethod
    def from_tag(cls, tag_or_elem: str | _Element) -> Element:
        """Element class and subclass factory.

        Turn an lxml Element or ODF string tag into an ODF XML Element
        of the relevant class.

        Args:

            tag_or_elem -- ODF str tag or lxml.Element

        Returns: Element (or subclass) instance
        """
        if isinstance(tag_or_elem, str):
            # assume the argument is a prefix:name tag
            elem = cls._make_etree_element(tag_or_elem)
        else:
            elem = tag_or_elem
        klass = _class_registry.get(elem.tag, cls)
        return klass(tag_or_elem=elem)

    @classmethod
    def from_tag_for_clone(
        cls: Any,  # ABCMeta, type, ...
        tree_element: _Element,
        cache: tuple | None,
    ) -> Element:
        tag = to_str(tree_element.tag)
        klass = _class_registry.get(tag, cls)
        element: Element = klass(tag_or_elem=tree_element)
        if cache:
            element._copy_cache(cache)
        return element

    def _copy_cache(self, cache: tuple) -> None:
        """Method redefined for cached elements."""
        pass

    @staticmethod
    def _make_etree_element(tag: str) -> _Element:
        if not isinstance(tag, str):
            raise TypeError(f"Tag is not str: {tag!r}")
        tag = tag.strip()
        if not tag:
            raise ValueError("Tag is empty")
        if "<" not in tag:
            # Qualified name
            # XXX don't build the element from scratch or lxml will pollute with
            # repeated namespace declarations
            tag = f"<{tag}/>"
        # XML fragment
        root = fromstring(NAMESPACES_XML % str_to_bytes(tag))
        return root[0]

    def _base_attrib_getter(self, attr_name: str) -> str | None:
        value = self.__element.get(_get_lxml_tag(attr_name))
        if value is None:
            return None
        return str(value)

    def _base_attrib_setter(
        self,
        attr_name: str,
        value: str | int | float | bool | None,
    ) -> None:
        if value is None:
            with contextlib.suppress(KeyError):
                del self.__element.attrib[_get_lxml_tag(attr_name)]
            return
        if isinstance(value, bool):
            value = Boolean.encode(value)
        self.__element.set(_get_lxml_tag(attr_name), str(value))

    @staticmethod
    def _generic_attrib_getter(attr_name: str, family: str | None = None) -> Callable:
        def getter(self: Element) -> str | bool | None:
            try:
                if family and self.family != family:  # type: ignore
                    return None
            except AttributeError:
                return None
            value = self._base_attrib_getter(attr_name)
            if value is None:
                return None
            elif value in ("true", "false"):
                return Boolean.decode(value)
            return value

        return getter

    @staticmethod
    def _generic_attrib_setter(attr_name: str, family: str | None = None) -> Callable:
        def setter(self: Element, value: Any) -> None:
            try:
                if family and self.family != family:  # type: ignore
                    return None
            except AttributeError:
                return None
            self._base_attrib_setter(attr_name, value)

        return setter

    @classmethod
    def _define_attribut_property(cls: type[Element]) -> None:
        for prop in cls._properties:
            setattr(
                cls,
                prop.name,
                property(
                    cls._generic_attrib_getter(prop.attr, prop.family or None),
                    cls._generic_attrib_setter(prop.attr, prop.family or None),
                    None,
                    f"Get/set the attribute {prop.attr}",
                ),
            )

    @staticmethod
    def _make_before_regex(
        before: str | None,
        after: str | None,
    ) -> re.Pattern:
        # 1) before xor after is not None
        if before is not None:
            return re.compile(before)
        else:
            if after is None:
                raise ValueError("Both 'before' and 'after' are None")
            return re.compile(after)

    @staticmethod
    def _search_negative_position(
        xpath_result: list[str],
        regex: re.Pattern,
    ) -> tuple[str, re.Match]:
        # Found the last text that matches the regex
        for text in xpath_result:
            if regex.search(text) is not None:
                break
        else:
            raise ValueError(f"Text not found: {xpath_result!r}")
        return text, list(regex.finditer(text))[-1]

    @staticmethod
    def _search_positive_position(
        xpath_result: list[str],
        regex: re.Pattern,
        position: int,
    ) -> tuple[str, re.Match]:
        # Found the last text that matches the regex
        count = 0
        for text in xpath_result:
            found_nb = len(regex.findall(text))
            if found_nb + count >= position + 1:
                break
            count += found_nb
        else:
            raise ValueError(f"Text not found: {xpath_result!r}")
        return text, list(regex.finditer(text))[position - count]

    def _insert_before_after(
        self,
        current: _Element,
        element: _Element,
        before: str | None,
        after: str | None,
        position: int,
        xpath_text: XPath,
    ) -> tuple[int, str]:
        regex = self._make_before_regex(before, after)
        xpath_result = xpath_return_strings(xpath_text, current)
        # position = -1
        if position < 0:
            text, sre = self._search_negative_position(xpath_result, regex)
        # position >= 0
        else:
            text, sre = self._search_positive_position(xpath_result, regex, position)
        # Compute pos
        if before is None:
            pos = sre.end()
        else:
            pos = sre.start()
        return pos, text

    def _insert_find_text(
        self,
        current: _Element,
        element: _Element,
        before: str | None,
        after: str | None,
        position: int,
        xpath_text: XPath,
    ) -> tuple[int, str]:
        # Find the text
        xpath_result = xpath_return_strings(xpath_text, current)
        count = 0
        for text in xpath_result:
            found_nb = len(text)
            if found_nb + count >= position:
                break
            count += found_nb
        else:
            raise ValueError(f"Text not found: {xpath_result!r}")
        # We insert before the character
        pos = position - count
        return pos, text

    def _insert(
        self,
        element: Element,
        before: str | None = None,
        after: str | None = None,
        position: int = 0,
    ) -> None:
        """Insert an element before or after the characters in the text which
        match the regex before/after.

        When the regex matches more of one part of the text, position can be
        set to choice which part must be used. If before and after are None,
        we use only position that is the number of characters. If position is
        positive and before=after=None, we insert before the position
        character. But if position=-1, we insert after the last character.

        Annotation text content is ignored.


        Args:

        element -- Element

        before -- str regex

        after -- str regex

        position -- int
        """
        current = self.__element
        xelement = element.__element

        # 1) before xor after is not None
        if (before is not None) ^ (after is not None):
            pos, text = self._insert_before_after(
                current,
                xelement,
                before,
                after,
                position,
                _xpath_text_descendant_no_annotation,
            )
        # 2) before=after=None => only with position
        elif before is None and after is None:
            # Hack if position is negative => quickly
            if position < 0:
                current.append(xelement)
                return
            pos, text = self._insert_find_text(
                current,
                xelement,
                before,
                after,
                position,
                _xpath_text_descendant_no_annotation,
            )
        else:
            raise ValueError("bad combination of arguments")

        # Compute new texts
        text_before = text[:pos] if text[:pos] else None
        text_after = text[pos:] if text[pos:] else None

        # Insert!
        parent = text.getparent()  # type: ignore
        if text.is_text:  # type: ignore
            parent.text = text_before
            element.tail = text_after
            parent.insert(0, xelement)
        else:
            parent.addnext(xelement)
            parent.tail = text_before
            element.tail = text_after

    @property
    def tag(self) -> str:
        """Get/set the underlying xml tag with the given qualified name.

        Warning: direct change of tag does not change the element class.

        Args:

            qname -- str (e.g. "text:span")
        """
        return _get_prefixed_name(self.__element.tag)

    @tag.setter
    def tag(self, qname: str) -> None:
        self.__element.tag = _get_lxml_tag(qname)

    def elements_repeated_sequence(
        self,
        xpath_instance: XPath,
        name: str,
    ) -> list[tuple[int, int]]:
        """Utility method for table module."""
        lxml_tag = _get_lxml_tag_or_name(name)
        sub_elements = xpath_return_elements(xpath_instance, self.__element)
        result: list[tuple[int, int]] = []
        idx = -1
        for sub_element in sub_elements:
            idx += 1
            value = sub_element.get(lxml_tag)
            if value is None:
                result.append((idx, 1))
                continue
            try:
                int_value = int(value)
            except ValueError:  # pragma: nocover
                int_value = 1
            result.append((idx, max(int_value, 1)))
        return result

    def get_elements(self, xpath_query: XPath | str) -> list[Element]:
        """Returns the elements obtained from the XPath query applied to the
        current element.

        Return list of Element.
        """
        if isinstance(xpath_query, str):
            elements = xpath_return_elements(xpath_compile(xpath_query), self.__element)
        else:
            elements = xpath_return_elements(xpath_query, self.__element)
        return [Element.from_tag_for_clone(e, None) for e in elements]

    def get_element(self, xpath_query: str) -> Element | None:
        """Returns the first element obtained from the XPath query applied to
        the current element.

        Return an Element or None.
        """
        result = self.__element.xpath(f"({xpath_query})[1]", namespaces=ODF_NAMESPACES)
        if result:
            return Element.from_tag(result[0])
        return None

    def _get_element_idx(self, xpath_query: XPath | str, idx: int) -> Element | None:
        result = self.__element.xpath(
            f"({xpath_query})[{idx + 1}]", namespaces=ODF_NAMESPACES
        )
        if result:
            return Element.from_tag(result[0])
        return None

    def _get_element_idx2(self, xpath_instance: XPath, idx: int) -> Element | None:
        result = xpath_instance(self.__element, idx=idx + 1)
        if result:
            return Element.from_tag(result[0])
        return None

    @property
    def attributes(self) -> dict[str, str]:
        return {
            _get_prefixed_name(str(key)): str(value)
            for key, value in self.__element.attrib.items()
        }

    def get_attribute(self, name: str) -> str | bool | None:
        """Return the attribute value as type str | bool | None."""
        element = self.__element
        lxml_tag = _get_lxml_tag_or_name(name)
        value = element.get(lxml_tag)
        if value is None:
            return None
        elif value in ("true", "false"):
            return Boolean.decode(value)
        return str(value)

    def get_attribute_integer(self, name: str) -> int | None:
        """Return either the attribute as type int, or None."""
        element = self.__element
        lxml_tag = _get_lxml_tag_or_name(name)
        value = element.get(lxml_tag)
        if value is None:
            return None
        try:
            return int(value)
        except ValueError:
            return None

    def get_attribute_string(self, name: str) -> str | None:
        """Return either the attribute as type str, or None."""
        element = self.__element
        lxml_tag = _get_lxml_tag_or_name(name)
        value = element.get(lxml_tag)
        if value is None:
            return None
        return str(value)

    def _get_attribute_bool_default(self, name: str, default: bool = True) -> bool:
        """Return boolean attribute, with default value."""
        element = self.__element
        lxml_tag = _get_lxml_tag_or_name(name)
        value = element.get(lxml_tag)
        if value is None:
            return default
        return Boolean.decode(value)

    def _set_attribute_bool_default(
        self, name: str, value: bool | str | None, default: bool = True
    ) -> None:
        """Set boolean attribute, with default value."""
        element = self.__element
        lxml_tag = _get_lxml_tag_or_name(name)
        if value is None:
            value = False
        if isinstance(value, str):
            value = value.lower() == "true"
        if value == default:
            with contextlib.suppress(KeyError):
                del element.attrib[lxml_tag]
            return
        element.set(lxml_tag, Boolean.encode(value))

    def _get_attribute_str_default(self, name: str, default: str = "") -> str:
        """Return string attribute, with default value."""
        element = self.__element
        lxml_tag = _get_lxml_tag_or_name(name)
        value = element.get(lxml_tag)
        if value is None:
            return default
        return str(value)

    def _set_attribute_str_default(
        self, name: str, value: str | None, default: str = ""
    ) -> None:
        """Set string attribute, with default value."""
        element = self.__element
        lxml_tag = _get_lxml_tag_or_name(name)
        if value is None or value == default:
            with contextlib.suppress(KeyError):
                del element.attrib[lxml_tag]
            return
        element.set(lxml_tag, value)

    def set_attribute(
        self, name: str, value: bool | str | tuple[int, int, int] | None
    ) -> None:
        if name in ODF_COLOR_PROPERTY:
            if isinstance(value, bool):
                raise TypeError(f"Wrong color type {value!r}")
            if value != "transparent":
                value = hexa_color(value)
        element = self.__element
        lxml_tag = _get_lxml_tag_or_name(name)
        if isinstance(value, bool):
            value = Boolean.encode(value)
        elif value is None:
            with contextlib.suppress(KeyError):
                del element.attrib[lxml_tag]
            return
        element.set(lxml_tag, str(value))

    def set_style_attribute(self, name: str, value: Style | str | None) -> None:
        """Shortcut to accept a style object as a value."""
        if isinstance(value, Element):
            value = str(value.name)
        return self.set_attribute(name, value)

    def del_attribute(self, name: str) -> None:
        element = self.__element
        lxml_tag = _get_lxml_tag_or_name(name)
        del element.attrib[lxml_tag]

    @property
    def text(self) -> str:
        """Get / set the text content of the element."""
        return self.__element.text or ""

    @text.setter
    def text(self, text: str | None) -> None:
        if text is None:
            text = ""
        try:
            self.__element.text = text
        except TypeError as e:
            raise TypeError(f'Str type expected: "{type(text)}"') from e

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

    @property
    def _text_tail(self) -> str:
        return str(self) + (self.tail or "")

    # def _elements_descendants(self) -> Iterator[Element]:
    #     for elem in self.__element.iterdescendants():
    #         if isinstance(elem, _Element):
    #             yield Element.from_tag(elem)

    @property
    def inner_text(self) -> str:
        return self.text + "".join(e._text_tail for e in self.children)

    @property
    def text_recursive(self) -> str:
        return self.inner_text + (self.tail or "")

    @property
    def tail(self) -> str | None:
        """Get / set the text immediately following the element."""
        return self.__element.tail  # type: ignore[no-any-return]

    @tail.setter
    def tail(self, text: str | None) -> None:
        self.__element.tail = text or ""

    def search(self, pattern: str) -> int | None:
        """Return the first position of the pattern in the text content of the
        element, or None if not found.

        Python regular expression syntax applies.

        Args:

            pattern -- str

        Returns: int or None
        """
        match = re.search(pattern, self.text_recursive)
        if match is None:
            return None
        return match.start()

    def search_first(self, pattern: str) -> tuple[int, int] | None:
        """Return the start and end position of the first occurrence of the
        regex pattern in the text content of the element.

        Result is tuples of start and end position, or None.
        Python regular expression syntax applies.

        Args:

            pattern -- str

        Returns: tuple[int,int] or None
        """
        match = re.search(pattern, self.text_recursive)
        if match is None:
            return None
        return match.start(), match.end()

    def search_all(self, pattern: str) -> list[tuple[int, int]]:
        """Return all start and end positions of the regex pattern in the text
        content of the element.

        Result is a list of tuples of start and end position of
        the matches.
        Python regular expression syntax applies.

        Args:

            pattern -- str

        Returns: list[tuple[int,int]]
        """
        results: list[tuple[int, int]] = []
        for match in re.finditer(pattern, self.text_recursive):
            results.append((match.start(), match.end()))
        return results

    def text_at(self, start: int, end: int | None = None) -> str:
        """Return the text (recursive) content of the element between start and
        end position.

        If the end parameter is not set, return from start to the end
        of the recursive text.

        Args:

            start -- int
            end -- int or None

        Returns: str
        """
        if start < 0:
            start = 0
        if end is None:
            return self.text_recursive[start:]
        else:
            if end < start:
                end = start
            return self.text_recursive[start:end]

    def match(self, pattern: str) -> bool:
        """Return True if the pattern is found one or more times anywhere in
        the text content of the element.

        Python regular expression syntax applies.

        Args:

            pattern -- str

        Returns: bool
        """
        return self.search(pattern) is not None

    def replace(
        self,
        pattern: str,
        new: str | None = None,
        formatted: bool = False,
    ) -> int:
        """Replace the pattern with the given text, or delete if text is an
        empty string, and return the number of replacements. By default, only
        return the number of occurrences that would be replaced.

        It cannot replace patterns found across several element, like a word
        split into two consecutive spans.

        Python regular expression syntax applies.

        If formatted is True, and the target is a Paragraph, Span or Header,
        and the replacement text contains spaces, tabs or newlines, try to
        convert them into actual ODF elements to obtain a formatted result.
        On very complex contents, result may differ of expectations.

        Args:

            pattern -- str

            new -- str

            formatted -- bool

        Returns: int
        """
        if not isinstance(pattern, str):
            # Fail properly if the pattern is an non-ascii bytestring
            pattern = str(pattern)
        cpattern = re.compile(pattern)
        count = 0
        for text in self.xpath("descendant::text()"):
            if new is None:
                count += len(cpattern.findall(str(text)))
            else:
                new_text, number = cpattern.subn(new, str(text))
                container = text.parent
                if not container:  # pragma: nocover
                    continue
                if text.is_text():  # type: ignore
                    container.text = new_text
                else:
                    container.tail = new_text
                if formatted and container.tag in {  # type; ignore
                    "text:h",
                    "text:p",
                    "text:span",
                }:
                    container.append_plain_text("")  # type: ignore[attr-defined]
                count += number
        return count

    @property
    def root(self) -> Element:
        element = self.__element
        tree = element.getroottree()
        root = tree.getroot()
        return Element.from_tag(root)

    @property
    def parent(self) -> Element | None:
        element = self.__element
        parent = element.getparent()
        if parent is None:
            # Already at root
            return None
        return Element.from_tag(parent)

    @property
    def is_bound(self) -> bool:
        return self.parent is not None

    # def get_next_sibling(self):
    #     element = self.__element
    #     next_one = element.getnext()
    #     if next_one is None:
    #         return None
    #     return Element.from_tag(next_one)
    #
    # def get_prev_sibling(self):
    #     element = self.__element
    #     prev = element.getprevious()
    #     if prev is None:
    #         return None
    #     return Element.from_tag(prev)

    @property
    def children(self) -> list[Element]:
        element = self.__element
        return [
            Element.from_tag(e)
            for e in element.iterchildren()
            if isinstance(e, _Element)
        ]

    def index(self, child: Element) -> int:
        """Return the position of the child in this element.

        Inspired by lxml.
        """
        idx: int = self.__element.index(child.__element)
        return idx

    @property
    def text_content(self) -> str:
        """Get / set the text of the embedded paragraphs, including embeded
        annotations, cells...

        Set does create a paragraph if missing.
        """
        content = "".join(
            str(child) for child in self.get_elements("descendant::text:p")
        )
        if content.endswith("\n"):
            return content[:-1]
        return content

    @text_content.setter
    def text_content(self, text: str | Element | None) -> None:
        paragraphs = self.get_elements("text:p")
        if not paragraphs:
            # E.g., text:p in draw:text-box in draw:frame
            paragraphs = self.get_elements("*/text:p")
        if paragraphs:
            paragraph = paragraphs.pop(0)
            for obsolete in paragraphs:
                obsolete.delete()
        else:
            paragraph = Element.from_tag("text:p")
            self.insert(paragraph, FIRST_CHILD)
        # As "text_content" returned all text nodes, "text_content"
        # will overwrite all text nodes and children that may contain them
        element = paragraph.__element
        # Clear but the attributes
        del element[:]
        if text is None:
            text = ""
        element.text = str(text)

    def is_empty(self) -> bool:
        """Check if the element is empty : no text, no children, no tail.

        Returns: Boolean
        """
        element = self.__element
        if element.tail is not None:
            return False
        if element.text is not None:
            return False
        if list(element.iterchildren()):  # noqa: SIM103
            return False
        return True

    def insert(
        self,
        element: Element,
        xmlposition: int | None = None,
        position: int | None = None,
        start: bool = False,
    ) -> None:
        """Insert an element relatively to ourself.

        Insert either using DOM vocabulary or by numeric position.
        If "start" is True, insert the element before any existing text.

        Position start at 0.

        Args:

            element -- Element

            xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
                           or PREV_SIBLING

            start -- Boolean

            position -- int
        """
        # child_tag = element.tag
        current = self.__element
        lx_element = element.__element
        if start:
            text = current.text
            if text is not None:
                current.text = None
                tail = lx_element.tail
                if tail is None:
                    tail = text
                else:
                    tail = tail + text
                lx_element.tail = tail
            position = 0
        if position is not None:
            current.insert(position, lx_element)
        elif xmlposition is FIRST_CHILD:
            current.insert(0, lx_element)
        elif xmlposition is LAST_CHILD:
            current.append(lx_element)
        elif xmlposition is NEXT_SIBLING:
            parent = current.getparent()
            index = parent.index(current)
            parent.insert(index + 1, lx_element)
        elif xmlposition is PREV_SIBLING:
            parent = current.getparent()
            index = parent.index(current)
            parent.insert(index, lx_element)
        else:
            raise ValueError("(xml)position must be defined")

    def extend(self, odf_elements: Iterable[Element]) -> None:
        """Fast append elements at the end of ourself using extend."""
        if odf_elements:
            current = self.__element
            elements = [element.__element for element in odf_elements]
            current.extend(elements)

    def __append(self, str_or_element: str | Element) -> None:
        """Insert element or text in the last position."""

        def _add_text(text1: str | None, text2: str | None) -> str:
            return _re_anyspace.sub(" ", (text1 or "") + (text2 or ""))

        current = self.__element
        if isinstance(str_or_element, str):
            # Has children ?
            children = list(current.iterchildren())
            if children:
                # Append to tail of the last child
                last_child = children[-1]
                last_child.tail = _add_text(last_child.tail, str_or_element)
            else:
                # Append to text of the element
                current.text = _add_text(current.text, str_or_element)
        elif isinstance(str_or_element, Element):
            current.append(str_or_element.__element)
        else:
            raise TypeError(f'Element or string expected, not "{type(str_or_element)}"')

    append = __append

    def delete(self, child: Element | None = None, keep_tail: bool = True) -> None:
        """Delete the given element from the XML tree. If no element is given,
        "self" is deleted. The XML library may allow to continue to use an
        element now "orphan" as long as you have a reference to it.

        if keep_tail is True (default), the tail text is not erased.

        Args:

            child -- Element

            keep_tail -- boolean (default to True), True for most usages.
        """
        if child is None:
            parent = self.parent
            if parent is None:
                raise ValueError(f"Can't delete the root element\n{self.serialize()}")
            child = self
        else:
            parent = self
        if keep_tail and child.__element.tail is not None:
            current = child.__element
            tail = str(current.tail)
            current.tail = None
            prev = current.getprevious()
            if prev is not None:
                if prev.tail is None:
                    prev.tail = tail
                else:
                    prev.tail += tail
            else:
                if parent.__element.text is None:
                    parent.__element.text = tail
                else:
                    parent.__element.text += tail
        parent.__element.remove(child.__element)

    def replace_element(self, old_element: Element, new_element: Element) -> None:
        """Replaces in place a sub element with the element passed as second
        argument.

        Warning : no clone for old element.
        """
        current = self.__element
        current.replace(old_element.__element, new_element.__element)

    def xpath(self, xpath_query: str) -> list[Element | EText]:
        """Apply XPath query to the element and its subtree.

        Return list of Element or EText instances.
        """
        xpath_instance = xpath_compile(xpath_query)
        x_elements = xpath_instance(self.__element)
        result: list[Element | EText] = []
        if isinstance(x_elements, list):
            for obj in x_elements:
                if isinstance(obj, (str, bytes)):
                    result.append(EText(obj))
                elif isinstance(obj, _Element):  # pragma: nocover
                    result.append(Element.from_tag(obj))
        return result

    def clear(self) -> None:
        """Remove text, children and attributes from the element."""
        self.__element.clear()

    @property
    def clone(self) -> Element:
        clone = deepcopy(self.__element)
        root = lxml_Element("ROOT", nsmap=ODF_NAMESPACES)
        root.append(clone)
        return self.from_tag(clone)

        # slow data = tostring(self.__element, encoding='unicode')
        # return self.from_tag(data)

    @staticmethod
    def _strip_namespaces(data: str) -> str:
        """Remove xmlns:* fields from serialized XML."""
        return re.sub(r' xmlns:\w*="[\w:\-\/\.#]*"', "", data)

    def serialize(self, pretty: bool = False, with_ns: bool = False) -> str:
        """Return text serialization of XML element."""
        # This copy bypasses serialization side-effects in lxml
        native = deepcopy(self.__element)
        data: str = tostring(
            native, with_tail=False, pretty_print=pretty, encoding="unicode"
        )
        if with_ns:
            return data
        # Remove namespaces
        return self._strip_namespaces(data)

    # Element helpers usable from any context

    @property
    def document_body(self) -> Body | None:
        """Return the first children of document body if any: 'office:body/*[1]'"""
        return self.get_element("//office:body/*[1]")  # type: ignore[return-value]

    def get_formatted_text(self, context: dict | None = None) -> str:
        """This function should return a beautiful version of the text."""
        return ""

    def get_styled_elements(self, name: str = "") -> list[Element]:
        """Brute-force to find paragraphs, tables, etc. using the given style
        name (or all by default).

        Args:

            name -- str

        Returns: list of Element
        """
        # FIXME incomplete (and possibly inaccurate)
        return (
            self._filtered_elements("descendant::*", text_style=name)
            + self._filtered_elements("descendant::*", draw_style=name)
            + self._filtered_elements("descendant::*", draw_text_style=name)
            + self._filtered_elements("descendant::*", table_style=name)
            + self._filtered_elements("descendant::*", page_layout=name)
            + self._filtered_elements("descendant::*", master_page=name)
            + self._filtered_elements("descendant::*", parent_style=name)
        )

    # Common attributes

    def _get_inner_text(self, tag: str) -> str | None:
        element = self.get_element(tag)
        if element is None:
            return None
        return element.text

    def _set_inner_text(self, tag: str, text: str) -> None:
        element = self.get_element(tag)
        if element is None:
            element = Element.from_tag(tag)
            self.__append(element)
        element.text = text

    # SVG

    @property
    def svg_title(self) -> str | None:
        return self._get_inner_text("svg:title")

    @svg_title.setter
    def svg_title(self, title: str) -> None:
        self._set_inner_text("svg:title", title)

    @property
    def svg_description(self) -> str | None:
        return self._get_inner_text("svg:desc")

    @svg_description.setter
    def svg_description(self, description: str) -> None:
        self._set_inner_text("svg:desc", description)

    # Sections

    def get_sections(
        self,
        style: str | None = None,
        content: str | None = None,
    ) -> list[Section]:
        """Return all the sections that match the criteria.

        Args:

            style -- str

            content -- str regex

        Returns: list of Section
        """
        return self._filtered_elements(
            "text:section", text_style=style, content=content
        )  # type: ignore[return-value]

    @property
    def sections(
        self,
    ) -> list[Section]:
        """Return all the sections.

        Returns: list of Section
        """
        return self.get_elements("text:section")  # type: ignore[return-value]

    def get_section(
        self,
        position: int = 0,
        content: str | None = None,
    ) -> Section | None:
        """Return the section that matches the criteria.

        Args:

            position -- int

            content -- str regex

        Returns: Section or None if not found
        """
        return self._filtered_element(
            "descendant::text:section", position, content=content
        )  # type: ignore[return-value]

    # Paragraphs

    def get_paragraphs(
        self,
        style: str | None = None,
        content: str | None = None,
    ) -> list[Paragraph]:
        """Return all the paragraphs that match the criteria.

        Args:

            style -- str

            content -- str regex

        Returns: list of Paragraph
        """
        return self._filtered_elements(
            "descendant::text:p", text_style=style, content=content
        )  # type: ignore[return-value]

    @property
    def paragraphs(self) -> list[Paragraph]:
        """Return all the paragraphs.

        Returns: list of Paragraph
        """
        return self.get_elements(
            "descendant::text:p",
        )  # type: ignore[return-value]

    def get_paragraph(
        self,
        position: int = 0,
        content: str | None = None,
    ) -> Paragraph | None:
        """Return the paragraph that matches the criteria.

        Args:

            position -- int

            content -- str regex

        Returns: Paragraph or None if not found
        """
        return self._filtered_element(
            "descendant::text:p",
            position,
            content=content,
        )  # type: ignore[return-value]

    # Span

    def get_spans(
        self,
        style: str | None = None,
        content: str | None = None,
    ) -> list[Span]:
        """Return all the spans that match the criteria.

        Args:

            style -- str

            content -- str regex

        Returns: list of Span
        """
        return self._filtered_elements(
            "descendant::text:span", text_style=style, content=content
        )  # type: ignore[return-value]

    @property
    def spans(self) -> list[Span]:
        """Return all the spans.

        Returns: list of Span
        """
        return self.get_elements("descendant::text:span")  # type: ignore[return-value]

    def get_span(
        self,
        position: int = 0,
        content: str | None = None,
    ) -> Span | None:
        """Return the span that matches the criteria.

        Args:

            position -- int

            content -- str regex

        Returns: Span or None if not found
        """
        return self._filtered_element(
            "descendant::text:span", position, content=content
        )  # type: ignore[return-value]

    # Headers

    def get_headers(
        self,
        style: str | None = None,
        outline_level: str | None = None,
        content: str | None = None,
    ) -> list[Header]:
        """Return all the Headers that match the criteria.

        Args:

            style -- str

            content -- str regex

        Returns: list of Header
        """
        return self._filtered_elements(
            "descendant::text:h",
            text_style=style,
            outline_level=outline_level,
            content=content,
        )  # type: ignore[return-value]

    @property
    def headers(self) -> list[Header]:
        """Return all the Headers.

        Returns: list of Header
        """
        return self.get_elements("descendant::text:h")  # type: ignore[return-value]

    def get_header(
        self,
        position: int = 0,
        outline_level: str | None = None,
        content: str | None = None,
    ) -> Header | None:
        """Return the Header that matches the criteria.

        Args:

            position -- int

            content -- str regex

        Returns: Header or None if not found
        """
        return self._filtered_element(
            "descendant::text:h",
            position,
            outline_level=outline_level,
            content=content,
        )  # type: ignore[return-value]

    # Lists

    def get_lists(
        self,
        style: str | None = None,
        content: str | None = None,
    ) -> list[List]:
        """Return all the lists that match the criteria.

        Args:

            style -- str

            content -- str regex

        Returns: list of List
        """
        return self._filtered_elements(
            "descendant::text:list", text_style=style, content=content
        )  # type: ignore[return-value]

    @property
    def lists(self) -> list[List]:
        """Return all the lists.

        Returns: list of List
        """
        return self.get_elements("descendant::text:list")  # type: ignore[return-value]

    def get_list(
        self,
        position: int = 0,
        content: str | None = None,
    ) -> List | None:
        """Return the list that matches the criteria.

        Args:

            position -- int

            content -- str regex

        Returns: List or None if not found
        """
        return self._filtered_element(
            "descendant::text:list", position, content=content
        )  # type: ignore[return-value]

    # Frames

    def get_frames(
        self,
        presentation_class: str | None = None,
        style: str | None = None,
        title: str | None = None,
        description: str | None = None,
        content: str | None = None,
    ) -> list[Frame]:
        """Return all the frames that match the criteria.

        Args:

            presentation_class -- str

            style -- str

            title -- str regex

            description -- str regex

            content -- str regex

        Returns: list of Frame
        """
        return self._filtered_elements(
            "descendant::draw:frame",
            presentation_class=presentation_class,
            draw_style=style,
            svg_title=title,
            svg_desc=description,
            content=content,
        )  # type: ignore[return-value]

    @property
    def frames(self) -> list[Frame]:
        """Return all the frames.

        Returns: list of Frame
        """
        return self.get_elements("descendant::draw:frame")  # type: ignore[return-value]

    def get_frame(
        self,
        position: int = 0,
        name: str | None = None,
        presentation_class: str | None = None,
        title: str | None = None,
        description: str | None = None,
        content: str | None = None,
    ) -> Frame | None:
        """Return the section that matches the criteria.

        Args:

            position -- int

            name -- str

            presentation_class -- str

            title -- str regex

            description -- str regex

            content -- str regex

        Returns: Frame or None if not found
        """
        return self._filtered_element(
            "descendant::draw:frame",
            position,
            draw_name=name,
            presentation_class=presentation_class,
            svg_title=title,
            svg_desc=description,
            content=content,
        )  # type: ignore[return-value]

    # Images

    def get_images(
        self,
        style: str | None = None,
        url: str | None = None,
        content: str | None = None,
    ) -> list[DrawImage]:
        """Return all the images matching the criteria.

        Args:

            style -- str

            url -- str regex

            content -- str regex

        Returns: list of DrawImage
        """
        return self._filtered_elements(
            "descendant::draw:image", text_style=style, url=url, content=content
        )  # type: ignore[return-value]

    @property
    def images(self) -> list[DrawImage]:
        """Return all the images.

        Returns: list of DrawImage
        """
        return self.get_elements("descendant::draw:image")  # type: ignore[return-value]

    def get_image(
        self,
        position: int = 0,
        name: str | None = None,
        url: str | None = None,
        content: str | None = None,
    ) -> DrawImage | None:
        """Return the image matching the criteria.

        Args:

            position -- int

            name -- str

            url -- str regex

            content -- str regex

        Returns: DrawImage or None if not found
        """
        # The frame is holding the name
        if name is not None:
            frame = self._filtered_element(
                "descendant::draw:frame", position, draw_name=name
            )
            if frame is None:
                return None
            # The name is supposedly unique
            return frame.get_element("draw:image")  # type: ignore[return-value]
        return self._filtered_element(
            "descendant::draw:image", position, url=url, content=content
        )  # type: ignore[return-value]

    # Named Range

    # Notes

    def get_notes(
        self,
        note_class: str | None = None,
        content: str | None = None,
    ) -> list[Note]:
        """Return all the notes that match the criteria.

        Args:

            note_class -- 'footnote' or 'endnote'

            content -- str regex

        Returns: list of Note
        """
        return self._filtered_elements(
            "descendant::text:note", note_class=note_class, content=content
        )  # type: ignore[return-value]

    def get_note(
        self,
        position: int = 0,
        note_id: str | None = None,
        note_class: str | None = None,
        content: str | None = None,
    ) -> Note | None:
        """Return the note that matches the criteria.

        Args:

            position -- int

            note_id -- str

            note_class -- 'footnote' or 'endnote'

            content -- str regex

        Returns: Note or None if not found
        """
        return self._filtered_element(
            "descendant::text:note",
            position,
            text_id=note_id,
            note_class=note_class,
            content=content,
        )  # type: ignore[return-value]

    # Annotations

    def get_annotations(
        self,
        creator: str | None = None,
        start_date: datetime | None = None,
        end_date: datetime | None = None,
        content: str | None = None,
    ) -> list[Annotation]:
        """Return all the annotations that match the criteria.

        Args:

            creator -- str

            start_date -- datetime instance

            end_date --  datetime instance

            content -- str regex

        Returns: list of Annotation
        """
        annotations: list[Annotation] = []
        for annotation in self._filtered_elements(
            "descendant::office:annotation", content=content
        ):
            if creator is not None and creator != annotation.dc_creator:  # type: ignore[attr-defined]
                continue
            date = annotation.date  # type: ignore[attr-defined]
            # date never None: recreated if missing
            if date is None:  # pragma: no cover
                continue
            if start_date is not None and date < start_date:
                continue
            if end_date is not None and date >= end_date:
                continue
            annotations.append(annotation)  # type: ignore[arg-type]
        return annotations

    def get_annotation(
        self,
        position: int = 0,
        creator: str | None = None,
        start_date: datetime | None = None,
        end_date: datetime | None = None,
        content: str | None = None,
        name: str | None = None,
    ) -> Annotation | None:
        """Return the annotation that matches the criteria.

        Args:

            position -- int

            creator -- str

            start_date -- datetime instance

            end_date -- datetime instance

            content -- str regex

            name -- str

        Returns: Annotation or None if not found
        """
        if name is not None:
            return self._filtered_element(
                "descendant::office:annotation", 0, office_name=name
            )  # type: ignore[return-value]
        annotations: list[Annotation] = self.get_annotations(
            creator=creator, start_date=start_date, end_date=end_date, content=content
        )
        if not annotations:
            return None
        try:
            return annotations[position]
        except IndexError:
            return None

    def get_annotation_ends(self) -> list[AnnotationEnd]:
        """Return all the annotation ends.

        Returns: list of AnnotationEnd
        """
        return self._filtered_elements(
            "descendant::office:annotation-end",
        )  # type: ignore[return-value]

    def get_annotation_end(
        self,
        position: int = 0,
        name: str | None = None,
    ) -> AnnotationEnd | None:
        """Return the annotation end that matches the criteria.

        Args:

            position -- int

            name -- str

        Returns: AnnotationEnd or None if not found
        """
        return self._filtered_element(
            "descendant::office:annotation-end", position, office_name=name
        )  # type: ignore[return-value]

    # office:names

    def get_office_names(self) -> list[str]:
        """Return all the used office:name tags values of the element.

        Returns: list of unique str
        """
        name_xpath_query = xpath_compile("//@office:name")
        strings = xpath_return_strings(name_xpath_query, self.__element)
        return list({name for name in strings if name})

    # Variables

    def get_variable_decls(self) -> VarDecls:
        """Return the container for variable declarations. Created if not
        found.

        Returns: VarDecls
        """
        variable_decls = self.get_element("//text:variable-decls")
        if variable_decls is None:
            body = self.document_body
            if not body:
                raise ValueError("Empty document.body")
            body.insert(Element.from_tag("text:variable-decls"), FIRST_CHILD)
            variable_decls = body.get_element("//text:variable-decls")

        return variable_decls  # type: ignore[return-value]

    def get_variable_decl_list(self) -> list[VarDecls]:
        """Return all the variable declarations.

        Returns: list of VarDecls
        """
        return self._filtered_elements(
            "descendant::text:variable-decl",
        )  # type: ignore[return-value]

    def get_variable_decl(self, name: str, position: int = 0) -> VarDecls | None:
        """Return the variable declaration for the given name.

        Args:

            name -- str

            position -- int

        Returns: VarDecls or none if not found
        """
        return self._filtered_element(
            "descendant::text:variable-decl", position, text_name=name
        )  # type: ignore[return-value]

    def get_variable_sets(self, name: str | None = None) -> list[VarSet]:
        """Return all the variable sets that match the criteria.

        Args:

            name -- str

        Returns: list of VarSet
        """
        return self._filtered_elements(
            "descendant::text:variable-set",
            text_name=name,
        )  # type: ignore[return-value]

    def get_variable_set(self, name: str, position: int = -1) -> VarSet | None:
        """Return the variable set for the given name (last one by default).

        Args:

            name -- str

            position -- int

        Returns: VarSet or None if not found
        """
        return self._filtered_element(
            "descendant::text:variable-set", position, text_name=name
        )  # type: ignore[return-value]

    def get_variable_set_value(
        self,
        name: str,
        value_type: str | None = None,
    ) -> bool | str | int | float | Decimal | datetime | timedelta | None:
        """Return the last value of the given variable name.

        Args:

            name -- str

            value_type -- 'boolean', 'currency', 'date', 'float',
                          'percentage', 'string', 'time' or automatic

        Returns: most appropriate Python type
        """
        variable_set = self.get_variable_set(name)
        if not variable_set:
            return None
        return variable_set.get_value(value_type)  # type: ignore[return-value]

    # User fields

    def get_user_field_decls(self) -> UserFieldDecls | None:
        """Return the container for user field declarations. Created if not
        found.

        Returns: UserFieldDecls
        """
        user_field_decls = self.get_element("//text:user-field-decls")
        if user_field_decls is None:
            body = self.document_body
            if not body:
                raise ValueError("Empty document.body")
            body.insert(Element.from_tag("text:user-field-decls"), FIRST_CHILD)
            user_field_decls = body.get_element("//text:user-field-decls")

        return user_field_decls  # type: ignore[return-value]

    def get_user_field_decl_list(self) -> list[UserFieldDecl]:
        """Return all the user field declarations.

        Returns: list of UserFieldDecl
        """
        return self._filtered_elements(
            "descendant::text:user-field-decl",
        )  # type: ignore[return-value]

    def get_user_field_decl(self, name: str, position: int = 0) -> UserFieldDecl | None:
        """Return the user field declaration for the given name.

        Returns: UserFieldDecl or none if not found
        """
        return self._filtered_element(
            "descendant::text:user-field-decl", position, text_name=name
        )  # type: ignore[return-value]

    def get_user_field_value(
        self, name: str, value_type: str | None = None
    ) -> bool | str | int | float | Decimal | datetime | timedelta | None:
        """Return the value of the given user field name.

        Args:

            name -- str

            value_type -- 'boolean', 'currency', 'date', 'float',
                          'percentage', 'string', 'time' or automatic

        Returns: most appropriate Python type
        """
        user_field_decl = self.get_user_field_decl(name)
        if user_field_decl is None:
            return None
        value = user_field_decl.get_value(value_type)
        return value  # type: ignore[return-value]

    # User defined fields
    # They are fields who should contain a copy of a user defined medtadata

    def get_user_defined_list(self) -> list[UserDefined]:
        """Return all the user defined field declarations.

        Returns: list of UserDefined
        """
        return self._filtered_elements(
            "descendant::text:user-defined",
        )  # type: ignore[return-value]

    @property
    def user_defined_list(self) -> list[UserDefined]:
        """Return all the user defined field declarations.

        Returns: list of UserDefined
        """
        return self.get_user_defined_list()

    def get_user_defined(self, name: str, position: int = 0) -> UserDefined | None:
        """Return the user defined declaration for the given name.

        Returns: UserDefined or none if not found
        """
        return self._filtered_element(
            "descendant::text:user-defined", position, text_name=name
        )  # type: ignore[return-value]

    def get_user_defined_value(
        self, name: str, value_type: str | None = None
    ) -> bool | str | int | float | Decimal | datetime | timedelta | None:
        """Return the value of the given user defined field name.

        Args:

            name -- str

            value_type -- 'boolean', 'date', 'float',
                          'string', 'time' or automatic

        Returns: most appropriate Python type
        """
        user_defined = self.get_user_defined(name)
        if user_defined is None:
            return None
        return user_defined.get_value(value_type)  # type: ignore[return-value]

    # Draw Pages

    def get_draw_pages(
        self,
        style: str | None = None,
        content: str | None = None,
    ) -> list[DrawPage]:
        """Return all the draw pages that match the criteria.

        Args:

            style -- str

            content -- str regex

        Returns: list of DrawPage
        """
        return self._filtered_elements(
            "descendant::draw:page", draw_style=style, content=content
        )  # type: ignore[return-value]

    def get_draw_page(
        self,
        position: int = 0,
        name: str | None = None,
        content: str | None = None,
    ) -> DrawPage | None:
        """Return the draw page that matches the criteria.

        Args:

            position -- int

            name -- str

            content -- str regex

        Returns: DrawPage or None if not found
        """
        return self._filtered_element(
            "descendant::draw:page", position, draw_name=name, content=content
        )  # type: ignore[return-value]

    # Links

    def get_links(
        self,
        name: str | None = None,
        title: str | None = None,
        url: str | None = None,
        content: str | None = None,
    ) -> list[Link]:
        """Return all the links that match the criteria.

        Args:

            name -- str

            title -- str

            url -- str regex

            content -- str regex

        Returns: list of Link
        """
        return self._filtered_elements(
            "descendant::text:a",
            office_name=name,
            office_title=title,
            url=url,
            content=content,
        )  # type: ignore[return-value]

    def get_link(
        self,
        position: int = 0,
        name: str | None = None,
        title: str | None = None,
        url: str | None = None,
        content: str | None = None,
    ) -> Link | None:
        """Return the link that matches the criteria.

        Args:

            position -- int

            name -- str

            title -- str

            url -- str regex

            content -- str regex

        Returns: Link or None if not found
        """
        return self._filtered_element(
            "descendant::text:a",
            position,
            office_name=name,
            office_title=title,
            url=url,
            content=content,
        )  # type: ignore[return-value]

    # Bookmarks

    def get_bookmarks(self) -> list[Bookmark]:
        """Return all the bookmarks.

        Returns: list of Bookmark
        """
        return self._filtered_elements(
            "descendant::text:bookmark",
        )  # type: ignore[return-value]

    def get_bookmark(
        self,
        position: int = 0,
        name: str | None = None,
    ) -> Bookmark | None:
        """Return the bookmark that matches the criteria.

        Args:

            position -- int

            name -- str

        Returns: Bookmark or None if not found
        """
        return self._filtered_element(
            "descendant::text:bookmark", position, text_name=name
        )  # type: ignore[return-value]

    def get_bookmark_starts(self) -> list[BookmarkStart]:
        """Return all the bookmark starts.

        Returns: list of BookmarkStart
        """
        return self._filtered_elements(
            "descendant::text:bookmark-start",
        )  # type: ignore[return-value]

    def get_bookmark_start(
        self,
        position: int = 0,
        name: str | None = None,
    ) -> BookmarkStart | None:
        """Return the bookmark start that matches the criteria.

        Args:

            position -- int

            name -- str

        Returns: BookmarkStart or None if not found
        """
        return self._filtered_element(
            "descendant::text:bookmark-start", position, text_name=name
        )  # type: ignore[return-value]

    def get_bookmark_ends(self) -> list[BookmarkEnd]:
        """Return all the bookmark ends.

        Returns: list of BookmarkEnd
        """
        return self._filtered_elements(
            "descendant::text:bookmark-end",
        )  # type: ignore[return-value]

    def get_bookmark_end(
        self,
        position: int = 0,
        name: str | None = None,
    ) -> BookmarkEnd | None:
        """Return the bookmark end that matches the criteria.

        Args:

            position -- int

            name -- str

        Returns: BookmarkEnd or None if not found
        """
        return self._filtered_element(
            "descendant::text:bookmark-end", position, text_name=name
        )  # type: ignore[return-value]

    # Reference marks

    def get_reference_marks_single(self) -> list[ReferenceMark]:
        """Return all the reference marks. Search only the tags
        text:reference-mark.
        Consider using : get_reference_marks()

        Returns: list of ReferenceMark
        """
        return self._filtered_elements(
            "descendant::text:reference-mark",
        )  # type: ignore[return-value]

    def get_reference_mark_single(
        self,
        position: int = 0,
        name: str | None = None,
    ) -> ReferenceMark | None:
        """Return the reference mark that matches the criteria. Search only the
        tags text:reference-mark.
        Consider using : get_reference_mark()

        Args:

            position -- int

            name -- str

        Returns: ReferenceMark or None if not found
        """
        return self._filtered_element(
            "descendant::text:reference-mark", position, text_name=name
        )  # type: ignore[return-value]

    def get_reference_mark_starts(self) -> list[ReferenceMarkStart]:
        """Return all the reference mark starts. Search only the tags
        text:reference-mark-start.
        Consider using : get_reference_marks()

        Returns: list of ReferenceMarkStart
        """
        return self._filtered_elements(
            "descendant::text:reference-mark-start",
        )  # type: ignore[return-value]

    def get_reference_mark_start(
        self,
        position: int = 0,
        name: str | None = None,
    ) -> ReferenceMarkStart | None:
        """Return the reference mark start that matches the criteria. Search
        only the tags text:reference-mark-start.
        Consider using : get_reference_mark()

        Args:

            position -- int

            name -- str

        Returns: ReferenceMarkStart or None if not found
        """
        return self._filtered_element(
            "descendant::text:reference-mark-start", position, text_name=name
        )  # type: ignore[return-value]

    def get_reference_mark_ends(self) -> list[ReferenceMarkEnd]:
        """Return all the reference mark ends. Search only the tags
        text:reference-mark-end.
        Consider using : get_reference_marks()

        Returns: list of ReferenceMarkEnd
        """
        return self._filtered_elements(
            "descendant::text:reference-mark-end",
        )  # type: ignore[return-value]

    def get_reference_mark_end(
        self,
        position: int = 0,
        name: str | None = None,
    ) -> ReferenceMarkEnd | None:
        """Return the reference mark end that matches the criteria. Search only
        the tags text:reference-mark-end.
        Consider using : get_reference_marks()

        Args:

            position -- int

            name -- str

        Returns: ReferenceMarkEnd or None if not found
        """
        return self._filtered_element(
            "descendant::text:reference-mark-end", position, text_name=name
        )  # type: ignore[return-value]

    def get_reference_marks(self) -> list[ReferenceMark | ReferenceMarkStart]:
        """Return all the reference marks, either single position reference
        (text:reference-mark) or start of range reference (text:reference-mark-
        start).

        Returns: list of ReferenceMark or ReferenceMarkStart
        """
        return self._filtered_elements(
            "descendant::text:reference-mark-start | descendant::text:reference-mark"
        )  # type: ignore[return-value]

    def get_reference_mark(
        self,
        position: int = 0,
        name: str | None = None,
    ) -> ReferenceMark | ReferenceMarkStart | None:
        """Return the reference mark that match the criteria. Either single
        position reference mark (text:reference-mark) or start of range
        reference (text:reference-mark-start).

        Args:

            position -- int

            name -- str

        Returns: ReferenceMark or ReferenceMarkStart or None if not found
        """
        if name:
            request = (
                f"descendant::text:reference-mark-start"
                f'[@text:name="{name}"] '
                f"| descendant::text:reference-mark"
                f'[@text:name="{name}"]'
            )
            return self._filtered_element(
                request,
                position=0,
            )  # type: ignore[return-value]
        request = (
            "descendant::text:reference-mark-start | descendant::text:reference-mark"
        )
        return self._filtered_element(request, position)  # type: ignore[return-value]

    def get_references(self, name: str | None = None) -> list[Reference]:
        """Return all the references (text:reference-ref). If name is provided,
        returns the references of that name.

        Args:

            name -- str or None

        Returns: list of Reference
        """
        if name is None:
            return self._filtered_elements(
                "descendant::text:reference-ref",
            )  # type: ignore[return-value]
        request = f'descendant::text:reference-ref[@text:ref-name="{name}"]'
        return self._filtered_elements(request)  # type: ignore[return-value]

    # Shapes elements

    # Groups

    def get_draw_groups(
        self,
        title: str | None = None,
        description: str | None = None,
        content: str | None = None,
    ) -> list[DrawGroup]:
        """Return all the draw groups that match the criteria.

        Args:

            title -- str or None

            description -- str regex or None

            content -- str regex or None

        Returns: list of DrawGroup
        """
        return self._filtered_elements(
            "descendant::draw:g",
            svg_title=title,
            svg_desc=description,
            content=content,
        )  # type: ignore[return-value]

    def get_draw_group(
        self,
        position: int = 0,
        name: str | None = None,
        title: str | None = None,
        description: str | None = None,
        content: str | None = None,
    ) -> DrawGroup | None:
        """Return the  draw group that matches the criteria.

        Args:

            position -- int

            name  -- str or None

            title -- str or None

            description -- str regex or None

            content -- str regex or None

        Returns: DrawGroup or None if not found
        """
        return self._filtered_element(
            "descendant::draw:g",
            position,
            draw_name=name,
            svg_title=title,
            svg_desc=description,
            content=content,
        )  # type: ignore[return-value]

    # Lines

    def get_draw_lines(
        self,
        draw_style: str | None = None,
        draw_text_style: str | None = None,
        content: str | None = None,
    ) -> list[LineShape]:
        """Return all the draw lines that match the criteria.

        Args:

            draw_style -- str

            draw_text_style -- str

            content -- str regex

        Returns: list of LineShape
        """
        return self._filtered_elements(
            "descendant::draw:line",
            draw_style=draw_style,
            draw_text_style=draw_text_style,
            content=content,
        )  # type: ignore[return-value]

    def get_draw_line(
        self,
        position: int = 0,
        id: str | None = None,  # noqa:A002
        content: str | None = None,
    ) -> LineShape | None:
        """Return the draw line that matches the criteria.

        Args:

            position -- int

            id -- str

            content -- str regex

        Returns: LineShape or None if not found
        """
        return self._filtered_element(
            "descendant::draw:line", position, draw_id=id, content=content
        )  # type: ignore[return-value]

    # Rectangles

    def get_draw_rectangles(
        self,
        draw_style: str | None = None,
        draw_text_style: str | None = None,
        content: str | None = None,
    ) -> list[RectangleShape]:
        """Return all the draw rectangles that match the criteria.

        Args:

            draw_style -- str

            draw_text_style -- str

            content -- str regex

        Returns: list of RectangleShape
        """
        return self._filtered_elements(
            "descendant::draw:rect",
            draw_style=draw_style,
            draw_text_style=draw_text_style,
            content=content,
        )  # type: ignore[return-value]

    def get_draw_rectangle(
        self,
        position: int = 0,
        id: str | None = None,  # noqa:A002
        content: str | None = None,
    ) -> RectangleShape | None:
        """Return the draw rectangle that matches the criteria.

        Args:

            position -- int

            id -- str

            content -- str regex

        Returns: RectangleShape or None if not found
        """
        return self._filtered_element(
            "descendant::draw:rect", position, draw_id=id, content=content
        )  # type: ignore[return-value]

    # Ellipse

    def get_draw_ellipses(
        self,
        draw_style: str | None = None,
        draw_text_style: str | None = None,
        content: str | None = None,
    ) -> list[EllipseShape]:
        """Return all the draw ellipses that match the criteria.

        Args:

            draw_style -- str

            draw_text_style -- str

            content -- str regex

        Returns: list of EllipseShape
        """
        return self._filtered_elements(
            "descendant::draw:ellipse",
            draw_style=draw_style,
            draw_text_style=draw_text_style,
            content=content,
        )  # type: ignore[return-value]

    def get_draw_ellipse(
        self,
        position: int = 0,
        id: str | None = None,  # noqa:A002
        content: str | None = None,
    ) -> EllipseShape | None:
        """Return the draw ellipse that matches the criteria.

        Args:

            position -- int

            id -- str

            content -- str regex

        Returns: EllipseShape or None if not found
        """
        return self._filtered_element(
            "descendant::draw:ellipse", position, draw_id=id, content=content
        )  # type: ignore[return-value]

    # Connectors

    def get_draw_connectors(
        self,
        draw_style: str | None = None,
        draw_text_style: str | None = None,
        content: str | None = None,
    ) -> list[ConnectorShape]:
        """Return all the draw connectors that match the criteria.

        Args:

            draw_style -- str

            draw_text_style -- str

            content -- str regex

        Returns: list of ConnectorShape
        """
        return self._filtered_elements(
            "descendant::draw:connector",
            draw_style=draw_style,
            draw_text_style=draw_text_style,
            content=content,
        )  # type: ignore[return-value]

    def get_draw_connector(
        self,
        position: int = 0,
        id: str | None = None,  # noqa:A002
        content: str | None = None,
    ) -> ConnectorShape | None:
        """Return the draw connector that matches the criteria.

        Args:

            position -- int

            id -- str

            content -- str regex

        Returns: ConnectorShape or None if not found
        """
        return self._filtered_element(
            "descendant::draw:connector", position, draw_id=id, content=content
        )  # type: ignore[return-value]

    def get_orphan_draw_connectors(self) -> list[ConnectorShape]:
        """Return a list of connectors which don't have any shape connected to
        them.

        Returns: list of ConnectorShape
        """
        connectors = []
        for connector in self.get_draw_connectors():
            start_shape = connector.get_attribute("draw:start-shape")
            end_shape = connector.get_attribute("draw:end-shape")
            if start_shape is None and end_shape is None:
                connectors.append(connector)
        return connectors

    # Tracked changes and text change

    def get_tracked_changes(self) -> TrackedChanges | None:
        """Return the tracked-changes part in the text body.

        Returns: TrackedChanges or None
        """
        return self.get_element("//text:tracked-changes")  # type: ignore[return-value]

    @property
    def tracked_changes(self) -> Element | None:
        """Return the tracked-changes part in the text body.

        Returns: Element or None
        """
        return self.get_tracked_changes()

    def get_changes_ids(self) -> list[Element | EText]:
        """Return a list of ids that refers to a change region in the tracked
        changes list.
        """
        # Insertion changes or deletion changes
        xpath_query = (
            "descendant::text:change-start/@text:change-id "
            "| descendant::text:change/@text:change-id"
        )
        return self.xpath(xpath_query)

    def get_text_change_deletions(self) -> list[TextChange]:
        """Return all the text changes of deletion kind: the tags text:change.
        Consider using : get_text_changes()

        Returns: list of TextChange
        """
        return self._filtered_elements(
            "descendant::text:text:change",
        )  # type: ignore[return-value]

    def get_text_change_deletion(
        self,
        position: int = 0,
        idx: str | None = None,
    ) -> TextChange | None:
        """Return the text change of deletion kind that matches the criteria.
        Search only for the tags text:change.
        Consider using : get_text_change()

        Args:

            position -- int

            idx -- str

        Returns: TextChange or None if not found
        """
        return self._filtered_element(
            "descendant::text:change", position, change_id=idx
        )  # type: ignore[return-value]

    def get_text_change_starts(self) -> list[TextChangeStart]:
        """Return all the text change-start. Search only for the tags
        text:change-start.
        Consider using : get_text_changes()

        Returns: list of TextChangeStart
        """
        return self._filtered_elements(
            "descendant::text:change-start",
        )  # type: ignore[return-value]

    def get_text_change_start(
        self,
        position: int = 0,
        idx: str | None = None,
    ) -> TextChangeStart | None:
        """Return the text change-start that matches the criteria. Search
        only the tags text:change-start.
        Consider using : get_text_change()

        Args:

            position -- int

            idx -- str

        Returns: TextChangeStart or None if not found
        """
        return self._filtered_element(
            "descendant::text:change-start", position, change_id=idx
        )  # type: ignore[return-value]

    def get_text_change_ends(self) -> list[TextChangeEnd]:
        """Return all the text change-end. Search only the tags
        text:change-end.
        Consider using : get_text_changes()

        Returns: list of TextChangeEnd
        """
        return self._filtered_elements(
            "descendant::text:change-end",
        )  # type: ignore[return-value]

    def get_text_change_end(
        self,
        position: int = 0,
        idx: str | None = None,
    ) -> TextChangeEnd | None:
        """Return the text change-end that matches the criteria. Search only
        the tags text:change-end.
        Consider using : get_text_change()

        Args:

            position -- int

            idx -- str

        Returns: TextChangeEnd or None if not found
        """
        return self._filtered_element(
            "descendant::text:change-end", position, change_id=idx
        )  # type: ignore[return-value]

    def get_text_changes(self) -> list[TextChange | TextChangeStart]:
        """Return all the text changes, either single deletion (text:change) or
        start of range of changes (text:change-start).

        Returns: list of TextChange or TextChangeStart
        """
        request = "descendant::text:change-start | descendant::text:change"
        return self._filtered_elements(request)  # type: ignore[return-value]

    @property
    def text_changes(self) -> list[TextChange | TextChangeStart]:
        """Return all the text changes, either single deletion (text:change) or
        start of range of changes (text:change-start).

        Returns: list of Element
        """
        return self.get_text_changes()

    def get_text_change(
        self,
        position: int = 0,
        idx: str | None = None,
    ) -> TextChange | TextChangeStart | None:
        """Return the text change that matches the criteria. Either single
        deletion (text:change) or start of range of changes (text:change-start).
        position : index of the element to retrieve if several matches, default
        is 0.
        idx : change-id of the element.

        Args:

            position -- int

            idx -- str

        Returns: Element or None if not found
        """
        if idx:
            request = (
                f'descendant::text:change-start[@text:change-id="{idx}"] '
                f'| descendant::text:change[@text:change-id="{idx}"]'
            )
            return self._filtered_element(request, 0)  # type: ignore[return-value]

        request = "descendant::text:change-start | descendant::text:change"
        return self._filtered_element(request, position)  # type: ignore[return-value]

    # Table Of Content

    def get_tocs(self) -> list[TOC]:
        """Return all the tables of contents.

        Returns: list of TOC
        """
        return self.get_elements("text:table-of-content")  # type: ignore[return-value]

    @property
    def tocs(self) -> list[TOC]:
        """Return all the tables of contents.

        Returns: list of TOC
        """
        return self.get_elements("text:table-of-content")  # type: ignore[return-value]

    def get_toc(
        self,
        position: int = 0,
        content: str | None = None,
    ) -> TOC | None:
        """Return the table of contents that matches the criteria.

        Args:

            position -- int

            content -- str regex

        Returns: TOC or None if not found
        """
        return self._filtered_element(
            "text:table-of-content", position, content=content
        )  # type: ignore[return-value]

    @property
    def toc(self) -> TOC | None:
        """Return the first table of contents.

        Returns: odf_toc or None if not found
        """
        return self.get_toc()

    # Styles

    @staticmethod
    def _get_style_tagname(family: str | None, is_default: bool = False) -> str:
        """Widely match possible tag names given the family (or not)."""
        if not family:
            tagname = "(style:default-style|*[@style:name]|draw:fill-image|draw:marker)"
        elif is_default:
            # Default style
            tagname = "style:default-style"
        else:
            tagname = _family_style_tagname(family)
            # if famattr:
            #    # Include family default style
            #    tagname = '(%s|style:default-style)' % tagname
            if family in FAMILY_ODF_STD:
                # Include family default style
                tagname = f"({tagname}|style:default-style)"
        return tagname

    def get_styles(self, family: str | None = None) -> list[StyleBase]:
        # Both common and default styles
        tagname = self._get_style_tagname(family)
        return self._filtered_elements(tagname, family=family)  # type: ignore[return-value]

    def get_style(
        self,
        family: str,
        name_or_element: str | Element | None = None,
        display_name: str | None = None,
    ) -> StyleBase | None:
        """Return the style uniquely identified by the family/name pair. If the
        argument is already a style object, it will return it.

        If the name is not the internal name but the name you gave in the
        desktop application, use display_name instead.

        Args:

            family -- 'paragraph', 'text', 'graphic', 'table', 'list',
                      'number'

            name_or_element -- str or Style

            display_name -- str

        Returns: Style or None if not found
        """
        if isinstance(name_or_element, Element):
            name = self.get_attribute("style:name")
            if name is not None:
                return name_or_element  # type: ignore[return-value]
            else:
                raise ValueError(f"Not a odf_style ? {name_or_element!r}")
        style_name = name_or_element
        is_default = not (style_name or display_name)
        tagname = self._get_style_tagname(family, is_default=is_default)
        # famattr became None if no "style:family" attribute
        if family:
            return self._filtered_element(
                tagname,
                0,
                style_name=style_name,
                display_name=display_name,
                family=family,
            )  # type: ignore[return-value]
        else:
            return self._filtered_element(
                tagname,
                0,
                draw_name=style_name or display_name,
                family=family,
            )  # type: ignore[return-value]

    def _filtered_element(
        self,
        query_string: str,
        position: int,
        **kwargs: Any,
    ) -> Element | None:
        results = self._filtered_elements(query_string, **kwargs)
        try:
            return results[position]
        except IndexError:
            return None

    def _filtered_elements(
        self,
        query_string: str,
        content: str | None = None,
        url: str | None = None,
        svg_title: str | None = None,
        svg_desc: str | None = None,
        dc_creator: str | None = None,
        dc_date: datetime | None = None,
        **kwargs: Any,
    ) -> list[Element]:
        query = make_xpath_query(query_string, **kwargs)
        elements = self.get_elements(query)
        # Filter the elements with the regex (TODO use XPath)
        if content is not None:
            elements = [element for element in elements if element.match(content)]
        if url is not None:
            filtered = []
            for element in elements:
                url_attr = element.get_attribute("xlink:href")
                if isinstance(url_attr, str) and search(url, url_attr) is not None:
                    filtered.append(element)
            elements = filtered
        if dc_date is None:
            dt_dc_date = None
        else:
            dt_dc_date = DateTime.encode(dc_date)
        for variable, childname in [
            (svg_title, "svg:title"),
            (svg_desc, "svg:desc"),
            (dc_creator, "descendant::dc:creator"),
            (dt_dc_date, "descendant::dc:date"),
        ]:
            if not variable:
                continue
            filtered = []
            for element in elements:
                child = element.get_element(childname)
                if child and child.match(variable):
                    filtered.append(element)
            elements = filtered
        return elements

append class-attribute instance-attribute

append = __append

attributes property

attributes: dict[str, str]

children property

children: list[Element]

clone property

clone: Element

document_body property

document_body: Body | None

Return the first children of document body if any: ‘office:body/*[1]’

frames property

frames: list[Frame]

Return all the frames.

Returns: list of Frame

headers property

headers: list[Header]

Return all the Headers.

Returns: list of Header

images property

images: list[DrawImage]

Return all the images.

Returns: list of DrawImage

inner_text property

inner_text: str

is_bound property

is_bound: bool

lists property

lists: list[List]

Return all the lists.

Returns: list of List

paragraphs property

paragraphs: list[Paragraph]

Return all the paragraphs.

Returns: list of Paragraph

parent property

parent: Element | None

root property

root: Element

sections property

sections: list[Section]

Return all the sections.

Returns: list of Section

spans property

spans: list[Span]

Return all the spans.

Returns: list of Span

svg_description property writable

svg_description: str | None

svg_title property writable

svg_title: str | None

tag property writable

tag: str

Get/set the underlying xml tag with the given qualified name.

Warning: direct change of tag does not change the element class.

Args:

qname -- str (e.g. "text:span")

tail property writable

tail: str | None

Get / set the text immediately following the element.

text property writable

text: str

Get / set the text content of the element.

text_changes property

text_changes: list[TextChange | TextChangeStart]

Return all the text changes, either single deletion (text:change) or start of range of changes (text:change-start).

Returns: list of Element

text_content property writable

text_content: str

Get / set the text of the embedded paragraphs, including embeded annotations, cells…

Set does create a paragraph if missing.

text_recursive property

text_recursive: str

toc property

toc: TOC | None

Return the first table of contents.

Returns: odf_toc or None if not found

tocs property

tocs: list[TOC]

Return all the tables of contents.

Returns: list of TOC

tracked_changes property

tracked_changes: Element | None

Return the tracked-changes part in the text body.

Returns: Element or None

user_defined_list property

user_defined_list: list[UserDefined]

Return all the user defined field declarations.

Returns: list of UserDefined

__init__

__init__(**kwargs: Any) -> None

Base class of all ODF classes, abstraction of the underlying XML.

Source code in odfdo/element.py

def __init__(self, **kwargs: Any) -> None:
    """Base class of all ODF classes, abstraction of the underlying XML."""
    tag_or_elem = kwargs.pop("tag_or_elem", None)
    if tag_or_elem is None:
        # Instance for newly created object: create new lxml element and
        # continue by subclass __init__
        # If the tag key word exists, make a custom element
        self._do_init = True
        tag = kwargs.pop("tag", self._tag)
        self.__element = self._make_etree_element(tag)
    else:
        # called with an existing lxml element, sould be a result of
        # from_tag() casting, do not execute the subclass __init__
        if not isinstance(tag_or_elem, _Element):
            raise TypeError(f'"{type(tag_or_elem)}" is not an element node')
        self._do_init = False
        self.__element = tag_or_elem

clear

clear() -> None

Remove text, children and attributes from the element.

Source code in odfdo/element.py

def clear(self) -> None:
    """Remove text, children and attributes from the element."""
    self.__element.clear()

del_attribute

del_attribute(name: str) -> None

Source code in odfdo/element.py

def del_attribute(self, name: str) -> None:
    element = self.__element
    lxml_tag = _get_lxml_tag_or_name(name)
    del element.attrib[lxml_tag]

delete

delete(
    child: Element | None = None, keep_tail: bool = True
) -> None

Delete the given element from the XML tree. If no element is given, “self” is deleted. The XML library may allow to continue to use an element now “orphan” as long as you have a reference to it.

if keep_tail is True (default), the tail text is not erased.

Args:

child -- Element

keep_tail -- boolean (default to True), True for most usages.

Source code in odfdo/element.py

def delete(self, child: Element | None = None, keep_tail: bool = True) -> None:
    """Delete the given element from the XML tree. If no element is given,
    "self" is deleted. The XML library may allow to continue to use an
    element now "orphan" as long as you have a reference to it.

    if keep_tail is True (default), the tail text is not erased.

    Args:

        child -- Element

        keep_tail -- boolean (default to True), True for most usages.
    """
    if child is None:
        parent = self.parent
        if parent is None:
            raise ValueError(f"Can't delete the root element\n{self.serialize()}")
        child = self
    else:
        parent = self
    if keep_tail and child.__element.tail is not None:
        current = child.__element
        tail = str(current.tail)
        current.tail = None
        prev = current.getprevious()
        if prev is not None:
            if prev.tail is None:
                prev.tail = tail
            else:
                prev.tail += tail
        else:
            if parent.__element.text is None:
                parent.__element.text = tail
            else:
                parent.__element.text += tail
    parent.__element.remove(child.__element)

elements_repeated_sequence

elements_repeated_sequence(
    xpath_instance: XPath, name: str
) -> list[tuple[int, int]]

Utility method for table module.

Source code in odfdo/element.py

def elements_repeated_sequence(
    self,
    xpath_instance: XPath,
    name: str,
) -> list[tuple[int, int]]:
    """Utility method for table module."""
    lxml_tag = _get_lxml_tag_or_name(name)
    sub_elements = xpath_return_elements(xpath_instance, self.__element)
    result: list[tuple[int, int]] = []
    idx = -1
    for sub_element in sub_elements:
        idx += 1
        value = sub_element.get(lxml_tag)
        if value is None:
            result.append((idx, 1))
            continue
        try:
            int_value = int(value)
        except ValueError:  # pragma: nocover
            int_value = 1
        result.append((idx, max(int_value, 1)))
    return result

extend

extend(odf_elements: Iterable[Element]) -> None

Fast append elements at the end of ourself using extend.

Source code in odfdo/element.py

def extend(self, odf_elements: Iterable[Element]) -> None:
    """Fast append elements at the end of ourself using extend."""
    if odf_elements:
        current = self.__element
        elements = [element.__element for element in odf_elements]
        current.extend(elements)

from_tag classmethod

from_tag(tag_or_elem: str | _Element) -> Element

Element class and subclass factory.

Turn an lxml Element or ODF string tag into an ODF XML Element of the relevant class.

Args:

tag_or_elem -- ODF str tag or lxml.Element

Returns: Element (or subclass) instance

Source code in odfdo/element.py

@classmethod
def from_tag(cls, tag_or_elem: str | _Element) -> Element:
    """Element class and subclass factory.

    Turn an lxml Element or ODF string tag into an ODF XML Element
    of the relevant class.

    Args:

        tag_or_elem -- ODF str tag or lxml.Element

    Returns: Element (or subclass) instance
    """
    if isinstance(tag_or_elem, str):
        # assume the argument is a prefix:name tag
        elem = cls._make_etree_element(tag_or_elem)
    else:
        elem = tag_or_elem
    klass = _class_registry.get(elem.tag, cls)
    return klass(tag_or_elem=elem)

from_tag_for_clone classmethod

from_tag_for_clone(
    tree_element: _Element, cache: tuple | None
) -> Element

Source code in odfdo/element.py

@classmethod
def from_tag_for_clone(
    cls: Any,  # ABCMeta, type, ...
    tree_element: _Element,
    cache: tuple | None,
) -> Element:
    tag = to_str(tree_element.tag)
    klass = _class_registry.get(tag, cls)
    element: Element = klass(tag_or_elem=tree_element)
    if cache:
        element._copy_cache(cache)
    return element

get_annotation

get_annotation(
    position: int = 0,
    creator: str | None = None,
    start_date: datetime | None = None,
    end_date: datetime | None = None,
    content: str | None = None,
    name: str | None = None,
) -> Annotation | None

Return the annotation that matches the criteria.

Args:

position -- int

creator -- str

start_date -- datetime instance

end_date -- datetime instance

content -- str regex

name -- str

Returns: Annotation or None if not found

Source code in odfdo/element.py

def get_annotation(
    self,
    position: int = 0,
    creator: str | None = None,
    start_date: datetime | None = None,
    end_date: datetime | None = None,
    content: str | None = None,
    name: str | None = None,
) -> Annotation | None:
    """Return the annotation that matches the criteria.

    Args:

        position -- int

        creator -- str

        start_date -- datetime instance

        end_date -- datetime instance

        content -- str regex

        name -- str

    Returns: Annotation or None if not found
    """
    if name is not None:
        return self._filtered_element(
            "descendant::office:annotation", 0, office_name=name
        )  # type: ignore[return-value]
    annotations: list[Annotation] = self.get_annotations(
        creator=creator, start_date=start_date, end_date=end_date, content=content
    )
    if not annotations:
        return None
    try:
        return annotations[position]
    except IndexError:
        return None

get_annotation_end

get_annotation_end(
    position: int = 0, name: str | None = None
) -> AnnotationEnd | None

Return the annotation end that matches the criteria.

Args:

position -- int

name -- str

Returns: AnnotationEnd or None if not found

Source code in odfdo/element.py

def get_annotation_end(
    self,
    position: int = 0,
    name: str | None = None,
) -> AnnotationEnd | None:
    """Return the annotation end that matches the criteria.

    Args:

        position -- int

        name -- str

    Returns: AnnotationEnd or None if not found
    """
    return self._filtered_element(
        "descendant::office:annotation-end", position, office_name=name
    )  # type: ignore[return-value]

get_annotation_ends

get_annotation_ends() -> list[AnnotationEnd]

Return all the annotation ends.

Returns: list of AnnotationEnd

Source code in odfdo/element.py

def get_annotation_ends(self) -> list[AnnotationEnd]:
    """Return all the annotation ends.

    Returns: list of AnnotationEnd
    """
    return self._filtered_elements(
        "descendant::office:annotation-end",
    )  # type: ignore[return-value]

get_annotations

get_annotations(
    creator: str | None = None,
    start_date: datetime | None = None,
    end_date: datetime | None = None,
    content: str | None = None,
) -> list[Annotation]

Return all the annotations that match the criteria.

Args:

creator -- str

start_date -- datetime instance

end_date --  datetime instance

content -- str regex

Returns: list of Annotation

Source code in odfdo/element.py

def get_annotations(
    self,
    creator: str | None = None,
    start_date: datetime | None = None,
    end_date: datetime | None = None,
    content: str | None = None,
) -> list[Annotation]:
    """Return all the annotations that match the criteria.

    Args:

        creator -- str

        start_date -- datetime instance

        end_date --  datetime instance

        content -- str regex

    Returns: list of Annotation
    """
    annotations: list[Annotation] = []
    for annotation in self._filtered_elements(
        "descendant::office:annotation", content=content
    ):
        if creator is not None and creator != annotation.dc_creator:  # type: ignore[attr-defined]
            continue
        date = annotation.date  # type: ignore[attr-defined]
        # date never None: recreated if missing
        if date is None:  # pragma: no cover
            continue
        if start_date is not None and date < start_date:
            continue
        if end_date is not None and date >= end_date:
            continue
        annotations.append(annotation)  # type: ignore[arg-type]
    return annotations

get_attribute

get_attribute(name: str) -> str | bool | None

Return the attribute value as type str | bool | None.

Source code in odfdo/element.py

def get_attribute(self, name: str) -> str | bool | None:
    """Return the attribute value as type str | bool | None."""
    element = self.__element
    lxml_tag = _get_lxml_tag_or_name(name)
    value = element.get(lxml_tag)
    if value is None:
        return None
    elif value in ("true", "false"):
        return Boolean.decode(value)
    return str(value)

get_attribute_integer

get_attribute_integer(name: str) -> int | None

Return either the attribute as type int, or None.

Source code in odfdo/element.py

def get_attribute_integer(self, name: str) -> int | None:
    """Return either the attribute as type int, or None."""
    element = self.__element
    lxml_tag = _get_lxml_tag_or_name(name)
    value = element.get(lxml_tag)
    if value is None:
        return None
    try:
        return int(value)
    except ValueError:
        return None

get_attribute_string

get_attribute_string(name: str) -> str | None

Return either the attribute as type str, or None.

Source code in odfdo/element.py

def get_attribute_string(self, name: str) -> str | None:
    """Return either the attribute as type str, or None."""
    element = self.__element
    lxml_tag = _get_lxml_tag_or_name(name)
    value = element.get(lxml_tag)
    if value is None:
        return None
    return str(value)

get_bookmark

get_bookmark(
    position: int = 0, name: str | None = None
) -> Bookmark | None

Return the bookmark that matches the criteria.

Args:

position -- int

name -- str

Returns: Bookmark or None if not found

Source code in odfdo/element.py

def get_bookmark(
    self,
    position: int = 0,
    name: str | None = None,
) -> Bookmark | None:
    """Return the bookmark that matches the criteria.

    Args:

        position -- int

        name -- str

    Returns: Bookmark or None if not found
    """
    return self._filtered_element(
        "descendant::text:bookmark", position, text_name=name
    )  # type: ignore[return-value]

get_bookmark_end

get_bookmark_end(
    position: int = 0, name: str | None = None
) -> BookmarkEnd | None

Return the bookmark end that matches the criteria.

Args:

position -- int

name -- str

Returns: BookmarkEnd or None if not found

Source code in odfdo/element.py

def get_bookmark_end(
    self,
    position: int = 0,
    name: str | None = None,
) -> BookmarkEnd | None:
    """Return the bookmark end that matches the criteria.

    Args:

        position -- int

        name -- str

    Returns: BookmarkEnd or None if not found
    """
    return self._filtered_element(
        "descendant::text:bookmark-end", position, text_name=name
    )  # type: ignore[return-value]

get_bookmark_ends

get_bookmark_ends() -> list[BookmarkEnd]

Return all the bookmark ends.

Returns: list of BookmarkEnd

Source code in odfdo/element.py

def get_bookmark_ends(self) -> list[BookmarkEnd]:
    """Return all the bookmark ends.

    Returns: list of BookmarkEnd
    """
    return self._filtered_elements(
        "descendant::text:bookmark-end",
    )  # type: ignore[return-value]

get_bookmark_start

get_bookmark_start(
    position: int = 0, name: str | None = None
) -> BookmarkStart | None

Return the bookmark start that matches the criteria.

Args:

position -- int

name -- str

Returns: BookmarkStart or None if not found

Source code in odfdo/element.py

def get_bookmark_start(
    self,
    position: int = 0,
    name: str | None = None,
) -> BookmarkStart | None:
    """Return the bookmark start that matches the criteria.

    Args:

        position -- int

        name -- str

    Returns: BookmarkStart or None if not found
    """
    return self._filtered_element(
        "descendant::text:bookmark-start", position, text_name=name
    )  # type: ignore[return-value]

get_bookmark_starts

get_bookmark_starts() -> list[BookmarkStart]

Return all the bookmark starts.

Returns: list of BookmarkStart

Source code in odfdo/element.py

def get_bookmark_starts(self) -> list[BookmarkStart]:
    """Return all the bookmark starts.

    Returns: list of BookmarkStart
    """
    return self._filtered_elements(
        "descendant::text:bookmark-start",
    )  # type: ignore[return-value]

get_bookmarks

get_bookmarks() -> list[Bookmark]

Return all the bookmarks.

Returns: list of Bookmark

Source code in odfdo/element.py

def get_bookmarks(self) -> list[Bookmark]:
    """Return all the bookmarks.

    Returns: list of Bookmark
    """
    return self._filtered_elements(
        "descendant::text:bookmark",
    )  # type: ignore[return-value]

get_changes_ids

get_changes_ids() -> list[Element | EText]

Return a list of ids that refers to a change region in the tracked changes list.

Source code in odfdo/element.py

def get_changes_ids(self) -> list[Element | EText]:
    """Return a list of ids that refers to a change region in the tracked
    changes list.
    """
    # Insertion changes or deletion changes
    xpath_query = (
        "descendant::text:change-start/@text:change-id "
        "| descendant::text:change/@text:change-id"
    )
    return self.xpath(xpath_query)

get_draw_connector

get_draw_connector(
    position: int = 0,
    id: str | None = None,
    content: str | None = None,
) -> ConnectorShape | None

Return the draw connector that matches the criteria.

Args:

position -- int

id -- str

content -- str regex

Returns: ConnectorShape or None if not found

Source code in odfdo/element.py

def get_draw_connector(
    self,
    position: int = 0,
    id: str | None = None,  # noqa:A002
    content: str | None = None,
) -> ConnectorShape | None:
    """Return the draw connector that matches the criteria.

    Args:

        position -- int

        id -- str

        content -- str regex

    Returns: ConnectorShape or None if not found
    """
    return self._filtered_element(
        "descendant::draw:connector", position, draw_id=id, content=content
    )  # type: ignore[return-value]

get_draw_connectors

get_draw_connectors(
    draw_style: str | None = None,
    draw_text_style: str | None = None,
    content: str | None = None,
) -> list[ConnectorShape]

Return all the draw connectors that match the criteria.

Args:

draw_style -- str

draw_text_style -- str

content -- str regex

Returns: list of ConnectorShape

Source code in odfdo/element.py

def get_draw_connectors(
    self,
    draw_style: str | None = None,
    draw_text_style: str | None = None,
    content: str | None = None,
) -> list[ConnectorShape]:
    """Return all the draw connectors that match the criteria.

    Args:

        draw_style -- str

        draw_text_style -- str

        content -- str regex

    Returns: list of ConnectorShape
    """
    return self._filtered_elements(
        "descendant::draw:connector",
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content,
    )  # type: ignore[return-value]

get_draw_ellipse

get_draw_ellipse(
    position: int = 0,
    id: str | None = None,
    content: str | None = None,
) -> EllipseShape | None

Return the draw ellipse that matches the criteria.

Args:

position -- int

id -- str

content -- str regex

Returns: EllipseShape or None if not found

Source code in odfdo/element.py

def get_draw_ellipse(
    self,
    position: int = 0,
    id: str | None = None,  # noqa:A002
    content: str | None = None,
) -> EllipseShape | None:
    """Return the draw ellipse that matches the criteria.

    Args:

        position -- int

        id -- str

        content -- str regex

    Returns: EllipseShape or None if not found
    """
    return self._filtered_element(
        "descendant::draw:ellipse", position, draw_id=id, content=content
    )  # type: ignore[return-value]

get_draw_ellipses

get_draw_ellipses(
    draw_style: str | None = None,
    draw_text_style: str | None = None,
    content: str | None = None,
) -> list[EllipseShape]

Return all the draw ellipses that match the criteria.

Args:

draw_style -- str

draw_text_style -- str

content -- str regex

Returns: list of EllipseShape

Source code in odfdo/element.py

def get_draw_ellipses(
    self,
    draw_style: str | None = None,
    draw_text_style: str | None = None,
    content: str | None = None,
) -> list[EllipseShape]:
    """Return all the draw ellipses that match the criteria.

    Args:

        draw_style -- str

        draw_text_style -- str

        content -- str regex

    Returns: list of EllipseShape
    """
    return self._filtered_elements(
        "descendant::draw:ellipse",
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content,
    )  # type: ignore[return-value]

get_draw_group

get_draw_group(
    position: int = 0,
    name: str | None = None,
    title: str | None = None,
    description: str | None = None,
    content: str | None = None,
) -> DrawGroup | None

Return the draw group that matches the criteria.

Args:

position -- int

name  -- str or None

title -- str or None

description -- str regex or None

content -- str regex or None

Returns: DrawGroup or None if not found

Source code in odfdo/element.py

def get_draw_group(
    self,
    position: int = 0,
    name: str | None = None,
    title: str | None = None,
    description: str | None = None,
    content: str | None = None,
) -> DrawGroup | None:
    """Return the  draw group that matches the criteria.

    Args:

        position -- int

        name  -- str or None

        title -- str or None

        description -- str regex or None

        content -- str regex or None

    Returns: DrawGroup or None if not found
    """
    return self._filtered_element(
        "descendant::draw:g",
        position,
        draw_name=name,
        svg_title=title,
        svg_desc=description,
        content=content,
    )  # type: ignore[return-value]

get_draw_groups

get_draw_groups(
    title: str | None = None,
    description: str | None = None,
    content: str | None = None,
) -> list[DrawGroup]

Return all the draw groups that match the criteria.

Args:

title -- str or None

description -- str regex or None

content -- str regex or None

Returns: list of DrawGroup

Source code in odfdo/element.py

def get_draw_groups(
    self,
    title: str | None = None,
    description: str | None = None,
    content: str | None = None,
) -> list[DrawGroup]:
    """Return all the draw groups that match the criteria.

    Args:

        title -- str or None

        description -- str regex or None

        content -- str regex or None

    Returns: list of DrawGroup
    """
    return self._filtered_elements(
        "descendant::draw:g",
        svg_title=title,
        svg_desc=description,
        content=content,
    )  # type: ignore[return-value]

get_draw_line

get_draw_line(
    position: int = 0,
    id: str | None = None,
    content: str | None = None,
) -> LineShape | None

Return the draw line that matches the criteria.

Args:

position -- int

id -- str

content -- str regex

Returns: LineShape or None if not found

Source code in odfdo/element.py

def get_draw_line(
    self,
    position: int = 0,
    id: str | None = None,  # noqa:A002
    content: str | None = None,
) -> LineShape | None:
    """Return the draw line that matches the criteria.

    Args:

        position -- int

        id -- str

        content -- str regex

    Returns: LineShape or None if not found
    """
    return self._filtered_element(
        "descendant::draw:line", position, draw_id=id, content=content
    )  # type: ignore[return-value]

get_draw_lines

get_draw_lines(
    draw_style: str | None = None,
    draw_text_style: str | None = None,
    content: str | None = None,
) -> list[LineShape]

Return all the draw lines that match the criteria.

Args:

draw_style -- str

draw_text_style -- str

content -- str regex

Returns: list of LineShape

Source code in odfdo/element.py

def get_draw_lines(
    self,
    draw_style: str | None = None,
    draw_text_style: str | None = None,
    content: str | None = None,
) -> list[LineShape]:
    """Return all the draw lines that match the criteria.

    Args:

        draw_style -- str

        draw_text_style -- str

        content -- str regex

    Returns: list of LineShape
    """
    return self._filtered_elements(
        "descendant::draw:line",
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content,
    )  # type: ignore[return-value]

get_draw_page

get_draw_page(
    position: int = 0,
    name: str | None = None,
    content: str | None = None,
) -> DrawPage | None

Return the draw page that matches the criteria.

Args:

position -- int

name -- str

content -- str regex

Returns: DrawPage or None if not found

Source code in odfdo/element.py

def get_draw_page(
    self,
    position: int = 0,
    name: str | None = None,
    content: str | None = None,
) -> DrawPage | None:
    """Return the draw page that matches the criteria.

    Args:

        position -- int

        name -- str

        content -- str regex

    Returns: DrawPage or None if not found
    """
    return self._filtered_element(
        "descendant::draw:page", position, draw_name=name, content=content
    )  # type: ignore[return-value]

get_draw_pages

get_draw_pages(
    style: str | None = None, content: str | None = None
) -> list[DrawPage]

Return all the draw pages that match the criteria.

Args:

style -- str

content -- str regex

Returns: list of DrawPage

Source code in odfdo/element.py

def get_draw_pages(
    self,
    style: str | None = None,
    content: str | None = None,
) -> list[DrawPage]:
    """Return all the draw pages that match the criteria.

    Args:

        style -- str

        content -- str regex

    Returns: list of DrawPage
    """
    return self._filtered_elements(
        "descendant::draw:page", draw_style=style, content=content
    )  # type: ignore[return-value]

get_draw_rectangle

get_draw_rectangle(
    position: int = 0,
    id: str | None = None,
    content: str | None = None,
) -> RectangleShape | None

Return the draw rectangle that matches the criteria.

Args:

position -- int

id -- str

content -- str regex

Returns: RectangleShape or None if not found

Source code in odfdo/element.py

def get_draw_rectangle(
    self,
    position: int = 0,
    id: str | None = None,  # noqa:A002
    content: str | None = None,
) -> RectangleShape | None:
    """Return the draw rectangle that matches the criteria.

    Args:

        position -- int

        id -- str

        content -- str regex

    Returns: RectangleShape or None if not found
    """
    return self._filtered_element(
        "descendant::draw:rect", position, draw_id=id, content=content
    )  # type: ignore[return-value]

get_draw_rectangles

get_draw_rectangles(
    draw_style: str | None = None,
    draw_text_style: str | None = None,
    content: str | None = None,
) -> list[RectangleShape]

Return all the draw rectangles that match the criteria.

Args:

draw_style -- str

draw_text_style -- str

content -- str regex

Returns: list of RectangleShape

Source code in odfdo/element.py

def get_draw_rectangles(
    self,
    draw_style: str | None = None,
    draw_text_style: str | None = None,
    content: str | None = None,
) -> list[RectangleShape]:
    """Return all the draw rectangles that match the criteria.

    Args:

        draw_style -- str

        draw_text_style -- str

        content -- str regex

    Returns: list of RectangleShape
    """
    return self._filtered_elements(
        "descendant::draw:rect",
        draw_style=draw_style,
        draw_text_style=draw_text_style,
        content=content,
    )  # type: ignore[return-value]

get_element

get_element(xpath_query: str) -> Element | None

Returns the first element obtained from the XPath query applied to the current element.

Return an Element or None.

Source code in odfdo/element.py

def get_element(self, xpath_query: str) -> Element | None:
    """Returns the first element obtained from the XPath query applied to
    the current element.

    Return an Element or None.
    """
    result = self.__element.xpath(f"({xpath_query})[1]", namespaces=ODF_NAMESPACES)
    if result:
        return Element.from_tag(result[0])
    return None

get_elements

get_elements(xpath_query: XPath | str) -> list[Element]

Returns the elements obtained from the XPath query applied to the current element.

Return list of Element.

Source code in odfdo/element.py

def get_elements(self, xpath_query: XPath | str) -> list[Element]:
    """Returns the elements obtained from the XPath query applied to the
    current element.

    Return list of Element.
    """
    if isinstance(xpath_query, str):
        elements = xpath_return_elements(xpath_compile(xpath_query), self.__element)
    else:
        elements = xpath_return_elements(xpath_query, self.__element)
    return [Element.from_tag_for_clone(e, None) for e in elements]

get_formatted_text

get_formatted_text(context: dict | None = None) -> str

This function should return a beautiful version of the text.

Source code in odfdo/element.py

def get_formatted_text(self, context: dict | None = None) -> str:
    """This function should return a beautiful version of the text."""
    return ""

get_frame

get_frame(
    position: int = 0,
    name: str | None = None,
    presentation_class: str | None = None,
    title: str | None = None,
    description: str | None = None,
    content: str | None = None,
) -> Frame | None

Return the section that matches the criteria.

Args:

position -- int

name -- str

presentation_class -- str

title -- str regex

description -- str regex

content -- str regex

Returns: Frame or None if not found

Source code in odfdo/element.py

def get_frame(
    self,
    position: int = 0,
    name: str | None = None,
    presentation_class: str | None = None,
    title: str | None = None,
    description: str | None = None,
    content: str | None = None,
) -> Frame | None:
    """Return the section that matches the criteria.

    Args:

        position -- int

        name -- str

        presentation_class -- str

        title -- str regex

        description -- str regex

        content -- str regex

    Returns: Frame or None if not found
    """
    return self._filtered_element(
        "descendant::draw:frame",
        position,
        draw_name=name,
        presentation_class=presentation_class,
        svg_title=title,
        svg_desc=description,
        content=content,
    )  # type: ignore[return-value]

get_frames

get_frames(
    presentation_class: str | None = None,
    style: str | None = None,
    title: str | None = None,
    description: str | None = None,
    content: str | None = None,
) -> list[Frame]

Return all the frames that match the criteria.

Args:

presentation_class -- str

style -- str

title -- str regex

description -- str regex

content -- str regex

Returns: list of Frame

Source code in odfdo/element.py

def get_frames(
    self,
    presentation_class: str | None = None,
    style: str | None = None,
    title: str | None = None,
    description: str | None = None,
    content: str | None = None,
) -> list[Frame]:
    """Return all the frames that match the criteria.

    Args:

        presentation_class -- str

        style -- str

        title -- str regex

        description -- str regex

        content -- str regex

    Returns: list of Frame
    """
    return self._filtered_elements(
        "descendant::draw:frame",
        presentation_class=presentation_class,
        draw_style=style,
        svg_title=title,
        svg_desc=description,
        content=content,
    )  # type: ignore[return-value]

get_header

get_header(
    position: int = 0,
    outline_level: str | None = None,
    content: str | None = None,
) -> Header | None

Return the Header that matches the criteria.

Args:

position -- int

content -- str regex

Returns: Header or None if not found

Source code in odfdo/element.py

def get_header(
    self,
    position: int = 0,
    outline_level: str | None = None,
    content: str | None = None,
) -> Header | None:
    """Return the Header that matches the criteria.

    Args:

        position -- int

        content -- str regex

    Returns: Header or None if not found
    """
    return self._filtered_element(
        "descendant::text:h",
        position,
        outline_level=outline_level,
        content=content,
    )  # type: ignore[return-value]

get_headers

get_headers(
    style: str | None = None,
    outline_level: str | None = None,
    content: str | None = None,
) -> list[Header]

Return all the Headers that match the criteria.

Args:

style -- str

content -- str regex

Returns: list of Header

Source code in odfdo/element.py

def get_headers(
    self,
    style: str | None = None,
    outline_level: str | None = None,
    content: str | None = None,
) -> list[Header]:
    """Return all the Headers that match the criteria.

    Args:

        style -- str

        content -- str regex

    Returns: list of Header
    """
    return self._filtered_elements(
        "descendant::text:h",
        text_style=style,
        outline_level=outline_level,
        content=content,
    )  # type: ignore[return-value]

get_image

get_image(
    position: int = 0,
    name: str | None = None,
    url: str | None = None,
    content: str | None = None,
) -> DrawImage | None

Return the image matching the criteria.

Args:

position -- int

name -- str

url -- str regex

content -- str regex

Returns: DrawImage or None if not found

Source code in odfdo/element.py

def get_image(
    self,
    position: int = 0,
    name: str | None = None,
    url: str | None = None,
    content: str | None = None,
) -> DrawImage | None:
    """Return the image matching the criteria.

    Args:

        position -- int

        name -- str

        url -- str regex

        content -- str regex

    Returns: DrawImage or None if not found
    """
    # The frame is holding the name
    if name is not None:
        frame = self._filtered_element(
            "descendant::draw:frame", position, draw_name=name
        )
        if frame is None:
            return None
        # The name is supposedly unique
        return frame.get_element("draw:image")  # type: ignore[return-value]
    return self._filtered_element(
        "descendant::draw:image", position, url=url, content=content
    )  # type: ignore[return-value]

get_images

get_images(
    style: str | None = None,
    url: str | None = None,
    content: str | None = None,
) -> list[DrawImage]

Return all the images matching the criteria.

Args:

style -- str

url -- str regex

content -- str regex

Returns: list of DrawImage

Source code in odfdo/element.py

def get_images(
    self,
    style: str | None = None,
    url: str | None = None,
    content: str | None = None,
) -> list[DrawImage]:
    """Return all the images matching the criteria.

    Args:

        style -- str

        url -- str regex

        content -- str regex

    Returns: list of DrawImage
    """
    return self._filtered_elements(
        "descendant::draw:image", text_style=style, url=url, content=content
    )  # type: ignore[return-value]

get_link

get_link(
    position: int = 0,
    name: str | None = None,
    title: str | None = None,
    url: str | None = None,
    content: str | None = None,
) -> Link | None

Return the link that matches the criteria.

Args:

position -- int

name -- str

title -- str

url -- str regex

content -- str regex

Returns: Link or None if not found

Source code in odfdo/element.py

def get_link(
    self,
    position: int = 0,
    name: str | None = None,
    title: str | None = None,
    url: str | None = None,
    content: str | None = None,
) -> Link | None:
    """Return the link that matches the criteria.

    Args:

        position -- int

        name -- str

        title -- str

        url -- str regex

        content -- str regex

    Returns: Link or None if not found
    """
    return self._filtered_element(
        "descendant::text:a",
        position,
        office_name=name,
        office_title=title,
        url=url,
        content=content,
    )  # type: ignore[return-value]

get_links

get_links(
    name: str | None = None,
    title: str | None = None,
    url: str | None = None,
    content: str | None = None,
) -> list[Link]

Return all the links that match the criteria.

Args:

name -- str

title -- str

url -- str regex

content -- str regex

Returns: list of Link

Source code in odfdo/element.py

def get_links(
    self,
    name: str | None = None,
    title: str | None = None,
    url: str | None = None,
    content: str | None = None,
) -> list[Link]:
    """Return all the links that match the criteria.

    Args:

        name -- str

        title -- str

        url -- str regex

        content -- str regex

    Returns: list of Link
    """
    return self._filtered_elements(
        "descendant::text:a",
        office_name=name,
        office_title=title,
        url=url,
        content=content,
    )  # type: ignore[return-value]

get_list

get_list(
    position: int = 0, content: str | None = None
) -> List | None

Return the list that matches the criteria.

Args:

position -- int

content -- str regex

Returns: List or None if not found

Source code in odfdo/element.py

def get_list(
    self,
    position: int = 0,
    content: str | None = None,
) -> List | None:
    """Return the list that matches the criteria.

    Args:

        position -- int

        content -- str regex

    Returns: List or None if not found
    """
    return self._filtered_element(
        "descendant::text:list", position, content=content
    )  # type: ignore[return-value]

get_lists

get_lists(
    style: str | None = None, content: str | None = None
) -> list[List]

Return all the lists that match the criteria.

Args:

style -- str

content -- str regex

Returns: list of List

Source code in odfdo/element.py

def get_lists(
    self,
    style: str | None = None,
    content: str | None = None,
) -> list[List]:
    """Return all the lists that match the criteria.

    Args:

        style -- str

        content -- str regex

    Returns: list of List
    """
    return self._filtered_elements(
        "descendant::text:list", text_style=style, content=content
    )  # type: ignore[return-value]

get_note

get_note(
    position: int = 0,
    note_id: str | None = None,
    note_class: str | None = None,
    content: str | None = None,
) -> Note | None

Return the note that matches the criteria.

Args:

position -- int

note_id -- str

note_class -- 'footnote' or 'endnote'

content -- str regex

Returns: Note or None if not found

Source code in odfdo/element.py

def get_note(
    self,
    position: int = 0,
    note_id: str | None = None,
    note_class: str | None = None,
    content: str | None = None,
) -> Note | None:
    """Return the note that matches the criteria.

    Args:

        position -- int

        note_id -- str

        note_class -- 'footnote' or 'endnote'

        content -- str regex

    Returns: Note or None if not found
    """
    return self._filtered_element(
        "descendant::text:note",
        position,
        text_id=note_id,
        note_class=note_class,
        content=content,
    )  # type: ignore[return-value]

get_notes

get_notes(
    note_class: str | None = None,
    content: str | None = None,
) -> list[Note]

Return all the notes that match the criteria.

Args:

note_class -- 'footnote' or 'endnote'

content -- str regex

Returns: list of Note

Source code in odfdo/element.py

def get_notes(
    self,
    note_class: str | None = None,
    content: str | None = None,
) -> list[Note]:
    """Return all the notes that match the criteria.

    Args:

        note_class -- 'footnote' or 'endnote'

        content -- str regex

    Returns: list of Note
    """
    return self._filtered_elements(
        "descendant::text:note", note_class=note_class, content=content
    )  # type: ignore[return-value]

get_office_names

get_office_names() -> list[str]

Return all the used office:name tags values of the element.

Returns: list of unique str

Source code in odfdo/element.py

def get_office_names(self) -> list[str]:
    """Return all the used office:name tags values of the element.

    Returns: list of unique str
    """
    name_xpath_query = xpath_compile("//@office:name")
    strings = xpath_return_strings(name_xpath_query, self.__element)
    return list({name for name in strings if name})

get_orphan_draw_connectors

get_orphan_draw_connectors() -> list[ConnectorShape]

Return a list of connectors which don’t have any shape connected to them.

Returns: list of ConnectorShape

Source code in odfdo/element.py

def get_orphan_draw_connectors(self) -> list[ConnectorShape]:
    """Return a list of connectors which don't have any shape connected to
    them.

    Returns: list of ConnectorShape
    """
    connectors = []
    for connector in self.get_draw_connectors():
        start_shape = connector.get_attribute("draw:start-shape")
        end_shape = connector.get_attribute("draw:end-shape")
        if start_shape is None and end_shape is None:
            connectors.append(connector)
    return connectors

get_paragraph

get_paragraph(
    position: int = 0, content: str | None = None
) -> Paragraph | None

Return the paragraph that matches the criteria.

Args:

position -- int

content -- str regex

Returns: Paragraph or None if not found

Source code in odfdo/element.py

def get_paragraph(
    self,
    position: int = 0,
    content: str | None = None,
) -> Paragraph | None:
    """Return the paragraph that matches the criteria.

    Args:

        position -- int

        content -- str regex

    Returns: Paragraph or None if not found
    """
    return self._filtered_element(
        "descendant::text:p",
        position,
        content=content,
    )  # type: ignore[return-value]

get_paragraphs

get_paragraphs(
    style: str | None = None, content: str | None = None
) -> list[Paragraph]

Return all the paragraphs that match the criteria.

Args:

style -- str

content -- str regex

Returns: list of Paragraph

Source code in odfdo/element.py

def get_paragraphs(
    self,
    style: str | None = None,
    content: str | None = None,
) -> list[Paragraph]:
    """Return all the paragraphs that match the criteria.

    Args:

        style -- str

        content -- str regex

    Returns: list of Paragraph
    """
    return self._filtered_elements(
        "descendant::text:p", text_style=style, content=content
    )  # type: ignore[return-value]

get_reference_mark

get_reference_mark(
    position: int = 0, name: str | None = None
) -> ReferenceMark | ReferenceMarkStart | None

Return the reference mark that match the criteria. Either single position reference mark (text:reference-mark) or start of range reference (text:reference-mark-start).

Args:

position -- int

name -- str

Returns: ReferenceMark or ReferenceMarkStart or None if not found

Source code in odfdo/element.py

def get_reference_mark(
    self,
    position: int = 0,
    name: str | None = None,
) -> ReferenceMark | ReferenceMarkStart | None:
    """Return the reference mark that match the criteria. Either single
    position reference mark (text:reference-mark) or start of range
    reference (text:reference-mark-start).

    Args:

        position -- int

        name -- str

    Returns: ReferenceMark or ReferenceMarkStart or None if not found
    """
    if name:
        request = (
            f"descendant::text:reference-mark-start"
            f'[@text:name="{name}"] '
            f"| descendant::text:reference-mark"
            f'[@text:name="{name}"]'
        )
        return self._filtered_element(
            request,
            position=0,
        )  # type: ignore[return-value]
    request = (
        "descendant::text:reference-mark-start | descendant::text:reference-mark"
    )
    return self._filtered_element(request, position)  # type: ignore[return-value]

get_reference_mark_end

get_reference_mark_end(
    position: int = 0, name: str | None = None
) -> ReferenceMarkEnd | None

Return the reference mark end that matches the criteria. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Args:

position -- int

name -- str

Returns: ReferenceMarkEnd or None if not found

Source code in odfdo/element.py

def get_reference_mark_end(
    self,
    position: int = 0,
    name: str | None = None,
) -> ReferenceMarkEnd | None:
    """Return the reference mark end that matches the criteria. Search only
    the tags text:reference-mark-end.
    Consider using : get_reference_marks()

    Args:

        position -- int

        name -- str

    Returns: ReferenceMarkEnd or None if not found
    """
    return self._filtered_element(
        "descendant::text:reference-mark-end", position, text_name=name
    )  # type: ignore[return-value]

get_reference_mark_ends

get_reference_mark_ends() -> list[ReferenceMarkEnd]

Return all the reference mark ends. Search only the tags text:reference-mark-end. Consider using : get_reference_marks()

Returns: list of ReferenceMarkEnd

Source code in odfdo/element.py

def get_reference_mark_ends(self) -> list[ReferenceMarkEnd]:
    """Return all the reference mark ends. Search only the tags
    text:reference-mark-end.
    Consider using : get_reference_marks()

    Returns: list of ReferenceMarkEnd
    """
    return self._filtered_elements(
        "descendant::text:reference-mark-end",
    )  # type: ignore[return-value]

get_reference_mark_single

get_reference_mark_single(
    position: int = 0, name: str | None = None
) -> ReferenceMark | None

Return the reference mark that matches the criteria. Search only the tags text:reference-mark. Consider using : get_reference_mark()

Args:

position -- int

name -- str

Returns: ReferenceMark or None if not found

Source code in odfdo/element.py

def get_reference_mark_single(
    self,
    position: int = 0,
    name: str | None = None,
) -> ReferenceMark | None:
    """Return the reference mark that matches the criteria. Search only the
    tags text:reference-mark.
    Consider using : get_reference_mark()

    Args:

        position -- int

        name -- str

    Returns: ReferenceMark or None if not found
    """
    return self._filtered_element(
        "descendant::text:reference-mark", position, text_name=name
    )  # type: ignore[return-value]

get_reference_mark_start

get_reference_mark_start(
    position: int = 0, name: str | None = None
) -> ReferenceMarkStart | None

Return the reference mark start that matches the criteria. Search only the tags text:reference-mark-start. Consider using : get_reference_mark()

Args:

position -- int

name -- str

Returns: ReferenceMarkStart or None if not found

Source code in odfdo/element.py

def get_reference_mark_start(
    self,
    position: int = 0,
    name: str | None = None,
) -> ReferenceMarkStart | None:
    """Return the reference mark start that matches the criteria. Search
    only the tags text:reference-mark-start.
    Consider using : get_reference_mark()

    Args:

        position -- int

        name -- str

    Returns: ReferenceMarkStart or None if not found
    """
    return self._filtered_element(
        "descendant::text:reference-mark-start", position, text_name=name
    )  # type: ignore[return-value]

get_reference_mark_starts

get_reference_mark_starts() -> list[ReferenceMarkStart]

Return all the reference mark starts. Search only the tags text:reference-mark-start. Consider using : get_reference_marks()

Returns: list of ReferenceMarkStart

Source code in odfdo/element.py

def get_reference_mark_starts(self) -> list[ReferenceMarkStart]:
    """Return all the reference mark starts. Search only the tags
    text:reference-mark-start.
    Consider using : get_reference_marks()

    Returns: list of ReferenceMarkStart
    """
    return self._filtered_elements(
        "descendant::text:reference-mark-start",
    )  # type: ignore[return-value]

get_reference_marks

get_reference_marks() -> list[
    ReferenceMark | ReferenceMarkStart
]

Return all the reference marks, either single position reference (text:reference-mark) or start of range reference (text:reference-mark- start).

Returns: list of ReferenceMark or ReferenceMarkStart

Source code in odfdo/element.py

def get_reference_marks(self) -> list[ReferenceMark | ReferenceMarkStart]:
    """Return all the reference marks, either single position reference
    (text:reference-mark) or start of range reference (text:reference-mark-
    start).

    Returns: list of ReferenceMark or ReferenceMarkStart
    """
    return self._filtered_elements(
        "descendant::text:reference-mark-start | descendant::text:reference-mark"
    )  # type: ignore[return-value]

get_reference_marks_single

get_reference_marks_single() -> list[ReferenceMark]

Return all the reference marks. Search only the tags text:reference-mark. Consider using : get_reference_marks()

Returns: list of ReferenceMark

Source code in odfdo/element.py

def get_reference_marks_single(self) -> list[ReferenceMark]:
    """Return all the reference marks. Search only the tags
    text:reference-mark.
    Consider using : get_reference_marks()

    Returns: list of ReferenceMark
    """
    return self._filtered_elements(
        "descendant::text:reference-mark",
    )  # type: ignore[return-value]

get_references

get_references(name: str | None = None) -> list[Reference]

Return all the references (text:reference-ref). If name is provided, returns the references of that name.

Args:

name -- str or None

Returns: list of Reference

Source code in odfdo/element.py

def get_references(self, name: str | None = None) -> list[Reference]:
    """Return all the references (text:reference-ref). If name is provided,
    returns the references of that name.

    Args:

        name -- str or None

    Returns: list of Reference
    """
    if name is None:
        return self._filtered_elements(
            "descendant::text:reference-ref",
        )  # type: ignore[return-value]
    request = f'descendant::text:reference-ref[@text:ref-name="{name}"]'
    return self._filtered_elements(request)  # type: ignore[return-value]

get_section

get_section(
    position: int = 0, content: str | None = None
) -> Section | None

Return the section that matches the criteria.

Args:

position -- int

content -- str regex

Returns: Section or None if not found

Source code in odfdo/element.py

def get_section(
    self,
    position: int = 0,
    content: str | None = None,
) -> Section | None:
    """Return the section that matches the criteria.

    Args:

        position -- int

        content -- str regex

    Returns: Section or None if not found
    """
    return self._filtered_element(
        "descendant::text:section", position, content=content
    )  # type: ignore[return-value]

get_sections

get_sections(
    style: str | None = None, content: str | None = None
) -> list[Section]

Return all the sections that match the criteria.

Args:

style -- str

content -- str regex

Returns: list of Section

Source code in odfdo/element.py

def get_sections(
    self,
    style: str | None = None,
    content: str | None = None,
) -> list[Section]:
    """Return all the sections that match the criteria.

    Args:

        style -- str

        content -- str regex

    Returns: list of Section
    """
    return self._filtered_elements(
        "text:section", text_style=style, content=content
    )  # type: ignore[return-value]

get_span

get_span(
    position: int = 0, content: str | None = None
) -> Span | None

Return the span that matches the criteria.

Args:

position -- int

content -- str regex

Returns: Span or None if not found

Source code in odfdo/element.py

def get_span(
    self,
    position: int = 0,
    content: str | None = None,
) -> Span | None:
    """Return the span that matches the criteria.

    Args:

        position -- int

        content -- str regex

    Returns: Span or None if not found
    """
    return self._filtered_element(
        "descendant::text:span", position, content=content
    )  # type: ignore[return-value]

get_spans

get_spans(
    style: str | None = None, content: str | None = None
) -> list[Span]

Return all the spans that match the criteria.

Args:

style -- str

content -- str regex

Returns: list of Span

Source code in odfdo/element.py

def get_spans(
    self,
    style: str | None = None,
    content: str | None = None,
) -> list[Span]:
    """Return all the spans that match the criteria.

    Args:

        style -- str

        content -- str regex

    Returns: list of Span
    """
    return self._filtered_elements(
        "descendant::text:span", text_style=style, content=content
    )  # type: ignore[return-value]

get_style

get_style(
    family: str,
    name_or_element: str | Element | None = None,
    display_name: str | None = None,
) -> StyleBase | None

Return the style uniquely identified by the family/name pair. If the argument is already a style object, it will return it.

If the name is not the internal name but the name you gave in the desktop application, use display_name instead.

Args:

family -- 'paragraph', 'text', 'graphic', 'table', 'list',
          'number'

name_or_element -- str or Style

display_name -- str

Returns: Style or None if not found

Source code in odfdo/element.py

def get_style(
    self,
    family: str,
    name_or_element: str | Element | None = None,
    display_name: str | None = None,
) -> StyleBase | None:
    """Return the style uniquely identified by the family/name pair. If the
    argument is already a style object, it will return it.

    If the name is not the internal name but the name you gave in the
    desktop application, use display_name instead.

    Args:

        family -- 'paragraph', 'text', 'graphic', 'table', 'list',
                  'number'

        name_or_element -- str or Style

        display_name -- str

    Returns: Style or None if not found
    """
    if isinstance(name_or_element, Element):
        name = self.get_attribute("style:name")
        if name is not None:
            return name_or_element  # type: ignore[return-value]
        else:
            raise ValueError(f"Not a odf_style ? {name_or_element!r}")
    style_name = name_or_element
    is_default = not (style_name or display_name)
    tagname = self._get_style_tagname(family, is_default=is_default)
    # famattr became None if no "style:family" attribute
    if family:
        return self._filtered_element(
            tagname,
            0,
            style_name=style_name,
            display_name=display_name,
            family=family,
        )  # type: ignore[return-value]
    else:
        return self._filtered_element(
            tagname,
            0,
            draw_name=style_name or display_name,
            family=family,
        )  # type: ignore[return-value]

get_styled_elements

get_styled_elements(name: str = '') -> list[Element]

Brute-force to find paragraphs, tables, etc. using the given style name (or all by default).

Args:

name -- str

Returns: list of Element

Source code in odfdo/element.py

def get_styled_elements(self, name: str = "") -> list[Element]:
    """Brute-force to find paragraphs, tables, etc. using the given style
    name (or all by default).

    Args:

        name -- str

    Returns: list of Element
    """
    # FIXME incomplete (and possibly inaccurate)
    return (
        self._filtered_elements("descendant::*", text_style=name)
        + self._filtered_elements("descendant::*", draw_style=name)
        + self._filtered_elements("descendant::*", draw_text_style=name)
        + self._filtered_elements("descendant::*", table_style=name)
        + self._filtered_elements("descendant::*", page_layout=name)
        + self._filtered_elements("descendant::*", master_page=name)
        + self._filtered_elements("descendant::*", parent_style=name)
    )

get_styles

get_styles(family: str | None = None) -> list[StyleBase]

Source code in odfdo/element.py

def get_styles(self, family: str | None = None) -> list[StyleBase]:
    # Both common and default styles
    tagname = self._get_style_tagname(family)
    return self._filtered_elements(tagname, family=family)  # type: ignore[return-value]

get_text_change

get_text_change(
    position: int = 0, idx: str | None = None
) -> TextChange | TextChangeStart | None

Return the text change that matches the criteria. Either single deletion (text:change) or start of range of changes (text:change-start). position : index of the element to retrieve if several matches, default is 0. idx : change-id of the element.

Args:

position -- int

idx -- str

Returns: Element or None if not found

Source code in odfdo/element.py

def get_text_change(
    self,
    position: int = 0,
    idx: str | None = None,
) -> TextChange | TextChangeStart | None:
    """Return the text change that matches the criteria. Either single
    deletion (text:change) or start of range of changes (text:change-start).
    position : index of the element to retrieve if several matches, default
    is 0.
    idx : change-id of the element.

    Args:

        position -- int

        idx -- str

    Returns: Element or None if not found
    """
    if idx:
        request = (
            f'descendant::text:change-start[@text:change-id="{idx}"] '
            f'| descendant::text:change[@text:change-id="{idx}"]'
        )
        return self._filtered_element(request, 0)  # type: ignore[return-value]

    request = "descendant::text:change-start | descendant::text:change"
    return self._filtered_element(request, position)  # type: ignore[return-value]

get_text_change_deletion

get_text_change_deletion(
    position: int = 0, idx: str | None = None
) -> TextChange | None

Return the text change of deletion kind that matches the criteria. Search only for the tags text:change. Consider using : get_text_change()

Args:

position -- int

idx -- str

Returns: TextChange or None if not found

Source code in odfdo/element.py

def get_text_change_deletion(
    self,
    position: int = 0,
    idx: str | None = None,
) -> TextChange | None:
    """Return the text change of deletion kind that matches the criteria.
    Search only for the tags text:change.
    Consider using : get_text_change()

    Args:

        position -- int

        idx -- str

    Returns: TextChange or None if not found
    """
    return self._filtered_element(
        "descendant::text:change", position, change_id=idx
    )  # type: ignore[return-value]

get_text_change_deletions

get_text_change_deletions() -> list[TextChange]

Return all the text changes of deletion kind: the tags text:change. Consider using : get_text_changes()

Returns: list of TextChange

Source code in odfdo/element.py

def get_text_change_deletions(self) -> list[TextChange]:
    """Return all the text changes of deletion kind: the tags text:change.
    Consider using : get_text_changes()

    Returns: list of TextChange
    """
    return self._filtered_elements(
        "descendant::text:text:change",
    )  # type: ignore[return-value]

get_text_change_end

get_text_change_end(
    position: int = 0, idx: str | None = None
) -> TextChangeEnd | None

Return the text change-end that matches the criteria. Search only the tags text:change-end. Consider using : get_text_change()

Args:

position -- int

idx -- str

Returns: TextChangeEnd or None if not found

Source code in odfdo/element.py

def get_text_change_end(
    self,
    position: int = 0,
    idx: str | None = None,
) -> TextChangeEnd | None:
    """Return the text change-end that matches the criteria. Search only
    the tags text:change-end.
    Consider using : get_text_change()

    Args:

        position -- int

        idx -- str

    Returns: TextChangeEnd or None if not found
    """
    return self._filtered_element(
        "descendant::text:change-end", position, change_id=idx
    )  # type: ignore[return-value]

get_text_change_ends

get_text_change_ends() -> list[TextChangeEnd]

Return all the text change-end. Search only the tags text:change-end. Consider using : get_text_changes()

Returns: list of TextChangeEnd

Source code in odfdo/element.py

def get_text_change_ends(self) -> list[TextChangeEnd]:
    """Return all the text change-end. Search only the tags
    text:change-end.
    Consider using : get_text_changes()

    Returns: list of TextChangeEnd
    """
    return self._filtered_elements(
        "descendant::text:change-end",
    )  # type: ignore[return-value]

get_text_change_start

get_text_change_start(
    position: int = 0, idx: str | None = None
) -> TextChangeStart | None

Return the text change-start that matches the criteria. Search only the tags text:change-start. Consider using : get_text_change()

Args:

position -- int

idx -- str

Returns: TextChangeStart or None if not found

Source code in odfdo/element.py

def get_text_change_start(
    self,
    position: int = 0,
    idx: str | None = None,
) -> TextChangeStart | None:
    """Return the text change-start that matches the criteria. Search
    only the tags text:change-start.
    Consider using : get_text_change()

    Args:

        position -- int

        idx -- str

    Returns: TextChangeStart or None if not found
    """
    return self._filtered_element(
        "descendant::text:change-start", position, change_id=idx
    )  # type: ignore[return-value]

get_text_change_starts

get_text_change_starts() -> list[TextChangeStart]

Return all the text change-start. Search only for the tags text:change-start. Consider using : get_text_changes()

Returns: list of TextChangeStart

Source code in odfdo/element.py

def get_text_change_starts(self) -> list[TextChangeStart]:
    """Return all the text change-start. Search only for the tags
    text:change-start.
    Consider using : get_text_changes()

    Returns: list of TextChangeStart
    """
    return self._filtered_elements(
        "descendant::text:change-start",
    )  # type: ignore[return-value]

get_text_changes

get_text_changes() -> list[TextChange | TextChangeStart]

Return all the text changes, either single deletion (text:change) or start of range of changes (text:change-start).

Returns: list of TextChange or TextChangeStart

Source code in odfdo/element.py

def get_text_changes(self) -> list[TextChange | TextChangeStart]:
    """Return all the text changes, either single deletion (text:change) or
    start of range of changes (text:change-start).

    Returns: list of TextChange or TextChangeStart
    """
    request = "descendant::text:change-start | descendant::text:change"
    return self._filtered_elements(request)  # type: ignore[return-value]

get_toc

get_toc(
    position: int = 0, content: str | None = None
) -> TOC | None

Return the table of contents that matches the criteria.

Args:

position -- int

content -- str regex

Returns: TOC or None if not found

Source code in odfdo/element.py

def get_toc(
    self,
    position: int = 0,
    content: str | None = None,
) -> TOC | None:
    """Return the table of contents that matches the criteria.

    Args:

        position -- int

        content -- str regex

    Returns: TOC or None if not found
    """
    return self._filtered_element(
        "text:table-of-content", position, content=content
    )  # type: ignore[return-value]

get_tocs

get_tocs() -> list[TOC]

Return all the tables of contents.

Returns: list of TOC

Source code in odfdo/element.py

def get_tocs(self) -> list[TOC]:
    """Return all the tables of contents.

    Returns: list of TOC
    """
    return self.get_elements("text:table-of-content")  # type: ignore[return-value]

get_tracked_changes

get_tracked_changes() -> TrackedChanges | None

Return the tracked-changes part in the text body.

Returns: TrackedChanges or None

Source code in odfdo/element.py

def get_tracked_changes(self) -> TrackedChanges | None:
    """Return the tracked-changes part in the text body.

    Returns: TrackedChanges or None
    """
    return self.get_element("//text:tracked-changes")  # type: ignore[return-value]

get_user_defined

get_user_defined(
    name: str, position: int = 0
) -> UserDefined | None

Return the user defined declaration for the given name.

Returns: UserDefined or none if not found

Source code in odfdo/element.py

def get_user_defined(self, name: str, position: int = 0) -> UserDefined | None:
    """Return the user defined declaration for the given name.

    Returns: UserDefined or none if not found
    """
    return self._filtered_element(
        "descendant::text:user-defined", position, text_name=name
    )  # type: ignore[return-value]

get_user_defined_list

get_user_defined_list() -> list[UserDefined]

Return all the user defined field declarations.

Returns: list of UserDefined

Source code in odfdo/element.py

def get_user_defined_list(self) -> list[UserDefined]:
    """Return all the user defined field declarations.

    Returns: list of UserDefined
    """
    return self._filtered_elements(
        "descendant::text:user-defined",
    )  # type: ignore[return-value]

get_user_defined_value

get_user_defined_value(
    name: str, value_type: str | None = None
) -> (
    bool
    | str
    | int
    | float
    | Decimal
    | datetime
    | timedelta
    | None
)

Return the value of the given user defined field name.

Args:

name -- str

value_type -- 'boolean', 'date', 'float',
              'string', 'time' or automatic

Returns: most appropriate Python type

Source code in odfdo/element.py

def get_user_defined_value(
    self, name: str, value_type: str | None = None
) -> bool | str | int | float | Decimal | datetime | timedelta | None:
    """Return the value of the given user defined field name.

    Args:

        name -- str

        value_type -- 'boolean', 'date', 'float',
                      'string', 'time' or automatic

    Returns: most appropriate Python type
    """
    user_defined = self.get_user_defined(name)
    if user_defined is None:
        return None
    return user_defined.get_value(value_type)  # type: ignore[return-value]

get_user_field_decl

get_user_field_decl(
    name: str, position: int = 0
) -> UserFieldDecl | None

Return the user field declaration for the given name.

Returns: UserFieldDecl or none if not found

Source code in odfdo/element.py

def get_user_field_decl(self, name: str, position: int = 0) -> UserFieldDecl | None:
    """Return the user field declaration for the given name.

    Returns: UserFieldDecl or none if not found
    """
    return self._filtered_element(
        "descendant::text:user-field-decl", position, text_name=name
    )  # type: ignore[return-value]

get_user_field_decl_list

get_user_field_decl_list() -> list[UserFieldDecl]

Return all the user field declarations.

Returns: list of UserFieldDecl

Source code in odfdo/element.py

def get_user_field_decl_list(self) -> list[UserFieldDecl]:
    """Return all the user field declarations.

    Returns: list of UserFieldDecl
    """
    return self._filtered_elements(
        "descendant::text:user-field-decl",
    )  # type: ignore[return-value]

get_user_field_decls

get_user_field_decls() -> UserFieldDecls | None

Return the container for user field declarations. Created if not found.

Returns: UserFieldDecls

Source code in odfdo/element.py

def get_user_field_decls(self) -> UserFieldDecls | None:
    """Return the container for user field declarations. Created if not
    found.

    Returns: UserFieldDecls
    """
    user_field_decls = self.get_element("//text:user-field-decls")
    if user_field_decls is None:
        body = self.document_body
        if not body:
            raise ValueError("Empty document.body")
        body.insert(Element.from_tag("text:user-field-decls"), FIRST_CHILD)
        user_field_decls = body.get_element("//text:user-field-decls")

    return user_field_decls  # type: ignore[return-value]

get_user_field_value

get_user_field_value(
    name: str, value_type: str | None = None
) -> (
    bool
    | str
    | int
    | float
    | Decimal
    | datetime
    | timedelta
    | None
)

Return the value of the given user field name.

Args:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Returns: most appropriate Python type

Source code in odfdo/element.py

def get_user_field_value(
    self, name: str, value_type: str | None = None
) -> bool | str | int | float | Decimal | datetime | timedelta | None:
    """Return the value of the given user field name.

    Args:

        name -- str

        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic

    Returns: most appropriate Python type
    """
    user_field_decl = self.get_user_field_decl(name)
    if user_field_decl is None:
        return None
    value = user_field_decl.get_value(value_type)
    return value  # type: ignore[return-value]

get_variable_decl

get_variable_decl(
    name: str, position: int = 0
) -> VarDecls | None

Return the variable declaration for the given name.

Args:

name -- str

position -- int

Returns: VarDecls or none if not found

Source code in odfdo/element.py

def get_variable_decl(self, name: str, position: int = 0) -> VarDecls | None:
    """Return the variable declaration for the given name.

    Args:

        name -- str

        position -- int

    Returns: VarDecls or none if not found
    """
    return self._filtered_element(
        "descendant::text:variable-decl", position, text_name=name
    )  # type: ignore[return-value]

get_variable_decl_list

get_variable_decl_list() -> list[VarDecls]

Return all the variable declarations.

Returns: list of VarDecls

Source code in odfdo/element.py

def get_variable_decl_list(self) -> list[VarDecls]:
    """Return all the variable declarations.

    Returns: list of VarDecls
    """
    return self._filtered_elements(
        "descendant::text:variable-decl",
    )  # type: ignore[return-value]

get_variable_decls

get_variable_decls() -> VarDecls

Return the container for variable declarations. Created if not found.

Returns: VarDecls

Source code in odfdo/element.py

def get_variable_decls(self) -> VarDecls:
    """Return the container for variable declarations. Created if not
    found.

    Returns: VarDecls
    """
    variable_decls = self.get_element("//text:variable-decls")
    if variable_decls is None:
        body = self.document_body
        if not body:
            raise ValueError("Empty document.body")
        body.insert(Element.from_tag("text:variable-decls"), FIRST_CHILD)
        variable_decls = body.get_element("//text:variable-decls")

    return variable_decls  # type: ignore[return-value]

get_variable_set

get_variable_set(
    name: str, position: int = -1
) -> VarSet | None

Return the variable set for the given name (last one by default).

Args:

name -- str

position -- int

Returns: VarSet or None if not found

Source code in odfdo/element.py

def get_variable_set(self, name: str, position: int = -1) -> VarSet | None:
    """Return the variable set for the given name (last one by default).

    Args:

        name -- str

        position -- int

    Returns: VarSet or None if not found
    """
    return self._filtered_element(
        "descendant::text:variable-set", position, text_name=name
    )  # type: ignore[return-value]

get_variable_set_value

get_variable_set_value(
    name: str, value_type: str | None = None
) -> (
    bool
    | str
    | int
    | float
    | Decimal
    | datetime
    | timedelta
    | None
)

Return the last value of the given variable name.

Args:

name -- str

value_type -- 'boolean', 'currency', 'date', 'float',
              'percentage', 'string', 'time' or automatic

Returns: most appropriate Python type

Source code in odfdo/element.py

def get_variable_set_value(
    self,
    name: str,
    value_type: str | None = None,
) -> bool | str | int | float | Decimal | datetime | timedelta | None:
    """Return the last value of the given variable name.

    Args:

        name -- str

        value_type -- 'boolean', 'currency', 'date', 'float',
                      'percentage', 'string', 'time' or automatic

    Returns: most appropriate Python type
    """
    variable_set = self.get_variable_set(name)
    if not variable_set:
        return None
    return variable_set.get_value(value_type)  # type: ignore[return-value]

get_variable_sets

get_variable_sets(name: str | None = None) -> list[VarSet]

Return all the variable sets that match the criteria.

Args:

name -- str

Returns: list of VarSet

Source code in odfdo/element.py

def get_variable_sets(self, name: str | None = None) -> list[VarSet]:
    """Return all the variable sets that match the criteria.

    Args:

        name -- str

    Returns: list of VarSet
    """
    return self._filtered_elements(
        "descendant::text:variable-set",
        text_name=name,
    )  # type: ignore[return-value]

index

index(child: Element) -> int

Return the position of the child in this element.

Inspired by lxml.

Source code in odfdo/element.py

def index(self, child: Element) -> int:
    """Return the position of the child in this element.

    Inspired by lxml.
    """
    idx: int = self.__element.index(child.__element)
    return idx

insert

insert(
    element: Element,
    xmlposition: int | None = None,
    position: int | None = None,
    start: bool = False,
) -> None

Insert an element relatively to ourself.

Insert either using DOM vocabulary or by numeric position. If “start” is True, insert the element before any existing text.

Position start at 0.

Args:

element -- Element

xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
               or PREV_SIBLING

start -- Boolean

position -- int

Source code in odfdo/element.py

def insert(
    self,
    element: Element,
    xmlposition: int | None = None,
    position: int | None = None,
    start: bool = False,
) -> None:
    """Insert an element relatively to ourself.

    Insert either using DOM vocabulary or by numeric position.
    If "start" is True, insert the element before any existing text.

    Position start at 0.

    Args:

        element -- Element

        xmlposition -- FIRST_CHILD, LAST_CHILD, NEXT_SIBLING
                       or PREV_SIBLING

        start -- Boolean

        position -- int
    """
    # child_tag = element.tag
    current = self.__element
    lx_element = element.__element
    if start:
        text = current.text
        if text is not None:
            current.text = None
            tail = lx_element.tail
            if tail is None:
                tail = text
            else:
                tail = tail + text
            lx_element.tail = tail
        position = 0
    if position is not None:
        current.insert(position, lx_element)
    elif xmlposition is FIRST_CHILD:
        current.insert(0, lx_element)
    elif xmlposition is LAST_CHILD:
        current.append(lx_element)
    elif xmlposition is NEXT_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index + 1, lx_element)
    elif xmlposition is PREV_SIBLING:
        parent = current.getparent()
        index = parent.index(current)
        parent.insert(index, lx_element)
    else:
        raise ValueError("(xml)position must be defined")

is_empty

is_empty() -> bool

Check if the element is empty : no text, no children, no tail.

Returns: Boolean

Source code in odfdo/element.py

def is_empty(self) -> bool:
    """Check if the element is empty : no text, no children, no tail.

    Returns: Boolean
    """
    element = self.__element
    if element.tail is not None:
        return False
    if element.text is not None:
        return False
    if list(element.iterchildren()):  # noqa: SIM103
        return False
    return True

match

match(pattern: str) -> bool

Return True if the pattern is found one or more times anywhere in the text content of the element.

Python regular expression syntax applies.

Args:

pattern -- str

Returns: bool

Source code in odfdo/element.py

def match(self, pattern: str) -> bool:
    """Return True if the pattern is found one or more times anywhere in
    the text content of the element.

    Python regular expression syntax applies.

    Args:

        pattern -- str

    Returns: bool
    """
    return self.search(pattern) is not None

replace

replace(
    pattern: str,
    new: str | None = None,
    formatted: bool = False,
) -> int

Replace the pattern with the given text, or delete if text is an empty string, and return the number of replacements. By default, only return the number of occurrences that would be replaced.

It cannot replace patterns found across several element, like a word split into two consecutive spans.

Python regular expression syntax applies.

If formatted is True, and the target is a Paragraph, Span or Header, and the replacement text contains spaces, tabs or newlines, try to convert them into actual ODF elements to obtain a formatted result. On very complex contents, result may differ of expectations.

Args:

pattern -- str

new -- str

formatted -- bool

Returns: int

Source code in odfdo/element.py

def replace(
    self,
    pattern: str,
    new: str | None = None,
    formatted: bool = False,
) -> int:
    """Replace the pattern with the given text, or delete if text is an
    empty string, and return the number of replacements. By default, only
    return the number of occurrences that would be replaced.

    It cannot replace patterns found across several element, like a word
    split into two consecutive spans.

    Python regular expression syntax applies.

    If formatted is True, and the target is a Paragraph, Span or Header,
    and the replacement text contains spaces, tabs or newlines, try to
    convert them into actual ODF elements to obtain a formatted result.
    On very complex contents, result may differ of expectations.

    Args:

        pattern -- str

        new -- str

        formatted -- bool

    Returns: int
    """
    if not isinstance(pattern, str):
        # Fail properly if the pattern is an non-ascii bytestring
        pattern = str(pattern)
    cpattern = re.compile(pattern)
    count = 0
    for text in self.xpath("descendant::text()"):
        if new is None:
            count += len(cpattern.findall(str(text)))
        else:
            new_text, number = cpattern.subn(new, str(text))
            container = text.parent
            if not container:  # pragma: nocover
                continue
            if text.is_text():  # type: ignore
                container.text = new_text
            else:
                container.tail = new_text
            if formatted and container.tag in {  # type; ignore
                "text:h",
                "text:p",
                "text:span",
            }:
                container.append_plain_text("")  # type: ignore[attr-defined]
            count += number
    return count

replace_element

replace_element(
    old_element: Element, new_element: Element
) -> None

Replaces in place a sub element with the element passed as second argument.

Warning : no clone for old element.

Source code in odfdo/element.py

def replace_element(self, old_element: Element, new_element: Element) -> None:
    """Replaces in place a sub element with the element passed as second
    argument.

    Warning : no clone for old element.
    """
    current = self.__element
    current.replace(old_element.__element, new_element.__element)

search

search(pattern: str) -> int | None

Return the first position of the pattern in the text content of the element, or None if not found.

Python regular expression syntax applies.

Args:

pattern -- str

Returns: int or None

Source code in odfdo/element.py

def search(self, pattern: str) -> int | None:
    """Return the first position of the pattern in the text content of the
    element, or None if not found.

    Python regular expression syntax applies.

    Args:

        pattern -- str

    Returns: int or None
    """
    match = re.search(pattern, self.text_recursive)
    if match is None:
        return None
    return match.start()

search_all

search_all(pattern: str) -> list[tuple[int, int]]

Return all start and end positions of the regex pattern in the text content of the element.

Result is a list of tuples of start and end position of the matches. Python regular expression syntax applies.

Args:

pattern -- str

Returns: list[tuple[int,int]]

Source code in odfdo/element.py

def search_all(self, pattern: str) -> list[tuple[int, int]]:
    """Return all start and end positions of the regex pattern in the text
    content of the element.

    Result is a list of tuples of start and end position of
    the matches.
    Python regular expression syntax applies.

    Args:

        pattern -- str

    Returns: list[tuple[int,int]]
    """
    results: list[tuple[int, int]] = []
    for match in re.finditer(pattern, self.text_recursive):
        results.append((match.start(), match.end()))
    return results

search_first

search_first(pattern: str) -> tuple[int, int] | None

Return the start and end position of the first occurrence of the regex pattern in the text content of the element.

Result is tuples of start and end position, or None. Python regular expression syntax applies.

Args:

pattern -- str

Returns: tuple[int,int] or None

Source code in odfdo/element.py

def search_first(self, pattern: str) -> tuple[int, int] | None:
    """Return the start and end position of the first occurrence of the
    regex pattern in the text content of the element.

    Result is tuples of start and end position, or None.
    Python regular expression syntax applies.

    Args:

        pattern -- str

    Returns: tuple[int,int] or None
    """
    match = re.search(pattern, self.text_recursive)
    if match is None:
        return None
    return match.start(), match.end()

serialize

serialize(
    pretty: bool = False, with_ns: bool = False
) -> str

Return text serialization of XML element.

Source code in odfdo/element.py

def serialize(self, pretty: bool = False, with_ns: bool = False) -> str:
    """Return text serialization of XML element."""
    # This copy bypasses serialization side-effects in lxml
    native = deepcopy(self.__element)
    data: str = tostring(
        native, with_tail=False, pretty_print=pretty, encoding="unicode"
    )
    if with_ns:
        return data
    # Remove namespaces
    return self._strip_namespaces(data)

set_attribute

set_attribute(
    name: str,
    value: bool | str | tuple[int, int, int] | None,
) -> None

Source code in odfdo/element.py

def set_attribute(
    self, name: str, value: bool | str | tuple[int, int, int] | None
) -> None:
    if name in ODF_COLOR_PROPERTY:
        if isinstance(value, bool):
            raise TypeError(f"Wrong color type {value!r}")
        if value != "transparent":
            value = hexa_color(value)
    element = self.__element
    lxml_tag = _get_lxml_tag_or_name(name)
    if isinstance(value, bool):
        value = Boolean.encode(value)
    elif value is None:
        with contextlib.suppress(KeyError):
            del element.attrib[lxml_tag]
        return
    element.set(lxml_tag, str(value))

set_style_attribute

set_style_attribute(
    name: str, value: Style | str | None
) -> None

Shortcut to accept a style object as a value.

Source code in odfdo/element.py

def set_style_attribute(self, name: str, value: Style | str | None) -> None:
    """Shortcut to accept a style object as a value."""
    if isinstance(value, Element):
        value = str(value.name)
    return self.set_attribute(name, value)

text_at

text_at(start: int, end: int | None = None) -> str

Return the text (recursive) content of the element between start and end position.

If the end parameter is not set, return from start to the end of the recursive text.

Args:

start -- int
end -- int or None

Returns: str

Source code in odfdo/element.py

def text_at(self, start: int, end: int | None = None) -> str:
    """Return the text (recursive) content of the element between start and
    end position.

    If the end parameter is not set, return from start to the end
    of the recursive text.

    Args:

        start -- int
        end -- int or None

    Returns: str
    """
    if start < 0:
        start = 0
    if end is None:
        return self.text_recursive[start:]
    else:
        if end < start:
            end = start
        return self.text_recursive[start:end]

xpath

xpath(xpath_query: str) -> list[Element | EText]

Apply XPath query to the element and its subtree.

Return list of Element or EText instances.

Source code in odfdo/element.py

def xpath(self, xpath_query: str) -> list[Element | EText]:
    """Apply XPath query to the element and its subtree.

    Return list of Element or EText instances.
    """
    xpath_instance = xpath_compile(xpath_query)
    x_elements = xpath_instance(self.__element)
    result: list[Element | EText] = []
    if isinstance(x_elements, list):
        for obj in x_elements:
            if isinstance(obj, (str, bytes)):
                result.append(EText(obj))
            elif isinstance(obj, _Element):  # pragma: nocover
                result.append(Element.from_tag(obj))
    return result

ElementTyped

Bases: Element

Subclass of Element for classes managing typed values.

Methods:

Name	Description
get_value	Return Python typed value.
set_value_and_type

Source code in odfdo/element_typed.py

class ElementTyped(Element):
    """Subclass of Element for classes managing typed values."""

    def _erase_text_content(self) -> None:
        paragraphs = self.get_elements("text:p")
        if not paragraphs:
            # E.g., text:p in draw:text-box in draw:frame
            paragraphs = self.get_elements("*/text:p")
        if paragraphs:
            paragraphs.pop(0)
            for obsolete in paragraphs:
                obsolete.delete()

    def set_value_and_type(
        self,
        value: Any,
        value_type: str | None = None,
        text: str | None = None,
        currency: str | None = None,
    ) -> str | None:
        # Remove possible previous value and type
        for name in (
            "office:value-type",
            "office:boolean-value",
            "office:value",
            "office:date-value",
            "office:string-value",
            "office:time-value",
            "table:formula",
            "office:currency",
            "calcext:value-type",
            "loext:value-type",
        ):
            with contextlib.suppress(KeyError):
                self.del_attribute(name)
        if isinstance(value, bytes):
            value = bytes_to_str(value)
        if isinstance(value_type, bytes):
            value_type = bytes_to_str(value_type)
        if isinstance(text, bytes):
            text = bytes_to_str(text)
        if isinstance(currency, bytes):
            currency = bytes_to_str(currency)
        if value is None:
            self._erase_text_content()
            return text
        if isinstance(value, bool):
            if value_type is None:
                value_type = "boolean"
            if text is None:
                text = "true" if value else "false"
            value = Boolean.encode(value)
        elif isinstance(value, (int, float, Decimal)):
            if value_type == "percentage":
                text = f"{int(value * 100)} %"
            if value_type is None:
                value_type = "float"
            if text is None:
                text = str(value)
            value = str(value)
        elif isinstance(value, datetime):
            if value_type is None:
                value_type = "date"
            if text is None:
                text = str(DateTime.encode(value))
            value = DateTime.encode(value)
        elif isinstance(value, date):
            if value_type is None:
                value_type = "date"
            if text is None:
                text = str(Date.encode(value))
            value = Date.encode(value)
        elif isinstance(value, str):
            if value_type is None:
                value_type = "string"
            if text is None:
                text = value
        elif isinstance(value, timedelta):
            if value_type is None:
                value_type = "time"
            if text is None:
                text = str(Duration.encode(value))
            value = Duration.encode(value)
        else:
            raise TypeError(f"Type unknown: '{value!r}'")

        if isinstance(value_type, str):
            self.set_attribute("office:value-type", value_type)
            self.set_attribute("calcext:value-type", value_type)
        if value_type == "boolean":
            self.set_attribute("office:boolean-value", value)
        elif value_type == "currency":
            self.set_attribute("office:value", value)
            self.set_attribute("office:currency", currency)
        elif value_type == "date":
            self.set_attribute("office:date-value", value)
        elif value_type in ("float", "percentage"):
            self.set_attribute("office:value", value)
            self.set_attribute("calcext:value", value)
        elif value_type == "string":
            self.set_attribute("office:string-value", value)
        elif value_type == "time":
            self.set_attribute("office:time-value", value)

        return text

    def _get_typed_value_boolean(self) -> Any:
        return self.get_attribute("office:boolean-value")

    def _get_typed_value_number_type(self) -> Decimal | int | float:
        read_number = self.get_attribute_string("office:value")
        if read_number is None:
            raise ValueError('"office:value" has None value')
        value = Decimal(read_number)
        # Return 3 instead of 3.0 if possible
        with contextlib.suppress(ValueError):
            if int(value) == value:
                return int(value)
        return value

    def _get_typed_value_float(self) -> Decimal | int | float:
        return self._get_typed_value_number_type()

    def _get_typed_value_percentage(self) -> Decimal | int | float:
        return self._get_typed_value_number_type()

    def _get_typed_value_currency(self) -> Decimal | int | float:
        return self._get_typed_value_number_type()

    def _get_typed_value_date(self) -> date | datetime:
        read_attribute = self.get_attribute_string("office:date-value")
        if read_attribute is None:
            raise ValueError('"office:date-value" has None value')
        if "T" in read_attribute:
            return DateTime.decode(read_attribute)
        return Date.decode(read_attribute)

    def _get_typed_value_string(self, try_get_text: bool) -> str | None:
        value = self.get_attribute_string("office:string-value")
        if value is not None:
            return str(value)
        if try_get_text:
            list_value = [para.inner_text for para in self.get_elements("text:p")]
            if list_value:
                return "\n".join(list_value)
        return None

    def _get_typed_value_time(self) -> timedelta:
        read_value = self.get_attribute_string("office:time-value")
        if read_value is None:
            raise ValueError('"office:time-value" has None value')
        return Duration.decode(read_value)

    def _get_typed_value(
        self,
        value_type: str = "",
        try_get_text: bool = True,
    ) -> Any:
        """Return Python typed value.

        Only for "with office:value-type" elements, not for meta fields.
        """
        if value_type == "string":
            return self._get_typed_value_string(try_get_text)
        method = getattr(self, f"_get_typed_value_{value_type}", None)
        if method is None:
            raise TypeError(f"Unexpected value type: {value_type}")
        return method()

    def _get_value_and_type(
        self, value_type: str | None = None, try_get_text: bool = True
    ) -> tuple[Any, str | None]:
        if value_type is None:
            read_value_type = self.get_attribute_string("office:value-type")
            if read_value_type is None:
                return None, None
            value_type = read_value_type
        return (
            self._get_typed_value(
                value_type=value_type,
                try_get_text=try_get_text,
            ),
            value_type,
        )

    def get_value(
        self,
        value_type: str | None = None,
        try_get_text: bool = True,
        get_type: bool = False,
    ) -> Any | tuple[Any, str]:
        """Return Python typed value.

        Only for "with office:value-type" elements, not for meta fields.
        """
        value, actual_type = self._get_value_and_type(
            value_type=value_type, try_get_text=try_get_text
        )
        if get_type:
            return (value, actual_type)
        return value

get_value

get_value(
    value_type: str | None = None,
    try_get_text: bool = True,
    get_type: bool = False,
) -> Any | tuple[Any, str]

Return Python typed value.

Only for “with office:value-type” elements, not for meta fields.

Source code in odfdo/element_typed.py

def get_value(
    self,
    value_type: str | None = None,
    try_get_text: bool = True,
    get_type: bool = False,
) -> Any | tuple[Any, str]:
    """Return Python typed value.

    Only for "with office:value-type" elements, not for meta fields.
    """
    value, actual_type = self._get_value_and_type(
        value_type=value_type, try_get_text=try_get_text
    )
    if get_type:
        return (value, actual_type)
    return value

set_value_and_type

set_value_and_type(
    value: Any,
    value_type: str | None = None,
    text: str | None = None,
    currency: str | None = None,
) -> str | None

Source code in odfdo/element_typed.py

def set_value_and_type(
    self,
    value: Any,
    value_type: str | None = None,
    text: str | None = None,
    currency: str | None = None,
) -> str | None:
    # Remove possible previous value and type
    for name in (
        "office:value-type",
        "office:boolean-value",
        "office:value",
        "office:date-value",
        "office:string-value",
        "office:time-value",
        "table:formula",
        "office:currency",
        "calcext:value-type",
        "loext:value-type",
    ):
        with contextlib.suppress(KeyError):
            self.del_attribute(name)
    if isinstance(value, bytes):
        value = bytes_to_str(value)
    if isinstance(value_type, bytes):
        value_type = bytes_to_str(value_type)
    if isinstance(text, bytes):
        text = bytes_to_str(text)
    if isinstance(currency, bytes):
        currency = bytes_to_str(currency)
    if value is None:
        self._erase_text_content()
        return text
    if isinstance(value, bool):
        if value_type is None:
            value_type = "boolean"
        if text is None:
            text = "true" if value else "false"
        value = Boolean.encode(value)
    elif isinstance(value, (int, float, Decimal)):
        if value_type == "percentage":
            text = f"{int(value * 100)} %"
        if value_type is None:
            value_type = "float"
        if text is None:
            text = str(value)
        value = str(value)
    elif isinstance(value, datetime):
        if value_type is None:
            value_type = "date"
        if text is None:
            text = str(DateTime.encode(value))
        value = DateTime.encode(value)
    elif isinstance(value, date):
        if value_type is None:
            value_type = "date"
        if text is None:
            text = str(Date.encode(value))
        value = Date.encode(value)
    elif isinstance(value, str):
        if value_type is None:
            value_type = "string"
        if text is None:
            text = value
    elif isinstance(value, timedelta):
        if value_type is None:
            value_type = "time"
        if text is None:
            text = str(Duration.encode(value))
        value = Duration.encode(value)
    else:
        raise TypeError(f"Type unknown: '{value!r}'")

    if isinstance(value_type, str):
        self.set_attribute("office:value-type", value_type)
        self.set_attribute("calcext:value-type", value_type)
    if value_type == "boolean":
        self.set_attribute("office:boolean-value", value)
    elif value_type == "currency":
        self.set_attribute("office:value", value)
        self.set_attribute("office:currency", currency)
    elif value_type == "date":
        self.set_attribute("office:date-value", value)
    elif value_type in ("float", "percentage"):
        self.set_attribute("office:value", value)
        self.set_attribute("calcext:value", value)
    elif value_type == "string":
        self.set_attribute("office:string-value", value)
    elif value_type == "time":
        self.set_attribute("office:time-value", value)

    return text

EllipseShape

Bases: ShapeBase

An ellipse shape, “draw:ellipse”.

Methods:

Name	Description
__init__	Create a ellipse shape “draw:ellipse”.

Source code in odfdo/shapes.py

class EllipseShape(ShapeBase):
    """An ellipse shape, "draw:ellipse"."""

    _tag = "draw:ellipse"
    _properties: tuple[PropDef, ...] = ()

    def __init__(
        self,
        style: str | None = None,
        text_style: str | None = None,
        draw_id: str | None = None,
        layer: str | None = None,
        position: tuple | None = None,
        size: tuple | None = None,
        **kwargs: Any,
    ) -> None:
        """Create a ellipse shape "draw:ellipse".

        Args:

            style -- str

            text_style -- str

            draw_id -- str

            layer -- str

            position -- (str, str)

            size -- (str, str)
        """
        kwargs.update(
            {
                "style": style,
                "text_style": text_style,
                "draw_id": draw_id,
                "layer": layer,
                "size": size,
                "position": position,
            }
        )
        super().__init__(**kwargs)

__init__

__init__(
    style: str | None = None,
    text_style: str | None = None,
    draw_id: str | None = None,
    layer: str | None = None,
    position: tuple | None = None,
    size: tuple | None = None,
    **kwargs: Any,
) -> None

Create a ellipse shape “draw:ellipse”.

Args:

style -- str

text_style -- str

draw_id -- str

layer -- str

position -- (str, str)

size -- (str, str)

Source code in odfdo/shapes.py

def __init__(
    self,
    style: str | None = None,
    text_style: str | None = None,
    draw_id: str | None = None,
    layer: str | None = None,
    position: tuple | None = None,
    size: tuple | None = None,
    **kwargs: Any,
) -> None:
    """Create a ellipse shape "draw:ellipse".

    Args:

        style -- str

        text_style -- str

        draw_id -- str

        layer -- str

        position -- (str, str)

        size -- (str, str)
    """
    kwargs.update(
        {
            "style": style,
            "text_style": text_style,
            "draw_id": draw_id,
            "layer": layer,
            "size": size,
            "position": position,
        }
    )
    super().__init__(**kwargs)

Frame

Bases: MDDrawFrame, Element, AnchorMix, PosMix, ZMix, SizeMix

ODF Frame, “draw:frame”.

Frames are not useful by themselves. Consider calling Frame.image_frame() or Frame.text_frame directly.

Methods:

Name	Description
__init__	ODF Frame, “draw:frame”.
get_formatted_text
get_image
get_text_box
image_frame	Create a ready-to-use image, since image must be embedded in a
set_image
set_text_box
text_frame	Create a ready-to-use text box, since text box must be embedded in a

Attributes:

Name	Type	Description
anchor_page
anchor_type
draw_id
layer
name
position
presentation_class
presentation_style
size
style
text_content	str
z_index

Source code in odfdo/frame.py

class Frame(MDDrawFrame, Element, AnchorMix, PosMix, ZMix, SizeMix):
    """ODF Frame, "draw:frame".

    Frames are not useful by themselves. Consider calling Frame.image_frame()
    or Frame.text_frame directly.
    """

    _tag = "draw:frame"
    _properties = (
        PropDef("name", "draw:name"),
        PropDef("draw_id", "draw:id"),
        PropDef("width", "svg:width"),
        PropDef("height", "svg:height"),
        PropDef("style", "draw:style-name"),
        PropDef("pos_x", "svg:x"),
        PropDef("pos_y", "svg:y"),
        PropDef("presentation_class", "presentation:class"),
        PropDef("layer", "draw:layer"),
        PropDef("presentation_style", "presentation:style-name"),
    )

    def __init__(
        self,
        name: str | None = None,
        draw_id: str | None = None,
        style: str | None = None,
        position: tuple | None = None,
        size: tuple = ("1cm", "1cm"),
        z_index: int = 0,
        presentation_class: str | None = None,
        anchor_type: str | None = None,
        anchor_page: int | None = None,
        layer: str | None = None,
        presentation_style: str | None = None,
        **kwargs: Any,
    ) -> None:
        """ODF Frame, "draw:frame".

        Frames are not useful by themselves. Consider calling
        Frame.image_frame() or Frame.text_frame directly.

        Create a frame element of the given size. Position is relative to the
        context the frame is inserted in. If positioned by page, give the page
        number and the x, y position.

        Size is a (width, height) tuple and position is a (left, top) tuple; items
        are strings including the unit, e.g. ('10cm', '15cm').

        Frames are not useful by themselves. You should consider calling:
            Frame.image_frame()
        or
            Frame.text_frame()


        Args:

            name -- str

            draw_id -- str

            style -- str

            position -- (str, str)

            size -- (str, str)

            z_index -- int (default 0)

            presentation_class -- str

            anchor_type -- 'page', 'frame', 'paragraph', 'char' or 'as-char'

            anchor_page -- int, page number is anchor_type is 'page'

            layer -- str

            presentation_style -- str
        """
        super().__init__(**kwargs)
        if self._do_init:
            self.size = size
            self.z_index = z_index
            if name:
                self.name = name
            if draw_id is not None:
                self.draw_id = draw_id
            if style is not None:
                self.style = style
            if position is not None:
                self.position = position
            if presentation_class is not None:
                self.presentation_class = presentation_class
            if anchor_type:
                self.anchor_type = anchor_type
            if position and not anchor_type:
                self.anchor_type = "paragraph"
            if anchor_page is not None:
                self.anchor_page = anchor_page
            if layer is not None:
                self.layer = layer
            if presentation_style is not None:
                self.presentation_style = presentation_style

    @classmethod
    def image_frame(
        cls,
        image: DrawImage | str,
        text: str | None = None,
        name: str | None = None,
        draw_id: str | None = None,
        style: str | None = None,
        position: tuple | None = None,
        size: tuple = ("1cm", "1cm"),
        z_index: int = 0,
        presentation_class: str | None = None,
        anchor_type: str | None = None,
        anchor_page: int | None = None,
        layer: str | None = None,
        presentation_style: str | None = None,
        **kwargs: Any,
    ) -> Element:
        """Create a ready-to-use image, since image must be embedded in a
        frame.

        The optional text will appear above the image.

        Args:

            image -- DrawImage or str, DrawImage element or URL of the image

            text -- str, text for the image

            See Frame() initialization for the other arguments

        Returns: Frame
        """
        frame = cls(
            name=name,
            draw_id=draw_id,
            style=style,
            position=position,
            size=size,
            z_index=z_index,
            presentation_class=presentation_class,
            anchor_type=anchor_type,
            anchor_page=anchor_page,
            layer=layer,
            presentation_style=presentation_style,
            **kwargs,
        )
        image_element = frame.set_image(image)
        if text:
            image_element.text_content = text
        return frame

    @classmethod
    def text_frame(
        cls,
        text_or_element: Iterable[Element] | Element | str,
        text_style: str | None = None,
        name: str | None = None,
        draw_id: str | None = None,
        style: str | None = None,
        position: tuple | None = None,
        size: tuple = ("1cm", "1cm"),
        z_index: int = 0,
        presentation_class: str | None = None,
        anchor_type: str | None = None,
        anchor_page: int | None = None,
        layer: str | None = None,
        presentation_style: str | None = None,
        **kwargs: Any,
    ) -> Element:
        """Create a ready-to-use text box, since text box must be embedded in a
        frame.

        The optional text will appear above the image.

        Args:

            text_or_element -- str or Element, or list of them, text content
                               of the text box.

            text_style -- str, name of the style for the text

            See Frame() initialization for the other arguments

        Returns: Frame
        """
        frame = cls(
            name=name,
            draw_id=draw_id,
            style=style,
            position=position,
            size=size,
            z_index=z_index,
            presentation_class=presentation_class,
            anchor_type=anchor_type,
            anchor_page=anchor_page,
            layer=layer,
            presentation_style=presentation_style,
            **kwargs,
        )
        frame.set_text_box(text_or_element, text_style)
        return frame

    @property
    def text_content(self) -> str:
        text_box = self.get_element("draw:text-box")
        if text_box is None:
            return ""
        return text_box.text_content

    @text_content.setter
    def text_content(self, text: str | Element | None) -> None:
        text_box = self.get_element("draw:text-box")
        if text_box is None:
            text_box = Element.from_tag("draw:text-box")
            self.append(text_box)
        if isinstance(text, Element):
            text_box.clear()
            text_box.append(text)
        else:
            text_box.text_content = text

    def get_image(
        self,
        position: int = 0,
        name: str | None = None,
        url: str | None = None,
        content: str | None = None,
    ) -> DrawImage | None:
        return self.get_element("draw:image")  # type: ignore[return-value]

    def set_image(self, url_or_element: DrawImage | str) -> Element:
        image: DrawImage | None = self.get_image()
        if image is None:
            if isinstance(url_or_element, Element):
                image = url_or_element
                self.append(image)
            else:
                image = DrawImage(url_or_element)
                self.append(image)
        else:
            if isinstance(url_or_element, Element):
                image.delete()
                image = url_or_element
                self.append(image)
            else:
                image.set_url(url_or_element)  # type: ignore
        return image

    def get_text_box(self) -> Element | None:
        return self.get_element("draw:text-box")

    def set_text_box(
        self,
        text_or_element: Iterable[Element | str] | Element | str,
        text_style: str | None = None,
    ) -> Element:
        text_box = self.get_text_box()
        if text_box is None:
            text_box = Element.from_tag("draw:text-box")
            self.append(text_box)
        else:
            text_box.clear()
        if isinstance(text_or_element, (Element, str)):
            text_or_element_list: Iterable[Element | str] = [text_or_element]
        else:
            text_or_element_list = text_or_element
        for item in text_or_element_list:
            if isinstance(item, str):
                text_box.append(Paragraph(item, style=text_style))
            else:
                text_box.append(item)
        return text_box

    @staticmethod
    def _get_formatted_text_subresult(context: dict, element: Element) -> str:
        str_list = ["  "]
        for child in element.children:
            str_list.append(child.get_formatted_text(context))
        subresult = "".join(str_list)
        subresult = subresult.replace("\n", "\n  ")
        return subresult.rstrip(" ")

    def get_formatted_text(
        self,
        context: dict | None = None,
    ) -> str:
        if not context:
            context = {}
        result = []
        for element in self.children:
            tag = element.tag
            if tag == "draw:image":
                if context["rst_mode"]:
                    filename = element.get_attribute("xlink:href")

                    # Compute width and height
                    width, height = self.size
                    if width is not None:
                        width = Unit(width)
                        width = width.convert("px", DPI)
                    if height is not None:
                        height = Unit(height)
                        height = height.convert("px", DPI)

                    # Insert or not ?
                    if context["no_img_level"]:
                        context["img_counter"] += 1
                        ref = f"|img{context['img_counter']}|"
                        result.append(ref)
                        context["images"].append((ref, filename, (width, height)))
                    else:
                        result.append(f"\n.. image:: {filename}\n")
                        if width is not None:
                            result.append(f"   :width: {width}\n")
                        if height is not None:
                            result.append(f"   :height: {height}\n")
                else:
                    result.append(f"[Image {element.get_attribute('xlink:href')}]\n")
            elif tag == "draw:text-box":
                result.append(self._get_formatted_text_subresult(context, element))
            else:
                result.append(element.get_formatted_text(context))
        result.append("\n")
        return "".join(result)

anchor_page instance-attribute

anchor_page = anchor_page

anchor_type instance-attribute

anchor_type = anchor_type

draw_id instance-attribute

draw_id = draw_id

layer instance-attribute

layer = layer

name instance-attribute

name = name

position instance-attribute

position = position

presentation_class instance-attribute

presentation_class = presentation_class

presentation_style instance-attribute

presentation_style = presentation_style

size instance-attribute

size = size

style instance-attribute

style = style

text_content property writable

text_content: str

z_index instance-attribute

z_index = z_index

__init__

__init__(
    name: str | None = None,
    draw_id: str | None = None,
    style: str | None = None,
    position: tuple | None = None,
    size: tuple = ("1cm", "1cm"),
    z_index: int = 0,
    presentation_class: str | None = None,
    anchor_type: str | None = None,
    anchor_page: int | None = None,
    layer: str | None = None,
    presentation_style: str | None = None,
    **kwargs: Any,
) -> None

ODF Frame, “draw:frame”.

Frames are not useful by themselves. Consider calling Frame.image_frame() or Frame.text_frame directly.

Create a frame element of the given size. Position is relative to the context the frame is inserted in. If positioned by page, give the page number and the x, y position.

Size is a (width, height) tuple and position is a (left, top) tuple; items are strings including the unit, e.g. (‘10cm’, ‘15cm’).

Frames are not useful by themselves. You should consider calling: Frame.image_frame() or Frame.text_frame()

Args:

name -- str

draw_id -- str

style -- str

position -- (str, str)

size -- (str, str)

z_index -- int (default 0)

presentation_class -- str

anchor_type -- 'page', 'frame', 'paragraph', 'char' or 'as-char'

anchor_page -- int, page number is anchor_type is 'page'

layer -- str

presentation_style -- str

Source code in odfdo/frame.py

def __init__(
    self,
    name: str | None = None,
    draw_id: str | None = None,
    style: str | None = None,
    position: tuple | None = None,
    size: tuple = ("1cm", "1cm"),
    z_index: int = 0,
    presentation_class: str | None = None,
    anchor_type: str | None = None,
    anchor_page: int | None = None,
    layer: str | None = None,
    presentation_style: str | None = None,
    **kwargs: Any,
) -> None:
    """ODF Frame, "draw:frame".

    Frames are not useful by themselves. Consider calling
    Frame.image_frame() or Frame.text_frame directly.

    Create a frame element of the given size. Position is relative to the
    context the frame is inserted in. If positioned by page, give the page
    number and the x, y position.

    Size is a (width, height) tuple and position is a (left, top) tuple; items
    are strings including the unit, e.g. ('10cm', '15cm').

    Frames are not useful by themselves. You should consider calling:
        Frame.image_frame()
    or
        Frame.text_frame()


    Args:

        name -- str

        draw_id -- str

        style -- str

        position -- (str, str)

        size -- (str, str)

        z_index -- int (default 0)

        presentation_class -- str

        anchor_type -- 'page', 'frame', 'paragraph', 'char' or 'as-char'

        anchor_page -- int, page number is anchor_type is 'page'

        layer -- str

        presentation_style -- str
    """
    super().__init__(**kwargs)
    if self._do_init:
        self.size = size
        self.z_index = z_index
        if name:
            self.name = name
        if draw_id is not None:
            self.draw_id = draw_id
        if style is not None:
            self.style = style
        if position is not None:
            self.position = position
        if presentation_class is not None:
            self.presentation_class = presentation_class
        if anchor_type:
            self.anchor_type = anchor_type
        if position and not anchor_type:
            self.anchor_type = "paragraph"
        if anchor_page is not None:
            self.anchor_page = anchor_page
        if layer is not None:
            self.layer = layer
        if presentation_style is not None:
            self.presentation_style = presentation_style

get_formatted_text

get_formatted_text(context: dict | None = None) -> str

Source code in odfdo/frame.py

def get_formatted_text(
    self,
    context: dict | None = None,
) -> str:
    if not context:
        context = {}
    result = []
    for element in self.children:
        tag = element.tag
        if tag == "draw:image":
            if context["rst_mode"]:
                filename = element.get_attribute("xlink:href")

                # Compute width and height
                width, height = self.size
                if width is not None:
                    width = Unit(width)
                    width = width.convert("px", DPI)
                if height is not None:
                    height = Unit(height)
                    height = height.convert("px", DPI)

                # Insert or not ?
                if context["no_img_level"]:
                    context["img_counter"] += 1
                    ref = f"|img{context['img_counter']}|"
                    result.append(ref)
                    context["images"].append((ref, filename, (width, height)))
                else:
                    result.append(f"\n.. image:: {filename}\n")
                    if width is not None:
                        result.append(f"   :width: {width}\n")
                    if height is not None:
                        result.append(f"   :height: {height}\n")
            else:
                result.append(f"[Image {element.get_attribute('xlink:href')}]\n")
        elif tag == "draw:text-box":
            result.append(self._get_formatted_text_subresult(context, element))
        else:
            result.append(element.get_formatted_text(context))
    result.append("\n")
    return "".join(result)

get_image

get_image(
    position: int = 0,
    name: str | None = None,
    url: str | None = None,
    content: str | None = None,
) -> DrawImage | None

Source code in odfdo/frame.py

def get_image(
    self,
    position: int = 0,
    name: str | None = None,
    url: str | None = None,
    content: str | None = None,
) -> DrawImage | None:
    return self.get_element("draw:image")  # type: ignore[return-value]

get_text_box

get_text_box() -> Element | None

Source code in odfdo/frame.py

def get_text_box(self) -> Element | None:
    return self.get_element("draw:text-box")

image_frame classmethod

image_frame(
    image: DrawImage | str,
    text: str | None = None,
    name: str | None = None,
    draw_id: str | None = None,
    style: str | None = None,
    position: tuple | None = None,
    size: tuple = ("1cm", "1cm"),
    z_index: int = 0,
    presentation_class: str | None = None,
    anchor_type: str | None = None,
    anchor_page: int | None = None,
    layer: str | None = None,
    presentation_style: str | None = None,
    **kwargs: Any,
) -> Element

Create a ready-to-use image, since image must be embedded in a frame.

The optional text will appear above the image.

Args:

image -- DrawImage or str, DrawImage element or URL of the image

text -- str, text for the image

See Frame() initialization for the other arguments

Returns: Frame

Source code in odfdo/frame.py

@classmethod
def image_frame(
    cls,
    image: DrawImage | str,
    text: str | None = None,
    name: str | None = None,
    draw_id: str | None = None,
    style: str | None = None,
    position: tuple | None = None,
    size: tuple = ("1cm", "1cm"),
    z_index: int = 0,
    presentation_class: str | None = None,
    anchor_type: str | None = None,
    anchor_page: int | None = None,
    layer: str | None = None,
    presentation_style: str | None = None,
    **kwargs: Any,
) -> Element:
    """Create a ready-to-use image, since image must be embedded in a
    frame.

    The optional text will appear above the image.

    Args:

        image -- DrawImage or str, DrawImage element or URL of the image

        text -- str, text for the image

        See Frame() initialization for the other arguments

    Returns: Frame
    """
    frame = cls(
        name=name,
        draw_id=draw_id,
        style=style,
        position=position,
        size=size,
        z_index=z_index,
        presentation_class=presentation_class,
        anchor_type=anchor_type,
        anchor_page=anchor_page,
        layer=layer,
        presentation_style=presentation_style,
        **kwargs,
    )
    image_element = frame.set_image(image)
    if text:
        image_element.text_content = text
    return frame

set_image

set_image(url_or_element: DrawImage | str) -> Element

Source code in odfdo/frame.py

def set_image(self, url_or_element: DrawImage | str) -> Element:
    image: DrawImage | None = self.get_image()
    if image is None:
        if isinstance(url_or_element, Element):
            image = url_or_element
            self.append(image)
        else:
            image = DrawImage(url_or_element)
            self.append(image)
    else:
        if isinstance(url_or_element, Element):
            image.delete()
            image = url_or_element
            self.append(image)
        else:
            image.set_url(url_or_element)  # type: ignore
    return image

set_text_box

set_text_box(
    text_or_element: Iterable[Element | str]
    | Element
    | str,
    text_style: str | None = None,
) -> Element

Source code in odfdo/frame.py

def set_text_box(
    self,
    text_or_element: Iterable[Element | str] | Element | str,
    text_style: str | None = None,
) -> Element:
    text_box = self.get_text_box()
    if text_box is None:
        text_box = Element.from_tag("draw:text-box")
        self.append(text_box)
    else:
        text_box.clear()
    if isinstance(text_or_element, (Element, str)):
        text_or_element_list: Iterable[Element | str] = [text_or_element]
    else:
        text_or_element_list = text_or_element
    for item in text_or_element_list:
        if isinstance(item, str):
            text_box.append(Paragraph(item, style=text_style))
        else:
            text_box.append(item)
    return text_box

text_frame classmethod

text_frame(
    text_or_element: Iterable[Element] | Element | str,
    text_style: str | None = None,
    name: str | None = None,
    draw_id: str | None = None,
    style: str | None = None,
    position: tuple | None = None,
    size: tuple = ("1cm", "1cm"),
    z_index: int = 0,
    presentation_class: str | None = None,
    anchor_type: str | None = None,
    anchor_page: int | None = None,
    layer: str | None = None,
    presentation_style: str | None = None,
    **kwargs: Any,
) -> Element

Create a ready-to-use text box, since text box must be embedded in a frame.

The optional text will appear above the image.

Args:

text_or_element -- str or Element, or list of them, text content
                   of the text box.

text_style -- str, name of the style for the text

See Frame() initialization for the other arguments

Returns: Frame

Source code in odfdo/frame.py

@classmethod
def text_frame(
    cls,
    text_or_element: Iterable[Element] | Element | str,
    text_style: str | None = None,
    name: str | None = None,
    draw_id: str | None = None,
    style: str | None = None,
    position: tuple | None = None,
    size: tuple = ("1cm", "1cm"),
    z_index: int = 0,
    presentation_class: str | None = None,
    anchor_type: str | None = None,
    anchor_page: int | None = None,
    layer: str | None = None,
    presentation_style: str | None = None,
    **kwargs: Any,
) -> Element:
    """Create a ready-to-use text box, since text box must be embedded in a
    frame.

    The optional text will appear above the image.

    Args:

        text_or_element -- str or Element, or list of them, text content
                           of the text box.

        text_style -- str, name of the style for the text

        See Frame() initialization for the other arguments

    Returns: Frame
    """
    frame = cls(
        name=name,
        draw_id=draw_id,
        style=style,
        position=position,
        size=size,
        z_index=z_index,
        presentation_class=presentation_class,
        anchor_type=anchor_type,
        anchor_page=anchor_page,
        layer=layer,
        presentation_style=presentation_style,
        **kwargs,
    )
    frame.set_text_box(text_or_element, text_style)
    return frame

Header

Bases: Paragraph, MDHeader

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

Methods:

Name	Description
__init__	A title, a specialized paragraph, “text:h”.
get_formatted_text

Attributes:

Name	Type	Description
level
restart_numbering
start_value
suppress_numbering
text

Source code in odfdo/header.py

class Header(Paragraph, MDHeader):
    """A title, a specialized paragraph, "text:h"."""

    _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:
        """A title, a specialized paragraph, "text:h".

        Create a header element of the given style and level, containing the
        optional given text.

        Level count begins at 1.

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

        Args:

            level -- int

            text -- str

            restart_numbering -- bool

            start_value -- int

            style -- str

            formatted -- bool
        """
        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:
        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)

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

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

Create a header element of the given style and level, containing the optional given text.

Level count begins at 1.

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

Args:

level -- int

text -- str

restart_numbering -- bool

start_value -- int

style -- str

formatted -- bool

Source code in odfdo/header.py

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:
    """A title, a specialized paragraph, "text:h".

    Create a header element of the given style and level, containing the
    optional given text.

    Level count begins at 1.

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

    Args:

        level -- int

        text -- str

        restart_numbering -- bool

        start_value -- int

        style -- str

        formatted -- bool
    """
    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

Source code in odfdo/header.py

def get_formatted_text(
    self,
    context: dict | None = None,
    simple: bool = False,
) -> str:
    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)

HeaderRows

Bases: Element

A header row of a table, “table:table-header-rows”.

Source code in odfdo/header_rows.py

class HeaderRows(Element):
    """A header row of a table, "table:table-header-rows"."""

    _tag = "table:table-header-rows"

Image

Bases: Body

Root of the Image document content, “office:image”.

Source code in odfdo/body.py

class Image(Body):
    """Root of the Image document content, "office:image"."""

    _tag: str = "office:image"
    _properties: tuple[PropDef, ...] = ()

IndexTitle

Bases: Element

The title of an index, “text:index-title”.

The element has the following attributes: text:name, text:protected, text:protection-key, text:protection-key-digest-algorithm, text:style-name, xml:id.

The actual title is stored in a child element

Methods:

Name	Description
__init__	Create title of an index “text:index-title”.
set_title_text

Attributes:

Name	Type	Description
name
style
xml_id

Source code in odfdo/toc.py

class IndexTitle(Element):
    """The title of an index, "text:index-title".

    The element has the following attributes:
    text:name, text:protected, text:protection-key,
    text:protection-key-digest-algorithm, text:style-name, xml:id.

    The actual title is stored in a child element
    """

    _tag = "text:index-title"
    _properties = (
        PropDef("name", "text:name"),
        PropDef("style", "text:style-name"),
        PropDef("xml_id", "xml:id"),
        PropDef("protected", "text:protected"),
        PropDef("protection_key", "text:protection-key"),
        PropDef(
            "protection_key_digest_algorithm", "text:protection-key-digest-algorithm"
        ),
    )

    def __init__(
        self,
        name: str | None = None,
        style: str | None = None,
        title_text: str | None = None,
        title_text_style: str | None = None,
        xml_id: str | None = None,
        **kwargs: Any,
    ) -> None:
        """Create title of an index "text:index-title".

        The element has the following attributes:
        text:name, text:protected, text:protection-key,
        text:protection-key-digest-algorithm, text:style-name, xml:id.

        The actual title is stored in a child element
        """
        super().__init__(**kwargs)
        if self._do_init:
            if name:
                self.name = name
            if style:
                self.style = style
            if xml_id:
                self.xml_id = xml_id
            if title_text:
                self.set_title_text(title_text, title_text_style)

    def set_title_text(
        self,
        title_text: str,
        title_text_style: str | None = None,
    ) -> None:
        title = Paragraph(title_text, style=title_text_style)
        self.append(title)

name instance-attribute

name = name

style instance-attribute

style = style

xml_id instance-attribute

xml_id = xml_id

__init__

__init__(
    name: str | None = None,
    style: str | None = None,
    title_text: str | None = None,
    title_text_style: str | None = None,
    xml_id: str | None = None,
    **kwargs: Any,
) -> None

Create title of an index “text:index-title”.

The element has the following attributes: text:name, text:protected, text:protection-key, text:protection-key-digest-algorithm, text:style-name, xml:id.

The actual title is stored in a child element

Source code in odfdo/toc.py

def __init__(
    self,
    name: str | None = None,
    style: str | None = None,
    title_text: str | None = None,
    title_text_style: str | None = None,
    xml_id: str | None = None,
    **kwargs: Any,
) -> None:
    """Create title of an index "text:index-title".

    The element has the following attributes:
    text:name, text:protected, text:protection-key,
    text:protection-key-digest-algorithm, text:style-name, xml:id.

    The actual title is stored in a child element
    """
    super().__init__(**kwargs)
    if self._do_init:
        if name:
            self.name = name
        if style:
            self.style = style
        if xml_id:
            self.xml_id = xml_id
        if title_text:
            self.set_title_text(title_text, title_text_style)

set_title_text

set_title_text(
    title_text: str, title_text_style: str | None = None
) -> None

Source code in odfdo/toc.py

def set_title_text(
    self,
    title_text: str,
    title_text_style: str | None = None,
) -> None:
    title = Paragraph(title_text, style=title_text_style)
    self.append(title)

IndexTitleTemplate

Bases: Element

Template style for title, “text:index-title-template”.

Methods:

Name	Description
__init__	Create template style for title “text:index-title-template”.

Attributes:

Name	Type	Description
style

Source code in odfdo/toc.py

class IndexTitleTemplate(Element):
    """Template style for title, "text:index-title-template"."""

    _tag = "text:index-title-template"
    _properties = (PropDef("style", "text:style-name"),)

    def __init__(self, style: str | None = None, **kwargs: Any) -> None:
        """Create template style for title "text:index-title-template".

        Args:

            style -- str
        """
        super().__init__(**kwargs)
        if self._do_init and style:
            self.style = style

style instance-attribute

style = style

__init__

__init__(style: str | None = None, **kwargs: Any) -> None

Create template style for title “text:index-title-template”.

Args:

style -- str

Source code in odfdo/toc.py

def __init__(self, style: str | None = None, **kwargs: Any) -> None:
    """Create template style for title "text:index-title-template".

    Args:

        style -- str
    """
    super().__init__(**kwargs)
    if self._do_init and style:
        self.style = style

LineBreak

Bases: MDLineBreak, Element

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

Methods:

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

Attributes:

Name	Type	Description
text	str	Get / set the string (line break).

Source code in odfdo/line_break.py

class LineBreak(MDLineBreak, Element):
    """Representation of a line break, "text:line-break"."""

    _tag = "text:line-break"

    def __init__(self, **kwargs: Any) -> None:
        """Representation of a line break, "text:line-break"."""
        super().__init__(**kwargs)

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

    @property
    def text(self) -> str:
        """Get / set the string (line break)."""
        return "\n"

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

text property writable

text: str

Get / set the string (line break).

__init__

__init__(**kwargs: Any) -> None

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

Source code in odfdo/line_break.py

def __init__(self, **kwargs: Any) -> None:
    """Representation of a line break, "text:line-break"."""
    super().__init__(**kwargs)

LineShape

Bases: ShapeBase

A line shape, “draw:line”.

Methods:

Name	Description
__init__	Create a line shape “draw:line”.

Attributes:

Name	Type	Description
x1
x2
y1
y2

Source code in odfdo/shapes.py

class LineShape(ShapeBase):
    """A line shape, "draw:line"."""

    _tag = "draw:line"
    _properties: tuple[PropDef, ...] = (
        PropDef("x1", "svg:x1"),
        PropDef("y1", "svg:y1"),
        PropDef("x2", "svg:x2"),
        PropDef("y2", "svg:y2"),
    )

    def __init__(
        self,
        style: str | None = None,
        text_style: str | None = None,
        draw_id: str | None = None,
        layer: str | None = None,
        p1: tuple | None = None,
        p2: tuple | None = None,
        **kwargs: Any,
    ) -> None:
        """Create a line shape "draw:line".

        Args:

            style -- str

            text_style -- str

            draw_id -- str

            layer -- str

            p1 -- (str, str)

            p2 -- (str, str)
        """
        kwargs.update(
            {
                "style": style,
                "text_style": text_style,
                "draw_id": draw_id,
                "layer": layer,
            }
        )
        super().__init__(**kwargs)
        if self._do_init:
            if p1:
                self.x1 = p1[0]
                self.y1 = p1[1]
            if p2:
                self.x2 = p2[0]
                self.y2 = p2[1]

x1 instance-attribute

x1 = p1[0]

x2 instance-attribute

x2 = p2[0]

y1 instance-attribute

y1 = p1[1]

y2 instance-attribute

y2 = p2[1]

__init__

__init__(
    style: str | None = None,
    text_style: str | None = None,
    draw_id: str | None = None,
    layer: str | None = None,
    p1: tuple | None = None,
    p2: tuple | None = None,
    **kwargs: Any,
) -> None

Create a line shape “draw:line”.

Args:

style -- str

text_style -- str

draw_id -- str

layer -- str

p1 -- (str, str)

p2 -- (str, str)

Source code in odfdo/shapes.py

def __init__(
    self,
    style: str | None = None,
    text_style: str | None = None,
    draw_id: str | None = None,
    layer: str | None = None,
    p1: tuple | None = None,
    p2: tuple | None = None,
    **kwargs: Any,
) -> None:
    """Create a line shape "draw:line".

    Args:

        style -- str

        text_style -- str

        draw_id -- str

        layer -- str

        p1 -- (str, str)

        p2 -- (str, str)
    """
    kwargs.update(
        {
            "style": style,
            "text_style": text_style,
            "draw_id": draw_id,
            "layer": layer,
        }
    )
    super().__init__(**kwargs)
    if self._do_init:
        if p1:
            self.x1 = p1[0]
            self.y1 = p1[1]
        if p2:
            self.x2 = p2[0]
            self.y2 = p2[1]

Link

Bases: MDLink, ParaFormattedTextMixin, Element

Representation of a link (URL), “text:a”.

Methods:

Name	Description
__init__	Representation of a link (URL), “text:a”.

Attributes:

Name	Type	Description
name
show
style
target_frame
text
title
url
visited_style

Source code in odfdo/link.py

class Link(MDLink, ParaFormattedTextMixin, Element):
    """Representation of a link (URL), "text:a"."""

    _tag = "text:a"
    _properties: tuple[PropDef, ...] = (
        PropDef("url", "xlink:href"),
        PropDef("name", "office:name"),
        PropDef("title", "office:title"),
        PropDef("target_frame", "office:target-frame-name"),
        PropDef("show", "xlink:show"),
        PropDef("visited_style", "text:visited-style-name"),
        PropDef("style", "text:style-name"),
    )

    def __init__(
        self,
        url: str | None = "",
        name: str | None = None,
        title: str | None = None,
        text: str | None = None,
        target_frame: str | None = None,
        style: str | None = None,
        visited_style: str | None = None,
        **kwargs: Any,
    ) -> None:
        """Representation of a link (URL), "text:a".

        Args:

            url -- str

            name -- str

            title -- str

            text -- str

            target_frame -- '_self', '_blank', '_parent', '_top'

            style -- str

            visited_style -- str
        """
        super().__init__(**kwargs)
        if self._do_init:
            self.url = url
            if name is not None:
                self.name = name
            if title is not None:
                self.title = title
            if text is not None:
                self.text = text
            if target_frame is not None:
                self.target_frame = target_frame
                # show can be: 'new' or 'replace'"
                if target_frame == "_blank":
                    self.show = "new"
                else:
                    self.show = "replace"
            if style is not None:
                self.style = style
            if visited_style is not None:
                self.visited_style = visited_style

    def __repr__(self) -> str:
        return f"<{self.__class__.__name__} tag={self.tag} link={self.url}>"

    def __str__(self) -> str:
        text = self.inner_text.strip()
        if text:
            return f"[{text}]({self.url})"
        return f"({self.url})"

name instance-attribute

name = name

show instance-attribute

show = 'new'

style instance-attribute

style = style

target_frame instance-attribute

target_frame = target_frame

text instance-attribute

text = text

title instance-attribute

title = title

url instance-attribute

url = url

visited_style instance-attribute

visited_style = visited_style

__init__

__init__(
    url: str | None = "",
    name: str | None = None,
    title: str | None = None,
    text: str | None = None,
    target_frame: str | None = None,
    style: str | None = None,
    visited_style: str | None = None,
    **kwargs: Any,
) -> None

Representation of a link (URL), “text:a”.

Args:

url -- str

name -- str

title -- str

text -- str

target_frame -- '_self', '_blank', '_parent', '_top'

style -- str

visited_style -- str

Source code in odfdo/link.py

def __init__(
    self,
    url: str | None = "",
    name: str | None = None,
    title: str | None = None,
    text: str | None = None,
    target_frame: str | None = None,
    style: str | None = None,
    visited_style: str | None = None,
    **kwargs: Any,
) -> None:
    """Representation of a link (URL), "text:a".

    Args:

        url -- str

        name -- str

        title -- str

        text -- str

        target_frame -- '_self', '_blank', '_parent', '_top'

        style -- str

        visited_style -- str
    """
    super().__init__(**kwargs)
    if self._do_init:
        self.url = url
        if name is not None:
            self.name = name
        if title is not None:
            self.title = title
        if text is not None:
            self.text = text
        if target_frame is not None:
            self.target_frame = target_frame
            # show can be: 'new' or 'replace'"
            if target_frame == "_blank":
                self.show = "new"
            else:
                self.show = "replace"
        if style is not None:
            self.style = style
        if visited_style is not None:
            self.visited_style = visited_style

List

Bases: MDList, Element

A list of elements, “text:list”.

Methods:

Name	Description
__init__	A list of elements, “text:list”.
append_item
get_formatted_text
get_item	Return the list item that matches the criteria. In nested lists,
get_items	Return all the list items that match the criteria.
insert_item
set_list_header

Attributes:

Name	Type	Description
style

Source code in odfdo/list.py

class List(MDList, Element):
    """A list of elements, "text:list"."""

    _tag = "text:list"
    _properties = (PropDef("style", "text:style-name"),)

    def __init__(
        self,
        list_content: str | Element | Iterable[str | Element] | None = None,
        style: str | None = None,
        **kwargs: Any,
    ) -> None:
        """A list of elements, "text:list".

        Create a list element, optionally loading the list by a list of
        item (str or elements).

        The list_content argument is just a shortcut for the most common case.
        To create more complex lists, first create an empty list, and fill it
        afterwards.

        Args:

            list_content -- str or Element, or a list of str or Element

            style -- str
        """
        super().__init__(**kwargs)
        if self._do_init:
            if list_content:
                if isinstance(list_content, (Element, str)):
                    self.append(ListItem(list_content))
                elif hasattr(list_content, "__iter__"):
                    for item in list_content:
                        self.append(ListItem(item))
            if style is not None:
                self.style = style

    def get_items(self, content: str | None = None) -> list[Element]:
        """Return all the list items that match the criteria.

        Args:

            style -- str

            content -- str regex

        Returns: list of Element
        """
        return self._filtered_elements("text:list-item", content=content)

    def get_item(
        self,
        position: int = 0,
        content: str | None = None,
    ) -> Element | None:
        """Return the list item that matches the criteria. In nested lists,
        return the list item that really contains that content.

        Args:

            position -- int

            content -- str regex

        Returns: Element or None if not found
        """
        # Custom implementation because of nested lists
        if content:
            # Don't search recursively but on the very own paragraph(s) of
            # each list item
            for paragraph in self.get_elements("descendant::text:p"):
                if paragraph.match(content):
                    return paragraph.get_element("parent::text:list-item")
            return None
        return self._filtered_element("text:list-item", position)

    def set_list_header(
        self,
        text_or_element: str | Element | Iterable[str | Element],
    ) -> None:
        if isinstance(text_or_element, (str, Element)):
            actual_list: list[str | Element] | tuple = [text_or_element]
        elif isinstance(text_or_element, (list, tuple)):
            actual_list = text_or_element
        else:
            raise TypeError
        # Remove existing header
        for element in self.get_elements("text:p"):
            self.delete(element)
        for paragraph in reversed(actual_list):
            if isinstance(paragraph, str):
                paragraph = Paragraph(paragraph)
            self.insert(paragraph, FIRST_CHILD)

    def insert_item(
        self,
        item: ListItem | str | Element | None,
        position: int | None = None,
        before: Element | None = None,
        after: Element | None = None,
    ) -> None:
        if not isinstance(item, ListItem):
            item = ListItem(item)
        if before is not None:
            before.insert(item, xmlposition=PREV_SIBLING)
        elif after is not None:
            after.insert(item, xmlposition=NEXT_SIBLING)
        elif position is not None:
            self.insert(item, position=position)
        else:
            raise ValueError("Position must be defined")

    def append_item(
        self,
        item: ListItem | str | Element | None,
    ) -> None:
        if not isinstance(item, ListItem):
            item = ListItem(item)
        self.append(item)

    def get_formatted_text(self, context: dict | None = None) -> str:
        if context is None:
            context = {
                "document": None,
                "footnotes": [],
                "endnotes": [],
                "annotations": [],
                "rst_mode": False,
                "img_counter": 0,
                "images": [],
                "no_img_level": 0,
            }
        rst_mode = bool(context.get("rst_mode"))
        result = []
        if rst_mode:
            result.append("\n")
        for list_item in self.get_elements("text:list-item"):
            textbuf = []
            for child in list_item.children:
                text = child.get_formatted_text(context)
                tag = child.tag
                if tag == "text:h":
                    # A title in a list is a bug
                    return text
                if tag == "text:list" and not text.lstrip().startswith("-"):
                    # If the list didn't indent, don't either
                    # (inner title)
                    return text  # pragma: nocover
                textbuf.append(text)
            text_sum = "".join(textbuf)
            text_sum = text_sum.strip("\n")
            # Indent the text
            text_sum = text_sum.replace("\n", "\n  ")
            text_sum = f"- {text_sum}\n"
            result.append(text_sum)
        if rst_mode:
            result.append("\n")
        return "".join(result)

style instance-attribute

style = style

__init__

__init__(
    list_content: str
    | Element
    | Iterable[str | Element]
    | None = None,
    style: str | None = None,
    **kwargs: Any,
) -> None

A list of elements, “text:list”.

Create a list element, optionally loading the list by a list of item (str or elements).

The list_content argument is just a shortcut for the most common case. To create more complex lists, first create an empty list, and fill it afterwards.

Args:

list_content -- str or Element, or a list of str or Element

style -- str

Source code in odfdo/list.py

def __init__(
    self,
    list_content: str | Element | Iterable[str | Element] | None = None,
    style: str | None = None,
    **kwargs: Any,
) -> None:
    """A list of elements, "text:list".

    Create a list element, optionally loading the list by a list of
    item (str or elements).

    The list_content argument is just a shortcut for the most common case.
    To create more complex lists, first create an empty list, and fill it
    afterwards.

    Args:

        list_content -- str or Element, or a list of str or Element

        style -- str
    """
    super().__init__(**kwargs)
    if self._do_init:
        if list_content:
            if isinstance(list_content, (Element, str)):
                self.append(ListItem(list_content))
            elif hasattr(list_content, "__iter__"):
                for item in list_content:
                    self.append(ListItem(item))
        if style is not None:
            self.style = style

append_item

append_item(item: ListItem | str | Element | None) -> None

Source code in odfdo/list.py

def append_item(
    self,
    item: ListItem | str | Element | None,
) -> None:
    if not isinstance(item, ListItem):
        item = ListItem(item)
    self.append(item)

get_formatted_text

get_formatted_text(context: dict | None = None) -> str

Source code in odfdo/list.py

def get_formatted_text(self, context: dict | None = None) -> str:
    if context is None:
        context = {
            "document": None,
            "footnotes": [],
            "endnotes": [],
            "annotations": [],
            "rst_mode": False,
            "img_counter": 0,
            "images": [],
            "no_img_level": 0,
        }
    rst_mode = bool(context.get("rst_mode"))
    result = []
    if rst_mode:
        result.append("\n")
    for list_item in self.get_elements("text:list-item"):
        textbuf = []
        for child in list_item.children:
            text = child.get_formatted_text(context)
            tag = child.tag
            if tag == "text:h":
                # A title in a list is a bug
                return text
            if tag == "text:list" and not text.lstrip().startswith("-"):
                # If the list didn't indent, don't either
                # (inner title)
                return text  # pragma: nocover
            textbuf.append(text)
        text_sum = "".join(textbuf)
        text_sum = text_sum.strip("\n")
        # Indent the text
        text_sum = text_sum.replace("\n", "\n  ")
        text_sum = f"- {text_sum}\n"
        result.append(text_sum)
    if rst_mode:
        result.append("\n")
    return "".join(result)

get_item

get_item(
    position: int = 0, content: str | None = None
) -> Element | None

Return the list item that matches the criteria. In nested lists, return the list item that really contains that content.

Args:

position -- int

content -- str regex

Returns: Element or None if not found

Source code in odfdo/list.py

def get_item(
    self,
    position: int = 0,
    content: str | None = None,
) -> Element | None:
    """Return the list item that matches the criteria. In nested lists,
    return the list item that really contains that content.

    Args:

        position -- int

        content -- str regex

    Returns: Element or None if not found
    """
    # Custom implementation because of nested lists
    if content:
        # Don't search recursively but on the very own paragraph(s) of
        # each list item
        for paragraph in self.get_elements("descendant::text:p"):
            if paragraph.match(content):
                return paragraph.get_element("parent::text:list-item")
        return None
    return self._filtered_element("text:list-item", position)

get_items

get_items(content: str | None = None) -> list[Element]

Return all the list items that match the criteria.

Args:

style -- str

content -- str regex

Returns: list of Element

Source code in odfdo/list.py

def get_items(self, content: str | None = None) -> list[Element]:
    """Return all the list items that match the criteria.

    Args:

        style -- str

        content -- str regex

    Returns: list of Element
    """
    return self._filtered_elements("text:list-item", content=content)

insert_item

insert_item(
    item: ListItem | str | Element | None,
    position: int | None = None,
    before: Element | None = None,
    after: Element | None = None,
) -> None

Source code in odfdo/list.py

def insert_item(
    self,
    item: ListItem | str | Element | None,
    position: int | None = None,
    before: Element | None = None,
    after: Element | None = None,
) -> None:
    if not isinstance(item, ListItem):
        item = ListItem(item)
    if before is not None:
        before.insert(item, xmlposition=PREV_SIBLING)
    elif after is not None:
        after.insert(item, xmlposition=NEXT_SIBLING)
    elif position is not None:
        self.insert(item, position=position)
    else:
        raise ValueError("Position must be defined")

set_list_header

set_list_header(
    text_or_element: str
    | Element
    | Iterable[str | Element],
) -> None

Source code in odfdo/list.py

def set_list_header(
    self,
    text_or_element: str | Element | Iterable[str | Element],
) -> None:
    if isinstance(text_or_element, (str, Element)):
        actual_list: list[str | Element] | tuple = [text_or_element]
    elif isinstance(text_or_element, (list, tuple)):
        actual_list = text_or_element
    else:
        raise TypeError
    # Remove existing header
    for element in self.get_elements("text:p"):
        self.delete(element)
    for paragraph in reversed(actual_list):
        if isinstance(paragraph, str):
            paragraph = Paragraph(paragraph)
        self.insert(paragraph, FIRST_CHILD)

ListItem

Bases: MDListItem, Element

An item of a list, “text:list-item”.

Methods:

Name	Description
__init__	An item of a list, “text:list-item”.

Attributes:

Name	Type	Description
text_content

Source code in odfdo/list.py

class ListItem(MDListItem, Element):
    """An item of a list, "text:list-item"."""

    _tag = "text:list-item"

    def __init__(
        self,
        text_or_element: str | Element | None = None,
        **kwargs: Any,
    ) -> None:
        """An item of a list, "text:list-item".

        Create a list item element, optionally passing at creation time a
        string or Element as content.

        Args:

            text_or_element -- str or ODF Element
        """
        super().__init__(**kwargs)
        if self._do_init:
            if isinstance(text_or_element, str):
                self.text_content = text_or_element
            elif isinstance(text_or_element, Element):
                self.append(text_or_element)
            elif text_or_element is not None:
                raise TypeError(f"Expected str or Element, not {type(text_or_element)}")

    def __str__(self) -> str:
        self._md_initialize_level()
        return "\n".join(self._md_collect())

text_content instance-attribute

text_content = text_or_element

__init__

__init__(
    text_or_element: str | Element | None = None,
    **kwargs: Any,
) -> None

An item of a list, “text:list-item”.

Create a list item element, optionally passing at creation time a string or Element as content.

Args:

text_or_element -- str or ODF Element

Source code in odfdo/list.py

def __init__(
    self,
    text_or_element: str | Element | None = None,
    **kwargs: Any,
) -> None:
    """An item of a list, "text:list-item".

    Create a list item element, optionally passing at creation time a
    string or Element as content.

    Args:

        text_or_element -- str or ODF Element
    """
    super().__init__(**kwargs)
    if self._do_init:
        if isinstance(text_or_element, str):
            self.text_content = text_or_element
        elif isinstance(text_or_element, Element):
            self.append(text_or_element)
        elif text_or_element is not None:
            raise TypeError(f"Expected str or Element, not {type(text_or_element)}")

Manifest

Bases: XmlPart

Representation of the “manifest.xml” part.

Methods:

Name	Description
add_full_path
del_full_path
get_media_type	Get the media type of an existing path.
get_path_medias	Return the list of (full_path, media_type) pairs in the manifest.
get_paths	Return the list of full paths in the manifest.
make_file_entry
set_media_type	Set the media type of an existing path.

Source code in odfdo/manifest.py

class Manifest(XmlPart):
    """Representation of the "manifest.xml" part."""

    def get_paths(self) -> list[Element | EText]:
        """Return the list of full paths in the manifest.

        Returns: list of str
        """
        xpath_query = "//manifest:file-entry/attribute::manifest:full-path"
        return self.xpath(xpath_query)

    def _file_entry(self, full_path: str) -> Element:
        xpath_query = (
            f'//manifest:file-entry[attribute::manifest:full-path="{full_path}"]'
        )
        result = self.xpath(xpath_query)
        if not result:
            raise KeyError(f"Path not found: '{full_path}'")
        return result[0]  # type: ignore

    def get_path_medias(self) -> list[tuple]:
        """Return the list of (full_path, media_type) pairs in the manifest.

        Returns: list of str tuples
        """
        xpath_query = "//manifest:file-entry"
        result = []
        for file_entry in self.xpath(xpath_query):
            if not isinstance(file_entry, Element):  # pragma: no cover
                continue
            result.append(
                (
                    file_entry.get_attribute_string("manifest:full-path"),
                    file_entry.get_attribute_string("manifest:media-type"),
                )
            )
        return result

    def get_media_type(self, full_path: str) -> str | None:
        """Get the media type of an existing path.

        Returns: str
        """
        xpath_query = (
            f'//manifest:file-entry[attribute::manifest:full-path="{full_path}"]'
            "/attribute::manifest:media-type"
        )
        result = self.xpath(xpath_query)
        if not result:
            return None
        return str(result[0])

    def set_media_type(self, full_path: str, media_type: str) -> None:
        """Set the media type of an existing path.

        Args:

            full_path -- str

            media_type -- str
        """
        file_entry = self._file_entry(full_path)
        file_entry.set_attribute("manifest:media-type", media_type)

    @staticmethod
    def make_file_entry(full_path: str, media_type: str) -> Element:
        tag = (
            f"<manifest:file-entry "
            f'manifest:media-type="{media_type}" '
            f'manifest:full-path="{full_path}"/>'
        )
        return Element.from_tag(tag)

    def add_full_path(self, full_path: str, media_type: str = "") -> None:
        # Existing?
        existing = self.get_media_type(full_path)
        if existing is not None:
            self.set_media_type(full_path, media_type)
        root = self.root
        root.append(self.make_file_entry(full_path, media_type))

    def del_full_path(self, full_path: str) -> None:
        file_entry = self._file_entry(full_path)
        self.root.delete(file_entry)

add_full_path

add_full_path(full_path: str, media_type: str = '') -> None

Source code in odfdo/manifest.py

def add_full_path(self, full_path: str, media_type: str = "") -> None:
    # Existing?
    existing = self.get_media_type(full_path)
    if existing is not None:
        self.set_media_type(full_path, media_type)
    root = self.root
    root.append(self.make_file_entry(full_path, media_type))

del_full_path

del_full_path(full_path: str) -> None

Source code in odfdo/manifest.py

def del_full_path(self, full_path: str) -> None:
    file_entry = self._file_entry(full_path)
    self.root.delete(file_entry)

get_media_type

get_media_type(full_path: str) -> str | None

Get the media type of an existing path.

Returns: str

Source code in odfdo/manifest.py

def get_media_type(self, full_path: str) -> str | None:
    """Get the media type of an existing path.

    Returns: str
    """
    xpath_query = (
        f'//manifest:file-entry[attribute::manifest:full-path="{full_path}"]'
        "/attribute::manifest:media-type"
    )
    result = self.xpath(xpath_query)
    if not result:
        return None
    return str(result[0])

get_path_medias

get_path_medias() -> list[tuple]

Return the list of (full_path, media_type) pairs in the manifest.

Returns: list of str tuples

Source code in odfdo/manifest.py

def get_path_medias(self) -> list[tuple]:
    """Return the list of (full_path, media_type) pairs in the manifest.

    Returns: list of str tuples
    """
    xpath_query = "//manifest:file-entry"
    result = []
    for file_entry in self.xpath(xpath_query):
        if not isinstance(file_entry, Element):  # pragma: no cover
            continue
        result.append(
            (
                file_entry.get_attribute_string("manifest:full-path"),
                file_entry.get_attribute_string("manifest:media-type"),
            )
        )
    return result

get_paths

get_paths() -> list[Element | EText]

Return the list of full paths in the manifest.

Returns: list of str

Source code in odfdo/manifest.py

def get_paths(self) -> list[Element | EText]:
    """Return the list of full paths in the manifest.

    Returns: list of str
    """
    xpath_query = "//manifest:file-entry/attribute::manifest:full-path"
    return self.xpath(xpath_query)

make_file_entry staticmethod

make_file_entry(full_path: str, media_type: str) -> Element

Source code in odfdo/manifest.py

@staticmethod
def make_file_entry(full_path: str, media_type: str) -> Element:
    tag = (
        f"<manifest:file-entry "
        f'manifest:media-type="{media_type}" '
        f'manifest:full-path="{full_path}"/>'
    )
    return Element.from_tag(tag)

set_media_type

set_media_type(full_path: str, media_type: str) -> None

Set the media type of an existing path.

Args:

full_path -- str

media_type -- str

Source code in odfdo/manifest.py

def set_media_type(self, full_path: str, media_type: str) -> None:
    """Set the media type of an existing path.

    Args:

        full_path -- str

        media_type -- str
    """
    file_entry = self._file_entry(full_path)
    file_entry.set_attribute("manifest:media-type", media_type)

Meta

Bases: XmlPart, DcCreatorMixin, DcDateMixin

Representation of the “meta.xml” part.

Methods:

Name	Description
__init__	Create the Meta XML part.
as_dict	Return the metadata of the document as a Python dict.
as_json	Return the metadata of the document as a JSON string.
as_text	Return meta information as text, with some formatting for
clear_user_defined_metadata	Remove all user-defined metadata.
delete_user_defined_metadata_of_name	Delete the user-defined metadata of that name.
from_dict	Set the metadata of the document from a Python dict.
get_auto_reload	Get the MetaAutoReload “meta:auto-reload” element or None.
get_creation_date	Get the creation date of the document.
get_description	Get the description of the document. Also known as comments.
get_editing_cycles	Get the number of times the document was edited, as reported by the
get_editing_duration	Get the time the document was edited, as reported by the generator.
get_generator	Get the signature of the software that generated this document.
get_hyperlink_behaviour	Get the MetaHyperlinkBehaviour “meta:hyperlink-behaviour” element or
get_initial_creator	Get the first creator of the document.
get_keywords	Get the keywords of the document. Return the field as-is, without
get_language	Get the default language of the document BUT only from the metadata,
get_statistic	Get the statistics about a document, “meta:document-statistic” tag.
get_subject	Get the subject of the document.
get_template	Get the MetaTemplate “meta:template” element or None.
get_title	Get the title of the document.
get_user_defined_metadata	Get all additional user-defined metadata for a document.
get_user_defined_metadata_of_name	Return the content of the user defined metadata of that name. Return
set_auto_reload	Set the MetaAutoReload “meta:auto-reload” element.
set_creation_date	Set the creation date of the document.
set_description	Set the description of the document. Also known as comments.
set_editing_cycles	Set the number of times the document was edited.
set_editing_duration	Set the time the document was edited.
set_generator	Set the signature of the software that generated this document.
set_generator_default	Set the signature of the software that generated this document to
set_hyperlink_behaviour	Set the MetaHyperlinkBehaviour “meta:hyperlink-behaviour”
set_initial_creator	Set the first creator of the document.
set_keywords	Set the keywords of the document. Although the name is plural, a str
set_language	Set the default language of the document BUT only in the metadata,
set_statistic	Set the statistics about a document, “meta:document-statistic” tag.
set_subject	Set the subject of the document.
set_template	Set the MetaTemplate “meta:template” element.
set_title	Set the title of the document.
set_user_defined_metadata	Set a user defined metadata of that name and value.
strip	Strip metadata to their minimal content.

Attributes:

Name	Type	Description
auto_reload	MetaAutoReload | None	Get the MetaAutoReload “meta:auto-reload” element or None.
creation_date	datetime | None	Get or set the date and time when a document was created
description	str | None	Get or set the description of a document .
editing_cycles	int | None	Get or set the number of times a document has been edited
editing_duration	timedelta | None	Get or set the total time spent editing a document <meta:editing-
generator	str | None	Get or set the signature of the software that generated this
get_comments
get_meta_body
hyperlink_behaviour	MetaHyperlinkBehaviour | None	Get the MetaHyperlinkBehaviour “meta:hyperlink-behaviour” element or
initial_creator	str | None	Get or set the initial creator of a document .
keyword	str | None	Get or set some keyword(s) keyword pertaining to a document
keywords
language	str | None	Get or set the default language of the document BUT only in the
meta_body	Metadata	Return the body of the “meta.xml” part.
odf_office_version	str	Return the “office:version” value of the document.
print_date	datetime | None	Get or set the date and time when a document when a document was
printed_by	str | None	Get or set the name of the last person who printed a document.
set_comments
statistic	dict[str, int] | None	Get or set the statistics about a document, “meta:document-
subject	str | None	Get or set the subject of a document .
template	MetaTemplate | None	Get the MetaTemplate “meta:template” element or None.
title	str | None	Get or set the title of the document .
user_defined_metadata	dict[str, Any]	Get or set all additional user-defined metadata for a document.

Source code in odfdo/meta.py

class Meta(XmlPart, DcCreatorMixin, DcDateMixin):
    """Representation of the "meta.xml" part."""

    def __init__(self, *args: Any, **kwargs: Any) -> None:
        """Create the Meta XML part."""
        super().__init__(*args, **kwargs)
        self._generator_modified: bool = False

    def _get_body(self) -> Metadata:
        return self.get_element("//office:meta")  # type: ignore[return-value]

    get_meta_body = _get_body

    @property
    def meta_body(self) -> Metadata:
        """Return the body of the "meta.xml" part."""
        return self._get_body()

    @property
    def odf_office_version(self) -> str:
        """Return the "office:version" value of the document."""
        odm = self.get_element("//office:document-meta")
        # "office:version" sould be always present
        if odm:
            return odm.get_attribute_string("office:version") or ""
        return ""  # pragma: nocover

    def get_title(self) -> str | None:
        """Get the title of the document.

        This is not the first heading but the title metadata.

        (Also available as "self.title" property.)

        Returns: str (or None if inexistent)
        """
        element = self.get_element("//dc:title")
        if element is None:
            return None
        return element.text

    def set_title(self, title: str) -> None:
        """Set the title of the document.

        This is not the first heading but the title metadata.

        (Also available as "self.title" property.)

        Args:

            title -- str
        """
        element = self.get_element("//dc:title")
        if element is None:
            element = Element.from_tag("dc:title")
            self.body.append(element)
        element.text = title

    @property
    def title(self) -> str | None:
        """Get or set the title of the document <dc:title>.

        Returns: str (or None if inexistent)
        """
        return self.get_title()

    @title.setter
    def title(self, title: str) -> None:
        return self.set_title(title)

    def get_description(self) -> str | None:
        """Get the description of the document. Also known as comments.

        (Also available as "self.description" property.)

        Returns: str (or None if inexistent)
        """
        element = self.get_element("//dc:description")
        if element is None:
            return None
        return element.text

    # As named in OOo
    get_comments = get_description

    def set_description(self, description: str) -> None:
        """Set the description of the document. Also known as comments.

        (Also available as "self.description" property.)

        Args:

            description -- str
        """
        element = self.get_element("//dc:description")
        if element is None:
            element = Element.from_tag("dc:description")
            self.body.append(element)
        element.text = description

    set_comments = set_description

    @property
    def description(self) -> str | None:
        """Get or set the description of a document <dc:description>.

        Returns: str (or None if inexistent)
        """
        return self.get_description()

    @description.setter
    def description(self, description: str) -> None:
        return self.set_description(description)

    def get_subject(self) -> str | None:
        """Get the subject of the document.

        (Also available as "self.subject" property.)

        Returns: str (or None if inexistent)
        """
        element = self.get_element("//dc:subject")
        if element is None:
            return None
        return element.text

    def set_subject(self, subject: str) -> None:
        """Set the subject of the document.

        (Also available as "self.subject" property.)

        Args:

            subject -- str
        """
        element = self.get_element("//dc:subject")
        if element is None:
            element = Element.from_tag("dc:subject")
            self.body.append(element)
        element.text = subject

    @property
    def subject(self) -> str | None:
        """Get or set the subject of a document <dc:subject>.

        Returns: str (or None if inexistent)
        """
        return self.get_subject()

    @subject.setter
    def subject(self, subject: str) -> None:
        return self.set_subject(subject)

    def get_language(self) -> str | None:
        """Get the default language of the document BUT only from the metadata,
        "dc:language".

        Prefer the Document.get_language() function.

        (Also available as "self.language" property.)

        Returns: str (or None if inexistent)

        Example::

            >>> document.meta.get_language()
            fr-FR
        """
        element = self.get_element("//dc:language")
        if element is None:
            return None
        return element.text

    def set_language(self, language: str) -> None:
        """Set the default language of the document BUT only in the metadata,
        "dc:language".

        To set globally the default language, prefer the
        Document.set_language() function.

        (Also available as "self.language" property.)

        Args:

            language -- str

        Example::

            >>> document.meta.set_language('fr-FR')
        """
        language = str(language)
        if not is_RFC3066(language):
            raise TypeError(
                'Language must be "xx" lang or "xx-YY" lang-COUNTRY code (RFC3066)'
            )
        element = self.get_element("//dc:language")
        if element is None:
            element = Element.from_tag("dc:language")
            self.body.append(element)
        element.text = language

    @property
    def language(self) -> str | None:
        """Get or set the default language of the document BUT only in the
        metadata, "dc:language".

        To set globally the default language, prefer the
        Document.language property.

        Returns: str (or None if inexistent)
        """
        return self.get_language()

    @language.setter
    def language(self, language: str) -> None:
        return self.set_language(language)

    def get_creation_date(self) -> datetime | None:
        """Get the creation date of the document.

        (Also available as "self.creation_date" property.)

        Returns: datetime (or None if inexistent)
        """
        element = self.get_element("//meta:creation-date")
        if element is None:
            return None
        creation_date = element.text
        return DateTime.decode(creation_date)

    def set_creation_date(self, date: datetime | None = None) -> None:
        """Set the creation date of the document.

        If provided datetime is None, use current time.

        (Also available as "self.creation_date" property.)

        Args:

            date -- datetime
        """
        element = self.get_element("//meta:creation-date")
        if element is None:
            element = Element.from_tag("meta:creation-date")
            self.body.append(element)
        if date is None:
            date = datetime.now()
        element.text = DateTime.encode(date)

    @property
    def creation_date(self) -> datetime | None:
        """Get or set the date and time when a document was created
        <meta:creation-date>.

        If provided datetime is None, use current time.

        Returns: datetime (or None if inexistent)
        """
        return self.get_creation_date()

    @creation_date.setter
    def creation_date(self, date: datetime | None = None) -> None:
        return self.set_creation_date(date)

    @property
    def print_date(self) -> datetime | None:
        """Get or set the date and time when a document when a document was
        last printed <meta:print-date>

        If provided datetime is None, use current time.

        Returns: datetime (or None if inexistent)
        """
        element = self.get_element("//meta:print-date")
        if element is None:
            return None
        date = element.text
        return DateTime.decode(date)

    @print_date.setter
    def print_date(self, date: datetime | None = None) -> None:
        element = self.get_element("//meta:print-date")
        if element is None:
            element = Element.from_tag("meta:print-date")
            self.body.append(element)
        if date is None:
            date = datetime.now()
        element.text = DateTime.encode(date)

    def get_template(self) -> MetaTemplate | None:
        """Get the MetaTemplate "meta:template" element or None."""
        element: MetaTemplate | None = self.get_element("//meta:template")  # type: ignore[assignment]
        return element

    @property
    def template(self) -> MetaTemplate | None:
        """Get the MetaTemplate "meta:template" element or None."""
        return self.get_template()

    def set_template(
        self,
        date: datetime | None = None,
        href: str = "",
        title: str = "",
    ) -> None:
        """Set the MetaTemplate "meta:template" element."""
        template = MetaTemplate(date=date, href=href, title=title)
        current = self.template
        if isinstance(current, MetaTemplate):
            current.delete()
        self.body.append(template)

    def get_auto_reload(self) -> MetaAutoReload | None:
        """Get the MetaAutoReload "meta:auto-reload" element or None."""
        element: MetaAutoReload | None = self.get_element("//meta:auto-reload")  # type: ignore[assignment]
        return element

    @property
    def auto_reload(self) -> MetaAutoReload | None:
        """Get the MetaAutoReload "meta:auto-reload" element or None."""
        return self.get_auto_reload()

    def set_auto_reload(self, delay: timedelta, href: str = "") -> None:
        """Set the MetaAutoReload "meta:auto-reload" element."""
        autoreload = MetaAutoReload(delay=delay, href=href)
        current = self.auto_reload
        if isinstance(current, MetaAutoReload):
            current.delete()
        self.body.append(autoreload)

    def get_hyperlink_behaviour(self) -> MetaHyperlinkBehaviour | None:
        """Get the MetaHyperlinkBehaviour "meta:hyperlink-behaviour" element or
        None.
        """
        element: MetaHyperlinkBehaviour | None = self.get_element(  # type: ignore[assignment]
            "//meta:hyperlink-behaviour"
        )
        return element

    @property
    def hyperlink_behaviour(self) -> MetaHyperlinkBehaviour | None:
        """Get the MetaHyperlinkBehaviour "meta:hyperlink-behaviour" element or
        None.
        """
        return self.get_hyperlink_behaviour()

    def set_hyperlink_behaviour(
        self,
        target_frame_name: str = "_blank",
        show: str = "replace",
    ) -> None:
        """Set the MetaHyperlinkBehaviour "meta:hyperlink-behaviour"
        element.
        """
        behaviour = MetaHyperlinkBehaviour(
            target_frame_name=target_frame_name, show=show
        )
        current = self.hyperlink_behaviour
        if isinstance(current, MetaHyperlinkBehaviour):
            current.delete()
        self.body.append(behaviour)

    def get_initial_creator(self) -> str | None:
        """Get the first creator of the document.

        (Also available as "self.initial_creator" property.)

        Returns: str (or None if inexistent)

        Example::

            >>> document.meta.get_initial_creator()
            Unknown
        """
        element = self.get_element("//meta:initial-creator")
        if element is None:
            return None
        return element.text

    def set_initial_creator(self, creator: str) -> None:
        """Set the first creator of the document.

        (Also available as "self.initial_creator" property.)

        Args:

            creator -- str

        Example::

            >>> document.meta.set_initial_creator("Plato")
        """
        element = self.get_element("//meta:initial-creator")
        if element is None:
            element = Element.from_tag("meta:initial-creator")
            self.body.append(element)
        element.text = creator

    @property
    def initial_creator(self) -> str | None:
        """Get or set the initial creator of a document <meta:initial-creator>.

        Returns: str (or None if inexistent)
        """
        return self.get_initial_creator()

    @initial_creator.setter
    def initial_creator(self, creator: str) -> None:
        return self.set_initial_creator(creator)

    @property
    def printed_by(self) -> str | None:
        """Get or set the name of the last person who printed a document.
        <meta:printed-by>

        Returns: str (or None if inexistent)
        """
        element = self.get_element("//meta:printed-by")
        if element is None:
            return None
        return element.text

    @printed_by.setter
    def printed_by(self, printed_by: str) -> None:
        element = self.get_element("//meta:printed-by")
        if element is None:
            element = Element.from_tag("meta:printed-by")
            self.body.append(element)
        element.text = printed_by

    def get_keywords(self) -> str | None:
        """Get the keywords of the document. Return the field as-is, without
        any assumption on the keyword separator.

        (Also available as "self.keyword" and "self.keywords" property.)

        Returns: str (or None if inexistent)
        """
        element = self.get_element("//meta:keyword")
        if element is None:
            return None
        return element.text

    def set_keywords(self, keywords: str) -> None:
        """Set the keywords of the document. Although the name is plural, a str
        string is required, so join your list first.

        (Also available as "self.keyword" and "self.keywords" property.)

        Args:

            keywords -- str
        """
        element = self.get_element("//meta:keyword")
        if element is None:
            element = Element.from_tag("meta:keyword")
            self.body.append(element)
        element.text = keywords

    @property
    def keyword(self) -> str | None:
        """Get or set some keyword(s) keyword pertaining to a document
        <dc:keyword>.

        Returns: str (or None if inexistent)
        """
        return self.get_keywords()

    @keyword.setter
    def keyword(self, keyword: str) -> None:
        return self.set_keywords(keyword)

    keywords = keyword

    def get_editing_duration(self) -> timedelta | None:
        """Get the time the document was edited, as reported by the generator.

        (Also available as "self.editing_duration" property.)

        Returns: timedelta (or None if inexistent)
        """
        element = self.get_element("//meta:editing-duration")
        if element is None:
            return None
        duration = element.text
        return Duration.decode(duration)

    def set_editing_duration(self, duration: timedelta) -> None:
        """Set the time the document was edited.

        (Also available as "self.editing_duration" property.)

        Args:

            duration -- timedelta
        """
        if not isinstance(duration, timedelta):
            raise TypeError("duration must be a timedelta")
        element = self.get_element("//meta:editing-duration")
        if element is None:
            element = Element.from_tag("meta:editing-duration")
            self.body.append(element)
        element.text = Duration.encode(duration)

    @property
    def editing_duration(self) -> timedelta | None:
        """Get or set the total time spent editing a document <meta:editing-
        duration>.

        Returns: timedelta (or None if inexistent)
        """
        return self.get_editing_duration()

    @editing_duration.setter
    def editing_duration(self, duration: timedelta) -> None:
        return self.set_editing_duration(duration)

    def get_editing_cycles(self) -> int | None:
        """Get the number of times the document was edited, as reported by the
        generator.

        (Also available as "self.editing_cycles" property.)

        Returns: int (or None if inexistent)
        """
        element = self.get_element("//meta:editing-cycles")
        if element is None:
            return None
        cycles = element.text
        return int(cycles)

    def set_editing_cycles(self, cycles: int) -> None:
        """Set the number of times the document was edited.

        (Also available as "self.editing_cycles" property.)

        Args:

            cycles -- int
        """
        if not isinstance(cycles, int):
            raise TypeError("cycles must be an int")
        if cycles < 1:
            raise ValueError("cycles must be a positive int")
        element = self.get_element("//meta:editing-cycles")
        if element is None:
            element = Element.from_tag("meta:editing-cycles")
            self.body.append(element)
        element.text = str(cycles)

    @property
    def editing_cycles(self) -> int | None:
        """Get or set the number of times a document has been edited
        <meta:editing-cycles>.

        When a document is created, this value is set to 1. Each time
        a document is saved, the editing-cycles number is incremented by 1.

        Returns: int (or None if inexistent)
        """
        return self.get_editing_cycles()

    @editing_cycles.setter
    def editing_cycles(self, cycles: int) -> None:
        return self.set_editing_cycles(cycles)

    @property
    def generator(self) -> str | None:
        """Get or set the signature of the software that generated this
        document.

        Returns: str (or None if inexistent)

        Example::

            >>> document.meta.generator
            KOffice/2.0.0
            >>> document.meta.generator = "Odfdo experiment"
        """
        element = self.get_element("//meta:generator")
        if element is None:
            return None
        return element.text

    @generator.setter
    def generator(self, generator: str) -> None:
        element = self.get_element("//meta:generator")
        if element is None:
            element = Element.from_tag("meta:generator")
            self.body.append(element)
        element.text = generator
        self._generator_modified = True

    def get_generator(self) -> str | None:
        """Get the signature of the software that generated this document.

        (Also available as "self.generator" property.)

        Returns: str (or None if inexistent)

        Example::

            >>> document.meta.get_generator()
            KOffice/2.0.0
        """
        return self.generator

    def set_generator(self, generator: str) -> None:
        """Set the signature of the software that generated this document.

        (Also available as "self.generator" property.)

        Args:

            generator -- str

        Example::

            >>> document.meta.set_generator("Odfdo experiment")
        """
        self.generator = generator

    def set_generator_default(self) -> None:
        """Set the signature of the software that generated this document to
        ourself.

        Example::

            >>> document.meta.set_generator_default()
        """
        if not self._generator_modified:
            self.generator = GENERATOR

    def get_statistic(self) -> dict[str, int] | None:
        """Get the statistics about a document, "meta:document-statistic" tag.

        (Also available as "self.statistic" property.)

        Returns: dict (or None if inexistent)

        Example::

            >>> document.get_statistic():
            {'meta:table-count': 1,
             'meta:image-count': 2,
             'meta:object-count': 3,
             'meta:page-count': 4,
             'meta:paragraph-count': 5,
             'meta:word-count': 6,
             'meta:character-count': 7,
             'meta:non-whitespace-character-count': 3}
        """
        element = self.get_element("//meta:document-statistic")
        if element is None:
            return None
        statistic = {}
        for key, value in element.attributes.items():
            statistic[to_str(key)] = int(value)
        return statistic

    def set_statistic(self, statistic: dict[str, int]) -> None:
        """Set the statistics about a document, "meta:document-statistic" tag.

        (Also available as "self.statistic" property.)

        Args:

            statistic -- dict

        Example::

            >>> statistic = {'meta:table-count': 1,
                             'meta:image-count': 2,
                             'meta:object-count': 3,
                             'meta:page-count': 4,
                             'meta:paragraph-count': 5,
                             'meta:word-count': 6,
                             'meta:character-count': 7,
                             'meta:non-whitespace-character-count': 3}
            >>> document.meta.set_statistic(statistic)
        """
        if not isinstance(statistic, dict):
            raise TypeError("Statistic must be a dict")
        element = self.get_element("//meta:document-statistic")
        if element is None:
            element = Element.from_tag("meta:document-statistic")
            self.body.append(element)
        for key, value in statistic.items():
            try:
                ivalue = int(value)
            except ValueError as e:
                msg = f"Statistic value must be a int: {key}:{value!r}"
                raise TypeError(msg) from e
            element.set_attribute(to_str(key), str(ivalue))

    @property
    def statistic(self) -> dict[str, int] | None:
        """Get or set the statistics about a document, "meta:document-
        statistic" tag.

        Returns: dict (or None if inexistent)

        Example::

            >>> document.get_statistic():
            {'meta:table-count': 1,
             'meta:image-count': 2,
             'meta:object-count': 3,
             'meta:page-count': 4,
             'meta:paragraph-count': 5,
             'meta:word-count': 6,
             'meta:character-count': 7,
             'meta:non-whitespace-character-count':3}
        """
        return self.get_statistic()

    @statistic.setter
    def statistic(self, statistic: dict[str, int]) -> None:
        return self.set_statistic(statistic)

    def get_user_defined_metadata(self) -> dict[str, Any]:
        """Get all additional user-defined metadata for a document.

        (Also available as "self.user_defined_metadata" property.)

        Return a dict of str/value mapping.

        Value types can be: Decimal, date, time, boolean or str.
        """
        result: dict[str, Any] = {}
        for item in self.get_elements("//meta:user-defined"):
            # Read the values
            name = item.get_attribute_string("meta:name")
            if name is None:
                continue
            value = self._get_meta_value(item)
            result[name] = value
        return result

    def _user_defined_metadata_list(self) -> list[dict[str, Any]]:
        user_defined: list[dict[str, Any]] = []
        for item in self.get_elements("//meta:user-defined"):
            # Read the values
            name = item.get_attribute_string("meta:name")
            if not name:
                continue
            value, value_type, _text = self._get_meta_value_full(item)
            user_defined.append(
                {"meta:name": name, "meta:value-type": value_type, "value": value}
            )
        return sorted(user_defined, key=itemgetter("meta:name"))

    def clear_user_defined_metadata(self) -> None:
        """Remove all user-defined metadata."""
        while True:
            element = self.get_element("//meta:user-defined")
            if isinstance(element, Element):
                element.delete()
                continue
            break

    @property
    def user_defined_metadata(self) -> dict[str, Any]:
        """Get or set all additional user-defined metadata for a document.

        Return a dict of str/value mapping.

        Value types can be: Decimal, date, time, boolean or str.
        """
        return self.get_user_defined_metadata()

    @user_defined_metadata.setter
    def user_defined_metadata(self, metadata: dict[str, Any]) -> None:
        self.clear_user_defined_metadata()
        for key, val in metadata.items():
            self.set_user_defined_metadata(name=key, value=val)

    def get_user_defined_metadata_of_name(self, keyname: str) -> dict[str, Any] | None:
        """Return the content of the user defined metadata of that name. Return
        None if no name matches or a dic of fields.

        Args:

            name -- string, name (meta:name content)

        Returns: a dict with keys "name", "value", "value_type", "text".
        """
        result = {}
        found = False
        for item in self.get_elements("//meta:user-defined"):
            # Read the values
            name = item.get_attribute("meta:name")
            if name == keyname:
                found = True
                break
        if not found:
            return None
        result["name"] = name
        value, value_type, text = self._get_meta_value(item, full=True)
        result["value"] = value
        result["value_type"] = value_type
        result["text"] = text
        return result

    def set_user_defined_metadata(self, name: str, value: Any) -> None:
        """Set a user defined metadata of that name and value.

        If value is None, any existing metadata of that name is deleted.

        Args:

            name -- string, name (meta:name content)

            value -- Decimal, date, time, boolean, str, None for deletion.
        """
        if value is None:
            return self.delete_user_defined_metadata_of_name(name)
        if isinstance(value, bool):
            value_type = "boolean"
            value = "true" if value else "false"
        elif isinstance(value, (int, float, Decimal)):
            value_type = "float"
            value = str(value)
        elif isinstance(value, datetime):
            value_type = "date"
            value = str(DateTime.encode(value))
        elif isinstance(value, dtdate):
            value_type = "date"
            value = str(Date.encode(value))
        elif isinstance(value, str):
            value_type = "string"
        elif isinstance(value, timedelta):
            value_type = "time"
            value = str(Duration.encode(value))
        else:
            raise TypeError(f'unexpected type "{type(value)}" for value')
        # Already the same element ?
        for metadata in self.get_elements("//meta:user-defined"):
            if metadata.get_attribute("meta:name") == name:
                break
        else:
            metadata = Element.from_tag("meta:user-defined")
            metadata.set_attribute("meta:name", name)
            self.body.append(metadata)
        metadata.set_attribute("meta:value-type", value_type)
        metadata.text = value

    def delete_user_defined_metadata_of_name(self, name: str) -> None:
        """Delete the user-defined metadata of that name.

        Args:

            name -- string, name (meta:name content)
        """
        for metadata in self.get_elements("//meta:user-defined"):
            if metadata.get_attribute("meta:name") == name:
                metadata.delete()

    def _get_meta_value(
        self, element: Element, full: bool = False
    ) -> Any | tuple[Any, str, str]:
        """get_value() dedicated to the meta data part, for one meta element."""
        if full:
            return self._get_meta_value_full(element)
        else:
            return self._get_meta_value_full(element)[0]

    @staticmethod
    def _get_meta_value_full(element: Element) -> tuple[Any, str, str]:
        """get_value dedicated to the meta data part, for one meta element."""
        # name = element.get_attribute('meta:name')
        value_type = element.get_attribute_string("meta:value-type")
        if value_type is None:
            value_type = "string"
        text = element.text
        # Interpretation
        if value_type == "boolean":
            return (Boolean.decode(text), value_type, text)
        if value_type in ("float", "percentage", "currency"):
            return (Decimal(text), value_type, text)
        if value_type == "date":
            if "T" in text:
                return (DateTime.decode(text), value_type, text)
            else:
                return (Date.decode(text), value_type, text)
        if value_type == "string":
            return (text, value_type, text)
        if value_type == "time":
            return (Duration.decode(text), value_type, text)
        # should never happen
        raise TypeError(f"Unknown value type: '{value_type!r}'")  # pragma: nocover

    def as_dict(self, full: bool = False) -> dict[str, Any]:
        """Return the metadata of the document as a Python dict.

        if 'full' is True, export also the keys with no value assigned.

        Args:

            full -- boolean
        """

        def _stats() -> dict[str, int]:
            doc_stats = self.statistic
            if doc_stats is None:
                msg = "Document statistics not found"
                raise LookupError(msg)
            return {
                key: doc_stats.get(key, 0)
                for key in (
                    "meta:table-count",
                    "meta:image-count",
                    "meta:object-count",
                    "meta:page-count",
                    "meta:paragraph-count",
                    "meta:word-count",
                    "meta:character-count",
                    "meta:non-whitespace-character-count",
                )
            }

        def _meta_template() -> dict[str, Any] | None:
            template = self.template
            if template is None:
                return None
            return template.as_dict()

        def _meta_reload() -> dict[str, Any] | None:
            reload = self.auto_reload
            if reload is None:
                return None
            return reload.as_dict()

        def _meta_behaviour() -> dict[str, Any] | None:
            behaviour = self.hyperlink_behaviour
            if behaviour is None:
                return None
            return behaviour.as_dict()

        meta_data: dict[str, Any] = {
            "meta:creation-date": self.creation_date,
            "dc:date": self.date,
            "meta:editing-duration": self.editing_duration,
            "meta:editing-cycles": self.editing_cycles,
            "meta:document-statistic": _stats(),
            "meta:generator": self.generator,
            "dc:title": self.title,
            "dc:description": self.description,
            "dc:creator": self.creator,
            "meta:keyword": self.keyword,
            "dc:subject": self.subject,
            "dc:language": self.language,
            "meta:initial-creator": self.initial_creator,
            "meta:print-date": self.print_date,
            "meta:printed-by": self.printed_by,
            "meta:template": _meta_template(),
            "meta:auto-reload": _meta_reload(),
            "meta:hyperlink-behaviour": _meta_behaviour(),
            "meta:user-defined": self._user_defined_metadata_list(),
        }

        if not full:
            meta_data = {key: val for key, val in meta_data.items() if val}
        return meta_data

    def _as_json_dict(self, full: bool = False) -> dict[str, Any]:
        def _convert(data: dict[str, Any]) -> None:
            for key, val in data.items():
                if isinstance(val, datetime):
                    data[key] = DateTime.encode(val)
                elif isinstance(val, timedelta):
                    data[key] = Duration.encode(val)
                elif isinstance(val, Decimal):
                    data[key] = json.loads(str(Decimal(val)))

        meta_data: dict[str, Any] = self.as_dict(full=full)
        user_defined = meta_data.get("meta:user-defined", [])
        for item in user_defined:
            _convert(item)
        meta_data["meta:user-defined"] = user_defined
        meta_template = meta_data.get("meta:template")
        if meta_template is not None:
            _convert(meta_template)
            meta_data["meta:template"] = meta_template
        reload = meta_data.get("meta:auto-reload")
        if reload is not None:
            _convert(reload)
            meta_data["meta:auto-reload"] = reload
        meta_data["meta:user-defined"] = user_defined

        _convert(meta_data)
        return meta_data

    def as_json(self, full: bool = False) -> str:
        """Return the metadata of the document as a JSON string.

        if 'full' is True, export also the keys with no value assigned.

        Args:

            full -- boolean
        """
        return json.dumps(
            self._as_json_dict(full=full),
            ensure_ascii=False,
            sort_keys=False,
            indent=4,
        )

    def as_text(self, no_user_defined_msg: str = "") -> str:
        """Return meta information as text, with some formatting for
        printing.
        """
        data = self._as_json_dict(full=False)
        result: list[str] = []

        def _append_info(name: str, key: str) -> None:
            value = data.get(key)
            if value:
                result.append(f"{name}: {value}")

        _append_info("Title", "dc:title")
        _append_info("Subject", "dc:subject")
        _append_info("Description", "dc:description")
        _append_info("Language", "dc:language")
        _append_info("Modification date", "dc:date")
        _append_info("Creation date", "meta:creation-date")
        _append_info("Creator", "dc:creator")
        _append_info("Initial creator", "meta:initial-creator")
        _append_info("Keyword", "meta:keyword")
        _append_info("Editing duration", "meta:editing-duration")
        _append_info("Editing cycles", "meta:editing-cycles")
        _append_info("Generator", "meta:generator")

        result.append("Statistic:")
        statistic = data.get("meta:document-statistic", {})
        for name, value in statistic.items():
            result.append(f"  - {name[5:].replace('-', ' ').capitalize()}: {value}")

        user_metadata = data.get("meta:user-defined", [])
        if user_metadata:
            msg = ""
        else:
            msg = f" {no_user_defined_msg}"
        result.append(f"User defined metadata:{msg}")
        for item in user_metadata:
            result.append(f"  - {item['meta:name']}: {item['value']}")

        return "\n".join(result)

    @staticmethod
    def _complete_stats(
        current_stats: dict[str, int],
        imported_stats: dict[str, int] | None,
    ) -> dict[str, int]:
        if imported_stats is None:
            imported_stats = {}
            current_stats = {}
        new: dict[str, int] = {}
        for key in (
            "meta:table-count",
            "meta:image-count",
            "meta:object-count",
            "meta:page-count",
            "meta:paragraph-count",
            "meta:word-count",
            "meta:character-count",
            "meta:non-whitespace-character-count",
        ):
            new[key] = imported_stats.get(key, current_stats.get(key, 0))
        return new

    def from_dict(self, data: dict[str, Any]) -> None:
        """Set the metadata of the document from a Python dict.

        The loaded metadata are merged with the existing metadata.
        If the new value of a key is None:
            - meta:creation-date: use current time,
            - dc:date: use creation date,
            - meta:editing-duration: set to zero,
            - meta:editing-cycles: set to 1,
            - meta:generator: use odfdo generator string.
            Other keys (not mandatory keys): remove key/value pair from
            metadata.

        Args:

            data -- dict of metadata.
        """

        def _value_delete(key: str) -> Any:
            value = data.get(key, current.get(key))
            if value is None:
                child = self.get_element(f"//{key}")
                if child is not None:
                    self.delete_element(child)
            return value

        current = self.as_dict()
        new_stats = self._complete_stats(
            current["meta:document-statistic"],
            data.get("meta:document-statistic", {}),
        )
        # mandatory
        self.statistic = new_stats

        key = "meta:creation-date"
        creation_date = data.get(key, current.get(key))
        if creation_date is None:
            creation_date = datetime.now().replace(microsecond=0)
        self.creation_date = creation_date

        key = "dc:date"
        dc_date = data.get(key, current.get(key))
        if dc_date is None:
            dc_date = creation_date
        if dc_date < creation_date:
            dc_date = creation_date
        max_editing = dc_date - creation_date
        self.date = dc_date

        key = "meta:editing-duration"
        editing_duration = data.get(key, current.get(key))
        if editing_duration is None:
            editing_duration = timedelta(0)
        if editing_duration > max_editing:
            editing_duration = max_editing
        self.editing_duration = editing_duration

        key = "meta:editing-cycles"
        editing_cycles = data.get(key, current.get(key))
        if editing_cycles is None:
            editing_cycles = 1
        self.editing_cycles = max(editing_cycles, 1)

        key = "meta:generator"
        generator = data.get(key, current.get(key))
        if not generator:
            generator = GENERATOR
        self.generator = generator

        # not mandatory values
        # - if not in imported: keep original value
        # - if imported is None: erase original value

        key = "dc:title"
        value = _value_delete(key)
        if value is not None:
            self.title = value

        key = "dc:description"
        value = _value_delete(key)
        if value is not None:
            self.description = value

        key = "dc:creator"
        value = _value_delete(key)
        if value is not None:
            self.creator = value

        key = "meta:keyword"
        value = _value_delete(key)
        if value is not None:
            self.keyword = value

        key = "dc:subject"
        value = _value_delete(key)
        if value is not None:
            self.subject = value

        key = "dc:language"
        value = _value_delete(key)
        if value is not None:
            self.language = value

        key = "meta:initial-creator"
        value = _value_delete(key)
        if value is not None:
            self.initial_creator = value

        key = "meta:print-date"
        value = _value_delete(key)
        if value is not None:
            self.print_date = value

        key = "meta:printed-by"
        value = _value_delete(key)
        if value is not None:
            self.printed_by = value

        key = "meta:template"
        value = _value_delete(key)
        if value is not None:
            self.set_template(
                date=value["meta:date"],
                href=value["xlink:href"],
                title=value["xlink:title"],
            )

        key = "meta:auto-reload"
        value = _value_delete(key)
        if value is not None:
            self.set_auto_reload(
                delay=value["meta:delay"],
                href=value["xlink:href"],
            )

        key = "meta:hyperlink-behaviour"
        value = _value_delete(key)
        if value is not None:
            self.set_hyperlink_behaviour(
                target_frame_name=value["office:target-frame-name"],
                show=value["xlink:show"],
            )

        key = "meta:user-defined"
        if key in data:
            value = data[key]
            if value is None:
                self.clear_user_defined_metadata()
            else:
                data_list = self._user_defined_metadata_list()
                current_dict = {d["meta:name"]: d for d in data_list}
                current_value = {d["meta:name"]: d for d in value}
                current_dict.update(current_value)
                new_ud = {
                    v["meta:name"]: v["value"]
                    for v in current_dict.values()
                    if v["value"] is not None
                }
                self.user_defined_metadata = new_ud

    def strip(
        self,
        generator: str = GENERATOR,
        creation_date: datetime | None = None,
    ) -> None:
        """Strip metadata to their minimal content.

        By default the new metadata values are:
            - meta:creation-date: use current time,
            - dc:date: use creation date,
            - meta:editing-duration: set to zero,
            - meta:editing-cycles: set to 1,
            - meta:generator: use odfdo generator string.
            - all meta:document-statistic values to 0.

        All user defined metadata are removed.

        Args:

            generator -- str, string for the meta:generator field.

            creation_date -- datetime or None, meta:creation-date value.
        """

        self.body.clear()
        self.statistic = self._complete_stats({}, None)
        if creation_date is None:
            self.creation_date = datetime.now().replace(microsecond=0)
        else:
            self.creation_date = creation_date.replace(microsecond=0)
        self.date = self.creation_date
        self.editing_duration = timedelta(0)
        self.editing_cycles = 1
        self.generator = generator
        self.clear_user_defined_metadata()

auto_reload property

auto_reload: MetaAutoReload | None

Get the MetaAutoReload “meta:auto-reload” element or None.

creation_date property writable

creation_date: datetime | None

Get or set the date and time when a document was created .

If provided datetime is None, use current time.

Returns: datetime (or None if inexistent)

description property writable

description: str | None

Get or set the description of a document .

Returns: str (or None if inexistent)

editing_cycles property writable

editing_cycles: int | None

Get or set the number of times a document has been edited .

When a document is created, this value is set to 1. Each time a document is saved, the editing-cycles number is incremented by 1.

Returns: int (or None if inexistent)

editing_duration property writable

editing_duration: timedelta | None

Get or set the total time spent editing a document .

Returns: timedelta (or None if inexistent)

generator property writable

generator: str | None

Get or set the signature of the software that generated this document.

Returns: str (or None if inexistent)

Example::

>>> document.meta.generator
KOffice/2.0.0
>>> document.meta.generator = "Odfdo experiment"

get_comments class-attribute instance-attribute

get_comments = get_description

get_meta_body class-attribute instance-attribute

get_meta_body = _get_body

hyperlink_behaviour property

hyperlink_behaviour: MetaHyperlinkBehaviour | None

Get the MetaHyperlinkBehaviour “meta:hyperlink-behaviour” element or None.

initial_creator property writable

initial_creator: str | None

Get or set the initial creator of a document .

Returns: str (or None if inexistent)

keyword property writable

keyword: str | None

Get or set some keyword(s) keyword pertaining to a document .

Returns: str (or None if inexistent)

keywords class-attribute instance-attribute

keywords = keyword

language property writable

language: str | None

Get or set the default language of the document BUT only in the metadata, “dc:language”.

To set globally the default language, prefer the Document.language property.

Returns: str (or None if inexistent)

meta_body property

meta_body: Metadata

Return the body of the “meta.xml” part.

odf_office_version property

odf_office_version: str

Return the “office:version” value of the document.

print_date property writable

print_date: datetime | None

Get or set the date and time when a document when a document was last printed

If provided datetime is None, use current time.

Returns: datetime (or None if inexistent)

printed_by property writable

printed_by: str | None

Get or set the name of the last person who printed a document.

Returns: str (or None if inexistent)

set_comments class-attribute instance-attribute

set_comments = set_description

statistic property writable

statistic: dict[str, int] | None

Get or set the statistics about a document, “meta:document- statistic” tag.

Returns: dict (or None if inexistent)

Example::

>>> document.get_statistic():
{'meta:table-count': 1,
 'meta:image-count': 2,
 'meta:object-count': 3,
 'meta:page-count': 4,
 'meta:paragraph-count': 5,
 'meta:word-count': 6,
 'meta:character-count': 7,
 'meta:non-whitespace-character-count':3}

subject property writable

subject: str | None

Get or set the subject of a document .

Returns: str (or None if inexistent)

template property

template: MetaTemplate | None

Get the MetaTemplate “meta:template” element or None.

title property writable

title: str | None

Get or set the title of the document .

Returns: str (or None if inexistent)

user_defined_metadata property writable

user_defined_metadata: dict[str, Any]

Get or set all additional user-defined metadata for a document.

Return a dict of str/value mapping.

Value types can be: Decimal, date, time, boolean or str.

__init__

__init__(*args: Any, **kwargs: Any) -> None

Create the Meta XML part.

Source code in odfdo/meta.py

def __init__(self, *args: Any, **kwargs: Any) -> None:
    """Create the Meta XML part."""
    super().__init__(*args, **kwargs)
    self._generator_modified: bool = False

as_dict

as_dict(full: bool = False) -> dict[str, Any]

Return the metadata of the document as a Python dict.

if ‘full’ is True, export also the keys with no value assigned.

Args:

full -- boolean

Source code in odfdo/meta.py

def as_dict(self, full: bool = False) -> dict[str, Any]:
    """Return the metadata of the document as a Python dict.

    if 'full' is True, export also the keys with no value assigned.

    Args:

        full -- boolean
    """

    def _stats() -> dict[str, int]:
        doc_stats = self.statistic
        if doc_stats is None:
            msg = "Document statistics not found"
            raise LookupError(msg)
        return {
            key: doc_stats.get(key, 0)
            for key in (
                "meta:table-count",
                "meta:image-count",
                "meta:object-count",
                "meta:page-count",
                "meta:paragraph-count",
                "meta:word-count",
                "meta:character-count",
                "meta:non-whitespace-character-count",
            )
        }

    def _meta_template() -> dict[str, Any] | None:
        template = self.template
        if template is None:
            return None
        return template.as_dict()

    def _meta_reload() -> dict[str, Any] | None:
        reload = self.auto_reload
        if reload is None:
            return None
        return reload.as_dict()

    def _meta_behaviour() -> dict[str, Any] | None:
        behaviour = self.hyperlink_behaviour
        if behaviour is None:
            return None
        return behaviour.as_dict()

    meta_data: dict[str, Any] = {
        "meta:creation-date": self.creation_date,
        "dc:date": self.date,
        "meta:editing-duration": self.editing_duration,
        "meta:editing-cycles": self.editing_cycles,
        "meta:document-statistic": _stats(),
        "meta:generator": self.generator,
        "dc:title": self.title,
        "dc:description": self.description,
        "dc:creator": self.creator,
        "meta:keyword": self.keyword,
        "dc:subject": self.subject,
        "dc:language": self.language,
        "meta:initial-creator": self.initial_creator,
        "meta:print-date": self.print_date,
        "meta:printed-by": self.printed_by,
        "meta:template": _meta_template(),
        "meta:auto-reload": _meta_reload(),
        "meta:hyperlink-behaviour": _meta_behaviour(),
        "meta:user-defined": self._user_defined_metadata_list(),
    }

    if not full:
        meta_data = {key: val for key, val in meta_data.items() if val}
    return meta_data

as_json

as_json(full: bool = False) -> str

Return the metadata of the document as a JSON string.

if ‘full’ is True, export also the keys with no value assigned.

Args:

full -- boolean

Source code in odfdo/meta.py

def as_json(self, full: bool = False) -> str:
    """Return the metadata of the document as a JSON string.

    if 'full' is True, export also the keys with no value assigned.

    Args:

        full -- boolean
    """
    return json.dumps(
        self._as_json_dict(full=full),
        ensure_ascii=False,
        sort_keys=False,
        indent=4,
    )

as_text

as_text(no_user_defined_msg: str = '') -> str

Return meta information as text, with some formatting for printing.

Source code in odfdo/meta.py

def as_text(self, no_user_defined_msg: str = "") -> str:
    """Return meta information as text, with some formatting for
    printing.
    """
    data = self._as_json_dict(full=False)
    result: list[str] = []

    def _append_info(name: str, key: str) -> None:
        value = data.get(key)
        if value:
            result.append(f"{name}: {value}")

    _append_info("Title", "dc:title")
    _append_info("Subject", "dc:subject")
    _append_info("Description", "dc:description")
    _append_info("Language", "dc:language")
    _append_info("Modification date", "dc:date")
    _append_info("Creation date", "meta:creation-date")
    _append_info("Creator", "dc:creator")
    _append_info("Initial creator", "meta:initial-creator")
    _append_info("Keyword", "meta:keyword")
    _append_info("Editing duration", "meta:editing-duration")
    _append_info("Editing cycles", "meta:editing-cycles")
    _append_info("Generator", "meta:generator")

    result.append("Statistic:")
    statistic = data.get("meta:document-statistic", {})
    for name, value in statistic.items():
        result.append(f"  - {name[5:].replace('-', ' ').capitalize()}: {value}")

    user_metadata = data.get("meta:user-defined", [])
    if user_metadata:
        msg = ""
    else:
        msg = f" {no_user_defined_msg}"
    result.append(f"User defined metadata:{msg}")
    for item in user_metadata:
        result.append(f"  - {item['meta:name']}: {item['value']}")

    return "\n".join(result)

clear_user_defined_metadata

clear_user_defined_metadata() -> None

Remove all user-defined metadata.

Source code in odfdo/meta.py

def clear_user_defined_metadata(self) -> None:
    """Remove all user-defined metadata."""
    while True:
        element = self.get_element("//meta:user-defined")
        if isinstance(element, Element):
            element.delete()
            continue
        break

delete_user_defined_metadata_of_name

delete_user_defined_metadata_of_name(name: str) -> None

Delete the user-defined metadata of that name.

Args:

name -- string, name (meta:name content)

Source code in odfdo/meta.py

def delete_user_defined_metadata_of_name(self, name: str) -> None:
    """Delete the user-defined metadata of that name.

    Args:

        name -- string, name (meta:name content)
    """
    for metadata in self.get_elements("//meta:user-defined"):
        if metadata.get_attribute("meta:name") == name:
            metadata.delete()

from_dict

from_dict(data: dict[str, Any]) -> None

Set the metadata of the document from a Python dict.

The loaded metadata are merged with the existing metadata. If the new value of a key is None: - meta:creation-date: use current time, - dc:date: use creation date, - meta:editing-duration: set to zero, - meta:editing-cycles: set to 1, - meta:generator: use odfdo generator string. Other keys (not mandatory keys): remove key/value pair from metadata.

Args:

data -- dict of metadata.

Source code in odfdo/meta.py

def from_dict(self, data: dict[str, Any]) -> None:
    """Set the metadata of the document from a Python dict.

    The loaded metadata are merged with the existing metadata.
    If the new value of a key is None:
        - meta:creation-date: use current time,
        - dc:date: use creation date,
        - meta:editing-duration: set to zero,
        - meta:editing-cycles: set to 1,
        - meta:generator: use odfdo generator string.
        Other keys (not mandatory keys): remove key/value pair from
        metadata.

    Args:

        data -- dict of metadata.
    """

    def _value_delete(key: str) -> Any:
        value = data.get(key, current.get(key))
        if value is None:
            child = self.get_element(f"//{key}")
            if child is not None:
                self.delete_element(child)
        return value

    current = self.as_dict()
    new_stats = self._complete_stats(
        current["meta:document-statistic"],
        data.get("meta:document-statistic", {}),
    )
    # mandatory
    self.statistic = new_stats

    key = "meta:creation-date"
    creation_date = data.get(key, current.get(key))
    if creation_date is None:
        creation_date = datetime.now().replace(microsecond=0)
    self.creation_date = creation_date

    key = "dc:date"
    dc_date = data.get(key, current.get(key))
    if dc_date is None:
        dc_date = creation_date
    if dc_date < creation_date:
        dc_date = creation_date
    max_editing = dc_date - creation_date
    self.date = dc_date

    key = "meta:editing-duration"
    editing_duration = data.get(key, current.get(key))
    if editing_duration is None:
        editing_duration = timedelta(0)
    if editing_duration > max_editing:
        editing_duration = max_editing
    self.editing_duration = editing_duration

    key = "meta:editing-cycles"
    editing_cycles = data.get(key, current.get(key))
    if editing_cycles is None:
        editing_cycles = 1
    self.editing_cycles = max(editing_cycles, 1)

    key = "meta:generator"
    generator = data.get(key, current.get(key))
    if not generator:
        generator = GENERATOR
    self.generator = generator

    # not mandatory values
    # - if not in imported: keep original value
    # - if imported is None: erase original value

    key = "dc:title"
    value = _value_delete(key)
    if value is not None:
        self.title = value

    key = "dc:description"
    value = _value_delete(key)
    if value is not None:
        self.description = value

    key = "dc:creator"
    value = _value_delete(key)
    if value is not None:
        self.creator = value

    key = "meta:keyword"
    value = _value_delete(key)
    if value is not None:
        self.keyword = value

    key = "dc:subject"
    value = _value_delete(key)
    if value is not None:
        self.subject = value

    key = "dc:language"
    value = _value_delete(key)
    if value is not None:
        self.language = value

    key = "meta:initial-creator"
    value = _value_delete(key)
    if value is not None:
        self.initial_creator = value

    key = "meta:print-date"
    value = _value_delete(key)
    if value is not None:
        self.print_date = value

    key = "meta:printed-by"
    value = _value_delete(key)
    if value is not None:
        self.printed_by = value

    key = "meta:template"
    value = _value_delete(key)
    if value is not None:
        self.set_template(
            date=value["meta:date"],
            href=value["xlink:href"],
            title=value["xlink:title"],
        )

    key = "meta:auto-reload"
    value = _value_delete(key)
    if value is not None:
        self.set_auto_reload(
            delay=value["meta:delay"],
            href=value["xlink:href"],
        )

    key = "meta:hyperlink-behaviour"
    value = _value_delete(key)
    if value is not None:
        self.set_hyperlink_behaviour(
            target_frame_name=value["office:target-frame-name"],
            show=value["xlink:show"],
        )

    key = "meta:user-defined"
    if key in data:
        value = data[key]
        if value is None:
            self.clear_user_defined_metadata()
        else:
            data_list = self._user_defined_metadata_list()
            current_dict = {d["meta:name"]: d for d in data_list}
            current_value = {d["meta:name"]: d for d in value}
            current_dict.update(current_value)
            new_ud = {
                v["meta:name"]: v["value"]
                for v in current_dict.values()
                if v["value"] is not None
            }
            self.user_defined_metadata = new_ud

get_auto_reload

get_auto_reload() -> MetaAutoReload | None

Get the MetaAutoReload “meta:auto-reload” element or None.

Source code in odfdo/meta.py

def get_auto_reload(self) -> MetaAutoReload | None:
    """Get the MetaAutoReload "meta:auto-reload" element or None."""
    element: MetaAutoReload | None = self.get_element("//meta:auto-reload")  # type: ignore[assignment]
    return element

get_creation_date

get_creation_date() -> datetime | None

Get the creation date of the document.

(Also available as “self.creation_date” property.)

Returns: datetime (or None if inexistent)

Source code in odfdo/meta.py

def get_creation_date(self) -> datetime | None:
    """Get the creation date of the document.

    (Also available as "self.creation_date" property.)

    Returns: datetime (or None if inexistent)
    """
    element = self.get_element("//meta:creation-date")
    if element is None:
        return None
    creation_date = element.text
    return DateTime.decode(creation_date)

get_description

get_description() -> str | None

Get the description of the document. Also known as comments.

(Also available as “self.description” property.)

Returns: str (or None if inexistent)

Source code in odfdo/meta.py

def get_description(self) -> str | None:
    """Get the description of the document. Also known as comments.

    (Also available as "self.description" property.)

    Returns: str (or None if inexistent)
    """
    element = self.get_element("//dc:description")
    if element is None:
        return None
    return element.text

get_editing_cycles

get_editing_cycles() -> int | None

Get the number of times the document was edited, as reported by the generator.

(Also available as “self.editing_cycles” property.)

Returns: int (or None if inexistent)

Source code in odfdo/meta.py

def get_editing_cycles(self) -> int | None:
    """Get the number of times the document was edited, as reported by the
    generator.

    (Also available as "self.editing_cycles" property.)

    Returns: int (or None if inexistent)
    """
    element = self.get_element("//meta:editing-cycles")
    if element is None:
        return None
    cycles = element.text
    return int(cycles)

get_editing_duration

get_editing_duration() -> timedelta | None

Get the time the document was edited, as reported by the generator.

(Also available as “self.editing_duration” property.)

Returns: timedelta (or None if inexistent)

Source code in odfdo/meta.py

def get_editing_duration(self) -> timedelta | None:
    """Get the time the document was edited, as reported by the generator.

    (Also available as "self.editing_duration" property.)

    Returns: timedelta (or None if inexistent)
    """
    element = self.get_element("//meta:editing-duration")
    if element is None:
        return None
    duration = element.text
    return Duration.decode(duration)

get_generator

get_generator() -> str | None

Get the signature of the software that generated this document.

(Also available as “self.generator” property.)

Returns: str (or None if inexistent)

Example::

>>> document.meta.get_generator()
KOffice/2.0.0

Source code in odfdo/meta.py

def get_generator(self) -> str | None:
    """Get the signature of the software that generated this document.

    (Also available as "self.generator" property.)

    Returns: str (or None if inexistent)

    Example::

        >>> document.meta.get_generator()
        KOffice/2.0.0
    """
    return self.generator

get_hyperlink_behaviour

get_hyperlink_behaviour() -> MetaHyperlinkBehaviour | None

Get the MetaHyperlinkBehaviour “meta:hyperlink-behaviour” element or None.

Source code in odfdo/meta.py

def get_hyperlink_behaviour(self) -> MetaHyperlinkBehaviour | None:
    """Get the MetaHyperlinkBehaviour "meta:hyperlink-behaviour" element or
    None.
    """
    element: MetaHyperlinkBehaviour | None = self.get_element(  # type: ignore[assignment]
        "//meta:hyperlink-behaviour"
    )
    return element

get_initial_creator

get_initial_creator() -> str | None

Get the first creator of the document.

(Also available as “self.initial_creator” property.)

Returns: str (or None if inexistent)

Example::

>>> document.meta.get_initial_creator()
Unknown

Source code in odfdo/meta.py

def get_initial_creator(self) -> str | None:
    """Get the first creator of the document.

    (Also available as "self.initial_creator" property.)

    Returns: str (or None if inexistent)

    Example::

        >>> document.meta.get_initial_creator()
        Unknown
    """
    element = self.get_element("//meta:initial-creator")
    if element is None:
        return None
    return element.text

get_keywords

get_keywords() -> str | None

Get the keywords of the document. Return the field as-is, without any assumption on the keyword separator.

(Also available as “self.keyword” and “self.keywords” property.)

Returns: str (or None if inexistent)

Source code in odfdo/meta.py

def get_keywords(self) -> str | None:
    """Get the keywords of the document. Return the field as-is, without
    any assumption on the keyword separator.

    (Also available as "self.keyword" and "self.keywords" property.)

    Returns: str (or None if inexistent)
    """
    element = self.get_element("//meta:keyword")
    if element is None:
        return None
    return element.text

get_language

get_language() -> str | None

Get the default language of the document BUT only from the metadata, “dc:language”.

Prefer the Document.get_language() function.

(Also available as “self.language” property.)

Returns: str (or None if inexistent)

Example::

>>> document.meta.get_language()
fr-FR

Source code in odfdo/meta.py

def get_language(self) -> str | None:
    """Get the default language of the document BUT only from the metadata,
    "dc:language".

    Prefer the Document.get_language() function.

    (Also available as "self.language" property.)

    Returns: str (or None if inexistent)

    Example::

        >>> document.meta.get_language()
        fr-FR
    """
    element = self.get_element("//dc:language")
    if element is None:
        return None
    return element.text

get_statistic

get_statistic() -> dict[str, int] | None

Get the statistics about a document, “meta:document-statistic” tag.

(Also available as “self.statistic” property.)

Returns: dict (or None if inexistent)

Example::

>>> document.get_statistic():
{'meta:table-count': 1,
 'meta:image-count': 2,
 'meta:object-count': 3,
 'meta:page-count': 4,
 'meta:paragraph-count': 5,
 'meta:word-count': 6,
 'meta:character-count': 7,
 'meta:non-whitespace-character-count': 3}

Source code in odfdo/meta.py

def get_statistic(self) -> dict[str, int] | None:
    """Get the statistics about a document, "meta:document-statistic" tag.

    (Also available as "self.statistic" property.)

    Returns: dict (or None if inexistent)

    Example::

        >>> document.get_statistic():
        {'meta:table-count': 1,
         'meta:image-count': 2,
         'meta:object-count': 3,
         'meta:page-count': 4,
         'meta:paragraph-count': 5,
         'meta:word-count': 6,
         'meta:character-count': 7,
         'meta:non-whitespace-character-count': 3}
    """
    element = self.get_element("//meta:document-statistic")
    if element is None:
        return None
    statistic = {}
    for key, value in element.attributes.items():
        statistic[to_str(key)] = int(value)
    return statistic

get_subject

get_subject() -> str | None

Get the subject of the document.

(Also available as “self.subject” property.)

Returns: str (or None if inexistent)

Source code in odfdo/meta.py

def get_subject(self) -> str | None:
    """Get the subject of the document.

    (Also available as "self.subject" property.)

    Returns: str (or None if inexistent)
    """
    element = self.get_element("//dc:subject")
    if element is None:
        return None
    return element.text

get_template

get_template() -> MetaTemplate | None

Get the MetaTemplate “meta:template” element or None.

Source code in odfdo/meta.py

def get_template(self) -> MetaTemplate | None:
    """Get the MetaTemplate "meta:template" element or None."""
    element: MetaTemplate | None = self.get_element("//meta:template")  # type: ignore[assignment]
    return element

get_title

get_title() -> str | None

Get the title of the document.

This is not the first heading but the title metadata.

(Also available as “self.title” property.)

Returns: str (or None if inexistent)

Source code in odfdo/meta.py

def get_title(self) -> str | None:
    """Get the title of the document.

    This is not the first heading but the title metadata.

    (Also available as "self.title" property.)

    Returns: str (or None if inexistent)
    """
    element = self.get_element("//dc:title")
    if element is None:
        return None
    return element.text

get_user_defined_metadata

get_user_defined_metadata() -> dict[str, Any]

Get all additional user-defined metadata for a document.

(Also available as “self.user_defined_metadata” property.)

Return a dict of str/value mapping.

Value types can be: Decimal, date, time, boolean or str.

Source code in odfdo/meta.py

def get_user_defined_metadata(self) -> dict[str, Any]:
    """Get all additional user-defined metadata for a document.

    (Also available as "self.user_defined_metadata" property.)

    Return a dict of str/value mapping.

    Value types can be: Decimal, date, time, boolean or str.
    """
    result: dict[str, Any] = {}
    for item in self.get_elements("//meta:user-defined"):
        # Read the values
        name = item.get_attribute_string("meta:name")
        if name is None:
            continue
        value = self._get_meta_value(item)
        result[name] = value
    return result

get_user_defined_metadata_of_name

get_user_defined_metadata_of_name(
    keyname: str,
) -> dict[str, Any] | None

Return the content of the user defined metadata of that name. Return None if no name matches or a dic of fields.

Args:

name -- string, name (meta:name content)

Returns: a dict with keys “name”, “value”, “value_type”, “text”.

Source code in odfdo/meta.py

def get_user_defined_metadata_of_name(self, keyname: str) -> dict[str, Any] | None:
    """Return the content of the user defined metadata of that name. Return
    None if no name matches or a dic of fields.

    Args:

        name -- string, name (meta:name content)

    Returns: a dict with keys "name", "value", "value_type", "text".
    """
    result = {}
    found = False
    for item in self.get_elements("//meta:user-defined"):
        # Read the values
        name = item.get_attribute("meta:name")
        if name == keyname:
            found = True
            break
    if not found:
        return None
    result["name"] = name
    value, value_type, text = self._get_meta_value(item, full=True)
    result["value"] = value
    result["value_type"] = value_type
    result["text"] = text
    return result

set_auto_reload

set_auto_reload(delay: timedelta, href: str = '') -> None

Set the MetaAutoReload “meta:auto-reload” element.

Source code in odfdo/meta.py

def set_auto_reload(self, delay: timedelta, href: str = "") -> None:
    """Set the MetaAutoReload "meta:auto-reload" element."""
    autoreload = MetaAutoReload(delay=delay, href=href)
    current = self.auto_reload
    if isinstance(current, MetaAutoReload):
        current.delete()
    self.body.append(autoreload)

set_creation_date

set_creation_date(date: datetime | None = None) -> None

Set the creation date of the document.

If provided datetime is None, use current time.

(Also available as “self.creation_date” property.)

Args:

date -- datetime

Source code in odfdo/meta.py

def set_creation_date(self, date: datetime | None = None) -> None:
    """Set the creation date of the document.

    If provided datetime is None, use current time.

    (Also available as "self.creation_date" property.)

    Args:

        date -- datetime
    """
    element = self.get_element("//meta:creation-date")
    if element is None:
        element = Element.from_tag("meta:creation-date")
        self.body.append(element)
    if date is None:
        date = datetime.now()
    element.text = DateTime.encode(date)

set_description

set_description(description: str) -> None

Set the description of the document. Also known as comments.

(Also available as “self.description” property.)

Args:

description -- str

Source code in odfdo/meta.py

def set_description(self, description: str) -> None:
    """Set the description of the document. Also known as comments.

    (Also available as "self.description" property.)

    Args:

        description -- str
    """
    element = self.get_element("//dc:description")
    if element is None:
        element = Element.from_tag("dc:description")
        self.body.append(element)
    element.text = description

set_editing_cycles

set_editing_cycles(cycles: int) -> None

Set the number of times the document was edited.

(Also available as “self.editing_cycles” property.)

Args:

cycles -- int

Source code in odfdo/meta.py

def set_editing_cycles(self, cycles: int) -> None:
    """Set the number of times the document was edited.

    (Also available as "self.editing_cycles" property.)

    Args:

        cycles -- int
    """
    if not isinstance(cycles, int):
        raise TypeError("cycles must be an int")
    if cycles < 1:
        raise ValueError("cycles must be a positive int")
    element = self.get_element("//meta:editing-cycles")
    if element is None:
        element = Element.from_tag("meta:editing-cycles")
        self.body.append(element)
    element.text = str(cycles)

set_editing_duration

set_editing_duration(duration: timedelta) -> None

Set the time the document was edited.

(Also available as “self.editing_duration” property.)

Args:

duration -- timedelta

Source code in odfdo/meta.py

def set_editing_duration(self, duration: timedelta) -> None:
    """Set the time the document was edited.

    (Also available as "self.editing_duration" property.)

    Args:

        duration -- timedelta
    """
    if not isinstance(duration, timedelta):
        raise TypeError("duration must be a timedelta")
    element = self.get_element("//meta:editing-duration")
    if element is None:
        element = Element.from_tag("meta:editing-duration")
        self.body.append(element)
    element.text = Duration.encode(duration)

set_generator

set_generator(generator: str) -> None

Set the signature of the software that generated this document.

(Also available as “self.generator” property.)

Args:

generator -- str

Example::

>>> document.meta.set_generator("Odfdo experiment")

Source code in odfdo/meta.py

def set_generator(self, generator: str) -> None:
    """Set the signature of the software that generated this document.

    (Also available as "self.generator" property.)

    Args:

        generator -- str

    Example::

        >>> document.meta.set_generator("Odfdo experiment")
    """
    self.generator = generator

set_generator_default

set_generator_default() -> None

Set the signature of the software that generated this document to ourself.

Example::

>>> document.meta.set_generator_default()

Source code in odfdo/meta.py

def set_generator_default(self) -> None:
    """Set the signature of the software that generated this document to
    ourself.

    Example::

        >>> document.meta.set_generator_default()
    """
    if not self._generator_modified:
        self.generator = GENERATOR

set_hyperlink_behaviour

set_hyperlink_behaviour(
    target_frame_name: str = "_blank", show: str = "replace"
) -> None

Set the MetaHyperlinkBehaviour “meta:hyperlink-behaviour” element.

Source code in odfdo/meta.py

def set_hyperlink_behaviour(
    self,
    target_frame_name: str = "_blank",
    show: str = "replace",
) -> None:
    """Set the MetaHyperlinkBehaviour "meta:hyperlink-behaviour"
    element.
    """
    behaviour = MetaHyperlinkBehaviour(
        target_frame_name=target_frame_name, show=show
    )
    current = self.hyperlink_behaviour
    if isinstance(current, MetaHyperlinkBehaviour):
        current.delete()
    self.body.append(behaviour)

set_initial_creator

set_initial_creator(creator: str) -> None

Set the first creator of the document.

(Also available as “self.initial_creator” property.)

Args:

creator -- str

Example::

>>> document.meta.set_initial_creator("Plato")

Source code in odfdo/meta.py

def set_initial_creator(self, creator: str) -> None:
    """Set the first creator of the document.

    (Also available as "self.initial_creator" property.)

    Args:

        creator -- str

    Example::

        >>> document.meta.set_initial_creator("Plato")
    """
    element = self.get_element("//meta:initial-creator")
    if element is None:
        element = Element.from_tag("meta:initial-creator")
        self.body.append(element)
    element.text = creator

set_keywords

set_keywords(keywords: str) -> None

Set the keywords of the document. Although the name is plural, a str string is required, so join your list first.

(Also available as “self.keyword” and “self.keywords” property.)

Args:

keywords -- str

Source code in odfdo/meta.py

def set_keywords(self, keywords: str) -> None:
    """Set the keywords of the document. Although the name is plural, a str
    string is required, so join your list first.

    (Also available as "self.keyword" and "self.keywords" property.)

    Args:

        keywords -- str
    """
    element = self.get_element("//meta:keyword")
    if element is None:
        element = Element.from_tag("meta:keyword")
        self.body.append(element)
    element.text = keywords

set_language

set_language(language: str) -> None

Set the default language of the document BUT only in the metadata, “dc:language”.

To set globally the default language, prefer the Document.set_language() function.

(Also available as “self.language” property.)

Args:

language -- str

Example::

>>> document.meta.set_language('fr-FR')

Source code in odfdo/meta.py

def set_language(self, language: str) -> None:
    """Set the default language of the document BUT only in the metadata,
    "dc:language".

    To set globally the default language, prefer the
    Document.set_language() function.

    (Also available as "self.language" property.)

    Args:

        language -- str

    Example::

        >>> document.meta.set_language('fr-FR')
    """
    language = str(language)
    if not is_RFC3066(language):
        raise TypeError(
            'Language must be "xx" lang or "xx-YY" lang-COUNTRY code (RFC3066)'
        )
    element = self.get_element("//dc:language")
    if element is None:
        element = Element.from_tag("dc:language")
        self.body.append(element)
    element.text = language

set_statistic

set_statistic(statistic: dict[str, int]) -> None

Set the statistics about a document, “meta:document-statistic” tag.

(Also available as “self.statistic” property.)

Args:

statistic -- dict

Example::

>>> statistic = {'meta:table-count': 1,
                 'meta:image-count': 2,
                 'meta:object-count': 3,
                 'meta:page-count': 4,
                 'meta:paragraph-count': 5,
                 'meta:word-count': 6,
                 'meta:character-count': 7,
                 'meta:non-whitespace-character-count': 3}
>>> document.meta.set_statistic(statistic)

Source code in odfdo/meta.py

def set_statistic(self, statistic: dict[str, int]) -> None:
    """Set the statistics about a document, "meta:document-statistic" tag.

    (Also available as "self.statistic" property.)

    Args:

        statistic -- dict

    Example::

        >>> statistic = {'meta:table-count': 1,
                         'meta:image-count': 2,
                         'meta:object-count': 3,
                         'meta:page-count': 4,
                         'meta:paragraph-count': 5,
                         'meta:word-count': 6,
                         'meta:character-count': 7,
                         'meta:non-whitespace-character-count': 3}
        >>> document.meta.set_statistic(statistic)
    """
    if not isinstance(statistic, dict):
        raise TypeError("Statistic must be a dict")
    element = self.get_element("//meta:document-statistic")
    if element is None:
        element = Element.from_tag("meta:document-statistic")
        self.body.append(element)
    for key, value in statistic.items():
        try:
            ivalue = int(value)
        except ValueError as e:
            msg = f"Statistic value must be a int: {key}:{value!r}"
            raise TypeError(msg) from e
        element.set_attribute(to_str(key), str(ivalue))

set_subject

set_subject(subject: str) -> None

Set the subject of the document.

(Also available as “self.subject” property.)

Args:

subject -- str

Source code in odfdo/meta.py

def set_subject(self, subject: str) -> None:
    """Set the subject of the document.

    (Also available as "self.subject" property.)

    Args:

        subject -- str
    """
    element = self.get_element("//dc:subject")
    if element is None:
        element = Element.from_tag("dc:subject")
        self.body.append(element)
    element.text = subject

set_template

set_template(
    date: datetime | None = None,
    href: str = "",
    title: str = "",
) -> None

Set the MetaTemplate “meta:template” element.

Source code in odfdo/meta.py

def set_template(
    self,
    date: datetime | None = None,
    href: str = "",
    title: str = "",
) -> None:
    """Set the MetaTemplate "meta:template" element."""
    template = MetaTemplate(date=date, href=href, title=title)
    current = self.template
    if isinstance(current, MetaTemplate):
        current.delete()
    self.body.append(template)

set_title

set_title(title: str) -> None

Set the title of the document.

This is not the first heading but the title metadata.

(Also available as “self.title” property.)

Args:

title -- str

Source code in odfdo/meta.py

def set_title(self, title: str) -> None:
    """Set the title of the document.

    This is not the first heading but the title metadata.

    (Also available as "self.title" property.)

    Args:

        title -- str
    """
    element = self.get_element("//dc:title")
    if element is None:
        element = Element.from_tag("dc:title")
        self.body.append(element)
    element.text = title

set_user_defined_metadata

set_user_defined_metadata(name: str, value: Any) -> None

Set a user defined metadata of that name and value.

If value is None, any existing metadata of that name is deleted.

Args:

name -- string, name (meta:name content)

value -- Decimal, date, time, boolean, str, None for deletion.

Source code in odfdo/meta.py

def set_user_defined_metadata(self, name: str, value: Any) -> None:
    """Set a user defined metadata of that name and value.

    If value is None, any existing metadata of that name is deleted.

    Args:

        name -- string, name (meta:name content)

        value -- Decimal, date, time, boolean, str, None for deletion.
    """
    if value is None:
        return self.delete_user_defined_metadata_of_name(name)
    if isinstance(value, bool):
        value_type = "boolean"
        value = "true" if value else "false"
    elif isinstance(value, (int, float, Decimal)):
        value_type = "float"
        value = str(value)
    elif isinstance(value, datetime):
        value_type = "date"
        value = str(DateTime.encode(value))
    elif isinstance(value, dtdate):
        value_type = "date"
        value = str(Date.encode(value))
    elif isinstance(value, str):
        value_type = "string"
    elif isinstance(value, timedelta):
        value_type = "time"
        value = str(Duration.encode(value))
    else:
        raise TypeError(f'unexpected type "{type(value)}" for value')
    # Already the same element ?
    for metadata in self.get_elements("//meta:user-defined"):
        if metadata.get_attribute("meta:name") == name:
            break
    else:
        metadata = Element.from_tag("meta:user-defined")
        metadata.set_attribute("meta:name", name)
        self.body.append(metadata)
    metadata.set_attribute("meta:value-type", value_type)
    metadata.text = value

strip

strip(
    generator: str = GENERATOR,
    creation_date: datetime | None = None,
) -> None

Strip metadata to their minimal content.

By default the new metadata values are

• meta:creation-date: use current time,
• dc:date: use creation date,
• meta:editing-duration: set to zero,
• meta:editing-cycles: set to 1,
• meta:generator: use odfdo generator string.
• all meta:document-statistic values to 0.

All user defined metadata are removed.

Args:

generator -- str, string for the meta:generator field.

creation_date -- datetime or None, meta:creation-date value.

Source code in odfdo/meta.py

def strip(
    self,
    generator: str = GENERATOR,
    creation_date: datetime | None = None,
) -> None:
    """Strip metadata to their minimal content.

    By default the new metadata values are:
        - meta:creation-date: use current time,
        - dc:date: use creation date,
        - meta:editing-duration: set to zero,
        - meta:editing-cycles: set to 1,
        - meta:generator: use odfdo generator string.
        - all meta:document-statistic values to 0.

    All user defined metadata are removed.

    Args:

        generator -- str, string for the meta:generator field.

        creation_date -- datetime or None, meta:creation-date value.
    """

    self.body.clear()
    self.statistic = self._complete_stats({}, None)
    if creation_date is None:
        self.creation_date = datetime.now().replace(microsecond=0)
    else:
        self.creation_date = creation_date.replace(microsecond=0)
    self.date = self.creation_date
    self.editing_duration = timedelta(0)
    self.editing_cycles = 1
    self.generator = generator
    self.clear_user_defined_metadata()

MetaAutoReload

Bases: Element

Container for auto-reload properties, “meta:auto-reload”.

Methods:

Name	Description
__init__	Container for auto-reload properties, “meta:auto-reload”.
as_dict	Return the MetaAutoReload attributes as a Python dict.
from_dict	Set all the MetaAutoReload attributes from a Python dict.

Attributes:

Name	Type	Description
actuate
href
show
type

Source code in odfdo/meta_auto_reload.py

class MetaAutoReload(Element):
    """Container for auto-reload properties, "meta:auto-reload"."""

    _tag = "meta:auto-reload"
    _properties: tuple[PropDef, ...] = (
        PropDef("delay", "meta:delay"),
        PropDef("actuate", "xlink:actuate"),
        PropDef("href", "xlink:href"),
        PropDef("show", "xlink:show"),
        PropDef("type", "xlink:type"),
    )

    def __init__(
        self,
        delay: timedelta | None = None,
        href: str = "",
        **kwargs: Any,
    ) -> None:
        """Container for auto-reload properties, "meta:auto-reload".

        The <meta:auto-reload> element specifies whether a document is
        reloaded or replaced by another document after a specified period
        of time has elapsed.

        Args:

            delay -- timedelta | None

            href -- str
        """
        super().__init__(**kwargs)

        self.actuate = "onLoad"
        self.show = "replace"
        self.type = "simple"
        if self._do_init:
            self._set_delay(delay)
            self.href = href

    def __repr__(self) -> str:
        if self.delay:
            delay = str(Duration.decode(self.delay))
        else:
            delay = ""
        return (
            f"<{self.__class__.__name__} tag={self.tag} href={self.href} delay={delay}>"
        )

    def __str__(self) -> str:
        return f"({self.href})"

    def _set_delay(self, delay: timedelta | None) -> None:
        if delay is None:
            delay = timedelta(0)
        self.delay = Duration.encode(delay)

    def as_dict(self) -> dict[str, Any]:
        """Return the MetaAutoReload attributes as a Python dict."""
        result: dict[str, Any] = {}
        if self.delay:
            result["meta:delay"] = Duration.decode(self.delay)
        else:
            result["meta:delay"] = timedelta(0)
        result.update(
            {
                "xlink:actuate": self.actuate or "onLoad",
                "xlink:href": self.href or "",
                "xlink:show": self.show or "replace",
                "xlink:type": self.type or "simple",
            }
        )
        return result

    def from_dict(self, data: dict[str, Any]) -> None:
        """Set all the MetaAutoReload attributes from a Python dict."""
        self._set_delay(data.get("meta:delay"))
        self.actuate = data.get("xlink:actuate", "onLoad")
        self.href = data.get("xlink:href", "")
        self.show = data.get("xlink:show", "replace")
        self.type = data.get("xlink:type", "simple")

actuate instance-attribute

actuate = 'onLoad'

href instance-attribute

href = href

show instance-attribute

show = 'replace'

type instance-attribute

type = 'simple'

__init__

__init__(
    delay: timedelta | None = None,
    href: str = "",
    **kwargs: Any,
) -> None

Container for auto-reload properties, “meta:auto-reload”.

The element specifies whether a document is reloaded or replaced by another document after a specified period of time has elapsed.

Args:

delay -- timedelta | None

href -- str

Source code in odfdo/meta_auto_reload.py

def __init__(
    self,
    delay: timedelta | None = None,
    href: str = "",
    **kwargs: Any,
) -> None:
    """Container for auto-reload properties, "meta:auto-reload".

    The <meta:auto-reload> element specifies whether a document is
    reloaded or replaced by another document after a specified period
    of time has elapsed.

    Args:

        delay -- timedelta | None

        href -- str
    """
    super().__init__(**kwargs)

    self.actuate = "onLoad"
    self.show = "replace"
    self.type = "simple"
    if self._do_init:
        self._set_delay(delay)
        self.href = href

as_dict

as_dict() -> dict[str, Any]

Return the MetaAutoReload attributes as a Python dict.

Source code in odfdo/meta_auto_reload.py

def as_dict(self) -> dict[str, Any]:
    """Return the MetaAutoReload attributes as a Python dict."""
    result: dict[str, Any] = {}
    if self.delay:
        result["meta:delay"] = Duration.decode(self.delay)
    else:
        result["meta:delay"] = timedelta(0)
    result.update(
        {
            "xlink:actuate": self.actuate or "onLoad",
            "xlink:href": self.href or "",
            "xlink:show": self.show or "replace",
            "xlink:type": self.type or "simple",
        }
    )
    return result

from_dict

from_dict(data: dict[str, Any]) -> None

Set all the MetaAutoReload attributes from a Python dict.

Source code in odfdo/meta_auto_reload.py

def from_dict(self, data: dict[str, Any]) -> None:
    """Set all the MetaAutoReload attributes from a Python dict."""
    self._set_delay(data.get("meta:delay"))
    self.actuate = data.get("xlink:actuate", "onLoad")
    self.href = data.get("xlink:href", "")
    self.show = data.get("xlink:show", "replace")
    self.type = data.get("xlink:type", "simple")

MetaHyperlinkBehaviour

Bases: Element

Container for hyperlink-behaviour properties, “meta:hyperlink- behaviour”.

Methods:

Name	Description
__init__	Container for hyperlink-behaviour properties, “meta:hyperlink-
as_dict	Return the MetaHyperlinkBehaviour attributes as a Python dict.
from_dict	Set all the MetaHyperlinkBehaviour attributes from a Python dict.

Attributes:

Name	Type	Description
show
target_frame_name

Source code in odfdo/meta_hyperlink_behaviour.py

class MetaHyperlinkBehaviour(Element):
    """Container for hyperlink-behaviour properties, "meta:hyperlink-
    behaviour".
    """

    _tag = "meta:hyperlink-behaviour"
    _properties: tuple[PropDef, ...] = (
        PropDef("target_frame_name", "office:target-frame-name"),
        PropDef("show", "xlink:show"),
    )

    def __init__(
        self,
        target_frame_name: str = "_blank",
        show: str = "replace",
        **kwargs: Any,
    ) -> None:
        """Container for hyperlink-behaviour properties, "meta:hyperlink-
        behaviour".

        The "meta:hyperlink-behaviour" element specifies the default behavior
        for hyperlinks in a document.

        Args:

            target_frame_name -- str

            show -- str
        """
        super().__init__(**kwargs)

        if self._do_init:
            self.target_frame_name = target_frame_name
            self.show = show

    def __repr__(self) -> str:
        return (
            f"<{self.__class__.__name__} tag={self.tag} "
            f"target={self.target_frame_name} show={self.show}>"
        )

    def __str__(self) -> str:
        return f"({self.target_frame_name})"

    def as_dict(self) -> dict[str, Any]:
        """Return the MetaHyperlinkBehaviour attributes as a Python dict."""
        return {
            "office:target-frame-name": self.target_frame_name,
            "xlink:show": self.show,
        }

    def from_dict(self, data: dict[str, Any]) -> None:
        """Set all the MetaHyperlinkBehaviour attributes from a Python dict."""
        self.target_frame_name = str(data.get("office:target-frame-name", ""))
        self.show = str(data.get("xlink:show", "replace"))

show instance-attribute

show = show

target_frame_name instance-attribute

target_frame_name = target_frame_name

__init__

__init__(
    target_frame_name: str = "_blank",
    show: str = "replace",
    **kwargs: Any,
) -> None

Container for hyperlink-behaviour properties, “meta:hyperlink- behaviour”.

The “meta:hyperlink-behaviour” element specifies the default behavior for hyperlinks in a document.

Args:

target_frame_name -- str

show -- str

Source code in odfdo/meta_hyperlink_behaviour.py

def __init__(
    self,
    target_frame_name: str = "_blank",
    show: str = "replace",
    **kwargs: Any,
) -> None:
    """Container for hyperlink-behaviour properties, "meta:hyperlink-
    behaviour".

    The "meta:hyperlink-behaviour" element specifies the default behavior
    for hyperlinks in a document.

    Args:

        target_frame_name -- str

        show -- str
    """
    super().__init__(**kwargs)

    if self._do_init:
        self.target_frame_name = target_frame_name
        self.show = show

as_dict

as_dict() -> dict[str, Any]

Return the MetaHyperlinkBehaviour attributes as a Python dict.

Source code in odfdo/meta_hyperlink_behaviour.py

def as_dict(self) -> dict[str, Any]:
    """Return the MetaHyperlinkBehaviour attributes as a Python dict."""
    return {
        "office:target-frame-name": self.target_frame_name,
        "xlink:show": self.show,
    }

from_dict

from_dict(data: dict[str, Any]) -> None

Set all the MetaHyperlinkBehaviour attributes from a Python dict.

Source code in odfdo/meta_hyperlink_behaviour.py

def from_dict(self, data: dict[str, Any]) -> None:
    """Set all the MetaHyperlinkBehaviour attributes from a Python dict."""
    self.target_frame_name = str(data.get("office:target-frame-name", ""))
    self.show = str(data.get("xlink:show", "replace"))

MetaTemplate

Bases: Element

Container for the meta template properties, “meta:template”.

Methods:

Name	Description
__init__	Container for the meta template properties, “meta:template”.
as_dict	Return the MetaTemplate attributes as a Python dict.
from_dict	Set all the MetaTemplate attributes from a Python dict.

Attributes:

Name	Type	Description
actuate
href
title
type

Source code in odfdo/meta_template.py

class MetaTemplate(Element):
    """Container for the meta template properties, "meta:template"."""

    _tag = "meta:template"
    _properties: tuple[PropDef, ...] = (
        PropDef("date", "meta:date"),
        PropDef("actuate", "xlink:actuate"),
        PropDef("href", "xlink:href"),
        PropDef("title", "xlink:title"),
        PropDef("type", "xlink:type"),
    )

    def __init__(
        self,
        date: datetime | None = None,
        href: str = "",
        title: str = "",
        **kwargs: Any,
    ) -> None:
        """Container for the meta template properties, "meta:template".

        The <meta:template> element specifies a URI for the document template
        that was used to create a document. The URI is specified as an
        Xlink.

        Args:

            date -- datetime or None

            href -- str

            title -- str
        """
        super().__init__(**kwargs)

        self.actuate = "onRequest"
        self.type = "simple"
        if self._do_init:
            self._set_date(date)
            self.href = href
            self.title = title

    def __repr__(self) -> str:
        return f"<{self.__class__.__name__} tag={self.tag} href={self.href}>"

    def __str__(self) -> str:
        if self.title:
            return f"[{self.title}]({self.href})"
        return f"({self.href})"

    def _set_date(self, date: datetime | None) -> None:
        if date is None:
            date = datetime.now()
        self.date = DateTime.encode(date)

    def as_dict(self) -> dict[str, Any]:
        """Return the MetaTemplate attributes as a Python dict."""
        result: dict[str, Any] = {}
        if self.date:
            result["meta:date"] = DateTime.decode(self.date)
        result.update(
            {
                "xlink:actuate": self.actuate or "",
                "xlink:href": self.href or "",
                "xlink:title": self.title or "",
                "xlink:type": self.type or "",
            }
        )
        return result

    def from_dict(self, data: dict[str, Any]) -> None:
        """Set all the MetaTemplate attributes from a Python dict."""
        self._set_date(data.get("meta:date"))
        self.actuate = data.get("xlink:actuate", "onRequest")
        self.href = data.get("xlink:href", "")
        self.title = data.get("xlink:title", "")
        self.type = data.get("xlink:type", "simple")

actuate instance-attribute

actuate = 'onRequest'

href instance-attribute

href = href

title instance-attribute

title = title

type instance-attribute

type = 'simple'

__init__

__init__(
    date: datetime | None = None,
    href: str = "",
    title: str = "",
    **kwargs: Any,
) -> None

Container for the meta template properties, “meta:template”.

The element specifies a URI for the document template that was used to create a document. The URI is specified as an Xlink.

Args:

date -- datetime or None

href -- str

title -- str

Source code in odfdo/meta_template.py

def __init__(
    self,
    date: datetime | None = None,
    href: str = "",
    title: str = "",
    **kwargs: Any,
) -> None:
    """Container for the meta template properties, "meta:template".

    The <meta:template> element specifies a URI for the document template
    that was used to create a document. The URI is specified as an
    Xlink.

    Args:

        date -- datetime or None

        href -- str

        title -- str
    """
    super().__init__(**kwargs)

    self.actuate = "onRequest"
    self.type = "simple"
    if self._do_init:
        self._set_date(date)
        self.href = href
        self.title = title

as_dict

as_dict() -> dict[str, Any]

Return the MetaTemplate attributes as a Python dict.

Source code in odfdo/meta_template.py

def as_dict(self) -> dict[str, Any]:
    """Return the MetaTemplate attributes as a Python dict."""
    result: dict[str, Any] = {}
    if self.date:
        result["meta:date"] = DateTime.decode(self.date)
    result.update(
        {
            "xlink:actuate": self.actuate or "",
            "xlink:href": self.href or "",
            "xlink:title": self.title or "",
            "xlink:type": self.type or "",
        }
    )
    return result

from_dict

from_dict(data: dict[str, Any]) -> None

Set all the MetaTemplate attributes from a Python dict.

Source code in odfdo/meta_template.py

def from_dict(self, data: dict[str, Any]) -> None:
    """Set all the MetaTemplate attributes from a Python dict."""
    self._set_date(data.get("meta:date"))
    self.actuate = data.get("xlink:actuate", "onRequest")
    self.href = data.get("xlink:href", "")
    self.title = data.get("xlink:title", "")
    self.type = data.get("xlink:type", "simple")

Metadata

Bases: Body

Root of the Meta document content, “office:meta”.

Source code in odfdo/body.py

class Metadata(Body):
    """Root of the Meta document content, "office:meta"."""

    _tag: str = "office:meta"
    _properties: tuple[PropDef, ...] = ()

NamedRange

Bases: Element

Named range of cells in a table, “table:named-range”.

Identifies inside the spreadsheet a range of cells of a table by a name and the name of the table.

Name Ranges have the following attributes:

name -- name of the named range

table_name -- name of the table

start -- first cell of the named range, tuple (x, y)

end -- last cell of the named range, tuple (x, y)

crange -- range of the named range, tuple (x, y, z, t)

usage -- None or str, usage of the named range.

Methods:

Name	Description
__init__	Named range of cells in a table, “table:named-range”.
get_value	Shortcut to retrieve the value of the first cell of the named range.
get_values	Shortcut to retrieve the values of the cells of the named range.
set_range	Set the range of the named range. Range can be either one cell (like
set_table_name	Set the name of the table of the Named Range.
set_usage	Set the usage of the Named Range. Usage can be None (default) or one
set_value	Shortcut to set the value of the first cell of the named range.
set_values	Shortcut to set the values of the cells of the named range.

Attributes:

Name	Type	Description
crange	tuple[int, int, int, int]
end	tuple[int, int]
name	str | None	Get / set the name of the Named Range.
start	tuple[int, int]
table_name	str
usage	str | None

Source code in odfdo/named_range.py

class NamedRange(Element):
    """Named range of cells in a table, "table:named-range".

    Identifies inside the spreadsheet
    a range of cells of a table by a name and the name of the table.

    Name Ranges have the following attributes:

        name -- name of the named range

        table_name -- name of the table

        start -- first cell of the named range, tuple (x, y)

        end -- last cell of the named range, tuple (x, y)

        crange -- range of the named range, tuple (x, y, z, t)

        usage -- None or str, usage of the named range.
    """

    _tag = "table:named-range"

    def __init__(
        self,
        name: str | None = None,
        crange: str | tuple | list | None = None,
        table_name: str | None = None,
        usage: str | None = None,
        **kwargs: Any,
    ) -> None:
        """Named range of cells in a table, "table:named-range".

        Create a Named Range element. 'name' must contains only letters, digits
        and '_', and must not be like a coordinate as 'A1'. 'table_name' must be
        a correct table name (no "'" or "/" in it).

        Args:

             name -- str, name of the named range

             crange -- str or tuple of int, cell or area coordinate

             table_name -- str, name of the table

             usage -- None or 'print-range', 'filter', 'repeat-column', 'repeat-row'
        """
        super().__init__(**kwargs)
        self.usage: str | None = None
        self.table_name: str = ""
        self.start: tuple[int, int] = 0, 0
        self.end: tuple[int, int] = 0, 0
        self.crange: tuple[int, int, int, int] = 0, 0, 0, 0
        self.usage = None
        if self._do_init:
            self.name = name or ""
            self.table_name = table_name_check(table_name)
            self.set_range(crange or "")
            self.set_usage(usage)
        cell_range_address = self.get_attribute_string("table:cell-range-address") or ""
        if not cell_range_address:
            return
        self.usage = self.get_attribute_string("table:range-usable-as")
        name_range = cell_range_address.replace("$", "")
        name, crange = name_range.split(".", 1)
        if name.startswith("'") and name.endswith("'"):
            name = name[1:-1]
        self.table_name = name
        crange = crange.replace(".", "")
        self._set_range(crange)

    def set_usage(self, usage: str | None = None) -> None:
        """Set the usage of the Named Range. Usage can be None (default) or one
        of :

            - 'print-range'
            - 'filter'
            - 'repeat-column'
            - 'repeat-row'

        Args:

            usage -- None or str
        """
        if usage is not None:
            usage = usage.strip().lower()
            if usage not in ("print-range", "filter", "repeat-column", "repeat-row"):
                usage = None
        if usage is None:
            with contextlib.suppress(KeyError):
                self.del_attribute("table:range-usable-as")
            self.usage = None
        else:
            self.set_attribute("table:range-usable-as", usage)
            self.usage = usage

    @staticmethod
    def _check_nr_name(name: str) -> str:
        name = name.strip()
        if not name:
            raise ValueError("Named Range name can't be empty.")
        for x in name:
            if x in _forbidden_in_named_range():
                msg = f"Character forbidden in Named Range name: {x!r} "
                raise ValueError(msg)
        step = ""
        for x in name:
            if x in string.ascii_letters and step in ("", "A"):
                step = "A"
                continue
            elif step in ("A", "A1") and x in string.digits:
                step = "A1"
                continue
            else:
                step = ""
                break
        if step == "A1":
            msg = f"Name of the type 'ABC123' is not allowed for Named Range: {name!r}"
            raise ValueError(msg)
        return name

    @property
    def name(self) -> str | None:
        """Get / set the name of the Named Range.

        The name is mandatory, if a Named Range of the same name exists, it will be replaced. Name must contains
        only alphanumerics characters and '_', and can not be of a cell coordinates form like 'AB12'.

        Args:

            name -- str
        """
        return self.get_attribute_string("table:name")

    @name.setter
    def name(self, name: str) -> None:
        """Get / set  the name of the Named Range."""
        name = self._check_nr_name(name)
        with contextlib.suppress(Exception):
            # we are not on an NR inserted in a document.
            # We know the body should contains NR mixin if
            # not exception.
            if body := self.document_body:
                named_range = body.get_named_range(name)  # type: ignore[attr-defined]
                if named_range:
                    named_range.delete()
        self.set_attribute("table:name", name)

    def set_table_name(self, name: str) -> None:
        """Set the name of the table of the Named Range.

        The name is mandatory.

        Args:

            name -- str
        """
        self.table_name = table_name_check(name)
        self._update_attributes()

    def _set_range(self, coord: tuple | list | str) -> None:
        digits = convert_coordinates(coord)
        if len(digits) == 4:
            x, y, z, t = digits
        else:
            x, y = digits
            z, t = digits
        if x is None or y is None or z is None or t is None:
            raise ValueError(f"Wrong format for cell range: {coord!r}")
        self.start = x, y
        self.end = z, t
        self.crange = x, y, z, t

    def set_range(
        self,
        crange: str | tuple[int, int] | tuple[int, int, int, int] | list[int],
    ) -> None:
        """Set the range of the named range. Range can be either one cell (like
        'A1') or an area ('A1:B2'). It can be provided as an alpha numeric
        value like "A1:B2' or a tuple like (0, 0, 1, 1) or (0, 0).

        Args:

            crange -- str or tuple of int, cell or area coordinate
        """
        self._set_range(crange)
        self._update_attributes()

    def _update_attributes(self) -> None:
        self.set_attribute("table:base-cell-address", self._make_base_cell_address())
        self.set_attribute("table:cell-range-address", self._make_cell_range_address())

    def _make_base_cell_address(self) -> str:
        # assuming we got table_name and range
        if " " in self.table_name:
            name = f"'{self.table_name}'"
        else:
            name = self.table_name
        return f"${name}.${digit_to_alpha(self.start[0])}${self.start[1] + 1}"

    def _make_cell_range_address(self) -> str:
        # assuming we got table_name and range
        if " " in self.table_name:
            name = f"'{self.table_name}'"
        else:
            name = self.table_name
        if self.start == self.end:
            return self._make_base_cell_address()
        return (
            f"${name}.${digit_to_alpha(self.start[0])}${self.start[1] + 1}:"
            f".${digit_to_alpha(self.end[0])}${self.end[1] + 1}"
        )

    def get_values(
        self,
        cell_type: str | None = None,
        complete: bool = True,
        get_type: bool = False,
        flat: bool = False,
    ) -> list:
        """Shortcut to retrieve the values of the cells of the named range.

        See table.get_values() for the arguments description and return format.
        """
        body = self.document_body
        if not body:
            raise ValueError("Table is not inside a document.")
        table = body.get_table(name=self.table_name)
        if table is None:
            raise ValueError(f"Table not found: {self.table_name!r}")
        return table.get_values(self.crange, cell_type, complete, get_type, flat)

    def get_value(self, get_type: bool = False) -> Any:
        """Shortcut to retrieve the value of the first cell of the named range.

        See table.get_value() for the arguments description and return format.
        """
        body = self.document_body
        if not body:
            raise ValueError("Table is not inside a document.")
        table: Table | None = body.get_table(name=self.table_name)
        if table is None:
            raise ValueError(f"Table not found: {self.table_name!r}")
        return table.get_value(self.start, get_type)

    def set_values(
        self,
        values: list,
        style: str | None = None,
        cell_type: str | None = None,
        currency: str | None = None,
    ) -> None:
        """Shortcut to set the values of the cells of the named range.

        See table.set_values() for the arguments description.
        """
        body = self.document_body
        if not body:
            raise ValueError("Table is not inside a document.")
        table = body.get_table(name=self.table_name)
        if table is None:
            raise ValueError(f"Table not found: {self.table_name!r}")
        table.set_values(
            values,
            coord=self.crange,
            style=style,
            cell_type=cell_type,
            currency=currency,
        )

    def set_value(
        self,
        value: Any,
        cell_type: str | None = None,
        currency: str | None = None,
        style: str | None = None,
    ) -> None:
        """Shortcut to set the value of the first cell of the named range.

        See table.set_value() for the arguments description.
        """
        body = self.document_body
        if not body:
            raise ValueError("Table is not inside a document.")
        table = body.get_table(name=self.table_name)
        if table is None:
            raise ValueError(f"Table not found: {self.table_name!r}")
        table.set_value(
            coord=self.start,
            value=value,
            cell_type=cell_type,
            currency=currency,
            style=style,
        )

crange instance-attribute

crange: tuple[int, int, int, int] = (0, 0, 0, 0)

end instance-attribute

end: tuple[int, int] = (0, 0)

name property writable

name: str | None

Get / set the name of the Named Range.

The name is mandatory, if a Named Range of the same name exists, it will be replaced. Name must contains only alphanumerics characters and ‘_’, and can not be of a cell coordinates form like ‘AB12’.

Args:

name -- str

start instance-attribute

start: tuple[int, int] = (0, 0)

table_name instance-attribute

table_name: str = name

usage instance-attribute

usage: str | None = get_attribute_string(
    "table:range-usable-as"
)

__init__

__init__(
    name: str | None = None,
    crange: str | tuple | list | None = None,
    table_name: str | None = None,
    usage: str | None = None,
    **kwargs: Any,
) -> None

Named range of cells in a table, “table:named-range”.

Create a Named Range element. ‘name’ must contains only letters, digits and ‘_’, and must not be like a coordinate as ‘A1’. ‘table_name’ must be a correct table name (no “’” or “/” in it).

Args:

 name -- str, name of the named range

 crange -- str or tuple of int, cell or area coordinate

 table_name -- str, name of the table

 usage -- None or 'print-range', 'filter', 'repeat-column', 'repeat-row'

Source code in odfdo/named_range.py

def __init__(
    self,
    name: str | None = None,
    crange: str | tuple | list | None = None,
    table_name: str | None = None,
    usage: str | None = None,
    **kwargs: Any,
) -> None:
    """Named range of cells in a table, "table:named-range".

    Create a Named Range element. 'name' must contains only letters, digits
    and '_', and must not be like a coordinate as 'A1'. 'table_name' must be
    a correct table name (no "'" or "/" in it).

    Args:

         name -- str, name of the named range

         crange -- str or tuple of int, cell or area coordinate

         table_name -- str, name of the table

         usage -- None or 'print-range', 'filter', 'repeat-column', 'repeat-row'
    """
    super().__init__(**kwargs)
    self.usage: str | None = None
    self.table_name: str = ""
    self.start: tuple[int, int] = 0, 0
    self.end: tuple[int, int] = 0, 0
    self.crange: tuple[int, int, int, int] = 0, 0, 0, 0
    self.usage = None
    if self._do_init:
        self.name = name or ""
        self.table_name = table_name_check(table_name)
        self.set_range(crange or "")
        self.set_usage(usage)
    cell_range_address = self.get_attribute_string("table:cell-range-address") or ""
    if not cell_range_address:
        return
    self.usage = self.get_attribute_string("table:range-usable-as")
    name_range = cell_range_address.replace("$", "")
    name, crange = name_range.split(".", 1)
    if name.startswith("'") and name.endswith("'"):
        name = name[1:-1]
    self.table_name = name
    crange = crange.replace(".", "")
    self._set_range(crange)

get_value

get_value(get_type: bool = False) -> Any

Shortcut to retrieve the value of the first cell of the named range.

See table.get_value() for the arguments description and return format.

Source code in odfdo/named_range.py

def get_value(self, get_type: bool = False) -> Any:
    """Shortcut to retrieve the value of the first cell of the named range.

    See table.get_value() for the arguments description and return format.
    """
    body = self.document_body
    if not body:
        raise ValueError("Table is not inside a document.")
    table: Table | None = body.get_table(name=self.table_name)
    if table is None:
        raise ValueError(f"Table not found: {self.table_name!r}")
    return table.get_value(self.start, get_type)

get_values

get_values(
    cell_type: str | None = None,
    complete: bool = True,
    get_type: bool = False,
    flat: bool = False,
) -> list

Shortcut to retrieve the values of the cells of the named range.

See table.get_values() for the arguments description and return format.

Source code in odfdo/named_range.py

def get_values(
    self,
    cell_type: str | None = None,
    complete: bool = True,
    get_type: bool = False,
    flat: bool = False,
) -> list:
    """Shortcut to retrieve the values of the cells of the named range.

    See table.get_values() for the arguments description and return format.
    """
    body = self.document_body
    if not body:
        raise ValueError("Table is not inside a document.")
    table = body.get_table(name=self.table_name)
    if table is None:
        raise ValueError(f"Table not found: {self.table_name!r}")
    return table.get_values(self.crange, cell_type, complete, get_type, flat)

set_range

set_range(
    crange: str
    | tuple[int, int]
    | tuple[int, int, int, int]
    | list[int],
) -> None

Set the range of the named range. Range can be either one cell (like ‘A1’) or an area (‘A1:B2’). It can be provided as an alpha numeric value like “A1:B2’ or a tuple like (0, 0, 1, 1) or (0, 0).

Args:

crange -- str or tuple of int, cell or area coordinate

Source code in odfdo/named_range.py

def set_range(
    self,
    crange: str | tuple[int, int] | tuple[int, int, int, int] | list[int],
) -> None:
    """Set the range of the named range. Range can be either one cell (like
    'A1') or an area ('A1:B2'). It can be provided as an alpha numeric
    value like "A1:B2' or a tuple like (0, 0, 1, 1) or (0, 0).

    Args:

        crange -- str or tuple of int, cell or area coordinate
    """
    self._set_range(crange)
    self._update_attributes()

set_table_name

set_table_name(name: str) -> None

Set the name of the table of the Named Range.

The name is mandatory.

Args:

name -- str

Source code in odfdo/named_range.py

def set_table_name(self, name: str) -> None:
    """Set the name of the table of the Named Range.

    The name is mandatory.

    Args:

        name -- str
    """
    self.table_name = table_name_check(name)
    self._update_attributes()

set_usage

set_usage(usage: str | None = None) -> None

Set the usage of the Named Range. Usage can be None (default) or one of :

- 'print-range'
- 'filter'
- 'repeat-column'
- 'repeat-row'

Args:

usage -- None or str

Source code in odfdo/named_range.py

def set_usage(self, usage: str | None = None) -> None:
    """Set the usage of the Named Range. Usage can be None (default) or one
    of :

        - 'print-range'
        - 'filter'
        - 'repeat-column'
        - 'repeat-row'

    Args:

        usage -- None or str
    """
    if usage is not None:
        usage = usage.strip().lower()
        if usage not in ("print-range", "filter", "repeat-column", "repeat-row"):
            usage = None
    if usage is None:
        with contextlib.suppress(KeyError):
            self.del_attribute("table:range-usable-as")
        self.usage = None
    else:
        self.set_attribute("table:range-usable-as", usage)
        self.usage = usage

set_value

set_value(
    value: Any,
    cell_type: str | None = None,
    currency: str | None = None,
    style: str | None = None,
) -> None

Shortcut to set the value of the first cell of the named range.

See table.set_value() for the arguments description.

Source code in odfdo/named_range.py

def set_value(
    self,
    value: Any,
    cell_type: str | None = None,
    currency: str | None = None,
    style: str | None = None,
) -> None:
    """Shortcut to set the value of the first cell of the named range.

    See table.set_value() for the arguments description.
    """
    body = self.document_body
    if not body:
        raise ValueError("Table is not inside a document.")
    table = body.get_table(name=self.table_name)
    if table is None:
        raise ValueError(f"Table not found: {self.table_name!r}")
    table.set_value(
        coord=self.start,
        value=value,
        cell_type=cell_type,
        currency=currency,
        style=style,
    )

set_values

set_values(
    values: list,
    style: str | None = None,
    cell_type: str | None = None,
    currency: str | None = None,
) -> None

Shortcut to set the values of the cells of the named range.

See table.set_values() for the arguments description.

Source code in odfdo/named_range.py

def set_values(
    self,
    values: list,
    style: str | None = None,
    cell_type: str | None = None,
    currency: str | None = None,
) -> None:
    """Shortcut to set the values of the cells of the named range.

    See table.set_values() for the arguments description.
    """
    body = self.document_body
    if not body:
        raise ValueError("Table is not inside a document.")
    table = body.get_table(name=self.table_name)
    if table is None:
        raise ValueError(f"Table not found: {self.table_name!r}")
    table.set_values(
        values,
        coord=self.crange,
        style=style,
        cell_type=cell_type,
        currency=currency,
    )

Note

Bases: MDNote, Element

A note (footnote or endnote), “text:note”.

Either a footnote or a endnote element with the given text, optionally referencing it using the given note_id.

Methods:

Name	Description
__init__	A note (footnote or endnote), “text:note”.
check_validity

Attributes:

Name	Type	Description
NOTE_CLASS	ClassVar
citation	str
note_body	str
note_class
note_id

Source code in odfdo/note.py

class Note(MDNote, Element):
    """A note (footnote or endnote), "text:note".

    Either a footnote or a endnote element with the given text, optionally
    referencing it using the given note_id.
    """

    _tag = "text:note"
    _properties = (
        PropDef("note_class", "text:note-class"),
        PropDef("note_id", "text:id"),
    )
    NOTE_CLASS: ClassVar = {"footnote", "endnote"}

    def __init__(
        self,
        note_class: str = "footnote",
        note_id: str | None = None,
        citation: str | None = None,
        body: str | None = None,
        **kwargs: Any,
    ) -> None:
        """A note (footnote or endnote), "text:note".

        Args:

            note_class -- 'footnote' or 'endnote'

            note_id -- str

            citation -- str

            body -- str or Element
        """
        super().__init__(**kwargs)
        if self._do_init:
            self.insert(Element.from_tag("text:note-body"), position=0)
            self.insert(Element.from_tag("text:note-citation"), position=0)
            self.note_class = note_class
            if note_id is not None:
                self.note_id = note_id
            if citation is not None:
                self.citation = citation
            if body is not None:
                self.note_body = body

    @property
    def citation(self) -> str:
        note_citation = self.get_element("text:note-citation")
        if note_citation:
            return note_citation.text
        return ""

    @citation.setter
    def citation(self, text: str | None) -> None:
        note_citation = self.get_element("text:note-citation")
        if note_citation:
            note_citation.text = text

    @property
    def note_body(self) -> str:
        note_body = self.get_element("text:note-body")
        if note_body:
            return note_body.text_content
        return ""

    @note_body.setter
    def note_body(self, text_or_element: Element | str | None) -> None:
        note_body = self.get_element("text:note-body")
        if not note_body:
            return None
        if text_or_element is None:
            note_body.text_content = ""
        elif isinstance(text_or_element, str):
            note_body.text_content = text_or_element
        elif isinstance(text_or_element, Element):
            note_body.clear()
            note_body.append(text_or_element)
        else:
            raise TypeError(f'Unexpected type for body: "{type(text_or_element)}"')

    def check_validity(self) -> None:
        if not self.note_class or self.note_class not in self.NOTE_CLASS:
            raise ValueError('Note class must be "footnote" or "endnote"')
        if not self.note_id:
            raise ValueError("Note must have an id")
        if not self.citation:
            raise ValueError("Note must have a citation")
        if not self.note_body:
            pass

    def __str__(self) -> str:
        if self.citation:
            return f"{self.citation}. {self.note_body}"
        return self.note_body

NOTE_CLASS class-attribute instance-attribute

NOTE_CLASS: ClassVar = {'footnote', 'endnote'}

citation property writable

citation: str

note_body property writable

note_body: str

note_class instance-attribute

note_class = note_class

note_id instance-attribute

note_id = note_id

__init__

__init__(
    note_class: str = "footnote",
    note_id: str | None = None,
    citation: str | None = None,
    body: str | None = None,
    **kwargs: Any,
) -> None

A note (footnote or endnote), “text:note”.

Args:

note_class -- 'footnote' or 'endnote'

note_id -- str

citation -- str

body -- str or Element

Source code in odfdo/note.py

def __init__(
    self,
    note_class: str = "footnote",
    note_id: str | None = None,
    citation: str | None = None,
    body: str | None = None,
    **kwargs: Any,
) -> None:
    """A note (footnote or endnote), "text:note".

    Args:

        note_class -- 'footnote' or 'endnote'

        note_id -- str

        citation -- str

        body -- str or Element
    """
    super().__init__(**kwargs)
    if self._do_init:
        self.insert(Element.from_tag("text:note-body"), position=0)
        self.insert(Element.from_tag("text:note-citation"), position=0)
        self.note_class = note_class
        if note_id is not None:
            self.note_id = note_id
        if citation is not None:
            self.citation = citation
        if body is not None:
            self.note_body = body

check_validity

check_validity() -> None

Source code in odfdo/note.py

def check_validity(self) -> None:
    if not self.note_class or self.note_class not in self.NOTE_CLASS:
        raise ValueError('Note class must be "footnote" or "endnote"')
    if not self.note_id:
        raise ValueError("Note must have an id")
    if not self.citation:
        raise ValueError("Note must have a citation")
    if not self.note_body:
        pass

OfficeAutomaticStyles

Bases: Element

Container for automatic styles used in the document, “office:automatic- styles”.

An automatic style is one contains formatting properties that are considered to be properties of the object to which the style is assigned.

The “office:automatic-styles” element is usable within the following elements: “office:document”, “office:document-content” and “office:document-styles”.

The “office:automatic-styles” element has no attributes.

Source code in odfdo/style_containers.py

class OfficeAutomaticStyles(Element):
    """Container for automatic styles used in the document, "office:automatic-
    styles".

    An automatic style is one contains formatting properties that are
    considered to be properties of the object to which the style is assigned.

    The "office:automatic-styles" element is usable within the following
    elements: "office:document", "office:document-content" and
    "office:document-styles".

    The "office:automatic-styles" element has no attributes.
    """

    _tag: str = "office:automatic-styles"
    _properties: tuple[PropDef, ...] = ()

OfficeMasterStyles

Bases: Element

Container for master styles used in the document, “office:master- styles”.

A master style contains formatting and other content that is displayed with document content when the style is used.

The “office:master-styles” element is usable within the following elements: “office:document” and “office:document-styles”.

The “office:master-styles” element has no attributes.

Source code in odfdo/style_containers.py

class OfficeMasterStyles(Element):
    """Container for master styles used in the document, "office:master-
    styles".

    A master style contains formatting and other content that is displayed with
    document content when the style is used.

    The "office:master-styles" element is usable within the following elements:
    "office:document" and "office:document-styles".

    The "office:master-styles" element has no attributes.
    """

    _tag: str = "office:master-styles"
    _properties: tuple[PropDef, ...] = ()

ParaMixin

Bases: Element

Mixin for Paragraph methods.

Methods:

Name	Description
append
append_plain_text	Append plain text to the paragraph, replacing , and
insert_annotation	Insert an annotation, at the position defined by the regex (before,
insert_annotation_end	Insert an annotation end tag for an existing annotation. If some end
insert_note
insert_reference	Create and insert a reference to a content marked by a reference
insert_variable
remove_link	Return a copy of the element (not a clone), with the sub links
remove_links	Return a copy of the element, without links tags.
remove_span	Return a copy of the element, the spans (not a clone) removed.
remove_spans	Return copy of the element, without span styles.
set_bookmark	Insert a bookmark before or after the characters in the text which
set_link	Make a link to the provided url from text content matching either:
set_reference_mark	Insert a reference mark, at the position defined by the regex
set_reference_mark_end	Insert/move a ReferenceMarkEnd for an existing reference mark. If
set_span	Apply the given style with a Span to text content matching either:

Source code in odfdo/mixin_paragraph.py

class ParaMixin(Element):
    """Mixin for Paragraph methods."""

    def _expand_spaces(self, added_string: str) -> list[Element | str]:
        result: list[Element | str] = []

        def _merge_text(txt: str) -> None:
            nonlocal result
            if result and isinstance(result[-1], str):
                result[-1] += txt
            else:
                result.append(txt)

        for obj in self.xpath("*|text()"):
            if isinstance(obj, EText):
                _merge_text(str(obj))
                continue
            obj.tail = ""
            if obj.tag != "text:s":
                result.append(obj)
                continue
            _merge_text(obj.text)
        _merge_text(added_string)
        return result

    def _merge_spaces(self, content: list[Element | str]) -> list[Element | str]:
        result: list[Element | str] = []
        for item in content:
            if isinstance(item, str):
                result.extend(self._sub_merge_spaces(item))
            else:
                result.append(item)
        return result

    @staticmethod
    def _sub_merge_spaces(text: str) -> list[Element | str]:
        result: list[Element | str] = []
        content = [x for x in _re_spaces_split.split(text) if x]

        def _merge_text(txt: str) -> None:
            nonlocal result
            if result and isinstance(result[-1], str):
                result[-1] += txt
            else:
                result.append(txt)

        if content:
            item0 = content[0]
            if isinstance(item0, str) and _re_only_spaces.match(item0):
                spacer = Spacer(len(item0))
                result.append(spacer)
            else:
                result.append(item0)
        for item in content[1:-1]:
            if isinstance(item, str):
                if len(item) > 1 and _re_only_spaces.match(item):
                    spacer = Spacer(len(item) - 1)
                    _merge_text(" ")
                    result.append(spacer)
                else:
                    _merge_text(item)
            else:
                result.append(item)
        if len(content) > 1:
            last_item = content[-1]
            if isinstance(last_item, str):
                if _re_only_spaces.match(last_item):
                    spacer = Spacer(len(last_item))
                    result.append(spacer)
                else:
                    _merge_text(last_item)
            else:
                result.append(last_item)
        return result

    def _replace_tabs_lb(self, content: list[Element | str]) -> list[Element | str]:
        result: list[Element | str] = []
        for item in content:
            if isinstance(item, str):
                result.extend(self._sub_replace_tabs_lb(item))
            else:
                result.append(item)
        return result

    @staticmethod
    def _sub_replace_tabs_lb(text: str) -> list[Element | str]:
        if not text:
            return []
        blocs = _re_splitter.split(text)
        result: list[Element | str] = []
        for bloc in blocs:
            if not bloc:
                continue
            if bloc == "\n":
                result.append(LineBreak())
                continue
            if bloc == "\t":
                result.append(Tab())
                continue
            result.append(bloc)
        return result

    def append_plain_text(self, text: str | bytes | None = "") -> None:
        """Append plain text to the paragraph, replacing <CR>, <TAB> and
        multiple spaces by ODF corresponding tags.
        """
        if text is None:
            stext = ""
        elif isinstance(text, bytes):
            stext = text.decode("utf-8")
        else:
            stext = str(text)
        content = self._expand_spaces(stext)
        content = self._merge_spaces(content)
        content = self._replace_tabs_lb(content)
        for child in self.children:
            self.delete(child, keep_tail=False)
        self.text = None
        for element in content:
            self._Element__append(element)  # type: ignore[attr-defined]

    @staticmethod
    def _unformatted(text: str | bytes | None) -> str:
        if not text:
            return ""
        if isinstance(text, bytes):
            stext = text.decode("utf-8")
        else:
            stext = str(text)
        return _re_sub_splitter.sub(" ", stext)

    def append(
        self,
        str_or_element: str | bytes | Element,
        formatted: bool = True,
    ) -> None:
        if isinstance(str_or_element, Element):
            if str_or_element.tag in {"text:p", "text:h", "text:s"}:
                # minimal compliancy or spacer summation
                self.append_plain_text(str(str_or_element))
                self.append_plain_text(str_or_element.tail)
            else:
                self._Element__append(str_or_element)  # type: ignore[attr-defined]
        elif formatted:
            self.append_plain_text(str_or_element)
        else:
            # self._Element__append(self._unformatted(str_or_element))
            # The added text is first "unformatted", but result needs
            # to be compliant
            self.append_plain_text(self._unformatted(str_or_element))

    def insert_note(
        self,
        note_element: Note | None = None,
        after: str | Element | None = None,
        note_class: str = "footnote",
        note_id: str | None = None,
        citation: str | None = None,
        body: str | None = None,
    ) -> None:
        if note_element is None:
            note_element = Note(
                note_class=note_class, note_id=note_id, citation=citation, body=body
            )
        else:
            # XXX clone or modify the argument?
            if note_class:
                note_element.note_class = note_class
            if note_id:
                note_element.note_id = note_id
            if citation:
                note_element.citation = citation
            if body:
                note_element.note_body = body
        note_element.check_validity()
        if isinstance(after, str):
            self._insert(note_element, after=after)
        elif isinstance(after, Element):
            after.insert(note_element, FIRST_CHILD)
        else:
            self.insert(note_element, FIRST_CHILD)

    def insert_annotation(
        self,
        annotation_element: Annotation | None = None,
        before: str | None = None,
        after: str | Element | None = None,
        position: int | tuple = 0,
        content: str | Element | None = None,
        body: str | None = None,
        creator: str | None = None,
        date: datetime | None = None,
    ) -> Annotation:
        """Insert an annotation, at the position defined by the regex (before,
        after, content) or by positional argument (position). If content is
        provided, the annotation covers the full content regex. Else, the
        annotation is positioned either 'before' or 'after' provided regex.

        If content is an odf element (ie: paragraph, span, ...), the full inner
        content is covered by the annotation (of the position just after if
        content is a single empty tag).

        If content/before or after exists (regex) and return a group of matching
        positions, the position value is the index of matching place to use.

        annotation_element can contain a previously created annotation, else
        the annotation is created from the body, creator and optional date
        (current date by default).

        Args:

            annotation_element -- Annotation or None

            before -- str regular expression or None

            after -- str regular expression or Element or None

            content -- str regular expression or None, or Element

            position -- int or tuple of int

            body -- str or Element

            creator -- str

            date -- datetime
        """

        if annotation_element is None:
            annotation_element = Annotation(
                text_or_element=body,
                creator=creator,
                date=date,
                parent=self,
            )
        else:
            # XXX clone or modify the argument?
            if body:
                annotation_element.note_body = body
            if creator:
                annotation_element.creator = creator
            if date:
                annotation_element.date = date
        annotation_element.check_validity()

        # special case: content is an odf element (ie: a paragraph)
        if isinstance(content, Element):
            if content.is_empty():
                content.insert(annotation_element, xmlposition=NEXT_SIBLING)
                return annotation_element
            content.insert(annotation_element, start=True)
            annotation_end = AnnotationEnd(annotation_element)
            content.append(annotation_end)
            return annotation_element

        # special case
        if isinstance(after, Element):
            after.insert(annotation_element, FIRST_CHILD)
            return annotation_element

        # With "content" => automatically insert a "start" and an "end"
        # bookmark
        if (
            before is None
            and after is None
            and content is not None
            and isinstance(position, int)
        ):
            # Start tag
            self._insert(annotation_element, before=content, position=position)
            # End tag
            annotation_end = AnnotationEnd(annotation_element)
            self._insert(annotation_end, after=content, position=position)
            return annotation_element

        # With "(int, int)" =>  automatically insert a "start" and an "end"
        # bookmark
        if (
            before is None
            and after is None
            and content is None
            and isinstance(position, tuple)
        ):
            # Start
            self._insert(annotation_element, position=position[0])
            # End
            annotation_end = AnnotationEnd(annotation_element)
            self._insert(annotation_end, position=position[1])
            return annotation_element

        # Without "content" nor "position"
        if content is not None or not isinstance(position, int):
            raise ValueError("Bad arguments")

        # Insert
        self._insert(annotation_element, before=before, after=after, position=position)
        return annotation_element

    def insert_annotation_end(
        self,
        annotation_element: Annotation,
        before: str | None = None,
        after: str | None = None,
        position: int = 0,
    ) -> AnnotationEnd:
        """Insert an annotation end tag for an existing annotation. If some end
        tag already exists, replace it. Annotation end tag is set at the
        position defined by the regex (before or after).

        If content/before or after (regex) returns a group of matching
        positions, the position value is the index of matching place to use.

        Args:

            annotation_element -- Annotation (mandatory)

            before -- str regular expression or None

            after -- str regular expression or None

            position -- int
        """

        if annotation_element is None:
            raise ValueError
        if not isinstance(annotation_element, Annotation):
            raise TypeError("Not a <office:annotation> Annotation")

        # remove existing end tag
        name = annotation_element.name
        existing_end_tag = self.get_annotation_end(name=name)
        if existing_end_tag:
            existing_end_tag.delete()

        # create the end tag
        end_tag = AnnotationEnd(annotation_element)

        # Insert
        self._insert(end_tag, before=before, after=after, position=position)
        return end_tag

    def set_reference_mark(
        self,
        name: str,
        before: str | None = None,
        after: str | None = None,
        position: int = 0,
        content: str | Element | None = None,
    ) -> Element:
        """Insert a reference mark, at the position defined by the regex
        (before, after, content) or by positional argument (position). If
        content is provided, the annotation covers the full range content regex
        (instances of ReferenceMarkStart and ReferenceMarkEnd are created).
        Else, an instance of ReferenceMark is positioned either 'before' or
        'after' provided regex.

        If content is an ODF Element (ie: Paragraph, Span, ...), the full inner
        content is referenced (of the position just after if content is a single
        empty tag).

        If content/before or after exists (regex) and return a group of matching
        positions, the position value is the index of matching place to use.

        Name is mandatory and shall be unique in the document for the preference
        mark range.

        Args:

            name -- str

            before -- str regular expression or None

            after -- str regular expression or None,

            content -- str regular expression or None, or Element

            position -- int or tuple of int

        Returns: the created ReferenceMark or ReferenceMarkStart
        """
        # special case: content is an odf element (ie: a paragraph)
        if isinstance(content, Element):
            if content.is_empty():
                reference = ReferenceMark(name)
                content.insert(reference, xmlposition=NEXT_SIBLING)
                return reference
            reference_start = ReferenceMarkStart(name)
            content.insert(reference_start, start=True)
            reference_end = ReferenceMarkEnd(name)
            content.append(reference_end)
            return reference_start

        # With "content" => automatically insert a "start" and an "end"
        # reference
        if (
            before is None
            and after is None
            and content is not None
            and isinstance(position, int)
        ):
            # Start tag
            reference_start = ReferenceMarkStart(name)
            self._insert(reference_start, before=content, position=position)
            # End tag
            reference_end = ReferenceMarkEnd(name)
            self._insert(reference_end, after=content, position=position)
            return reference_start

        # With "(int, int)" =>  automatically insert a "start" and an "end"
        if (
            before is None
            and after is None
            and content is None
            and isinstance(position, tuple)
        ):
            # Start
            reference_start = ReferenceMarkStart(name)
            self._insert(reference_start, position=position[0])
            # End
            reference_end = ReferenceMarkEnd(name)
            self._insert(reference_end, position=position[1])
            return reference_start

        # Without "content" nor "position"
        if content is not None or not isinstance(position, int):
            raise ValueError("bad arguments")

        # Insert a positional reference mark
        reference = ReferenceMark(name)
        self._insert(reference, before=before, after=after, position=position)
        return reference

    def set_reference_mark_end(
        self,
        reference_mark: Element,
        before: str | None = None,
        after: str | None = None,
        position: int = 0,
    ) -> ReferenceMarkEnd:
        """Insert/move a ReferenceMarkEnd for an existing reference mark. If
        some end tag already exists, replace it. Reference tag is set at the
        position defined by the regex (before or after).

        If content/before or after (regex) returns a group of matching
        positions, the position value is the index of matching place to use.

        Args:

            reference_mark -- ReferenceMark or ReferenceMarkStart (mandatory)

            before -- str regular expression or None

            after -- str regular expression or None

            position -- int
        """
        if not isinstance(reference_mark, (ReferenceMark, ReferenceMarkStart)):
            raise TypeError("Not a ReferenceMark or ReferenceMarkStart")
        name = reference_mark.name
        if isinstance(reference_mark, ReferenceMark):
            # change it to a range reference:
            reference_mark.tag = ReferenceMarkStart._tag

        existing_end_tag = self.get_reference_mark_end(name=name)
        if existing_end_tag:
            existing_end_tag.delete()

        # create the end tag
        end_tag = ReferenceMarkEnd(name)

        # Insert
        self._insert(end_tag, before=before, after=after, position=position)
        return end_tag

    def insert_variable(self, variable_element: Element, after: str | None) -> None:
        self._insert(variable_element, after=after)

    @_by_regex_offset
    def set_span(
        self,
        style: str,
        regex: str | None = None,
        offset: int | None = None,
        length: int = 0,
        **kwargs: Any,
    ) -> list[Span]:
        """
        Apply the given style  with a Span to text content matching either:

          - the 'regex' match,
          - or the string of length 'length' starting at 'offset'.

        Args:

            style -- str

            regex -- str regular expression, or None

            offset -- int, or None

            length -- int

        Returns: list of generated Span instances.
        """
        # span = Span(match, style=style)
        # span.tail = tail
        span: Span = Element.from_tag("text:span")  # type: ignore[assignment]
        span.text = ""
        span.append_plain_text(kwargs["match_string"])
        span.style = style
        return span  # type: ignore[return-value]

    def remove_spans(self, keep_heading: bool = True) -> Element:
        """Return copy of the element, without span styles.

        If keep_heading is True (default), the first level heading style is
        left unchanged.
        """
        strip = ("text:span",)
        if keep_heading:
            protect = ("text:h",)
        else:
            protect = None
        return strip_tags(self, strip=strip, protect=protect)  # type: ignore [return-value]

    def remove_span(self, spans: Element | list[Element]) -> Element:
        """Return a copy of the element, the spans (not a clone) removed.

        Args:

            spans -- Element or list of Element
        """
        return strip_elements(self, spans)  # type: ignore [return-value]

    @_by_regex_offset
    def set_link(
        self,
        url: str,
        regex: str | None = None,
        offset: int | None = None,
        length: int = 0,
        **kwargs: Any,
    ) -> list[Link]:
        """
        Make a link to the provided url from text content matching either:

          - the 'regex' match,
          - or the string of length 'length' starting at 'offset'.

        Args:

            url -- str

            regex -- str regular expression, or None

            offset -- int, or None

            length -- int

        Returns: list of generated Link instances.
        """

        return Link(url, text=kwargs["match_string"])  # type: ignore[return-value]

    def remove_links(self) -> Element:
        """Return a copy of the element, without links tags."""
        strip = (Link._tag,)
        return strip_tags(self, strip=strip)  # type: ignore [return-value]

    def remove_link(self, links: Link | list[Link]) -> Element:
        """Return a copy of the element (not a clone), with the sub links
        removed.

        Args:

            links -- Link or list of Link
        """
        return strip_elements(self, links)  # type: ignore [return-value]

    def insert_reference(
        self,
        name: str,
        ref_format: str = "",
        before: str | None = None,
        after: str | Element | None = None,
        position: int = 0,
        display: str | None = None,
    ) -> None:
        """Create and insert a reference to a content marked by a reference
        mark. The Reference element ("text:reference-ref") represents a field
        that references a "text:reference-mark-start" or "text:reference-mark"
        element. Its "text:reference-format" attribute specifies what is
        displayed from the referenced element. Default is 'page'. Actual
        content is not automatically updated except for the 'text' format.

        name is mandatory and should represent an existing reference mark of the
        document.

        ref_format is the argument for format reference (default is 'page').

        The reference is inserted the position defined by the regex (before /
        after), or by positional argument (position). If 'display' is provided,
        it will be used as the text value for the reference.

        If after is an ODF Element, the reference is inserted as first child of
        this element.

        Args:

            name -- str

            ref_format -- one of : 'chapter', 'direction', 'page', 'text',
                                    'caption', 'category-and-value', 'value',
                                    'number', 'number-all-superior',
                                    'number-no-superior'

            before -- str regular expression or None

            after -- str regular expression or odf element or None

            position -- int

            display -- str or None
        """
        reference = Reference(name, ref_format)
        if display is None and ref_format == "text":
            # get reference content
            body: Body | Element = self.document_body or self.root
            mark = body.get_reference_mark(name=name)
            if isinstance(mark, ReferenceMarkStart):
                display = mark.referenced_text()
        if not display:
            display = " "
        reference.text = display
        if isinstance(after, Element):
            after.insert(reference, FIRST_CHILD)
        else:
            self._insert(reference, before=before, after=after, position=position)

    def set_bookmark(
        self,
        name: str,
        before: str | None = None,
        after: str | None = None,
        position: int | tuple = 0,
        role: str | None = None,
        content: str | None = None,
    ) -> Element | tuple[Element, Element]:
        """Insert a bookmark before or after the characters in the text which
        match the regex before/after. When the regex matches more of one part
        of the text, position can be set to choose which part must be used. If
        before and after are None, we use only position that is the number of
        characters.

        So, by default, this function inserts a bookmark before the first
        character of the content. Role can be None, "start" or "end", we
        insert respectively a position bookmark a bookmark-start or a
        bookmark-end.

        If content is not None these 2 calls are equivalent:

          paragraph.set_bookmark("bookmark", content="xyz")

        and:

          paragraph.set_bookmark("bookmark", before="xyz", role="start")
          paragraph.set_bookmark("bookmark", after="xyz", role="end")


        If position is a 2-tuple, these 2 calls are equivalent:

          paragraph.set_bookmark("bookmark", position=(10, 20))

        and:

          paragraph.set_bookmark("bookmark", position=10, role="start")
          paragraph.set_bookmark("bookmark", position=20, role="end")


        Args:

            name -- str

            before -- str regex

            after -- str regex

            position -- int or (int, int)

            role -- None, "start" or "end"

            content -- str regex
        """
        # With "content" => automatically insert a "start" and an "end"
        # bookmark
        if (
            before is None
            and after is None
            and role is None
            and content is not None
            and isinstance(position, int)
        ):
            # Start
            start = BookmarkStart(name)
            self._insert(start, before=content, position=position)
            # End
            end = BookmarkEnd(name)
            self._insert(end, after=content, position=position)
            return start, end

        # With "(int, int)" =>  automatically insert a "start" and an "end"
        # bookmark
        if (
            before is None
            and after is None
            and role is None
            and content is None
            and isinstance(position, tuple)
        ):
            # Start
            start = BookmarkStart(name)
            self._insert(start, position=position[0])
            # End
            end = BookmarkEnd(name)
            self._insert(end, position=position[1])
            return start, end

        # Without "content" nor "position"
        if content is not None or not isinstance(position, int):
            raise ValueError("bad arguments")

        # Role
        if role is None:
            bookmark: Element = Bookmark(name)
        elif role == "start":
            bookmark = BookmarkStart(name)
        elif role == "end":
            bookmark = BookmarkEnd(name)
        else:
            raise ValueError("bad arguments")

        # Insert
        self._insert(bookmark, before=before, after=after, position=position)

        return bookmark

append

append(
    str_or_element: str | bytes | Element,
    formatted: bool = True,
) -> None

Source code in odfdo/mixin_paragraph.py

def append(
    self,
    str_or_element: str | bytes | Element,
    formatted: bool = True,
) -> None:
    if isinstance(str_or_element, Element):
        if str_or_element.tag in {"text:p", "text:h", "text:s"}:
            # minimal compliancy or spacer summation
            self.append_plain_text(str(str_or_element))
            self.append_plain_text(str_or_element.tail)
        else:
            self._Element__append(str_or_element)  # type: ignore[attr-defined]
    elif formatted:
        self.append_plain_text(str_or_element)
    else:
        # self._Element__append(self._unformatted(str_or_element))
        # The added text is first "unformatted", but result needs
        # to be compliant
        self.append_plain_text(self._unformatted(str_or_element))

append_plain_text

append_plain_text(text: str | bytes | None = '') -> None

Append plain text to the paragraph, replacing , and multiple spaces by ODF corresponding tags.

Source code in odfdo/mixin_paragraph.py

def append_plain_text(self, text: str | bytes | None = "") -> None:
    """Append plain text to the paragraph, replacing <CR>, <TAB> and
    multiple spaces by ODF corresponding tags.
    """
    if text is None:
        stext = ""
    elif isinstance(text, bytes):
        stext = text.decode("utf-8")
    else:
        stext = str(text)
    content = self._expand_spaces(stext)
    content = self._merge_spaces(content)
    content = self._replace_tabs_lb(content)
    for child in self.children:
        self.delete(child, keep_tail=False)
    self.text = None
    for element in content:
        self._Element__append(element)  # type: ignore[attr-defined]

insert_annotation

insert_annotation(
    annotation_element: Annotation | None = None,
    before: str | None = None,
    after: str | Element | None = None,
    position: int | tuple = 0,
    content: str | Element | None = None,
    body: str | None = None,
    creator: str | None = None,
    date: datetime | None = None,
) -> Annotation

Insert an annotation, at the position defined by the regex (before, after, content) or by positional argument (position). If content is provided, the annotation covers the full content regex. Else, the annotation is positioned either ‘before’ or ‘after’ provided regex.

If content is an odf element (ie: paragraph, span, …), the full inner content is covered by the annotation (of the position just after if content is a single empty tag).

If content/before or after exists (regex) and return a group of matching positions, the position value is the index of matching place to use.

annotation_element can contain a previously created annotation, else the annotation is created from the body, creator and optional date (current date by default).

Args:

annotation_element -- Annotation or None

before -- str regular expression or None

after -- str regular expression or Element or None

content -- str regular expression or None, or Element

position -- int or tuple of int

body -- str or Element

creator -- str

date -- datetime

Source code in odfdo/mixin_paragraph.py

def insert_annotation(
    self,
    annotation_element: Annotation | None = None,
    before: str | None = None,
    after: str | Element | None = None,
    position: int | tuple = 0,
    content: str | Element | None = None,
    body: str | None = None,
    creator: str | None = None,
    date: datetime | None = None,
) -> Annotation:
    """Insert an annotation, at the position defined by the regex (before,
    after, content) or by positional argument (position). If content is
    provided, the annotation covers the full content regex. Else, the
    annotation is positioned either 'before' or 'after' provided regex.

    If content is an odf element (ie: paragraph, span, ...), the full inner
    content is covered by the annotation (of the position just after if
    content is a single empty tag).

    If content/before or after exists (regex) and return a group of matching
    positions, the position value is the index of matching place to use.

    annotation_element can contain a previously created annotation, else
    the annotation is created from the body, creator and optional date
    (current date by default).

    Args:

        annotation_element -- Annotation or None

        before -- str regular expression or None

        after -- str regular expression or Element or None

        content -- str regular expression or None, or Element

        position -- int or tuple of int

        body -- str or Element

        creator -- str

        date -- datetime
    """

    if annotation_element is None:
        annotation_element = Annotation(
            text_or_element=body,
            creator=creator,
            date=date,
            parent=self,
        )
    else:
        # XXX clone or modify the argument?
        if body:
            annotation_element.note_body = body
        if creator:
            annotation_element.creator = creator
        if date:
            annotation_element.date = date
    annotation_element.check_validity()

    # special case: content is an odf element (ie: a paragraph)
    if isinstance(content, Element):
        if content.is_empty():
            content.insert(annotation_element, xmlposition=NEXT_SIBLING)
            return annotation_element
        content.insert(annotation_element, start=True)
        annotation_end = AnnotationEnd(annotation_element)
        content.append(annotation_end)
        return annotation_element

    # special case
    if isinstance(after, Element):
        after.insert(annotation_element, FIRST_CHILD)
        return annotation_element

    # With "content" => automatically insert a "start" and an "end"
    # bookmark
    if (
        before is None
        and after is None
        and content is not None
        and isinstance(position, int)
    ):
        # Start tag
        self._insert(annotation_element, before=content, position=position)
        # End tag
        annotation_end = AnnotationEnd(annotation_element)
        self._insert(annotation_end, after=content, position=position)
        return annotation_element

    # With "(int, int)" =>  automatically insert a "start" and an "end"
    # bookmark
    if (
        before is None
        and after is None
        and content is None
        and isinstance(position, tuple)
    ):
        # Start
        self._insert(annotation_element, position=position[0])
        # End
        annotation_end = AnnotationEnd(annotation_element)
        self._insert(annotation_end, position=position[1])
        return annotation_element

    # Without "content" nor "position"
    if content is not None or not isinstance(position, int):
        raise ValueError("Bad arguments")

    # Insert
    self._insert(annotation_element, before=before, after=after, position=position)
    return annotation_element

insert_annotation_end

insert_annotation_end(
    annotation_element: Annotation,
    before: str | None = None,
    after: str | None = None,
    position: int = 0,
) -> AnnotationEnd

Insert an annotation end tag for an existing annotation. If some end tag already exists, replace it. Annotation end tag is set at the position defined by the regex (before or after).

If content/before or after (regex) returns a group of matching positions, the position value is the index of matching place to use.

Args:

annotation_element -- Annotation (mandatory)

before -- str regular expression or None

after -- str regular expression or None

position -- int

Source code in odfdo/mixin_paragraph.py

def insert_annotation_end(
    self,
    annotation_element: Annotation,
    before: str | None = None,
    after: str | None = None,
    position: int = 0,
) -> AnnotationEnd:
    """Insert an annotation end tag for an existing annotation. If some end
    tag already exists, replace it. Annotation end tag is set at the
    position defined by the regex (before or after).

    If content/before or after (regex) returns a group of matching
    positions, the position value is the index of matching place to use.

    Args:

        annotation_element -- Annotation (mandatory)

        before -- str regular expression or None

        after -- str regular expression or None

        position -- int
    """

    if annotation_element is None:
        raise ValueError
    if not isinstance(annotation_element, Annotation):
        raise TypeError("Not a <office:annotation> Annotation")

    # remove existing end tag
    name = annotation_element.name
    existing_end_tag = self.get_annotation_end(name=name)
    if existing_end_tag:
        existing_end_tag.delete()

    # create the end tag
    end_tag = AnnotationEnd(annotation_element)

    # Insert
    self._insert(end_tag, before=before, after=after, position=position)
    return end_tag

insert_note

insert_note(
    note_element: Note | None = None,
    after: str | Element | None = None,
    note_class: str = "footnote",
    note_id: str | None = None,
    citation: str | None = None,
    body: str | None = None,
) -> None

Source code in odfdo/mixin_paragraph.py

def insert_note(
    self,
    note_element: Note | None = None,
    after: str | Element | None = None,
    note_class: str = "footnote",
    note_id: str | None = None,
    citation: str | None = None,
    body: str | None = None,
) -> None:
    if note_element is None:
        note_element = Note(
            note_class=note_class, note_id=note_id, citation=citation, body=body
        )
    else:
        # XXX clone or modify the argument?
        if note_class:
            note_element.note_class = note_class
        if note_id:
            note_element.note_id = note_id
        if citation:
            note_element.citation = citation
        if body:
            note_element.note_body = body
    note_element.check_validity()
    if isinstance(after, str):
        self._insert(note_element, after=after)
    elif isinstance(after, Element):
        after.insert(note_element, FIRST_CHILD)
    else:
        self.insert(note_element, FIRST_CHILD)

insert_reference

insert_reference(
    name: str,
    ref_format: str = "",
    before: str | None = None,
    after: str | Element | None = None,
    position: int = 0,
    display: str | None = None,
) -> None

Create and insert a reference to a content marked by a reference mark. The Reference element (“text:reference-ref”) represents a field that references a “text:reference-mark-start” or “text:reference-mark” element. Its “text:reference-format” attribute specifies what is displayed from the referenced element. Default is ‘page’. Actual content is not automatically updated except for the ‘text’ format.

name is mandatory and should represent an existing reference mark of the document.

ref_format is the argument for format reference (default is ‘page’).

The reference is inserted the position defined by the regex (before / after), or by positional argument (position). If ‘display’ is provided, it will be used as the text value for the reference.

If after is an ODF Element, the reference is inserted as first child of this element.

Args:

name -- str

ref_format -- one of : 'chapter', 'direction', 'page', 'text',
                        'caption', 'category-and-value', 'value',
                        'number', 'number-all-superior',
                        'number-no-superior'

before -- str regular expression or None

after -- str regular expression or odf element or None

position -- int

display -- str or None

Source code in odfdo/mixin_paragraph.py

def insert_reference(
    self,
    name: str,
    ref_format: str = "",
    before: str | None = None,
    after: str | Element | None = None,
    position: int = 0,
    display: str | None = None,
) -> None:
    """Create and insert a reference to a content marked by a reference
    mark. The Reference element ("text:reference-ref") represents a field
    that references a "text:reference-mark-start" or "text:reference-mark"
    element. Its "text:reference-format" attribute specifies what is
    displayed from the referenced element. Default is 'page'. Actual
    content is not automatically updated except for the 'text' format.

    name is mandatory and should represent an existing reference mark of the
    document.

    ref_format is the argument for format reference (default is 'page').

    The reference is inserted the position defined by the regex (before /
    after), or by positional argument (position). If 'display' is provided,
    it will be used as the text value for the reference.

    If after is an ODF Element, the reference is inserted as first child of
    this element.

    Args:

        name -- str

        ref_format -- one of : 'chapter', 'direction', 'page', 'text',
                                'caption', 'category-and-value', 'value',
                                'number', 'number-all-superior',
                                'number-no-superior'

        before -- str regular expression or None

        after -- str regular expression or odf element or None

        position -- int

        display -- str or None
    """
    reference = Reference(name, ref_format)
    if display is None and ref_format == "text":
        # get reference content
        body: Body | Element = self.document_body or self.root
        mark = body.get_reference_mark(name=name)
        if isinstance(mark, ReferenceMarkStart):
            display = mark.referenced_text()
    if not display:
        display = " "
    reference.text = display
    if isinstance(after, Element):
        after.insert(reference, FIRST_CHILD)
    else:
        self._insert(reference, before=before, after=after, position=position)

insert_variable

insert_variable(
    variable_element: Element, after: str | None
) -> None

Source code in odfdo/mixin_paragraph.py

def insert_variable(self, variable_element: Element, after: str | None) -> None:
    self._insert(variable_element, after=after)

remove_link

remove_link(links: Link | list[Link]) -> Element

Return a copy of the element (not a clone), with the sub links removed.

Args:

links -- Link or list of Link

Source code in odfdo/mixin_paragraph.py

def remove_link(self, links: Link | list[Link]) -> Element:
    """Return a copy of the element (not a clone), with the sub links
    removed.

    Args:

        links -- Link or list of Link
    """
    return strip_elements(self, links)  # type: ignore [return-value]

remove_links

remove_links() -> Element

Return a copy of the element, without links tags.

Source code in odfdo/mixin_paragraph.py

def remove_links(self) -> Element:
    """Return a copy of the element, without links tags."""
    strip = (Link._tag,)
    return strip_tags(self, strip=strip)  # type: ignore [return-value]

remove_span

remove_span(spans: Element | list[Element]) -> Element

Return a copy of the element, the spans (not a clone) removed.

Args:

spans -- Element or list of Element

Source code in odfdo/mixin_paragraph.py

def remove_span(self, spans: Element | list[Element]) -> Element:
    """Return a copy of the element, the spans (not a clone) removed.

    Args:

        spans -- Element or list of Element
    """
    return strip_elements(self, spans)  # type: ignore [return-value]

remove_spans

remove_spans(keep_heading: bool = True) -> Element

Return copy of the element, without span styles.

If keep_heading is True (default), the first level heading style is left unchanged.

Source code in odfdo/mixin_paragraph.py

def remove_spans(self, keep_heading: bool = True) -> Element:
    """Return copy of the element, without span styles.

    If keep_heading is True (default), the first level heading style is
    left unchanged.
    """
    strip = ("text:span",)
    if keep_heading:
        protect = ("text:h",)
    else:
        protect = None
    return strip_tags(self, strip=strip, protect=protect)  # type: ignore [return-value]

set_bookmark

set_bookmark(
    name: str,
    before: str | None = None,
    after: str | None = None,
    position: int | tuple = 0,
    role: str | None = None,
    content: str | None = None,
) -> Element | tuple[Element, Element]

Insert a bookmark before or after the characters in the text which match the regex before/after. When the regex matches more of one part of the text, position can be set to choose which part must be used. If before and after are None, we use only position that is the number of characters.

So, by default, this function inserts a bookmark before the first character of the content. Role can be None, “start” or “end”, we insert respectively a position bookmark a bookmark-start or a bookmark-end.

If content is not None these 2 calls are equivalent:

paragraph.set_bookmark(“bookmark”, content=”xyz”)

and:

paragraph.set_bookmark(“bookmark”, before=”xyz”, role=”start”) paragraph.set_bookmark(“bookmark”, after=”xyz”, role=”end”)

If position is a 2-tuple, these 2 calls are equivalent:

paragraph.set_bookmark(“bookmark”, position=(10, 20))

and:

paragraph.set_bookmark(“bookmark”, position=10, role=”start”) paragraph.set_bookmark(“bookmark”, position=20, role=”end”)

Args:

name -- str

before -- str regex

after -- str regex

position -- int or (int, int)

role -- None, "start" or "end"

content -- str regex

Source code in odfdo/mixin_paragraph.py

def set_bookmark(
    self,
    name: str,
    before: str | None = None,
    after: str | None = None,
    position: int | tuple = 0,
    role: str | None = None,
    content: str | None = None,
) -> Element | tuple[Element, Element]:
    """Insert a bookmark before or after the characters in the text which
    match the regex before/after. When the regex matches more of one part
    of the text, position can be set to choose which part must be used. If
    before and after are None, we use only position that is the number of
    characters.

    So, by default, this function inserts a bookmark before the first
    character of the content. Role can be None, "start" or "end", we
    insert respectively a position bookmark a bookmark-start or a
    bookmark-end.

    If content is not None these 2 calls are equivalent:

      paragraph.set_bookmark("bookmark", content="xyz")

    and:

      paragraph.set_bookmark("bookmark", before="xyz", role="start")
      paragraph.set_bookmark("bookmark", after="xyz", role="end")


    If position is a 2-tuple, these 2 calls are equivalent:

      paragraph.set_bookmark("bookmark", position=(10, 20))

    and:

      paragraph.set_bookmark("bookmark", position=10, role="start")
      paragraph.set_bookmark("bookmark", position=20, role="end")


    Args:

        name -- str

        before -- str regex

        after -- str regex

        position -- int or (int, int)

        role -- None, "start" or "end"

        content -- str regex
    """
    # With "content" => automatically insert a "start" and an "end"
    # bookmark
    if (
        before is None
        and after is None
        and role is None
        and content is not None
        and isinstance(position, int)
    ):
        # Start
        start = BookmarkStart(name)
        self._insert(start, before=content, position=position)
        # End
        end = BookmarkEnd(name)
        self._insert(end, after=content, position=position)
        return start, end

    # With "(int, int)" =>  automatically insert a "start" and an "end"
    # bookmark
    if (
        before is None
        and after is None
        and role is None
        and content is None
        and isinstance(position, tuple)
    ):
        # Start
        start = BookmarkStart(name)
        self._insert(start, position=position[0])
        # End
        end = BookmarkEnd(name)
        self._insert(end, position=position[1])
        return start, end

    # Without "content" nor "position"
    if content is not None or not isinstance(position, int):
        raise ValueError("bad arguments")

    # Role
    if role is None:
        bookmark: Element = Bookmark(name)
    elif role == "start":
        bookmark = BookmarkStart(name)
    elif role == "end":
        bookmark = BookmarkEnd(name)
    else:
        raise ValueError("bad arguments")

    # Insert
    self._insert(bookmark, before=before, after=after, position=position)

    return bookmark

set_link

set_link(
    url: str,
    regex: str | None = None,
    offset: int | None = None,
    length: int = 0,
    **kwargs: Any,
) -> list[Link]

Make a link to the provided url from text content matching either:

• the ‘regex’ match,
• or the string of length ‘length’ starting at ‘offset’.

Args:

url -- str

regex -- str regular expression, or None

offset -- int, or None

length -- int

Returns: list of generated Link instances.

Source code in odfdo/mixin_paragraph.py

@_by_regex_offset
def set_link(
    self,
    url: str,
    regex: str | None = None,
    offset: int | None = None,
    length: int = 0,
    **kwargs: Any,
) -> list[Link]:
    """
    Make a link to the provided url from text content matching either:

      - the 'regex' match,
      - or the string of length 'length' starting at 'offset'.

    Args:

        url -- str

        regex -- str regular expression, or None

        offset -- int, or None

        length -- int

    Returns: list of generated Link instances.
    """

    return Link(url, text=kwargs["match_string"])  # type: ignore[return-value]

set_reference_mark

set_reference_mark(
    name: str,
    before: str | None = None,
    after: str | None = None,
    position: int = 0,
    content: str | Element | None = None,
) -> Element

Insert a reference mark, at the position defined by the regex (before, after, content) or by positional argument (position). If content is provided, the annotation covers the full range content regex (instances of ReferenceMarkStart and ReferenceMarkEnd are created). Else, an instance of ReferenceMark is positioned either ‘before’ or ‘after’ provided regex.

If content is an ODF Element (ie: Paragraph, Span, …), the full inner content is referenced (of the position just after if content is a single empty tag).

If content/before or after exists (regex) and return a group of matching positions, the position value is the index of matching place to use.

Name is mandatory and shall be unique in the document for the preference mark range.

Args:

name -- str

before -- str regular expression or None

after -- str regular expression or None,

content -- str regular expression or None, or Element

position -- int or tuple of int

Returns: the created ReferenceMark or ReferenceMarkStart

Source code in odfdo/mixin_paragraph.py

def set_reference_mark(
    self,
    name: str,
    before: str | None = None,
    after: str | None = None,
    position: int = 0,
    content: str | Element | None = None,
) -> Element:
    """Insert a reference mark, at the position defined by the regex
    (before, after, content) or by positional argument (position). If
    content is provided, the annotation covers the full range content regex
    (instances of ReferenceMarkStart and ReferenceMarkEnd are created).
    Else, an instance of ReferenceMark is positioned either 'before' or
    'after' provided regex.

    If content is an ODF Element (ie: Paragraph, Span, ...), the full inner
    content is referenced (of the position just after if content is a single
    empty tag).

    If content/before or after exists (regex) and return a group of matching
    positions, the position value is the index of matching place to use.

    Name is mandatory and shall be unique in the document for the preference
    mark range.

    Args:

        name -- str

        before -- str regular expression or None

        after -- str regular expression or None,

        content -- str regular expression or None, or Element

        position -- int or tuple of int

    Returns: the created ReferenceMark or ReferenceMarkStart
    """
    # special case: content is an odf element (ie: a paragraph)
    if isinstance(content, Element):
        if content.is_empty():
            reference = ReferenceMark(name)
            content.insert(reference, xmlposition=NEXT_SIBLING)
            return reference
        reference_start = ReferenceMarkStart(name)
        content.insert(reference_start, start=True)
        reference_end = ReferenceMarkEnd(name)
        content.append(reference_end)
        return reference_start

    # With "content" => automatically insert a "start" and an "end"
    # reference
    if (
        before is None
        and after is None
        and content is not None
        and isinstance(position, int)
    ):
        # Start tag
        reference_start = ReferenceMarkStart(name)
        self._insert(reference_start, before=content, position=position)
        # End tag
        reference_end = ReferenceMarkEnd(name)
        self._insert(reference_end, after=content, position=position)
        return reference_start

    # With "(int, int)" =>  automatically insert a "start" and an "end"
    if (
        before is None
        and after is None
        and content is None
        and isinstance(position, tuple)
    ):
        # Start
        reference_start = ReferenceMarkStart(name)
        self._insert(reference_start, position=position[0])
        # End
        reference_end = ReferenceMarkEnd(name)
        self._insert(reference_end, position=position[1])
        return reference_start

    # Without "content" nor "position"
    if content is not None or not isinstance(position, int):
        raise ValueError("bad arguments")

    # Insert a positional reference mark
    reference = ReferenceMark(name)
    self._insert(reference, before=before, after=after, position=position)
    return reference

set_reference_mark_end

set_reference_mark_end(
    reference_mark: Element,
    before: str | None = None,
    after: str | None = None,
    position: int = 0,
) -> ReferenceMarkEnd

Insert/move a ReferenceMarkEnd for an existing reference mark. If some end tag already exists, replace it. Reference tag is set at the position defined by the regex (before or after).

If content/before or after (regex) returns a group of matching positions, the position value is the index of matching place to use.

Args:

reference_mark -- ReferenceMark or ReferenceMarkStart (mandatory)

before -- str regular expression or None

after -- str regular expression or None

position -- int

Source code in odfdo/mixin_paragraph.py

def set_reference_mark_end(
    self,
    reference_mark: Element,
    before: str | None = None,
    after: str | None = None,
    position: int = 0,
) -> ReferenceMarkEnd:
    """Insert/move a ReferenceMarkEnd for an existing reference mark. If
    some end tag already exists, replace it. Reference tag is set at the
    position defined by the regex (before or after).

    If content/before or after (regex) returns a group of matching
    positions, the position value is the index of matching place to use.

    Args:

        reference_mark -- ReferenceMark or ReferenceMarkStart (mandatory)

        before -- str regular expression or None

        after -- str regular expression or None

        position -- int
    """
    if not isinstance(reference_mark, (ReferenceMark, ReferenceMarkStart)):
        raise TypeError("Not a ReferenceMark or ReferenceMarkStart")
    name = reference_mark.name
    if isinstance(reference_mark, ReferenceMark):
        # change it to a range reference:
        reference_mark.tag = ReferenceMarkStart._tag

    existing_end_tag = self.get_reference_mark_end(name=name)
    if existing_end_tag:
        existing_end_tag.delete()

    # create the end tag
    end_tag = ReferenceMarkEnd(name)

    # Insert
    self._insert(end_tag, before=before, after=after, position=position)
    return end_tag

set_span

set_span(
    style: str,
    regex: str | None = None,
    offset: int | None = None,
    length: int = 0,
    **kwargs: Any,
) -> list[Span]

Apply the given style with a Span to text content matching either:

• the ‘regex’ match,
• or the string of length ‘length’ starting at ‘offset’.

Args:

style -- str

regex -- str regular expression, or None

offset -- int, or None

length -- int

Returns: list of generated Span instances.

Source code in odfdo/mixin_paragraph.py

@_by_regex_offset
def set_span(
    self,
    style: str,
    regex: str | None = None,
    offset: int | None = None,
    length: int = 0,
    **kwargs: Any,
) -> list[Span]:
    """
    Apply the given style  with a Span to text content matching either:

      - the 'regex' match,
      - or the string of length 'length' starting at 'offset'.

    Args:

        style -- str

        regex -- str regular expression, or None

        offset -- int, or None

        length -- int

    Returns: list of generated Span instances.
    """
    # span = Span(match, style=style)
    # span.tail = tail
    span: Span = Element.from_tag("text:span")  # type: ignore[assignment]
    span.text = ""
    span.append_plain_text(kwargs["match_string"])
    span.style = style
    return span  # type: ignore[return-value]

Paragraph

Bases: MDParagraph, ParaFormattedTextMixin, ParaMixin, 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__	Create a paragraph element “text:p” of the given style containing

Attributes:

Name	Type	Description
style
text

Source code in odfdo/paragraph.py

class Paragraph(MDParagraph, ParaFormattedTextMixin, ParaMixin, 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, ...] = (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,
    ):
        """Create a paragraph element "text:p" 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 -- str, bytes or Element

            style -- str

            formatted -- bool
        """
        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:
        # '\n' at the end slightly breaks compatibility, but is clearly better
        return self.inner_text + "\n"

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,
)

Create a paragraph element “text:p” 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.

Args:

text -- str, bytes or Element

style -- str

formatted -- bool

Source code in odfdo/paragraph.py

def __init__(
    self,
    text_or_element: str | bytes | Element | None = None,
    style: str | None = None,
    formatted: bool = True,
    **kwargs: Any,
):
    """Create a paragraph element "text:p" 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 -- str, bytes or Element

        style -- str

        formatted -- bool
    """
    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

Presentation

Bases: NRMixin, Body

Root of the Presentation document content, “office:presentation”.

Source code in odfdo/body.py

class Presentation(NRMixin, Body):
    """Root of the Presentation document content, "office:presentation"."""

    _tag: str = "office:presentation"
    _properties: tuple[PropDef, ...] = ()

RectangleShape

Bases: ShapeBase

A rectangle shape, “draw:rect”.

Methods:

Name	Description
__init__	Create a rectangle shape “draw:rect”.

Source code in odfdo/shapes.py

class RectangleShape(ShapeBase):
    """A rectangle shape, "draw:rect"."""

    _tag = "draw:rect"
    _properties: tuple[PropDef, ...] = ()

    def __init__(
        self,
        style: str | None = None,
        text_style: str | None = None,
        draw_id: str | None = None,
        layer: str | None = None,
        position: tuple | None = None,
        size: tuple | None = None,
        **kwargs: Any,
    ) -> None:
        """Create a rectangle shape "draw:rect".

        Args:

            style -- str

            text_style -- str

            draw_id -- str

            layer -- str

            position -- (str, str)

            size -- (str, str)
        """
        kwargs.update(
            {
                "style": style,
                "text_style": text_style,
                "draw_id": draw_id,
                "layer": layer,
                "size": size,
                "position": position,
            }
        )
        super().__init__(**kwargs)

__init__

__init__(
    style: str | None = None,
    text_style: str | None = None,
    draw_id: str | None = None,
    layer: str | None = None,
    position: tuple | None = None,
    size: tuple | None = None,
    **kwargs: Any,
) -> None

Create a rectangle shape “draw:rect”.

Args:

style -- str

text_style -- str

draw_id -- str

layer -- str

position -- (str, str)

size -- (str, str)

Source code in odfdo/shapes.py

def __init__(
    self,
    style: str | None = None,
    text_style: str | None = None,
    draw_id: str | None = None,
    layer: str | None = None,
    position: tuple | None = None,
    size: tuple | None = None,
    **kwargs: Any,
) -> None:
    """Create a rectangle shape "draw:rect".

    Args:

        style -- str

        text_style -- str

        draw_id -- str

        layer -- str

        position -- (str, str)

        size -- (str, str)
    """
    kwargs.update(
        {
            "style": style,
            "text_style": text_style,
            "draw_id": draw_id,
            "layer": layer,
            "size": size,
            "position": position,
        }
    )
    super().__init__(**kwargs)

Reference

Bases: Element

A reference to a content marked by a reference mark, “text:reference- ref”.”.

The odf_reference element (“text:reference-ref”) represents a field that references a “text:reference-mark-start” or “text:reference-mark” element. Its text:reference-format attribute specifies what is displayed from the referenced element. Default is ‘page’ Actual content is not updated except for the ‘text’ format by the update() method.

Creation of references can be tricky, consider using this method: odfdo.paragraph.insert_reference()

Values for text:reference-format : The defined values for the text:reference-format attribute supported by all reference fields are: - ‘chapter’: displays the number of the chapter in which the referenced item appears. - ‘direction’: displays whether the referenced item is above or below the reference field. - ‘page’: displays the number of the page on which the referenced item appears. - ‘text’: displays the text of the referenced item. Additional defined values for the text:reference-format attribute supported by references to sequence fields are: - ‘caption’: displays the caption in which the sequence is used. - ‘category-and-value’: displays the name and value of the sequence. - ‘value’: displays the value of the sequence.

References to bookmarks and other references support additional values,
which display the list label of the referenced item. If the referenced
item is contained in a list or a numbered paragraph, the list label is
the formatted number of the paragraph which contains the referenced
item. If the referenced item is not contained in a list or numbered
paragraph, the list label is empty, and the referenced field therefore
displays nothing. If the referenced bookmark or reference contains more
than one paragraph, the list label of the paragraph at which the
bookmark or reference starts is taken.

Additional defined values for the text:reference-format attribute
supported by all references to bookmark's or other reference fields
are:
  - 'number': displays the list label of the referenced item. [...]
  - 'number-all-superior': displays the list label of the referenced
    item and adds the contents of all list labels of superior levels
    in front of it. [...]
  - 'number-no-superior': displays the contents of the list label of
    the referenced item.

Methods:

Name	Description
__init__	Create a reference to a content marked by a reference mark
update	Update the content of the reference text field.

Attributes:

Name	Type	Description
FORMAT_ALLOWED
name
ref_format	str | None

Source code in odfdo/reference.py

class Reference(Element):
    """A reference to a content marked by a reference mark, "text:reference-
    ref".".

    The odf_reference element ("text:reference-ref") represents a field that
    references a "text:reference-mark-start" or "text:reference-mark" element.
    Its text:reference-format attribute specifies what is displayed from the
    referenced element. Default is 'page'
    Actual content is not updated except for the 'text' format by the
    update() method.


    Creation of references can be tricky, consider using this method:
        odfdo.paragraph.insert_reference()

    Values for text:reference-format :
        The defined values for the text:reference-format attribute supported by
        all reference fields are:
          - 'chapter': displays the number of the chapter in which the
            referenced item appears.
          - 'direction': displays whether the referenced item is above or
            below the reference field.
          - 'page': displays the number of the page on which the referenced
            item appears.
          - 'text': displays the text of the referenced item.
        Additional defined values for the text:reference-format attribute
        supported by references to sequence fields are:
          - 'caption': displays the caption in which the sequence is used.
          - 'category-and-value': displays the name and value of the sequence.
          - 'value': displays the value of the sequence.

        References to bookmarks and other references support additional values,
        which display the list label of the referenced item. If the referenced
        item is contained in a list or a numbered paragraph, the list label is
        the formatted number of the paragraph which contains the referenced
        item. If the referenced item is not contained in a list or numbered
        paragraph, the list label is empty, and the referenced field therefore
        displays nothing. If the referenced bookmark or reference contains more
        than one paragraph, the list label of the paragraph at which the
        bookmark or reference starts is taken.

        Additional defined values for the text:reference-format attribute
        supported by all references to bookmark's or other reference fields
        are:
          - 'number': displays the list label of the referenced item. [...]
          - 'number-all-superior': displays the list label of the referenced
            item and adds the contents of all list labels of superior levels
            in front of it. [...]
          - 'number-no-superior': displays the contents of the list label of
            the referenced item.
    """

    _tag = "text:reference-ref"
    _properties = (PropDef("name", "text:ref-name"),)
    FORMAT_ALLOWED = (
        "chapter",
        "direction",
        "page",
        "text",
        "caption",
        "category-and-value",
        "value",
        "number",
        "number-all-superior",
        "number-no-superior",
    )

    def __init__(self, name: str = "", ref_format: str = "", **kwargs: Any) -> None:
        """Create a reference to a content marked by a reference mark
        "text:reference-ref".

        An actual reference mark with the provided name should exist.

        Consider using: odfdo.paragraph.insert_reference()

        The text:ref-name attribute identifies a "text:reference-mark" or
        "text:referencemark-start" element by the value of that element's
        text:name attribute.
        If ref_format is 'text', the current text content of the reference_mark
        is retrieved.

        Args:

            name -- str : name of the reference mark

            ref_format -- str : format of the field. Default is 'page', allowed
                            values are 'chapter', 'direction', 'page', 'text',
                            'caption', 'category-and-value', 'value', 'number',
                            'number-all-superior', 'number-no-superior'.
        """
        super().__init__(**kwargs)
        if self._do_init:
            self.name = name
            self.ref_format = ref_format

    @property
    def ref_format(self) -> str | None:
        reference = self.get_attribute("text:reference-format")
        if isinstance(reference, str):
            return reference
        return None

    @ref_format.setter
    def ref_format(self, ref_format: str) -> None:
        """Set the text:reference-format attribute.

        Args:

            ref_format -- str
        """
        if not ref_format or ref_format not in self.FORMAT_ALLOWED:
            ref_format = "page"
        self.set_attribute("text:reference-format", ref_format)

    def update(self) -> None:
        """Update the content of the reference text field.

        Currently only 'text' format is implemented. Other values, for example
        the 'page' text field, may need to be refreshed through a visual ODF
        parser.
        """
        ref_format = self.ref_format
        if ref_format != "text":
            # only 'text' is implemented
            return None
        body: Body | Element = self.document_body or self.root
        name = self.name
        reference = body.get_reference_mark(name=name)
        if isinstance(reference, ReferenceMarkStart):
            self.text = reference.referenced_text()

FORMAT_ALLOWED class-attribute instance-attribute

FORMAT_ALLOWED = (
    "chapter",
    "direction",
    "page",
    "text",
    "caption",
    "category-and-value",
    "value",
    "number",
    "number-all-superior",
    "number-no-superior",
)

name instance-attribute

name = name

ref_format property writable

ref_format: str | None

__init__

__init__(
    name: str = "", ref_format: str = "", **kwargs: Any
) -> None

Create a reference to a content marked by a reference mark “text:reference-ref”.

An actual reference mark with the provided name should exist.

Consider using: odfdo.paragraph.insert_reference()

The text:ref-name attribute identifies a “text:reference-mark” or “text:referencemark-start” element by the value of that element’s text:name attribute. If ref_format is ‘text’, the current text content of the reference_mark is retrieved.

Args:

name -- str : name of the reference mark

ref_format -- str : format of the field. Default is 'page', allowed
                values are 'chapter', 'direction', 'page', 'text',
                'caption', 'category-and-value', 'value', 'number',
                'number-all-superior', 'number-no-superior'.

Source code in odfdo/reference.py

def __init__(self, name: str = "", ref_format: str = "", **kwargs: Any) -> None:
    """Create a reference to a content marked by a reference mark
    "text:reference-ref".

    An actual reference mark with the provided name should exist.

    Consider using: odfdo.paragraph.insert_reference()

    The text:ref-name attribute identifies a "text:reference-mark" or
    "text:referencemark-start" element by the value of that element's
    text:name attribute.
    If ref_format is 'text', the current text content of the reference_mark
    is retrieved.

    Args:

        name -- str : name of the reference mark

        ref_format -- str : format of the field. Default is 'page', allowed
                        values are 'chapter', 'direction', 'page', 'text',
                        'caption', 'category-and-value', 'value', 'number',
                        'number-all-superior', 'number-no-superior'.
    """
    super().__init__(**kwargs)
    if self._do_init:
        self.name = name
        self.ref_format = ref_format

update

update() -> None

Update the content of the reference text field.

Currently only ‘text’ format is implemented. Other values, for example the ‘page’ text field, may need to be refreshed through a visual ODF parser.

Source code in odfdo/reference.py

def update(self) -> None:
    """Update the content of the reference text field.

    Currently only 'text' format is implemented. Other values, for example
    the 'page' text field, may need to be refreshed through a visual ODF
    parser.
    """
    ref_format = self.ref_format
    if ref_format != "text":
        # only 'text' is implemented
        return None
    body: Body | Element = self.document_body or self.root
    name = self.name
    reference = body.get_reference_mark(name=name)
    if isinstance(reference, ReferenceMarkStart):
        self.text = reference.referenced_text()

ReferenceMark

Bases: Element

A point reference, “text:reference-mark”.

A point reference marks a position in text and is represented by a single “text:reference-mark” element.

Methods:

Name	Description
__init__	A point reference “text:reference-mark”.

Attributes:

Name	Type	Description
name

Source code in odfdo/reference.py

class ReferenceMark(Element):
    """A point reference, "text:reference-mark".

    A point reference marks a position in text and is represented by a single
    "text:reference-mark" element.
    """

    _tag = "text:reference-mark"
    _properties = (PropDef("name", "text:name"),)

    def __init__(self, name: str = "", **kwargs: Any) -> None:
        """A point reference "text:reference-mark".

        A point reference marks a position in text and is
        represented by a single "text:reference-mark" element.
        Consider using the wrapper: odfdo.paragraph.set_reference_mark()

        Args:

            name -- str
        """
        super().__init__(**kwargs)
        if self._do_init:
            self.name = name

name instance-attribute

name = name

__init__

__init__(name: str = '', **kwargs: Any) -> None

A point reference “text:reference-mark”.

A point reference marks a position in text and is represented by a single “text:reference-mark” element. Consider using the wrapper: odfdo.paragraph.set_reference_mark()

Args:

name -- str

Source code in odfdo/reference.py

def __init__(self, name: str = "", **kwargs: Any) -> None:
    """A point reference "text:reference-mark".

    A point reference marks a position in text and is
    represented by a single "text:reference-mark" element.
    Consider using the wrapper: odfdo.paragraph.set_reference_mark()

    Args:

        name -- str
    """
    super().__init__(**kwargs)
    if self._do_init:
        self.name = name

ReferenceMarkEnd

Bases: Element

End of a range reference, “text:reference-mark-end”.

Methods:

Name	Description
__init__	The “text:reference-mark-end” element represent the end of a range
referenced_text	Return the text between reference-mark-start and reference-mark-

Attributes:

Name	Type	Description
name

Source code in odfdo/reference.py

class ReferenceMarkEnd(Element):
    """End of a range reference, "text:reference-mark-end"."""

    _tag = "text:reference-mark-end"
    _properties = (PropDef("name", "text:name"),)

    def __init__(self, name: str = "", **kwargs: Any) -> None:
        """The "text:reference-mark-end" element represent the end of a range
        reference.
        Consider using the wrappers: odfdo.paragraph.set_reference_mark() and
        odfdo.paragraph.set_reference_mark_end()

        Args:

            name -- str
        """
        super().__init__(**kwargs)
        if self._do_init:
            self.name = name

    def referenced_text(self) -> str:
        """Return the text between reference-mark-start and reference-mark-
        end.
        """
        name = self.name
        request = (
            f"//text()"
            f"[preceding::text:reference-mark-start[@text:name='{name}'] "
            f"and following::text:reference-mark-end[@text:name='{name}']]"
        )
        result = " ".join(str(x) for x in self.xpath(request))
        return result

name instance-attribute

name = name

__init__

__init__(name: str = '', **kwargs: Any) -> None

The “text:reference-mark-end” element represent the end of a range reference. Consider using the wrappers: odfdo.paragraph.set_reference_mark() and odfdo.paragraph.set_reference_mark_end()

Args:

name -- str

Source code in odfdo/reference.py

def __init__(self, name: str = "", **kwargs: Any) -> None:
    """The "text:reference-mark-end" element represent the end of a range
    reference.
    Consider using the wrappers: odfdo.paragraph.set_reference_mark() and
    odfdo.paragraph.set_reference_mark_end()

    Args:

        name -- str
    """
    super().__init__(**kwargs)
    if self._do_init:
        self.name = name

referenced_text

referenced_text() -> str

Return the text between reference-mark-start and reference-mark- end.

Source code in odfdo/reference.py

def referenced_text(self) -> str:
    """Return the text between reference-mark-start and reference-mark-
    end.
    """
    name = self.name
    request = (
        f"//text()"
        f"[preceding::text:reference-mark-start[@text:name='{name}'] "
        f"and following::text:reference-mark-end[@text:name='{name}']]"
    )
    result = " ".join(str(x) for x in self.xpath(request))
    return result

ReferenceMarkStart

Bases: Element

Start of a range reference, “text:reference-mark-start”.

Methods:

Name	Description
__init__	The “text:reference-mark-start” element represent the start of a range
delete	Delete the given element from the XML tree. If no element is given,
get_referenced	Return the document content between the start and end tags of the
referenced_text	Return the text between reference-mark-start and reference-mark-

Attributes:

Name	Type	Description
name

Source code in odfdo/reference.py

class ReferenceMarkStart(Element):
    """Start of a range reference, "text:reference-mark-start"."""

    _tag = "text:reference-mark-start"
    _properties = (PropDef("name", "text:name"),)

    def __init__(self, name: str = "", **kwargs: Any) -> None:
        """The "text:reference-mark-start" element represent the start of a range
        reference.
        Consider using the wrapper: odfdo.paragraph.set_reference_mark()

        Args:

            name -- str
        """
        super().__init__(**kwargs)
        if self._do_init:
            self.name = name

    def referenced_text(self) -> str:
        """Return the text between reference-mark-start and reference-mark-
        end.
        """
        name = self.name
        request = (
            f"//text()"
            f"[preceding::text:reference-mark-start[@text:name='{name}'] "
            f"and following::text:reference-mark-end[@text:name='{name}']]"
        )
        result = " ".join(str(x) for x in self.xpath(request))
        return result

    def get_referenced(
        self,
        no_header: bool = False,
        clean: bool = True,
        as_xml: bool = False,
        as_list: bool = False,
    ) -> Element | list | str | None:
        """Return the document content between the start and end tags of the
        reference. The content returned by this method can spread over several
        headers and paragraphs. By default, the content is returned as an
        "office:text" odf element.

        Args:

            no_header -- boolean (default to False), translate existing headers
                         tags "text:h" into paragraphs "text:p".

            clean -- boolean (default to True), suppress unwanted tags. Striped
                     tags are : 'text:change', 'text:change-start',
                     'text:change-end', 'text:reference-mark',
                     'text:reference-mark-start', 'text:reference-mark-end'.

            as_xml -- boolean (default to False), format the returned content as
                      a XML string (serialization).

            as_list -- boolean (default to False), do not embed the returned
                       content in a "office:text'" element, instead simply
                       return a raw list of odf elements.
        """
        if self.parent is None:
            raise ValueError(
                "Reference need some upper document part"
            )  # pragma: nocover
        body: Body | Element = self.document_body or self.parent
        end = body.get_reference_mark_end(name=self.name)
        if end is None:
            raise ValueError("No reference-end found")
        content_list = elements_between(
            body, self, end, as_text=False, no_header=no_header, clean=clean
        )
        if as_list:
            return content_list
        referenced = Element.from_tag("office:text")
        for chunk in content_list:
            referenced.append(chunk)
        if as_xml:
            return referenced.serialize()
        else:
            return referenced

    def delete(self, child: Element | None = None, keep_tail: bool = True) -> None:
        """Delete the given element from the XML tree. If no element is given,
        "self" is deleted. The XML library may allow to continue to use an
        element now "orphan" as long as you have a reference to it.

        For odf_reference_mark_start : delete the reference-end tag if exists.

        Args:

            child -- Element

            keep_tail -- boolean (default to True), True for most usages.
        """
        if child is not None:  # act like normal delete
            return super().delete(child, keep_tail)  # pragma: nocover
        name = self.name
        if self.parent is None:
            raise ValueError("Can't delete the root element")  # pragma: nocover
        body: Body | Element = self.document_body or self.parent
        ref_end = body.get_reference_mark_end(name=name)
        if ref_end:  # pragma: nocover
            ref_end.delete()
        # act like normal delete
        return super().delete()

name instance-attribute

name = name

__init__

__init__(name: str = '', **kwargs: Any) -> None

The “text:reference-mark-start” element represent the start of a range reference. Consider using the wrapper: odfdo.paragraph.set_reference_mark()

Args:

name -- str

Source code in odfdo/reference.py

def __init__(self, name: str = "", **kwargs: Any) -> None:
    """The "text:reference-mark-start" element represent the start of a range
    reference.
    Consider using the wrapper: odfdo.paragraph.set_reference_mark()

    Args:

        name -- str
    """
    super().__init__(**kwargs)
    if self._do_init:
        self.name = name

delete

delete(
    child: Element | None = None, keep_tail: bool = True
) -> None

Delete the given element from the XML tree. If no element is given, “self” is deleted. The XML library may allow to continue to use an element now “orphan” as long as you have a reference to it.

For odf_reference_mark_start : delete the reference-end tag if exists.

Args:

child -- Element

keep_tail -- boolean (default to True), True for most usages.

Source code in odfdo/reference.py

def delete(self, child: Element | None = None, keep_tail: bool = True) -> None:
    """Delete the given element from the XML tree. If no element is given,
    "self" is deleted. The XML library may allow to continue to use an
    element now "orphan" as long as you have a reference to it.

    For odf_reference_mark_start : delete the reference-end tag if exists.

    Args:

        child -- Element

        keep_tail -- boolean (default to True), True for most usages.
    """
    if child is not None:  # act like normal delete
        return super().delete(child, keep_tail)  # pragma: nocover
    name = self.name
    if self.parent is None:
        raise ValueError("Can't delete the root element")  # pragma: nocover
    body: Body | Element = self.document_body or self.parent
    ref_end = body.get_reference_mark_end(name=name)
    if ref_end:  # pragma: nocover
        ref_end.delete()
    # act like normal delete
    return super().delete()

get_referenced

get_referenced(
    no_header: bool = False,
    clean: bool = True,
    as_xml: bool = False,
    as_list: bool = False,
) -> Element | list | str | None

Return the document content between the start and end tags of the reference. The content returned by this method can spread over several headers and paragraphs. By default, the content is returned as an “office:text” odf element.

Args:

no_header -- boolean (default to False), translate existing headers
             tags "text:h" into paragraphs "text:p".

clean -- boolean (default to True), suppress unwanted tags. Striped
         tags are : 'text:change', 'text:change-start',
         'text:change-end', 'text:reference-mark',
         'text:reference-mark-start', 'text:reference-mark-end'.

as_xml -- boolean (default to False), format the returned content as
          a XML string (serialization).

as_list -- boolean (default to False), do not embed the returned
           content in a "office:text'" element, instead simply
           return a raw list of odf elements.

Source code in odfdo/reference.py

def get_referenced(
    self,
    no_header: bool = False,
    clean: bool = True,
    as_xml: bool = False,
    as_list: bool = False,
) -> Element | list | str | None:
    """Return the document content between the start and end tags of the
    reference. The content returned by this method can spread over several
    headers and paragraphs. By default, the content is returned as an
    "office:text" odf element.

    Args:

        no_header -- boolean (default to False), translate existing headers
                     tags "text:h" into paragraphs "text:p".

        clean -- boolean (default to True), suppress unwanted tags. Striped
                 tags are : 'text:change', 'text:change-start',
                 'text:change-end', 'text:reference-mark',
                 'text:reference-mark-start', 'text:reference-mark-end'.

        as_xml -- boolean (default to False), format the returned content as
                  a XML string (serialization).

        as_list -- boolean (default to False), do not embed the returned
                   content in a "office:text'" element, instead simply
                   return a raw list of odf elements.
    """
    if self.parent is None:
        raise ValueError(
            "Reference need some upper document part"
        )  # pragma: nocover
    body: Body | Element = self.document_body or self.parent
    end = body.get_reference_mark_end(name=self.name)
    if end is None:
        raise ValueError("No reference-end found")
    content_list = elements_between(
        body, self, end, as_text=False, no_header=no_header, clean=clean
    )
    if as_list:
        return content_list
    referenced = Element.from_tag("office:text")
    for chunk in content_list:
        referenced.append(chunk)
    if as_xml:
        return referenced.serialize()
    else:
        return referenced

referenced_text

referenced_text() -> str

Return the text between reference-mark-start and reference-mark- end.

Source code in odfdo/reference.py

def referenced_text(self) -> str:
    """Return the text between reference-mark-start and reference-mark-
    end.
    """
    name = self.name
    request = (
        f"//text()"
        f"[preceding::text:reference-mark-start[@text:name='{name}'] "
        f"and following::text:reference-mark-end[@text:name='{name}']]"
    )
    result = " ".join(str(x) for x in self.xpath(request))
    return result

Row

Bases: Element

A row of a table, “table:table-row”.

Methods:

Name	Description
__init__	Create a Row, “table:table-row”, optionally filled with “width”
append_cell	Append the given cell at the end of the row. Repeated cells are
clear	Remove text, children and attributes from the Row.
delete_cell	Delete the cell at the given position “x” starting from 0.
extend_cells
force_width	Change the repeated property of the last cell of the row to comply
get_cell	Get the cell at position “x” starting from 0. Alphabetical positions
get_cells	Get the list of cells matching the criteria.
get_elements
get_sub_elements	Shortcut to get the Elements inside cells in this row.
get_value	Shortcut to get the value of the cell at position “x”. If get_type
get_values	Shortcut to get the cell values in this row.
insert_cell	Insert the given cell at position “x” starting from 0. If no cell is
is_empty	Return whether every cell in the row has no value or the value
iter_cells	Yield as many cell elements as expected cells in the row, i.e.
last_cell	Return the las cell of the row.
minimized_width	Return the length of the row if the last repeated sequence is
rstrip	Remove in-place empty cells at the right of the row. An empty cell
set_cell	Push the cell back in the row at position “x” starting from 0.
set_cells	Set the cells in the row, from the ‘start’ column. This method does
set_value	Shortcut to set the value of the cell at position “x”.
set_values	Shortcut to set the value of cells in the row, from the ‘start’

Attributes:

Name	Type	Description
append
cells	list[Cell]	Get the list of all cells.
clone	Row
repeated	int | None	Get / set the number of times the row is repeated.
style	str | None	Get /set the style of the row itself.
traverse
width	int	Get the number of expected cells in the row, i.e. addition
y

Source code in odfdo/row.py

class Row(Element):
    """A row of a table, "table:table-row"."""

    _tag = "table:table-row"
    _append = Element.append

    def __init__(
        self,
        width: int | None = None,
        repeated: int | None = None,
        style: str | None = None,
        **kwargs: Any,
    ) -> None:
        """Create a Row, "table:table-row", optionally filled with "width"
        number of cells.

        Rows contain cells, their number determine the number of columns.

        You don't generally have to create rows by hand, use the Table API.

        Args:

            width -- int

            repeated -- int

            style -- str
        """
        super().__init__(**kwargs)
        self._table_cache = TableCache()
        self._row_cache = RowCache()
        self.y = None
        self._compute_row_cache()
        if self._do_init:
            if width is not None:
                for _i in range(width):
                    self.append(Cell())
            if repeated:
                self.repeated = repeated
            if style is not None:
                self.style = style
            self._compute_row_cache()

    def __repr__(self) -> str:
        return f"<{self.__class__.__name__} y={self.y}>"

    def get_elements(self, xpath_query: XPath | str) -> list[Element]:
        if isinstance(xpath_query, str):
            elements = xpath_return_elements(
                xpath_compile(xpath_query),
                self._Element__element,  # type: ignore[attr-defined]
            )
        else:
            elements = xpath_return_elements(
                xpath_query,
                self._Element__element,  # type: ignore[attr-defined]
            )
        cache = (self._table_cache, self._row_cache)
        return [Element.from_tag_for_clone(e, cache) for e in elements]

    def _copy_cache(self, cache: tuple) -> None:
        """Copy cache when cloning."""
        self._table_cache = cache[0]
        if cache[1]:  # pragma: no cover
            self._row_cache = cache[1]

    def clear(self) -> None:
        """Remove text, children and attributes from the Row."""
        self._Element__element.clear()  # type: ignore[attr-defined]
        self._table_cache = TableCache()
        self._row_cache = RowCache()

    def _get_cells(self) -> list[Cell]:
        return self.get_elements(_xpath_cell)  # type: ignore[return-value]

    def _translate_row_coordinates(
        self,
        coord: tuple | list | str,
    ) -> tuple[int | None, int | None]:
        xyzt = convert_coordinates(coord)
        if len(xyzt) == 2:
            x, z = xyzt
        else:
            x, _, z, __ = xyzt
        if x and x < 0:
            x = increment(x, self.width)
        if z and z < 0:
            z = increment(z, self.width)
        return (x, z)

    def _compute_row_cache(self) -> None:
        idx_repeated_seq = self.elements_repeated_sequence(
            _xpath_cell, "table:number-columns-repeated"
        )
        self._row_cache.make_cell_map(idx_repeated_seq)

    # Public API

    @property
    def clone(self) -> Row:
        cloned_row: Row = Element.clone.fget(self)  # type: ignore[attr-defined]
        cloned_row.y = self.y
        cloned_row._table_cache = TableCache.copy(self._table_cache)
        cloned_row._row_cache = RowCache.copy(self._row_cache)
        return cloned_row

    def _set_repeated(self, repeated: int | None) -> None:
        """Method Internal only. Set the number of times the row is repeated,
        or None to delete it. Without changing cache.

        Args:

            repeated -- int
        """
        if repeated is None or repeated < 2:
            with contextlib.suppress(KeyError):
                self.del_attribute("table:number-rows-repeated")
            return
        self.set_attribute("table:number-rows-repeated", str(repeated))

    @property
    def repeated(self) -> int | None:
        """Get / set the number of times the row is repeated.

        Always None when using the table API.

        Returns: int or None
        """
        repeated = self.get_attribute("table:number-rows-repeated")
        if repeated is None:
            return None
        return int(repeated)

    @repeated.setter
    def repeated(self, repeated: int | None) -> None:
        self._set_repeated(repeated)
        # update cache
        current: Element = self
        while True:
            # look for Table, parent may be group of rows
            upper = current.parent
            if not upper:
                # lonely row
                return
            # parent may be group of rows, not table
            if isinstance(upper, Element) and upper._tag == "table:table":
                upper._table_cache = self._table_cache  # type: ignore[attr-defined]
                upper._compute_table_cache()  # type: ignore[attr-defined]
                return
            current = upper

    @property
    def style(self) -> str | None:
        """Get /set the style of the row itself.

        Returns: str
        """
        return self.get_attribute_string("table:style-name")

    @style.setter
    def style(self, style: str | Style) -> None:
        self.set_style_attribute("table:style-name", style)

    @property
    def width(self) -> int:
        """Get the number of expected cells in the row, i.e. addition
        repetitions.

        Returns: int
        """
        return self._row_cache.width()

    def _translate_x_from_any(self, x: str | int) -> int:
        return translate_from_any(x, self.width, 0)

    def _yield_odf_cells(self) -> Iterator[Cell]:
        for cell in self._get_cells():
            if cell.repeated is None:
                yield cell
            else:
                for _ in range(cell.repeated):
                    cell_copy = cell.clone
                    cell_copy.repeated = None
                    yield cell_copy

    def iter_cells(
        self,
        start: int | None = None,
        end: int | None = None,
    ) -> Iterator[Cell]:
        """Yield as many cell elements as expected cells in the row, i.e.
        expand repetitions by returning the same cell as many times as
        necessary.

        Copies are returned, use set_cell() to push them back.

            Args:

                start -- int

                end -- int
        """
        if start is None:
            start = 0
        start = max(0, start)
        if end is None:
            end = 2**32
        if end < start:
            return
        x: int = -1
        for cell in self._yield_odf_cells():
            x += 1
            if x < start:
                continue
            if x > end:
                return
            cell.x = x
            cell.y = self.y
            yield cell

    traverse = iter_cells

    def get_cells(
        self,
        coord: str | tuple | None = None,
        style: str | None = None,
        content: str | None = None,
        cell_type: str | None = None,
    ) -> list[Cell]:
        """Get the list of cells matching the criteria.

        Filter by cell_type, with cell_type 'all' will retrieve cells of any
        type, aka non empty cells.

        Filter by coordinates will retrieve the amount of cells defined by
        'coord', minus the other filters.

        Args:

            coord -- str or tuple of int : coordinates

            cell_type -- 'boolean', 'float', 'date', 'string', 'time',
                         'currency', 'percentage' or 'all'

            content -- str regex

            style -- str

        Returns: list of Cell
        """
        # fixme : not clones ?
        if coord:
            x, z = self._translate_row_coordinates(coord)
        else:
            x = None
            z = None
        if cell_type:
            cell_type = cell_type.lower().strip()
        cells: list[Cell] = []
        for cell in self.iter_cells(start=x, end=z):
            # Filter the cells by cell_type
            if cell_type:
                ctype = cell.type
                if not ctype or not (ctype == cell_type or cell_type == "all"):
                    continue
            # Filter the cells with the regex
            if content and not cell.match(content):
                continue
            # Filter the cells with the style
            if style and style != cell.style:
                continue
            cells.append(cell)
        return cells

    @property
    def cells(self) -> list[Cell]:
        """Get the list of all cells.

        Returns: list of Cell
        """
        # fixme : not clones ?
        return list(self.iter_cells())

    def _get_cell2(self, x: int, clone: bool = True) -> Cell | None:
        if x >= self.width:
            return Cell()
        base_cell = self._get_cell2_base(x)
        if base_cell is None:  # pragma: no cover
            return None
        if clone:
            return base_cell.clone
        return base_cell

    def _get_cell2_base(self, x: int) -> Cell | None:
        idx = self._row_cache.cell_idx(x)
        if idx is None:
            return None
        cell: Cell | None = self._row_cache.cached_cell(idx)
        if cell is None:
            cell = self._get_element_idx2(_XP_CELL_IDX, idx)  # type: ignore[assignment]
            if cell is None:  # pragma: no cover
                return None
            self._row_cache.store_cell(cell, idx)
        return cell

    def get_cell(self, x: int, clone: bool = True) -> Cell | None:
        """Get the cell at position "x" starting from 0. Alphabetical positions
        like "D" are accepted.

        A  copy is returned, use set_cell() to push it back.

        Args:

            x -- int or str

        Returns: Cell | None
        """
        x = self._translate_x_from_any(x)
        cell = self._get_cell2(x, clone=clone)
        if not cell:
            return None  # pragma: no cover
        cell.y = self.y
        cell.x = x
        return cell

    def get_value(
        self,
        x: int | str,
        get_type: bool = False,
    ) -> Any | tuple[Any, str]:
        """Shortcut to get the value of the cell at position "x". If get_type
        is True, returns the tuples (value, ODF type).

        If the cell is empty, returns None or (None, None)

        See get_cell() and Cell.get_value().
        """
        if get_type:
            x = self._translate_x_from_any(x)
            cell = self._get_cell2_base(x)
            if cell is None:
                return (None, None)
            return cell.get_value(get_type=get_type)
        x = self._translate_x_from_any(x)
        cell = self._get_cell2_base(x)
        if cell is None:
            return None
        return cell.get_value()

    def set_cell(
        self,
        x: int | str,
        cell: Cell | None = None,
        clone: bool = True,
    ) -> Cell:
        """Push the cell back in the row at position "x" starting from 0.
        Alphabetical positions like "D" are accepted.

        Args:

            x -- int or str

        returns the cell with x and y updated
        """
        cell_back: Cell
        if cell is None:
            cell = Cell()
            repeated = 1
            clone = False
        else:
            repeated = cell.repeated or 1
        x = self._translate_x_from_any(x)
        # Outside the defined row
        diff = x - self.width
        if diff == 0:
            cell_back = self.append_cell(cell, _repeated=repeated, clone=clone)
        elif diff > 0:
            self.append_cell(Cell(repeated=diff), _repeated=diff, clone=False)
            cell_back = self.append_cell(cell, _repeated=repeated, clone=clone)
        else:
            # Inside the defined row
            cell_back = self._row_cache.set_cell_in_cache(x, cell, self, clone=clone)
            cell_back.x = x
            cell_back.y = self.y
        return cell_back

    def set_value(
        self,
        x: int | str,
        value: Any,
        style: str | None = None,
        cell_type: str | None = None,
        currency: str | None = None,
    ) -> None:
        """Shortcut to set the value of the cell at position "x".

        Args:

            x -- int or str

            value -- Python type

            cell_type -- 'boolean', 'currency', 'date', 'float', 'percentage',
                     'string' or 'time'

            currency -- three-letter str

            style -- str

        See get_cell() and Cell.get_value().
        """
        self.set_cell(
            x,
            Cell(value, style=style, cell_type=cell_type, currency=currency),
            clone=False,
        )

    def insert_cell(
        self,
        x: int | str,
        cell: Cell | None = None,
        clone: bool = True,
    ) -> Cell:
        """Insert the given cell at position "x" starting from 0. If no cell is
        given, an empty one is created.

        Alphabetical positions like "D" are accepted.

        Do not use when working on a table, use Table.insert_cell().

        Args:

            x -- int or str

            cell -- Cell

        returns the cell with x and y updated
        """
        cell_back: Cell
        if cell is None:
            cell = Cell()
        x = self._translate_x_from_any(x)
        # Outside the defined row
        diff = x - self.width
        if diff < 0:
            cell_back = self._row_cache.insert_cell_in_cache(x, cell, self)
            cell_back.x = x
            cell_back.y = self.y
        elif diff == 0:
            cell_back = self.append_cell(cell, clone=clone)
        else:
            self.append_cell(Cell(repeated=diff), _repeated=diff, clone=False)
            cell_back = self.append_cell(cell, clone=clone)
        return cell_back

    def extend_cells(self, cells: Iterable[Cell] | None = None) -> None:
        if cells is None:
            cells = []
        self.extend(cells)
        self._compute_row_cache()

    def append_cell(
        self,
        cell: Cell | None = None,
        clone: bool = True,
        _repeated: int | None = None,
    ) -> Cell:
        """Append the given cell at the end of the row. Repeated cells are
        accepted. If no cell is given, an empty one is created.

        Do not use when working on a table, use Table.append_cell().

        Args:

            cell -- Cell

            _repeated -- (optional), repeated value of the row

        returns the cell with x and y updated
        """
        if cell is None:
            cell = Cell()
            clone = False
        if clone:
            cell = cell.clone
        self._append(cell)
        if _repeated is None:
            _repeated = cell.repeated or 1
        self._row_cache.insert_cell_map_once(_repeated)
        cell.x = self.width - 1
        cell.y = self.y
        return cell

    # fix for unit test and typos
    append = append_cell  # type:ignore[assignment]

    def delete_cell(self, x: int | str) -> None:
        """Delete the cell at the given position "x" starting from 0.
        Alphabetical positions like "D" are accepted.

        Cells on the right will be shifted to the left. In a table, other
        rows remain unaffected.

        Args:

            x -- int or str
        """
        x = self._translate_x_from_any(x)
        if x >= self.width:
            return
        self._row_cache.delete_cell_in_cache(x, self)

    def get_values(
        self,
        coord: str | tuple | None = None,
        cell_type: str | None = None,
        complete: bool = False,
        get_type: bool = False,
    ) -> list[Any | tuple[Any, Any]]:
        """Shortcut to get the cell values in this row.

        Filter by cell_type, with cell_type 'all' will retrieve cells of any
        type, aka non empty cells.
        If cell_type is used and complete is True, missing values are
        replaced by None.
        If cell_type is None, complete is always True : with no cell type
        queried, get_values() returns None for each empty cell, the length
        of the list is equal to the length of the row (depending on
        coordinates use).

        If get_type is True, returns a tuple (value, ODF type of value), or
        (None, None) for empty cells if complete is True.

        Filter by coordinates will retrieve the amount of cells defined by
        coordinates with None for empty cells, except when using cell_type.


        Args:

            coord -- str or tuple of int : coordinates in row

            cell_type -- 'boolean', 'float', 'date', 'string', 'time',
                         'currency', 'percentage' or 'all'

            complete -- boolean

            get_type -- boolean

        Returns: list of Python types, or list of tuples.
        """
        if coord:
            x, z = self._translate_row_coordinates(coord)
        else:
            x = None
            z = None
        if cell_type:
            cell_type = cell_type.lower().strip()
            values: list[Any | tuple[Any, Any]] = []
            for cell in self.iter_cells(start=x, end=z):
                # Filter the cells by cell_type
                ctype = cell.type
                if not ctype or not (ctype == cell_type or cell_type == "all"):
                    if complete:
                        if get_type:
                            values.append((None, None))
                        else:
                            values.append(None)
                    continue
                values.append(cell.get_value(get_type=get_type))
            return values
        else:
            return [
                cell.get_value(get_type=get_type)
                for cell in self.iter_cells(start=x, end=z)
            ]

    def get_sub_elements(
        self,
    ) -> list[Any]:
        """Shortcut to get the Elements inside cells in this row.

        Missing values are replaced by None. Cell type should be always
        'string' when using this method, the length of the list is equal
        to the length of the row.

        Returns: list of Elements.
        """
        return [cell.children for cell in self.iter_cells()]

    def set_cells(
        self,
        cells: list[Cell] | tuple[Cell] | None = None,
        start: int | str = 0,
        clone: bool = True,
    ) -> None:
        """Set the cells in the row, from the 'start' column. This method does
        not clear the row, use row.clear() before to start with an empty row.

        Args:

            cells -- list of cells

            start -- int or str
        """
        if cells is None:
            cells = []
        if start is None:
            start = 0
        else:
            start = self._translate_x_from_any(start)
        if start == 0 and clone is False and (len(cells) >= self.width):
            self.clear()
            self.extend_cells(cells)
        else:
            x = start
            for cell in cells:
                self.set_cell(x, cell, clone=clone)
                if cell:
                    x += cell.repeated or 1
                else:
                    x += 1

    def set_values(
        self,
        values: list[Any],
        start: int | str = 0,
        style: str | None = None,
        cell_type: str | None = None,
        currency: str | None = None,
    ) -> None:
        """Shortcut to set the value of cells in the row, from the 'start'
        column with values. This method does not clear the row, use row.clear()
        before to start with an empty row.

        Args:

            values -- list of Python types

            start -- int or str

            cell_type -- 'boolean', 'float', 'date', 'string', 'time',
                         'currency' or 'percentage'

            currency -- three-letter str

            style -- cell style
        """
        # fixme : if values n, n+ are same, use repeat
        if start is None:
            start = 0
        else:
            start = self._translate_x_from_any(start)
        if start == 0 and (len(values) >= self.width):
            self.clear()
            cells = [
                Cell(value, style=style, cell_type=cell_type, currency=currency)
                for value in values
            ]
            self.extend_cells(cells)
        else:
            x = start
            for value in values:
                self.set_cell(
                    x,
                    Cell(value, style=style, cell_type=cell_type, currency=currency),
                    clone=False,
                )
                x += 1

    def rstrip(self, aggressive: bool = False) -> None:
        """Remove *in-place* empty cells at the right of the row. An empty cell
        has no value but can have style. If "aggressive" is True, style is
        ignored.

        Args:

            aggressive -- bool
        """
        for cell in reversed(self._get_cells()):
            if not cell.is_empty(aggressive=aggressive):
                break
            self.delete(cell)
        self._compute_row_cache()
        self._row_cache.clear_cell_indexes()

    def _current_length(self) -> int:
        """Return the current estimated length of the row.

        Returns: int
        """
        idx_repeated_seq = self.elements_repeated_sequence(
            _xpath_cell, "table:number-columns-repeated"
        )
        repeated = [item[1] for item in idx_repeated_seq]
        if repeated:
            return sum(repeated)
        return 1

    def minimized_width(self) -> int:
        """Return the length of the row if the last repeated sequence is
        reduced to one.

        Returns: int
        """
        idx_repeated_seq = self.elements_repeated_sequence(
            _xpath_cell, "table:number-columns-repeated"
        )
        repeated = [item[1] for item in idx_repeated_seq]
        if repeated:
            cell = self.last_cell()
            if cell is not None and cell.is_empty(aggressive=True):
                repeated[-1] = 1
            min_width = sum(repeated)
        else:
            min_width = 1
        self._compute_row_cache()
        self._row_cache.clear_cell_indexes()
        return min_width

    def last_cell(self) -> Cell | None:
        """Return the las cell of the row.

        Return Cell | None
        """
        try:
            return self._get_cells()[-1]
        except IndexError:
            return None

    def force_width(self, width: int) -> None:
        """Change the repeated property of the last cell of the row to comply
        with the required max width.

        Args:

            width -- int
        """
        cell = self.last_cell()
        if cell is None or not cell.is_empty(aggressive=True):
            return
        repeated = cell.repeated
        if repeated is None:
            return
        # empty repeated cell
        delta = self._current_length() - width
        if delta > 0:
            cell._set_repeated(repeated - delta)
            self._compute_row_cache()

    def is_empty(self, aggressive: bool = False) -> bool:
        """Return whether every cell in the row has no value or the value
        evaluates to False (empty string), and no style.

        If aggressive is True, empty cells with style are considered empty.

        Args:

            aggressive -- bool

        Returns: bool
        """
        return all(cell.is_empty(aggressive=aggressive) for cell in self._get_cells())

append class-attribute instance-attribute

append = append_cell

cells property

cells: list[Cell]

Get the list of all cells.

Returns: list of Cell

clone property

clone: Row

repeated property writable

repeated: int | None

Get / set the number of times the row is repeated.

Always None when using the table API.

Returns: int or None

style property writable

style: str | None

Get /set the style of the row itself.

Returns: str

traverse class-attribute instance-attribute

traverse = iter_cells

width property

width: int

Get the number of expected cells in the row, i.e. addition repetitions.

Returns: int

y instance-attribute

y = None

__init__

__init__(
    width: int | None = None,
    repeated: int | None = None,
    style: str | None = None,
    **kwargs: Any,
) -> None

Create a Row, “table:table-row”, optionally filled with “width” number of cells.

Rows contain cells, their number determine the number of columns.

You don’t generally have to create rows by hand, use the Table API.

Args:

width -- int

repeated -- int

style -- str

Source code in odfdo/row.py

def __init__(
    self,
    width: int | None = None,
    repeated: int | None = None,
    style: str | None = None,
    **kwargs: Any,
) -> None:
    """Create a Row, "table:table-row", optionally filled with "width"
    number of cells.

    Rows contain cells, their number determine the number of columns.

    You don't generally have to create rows by hand, use the Table API.

    Args:

        width -- int

        repeated -- int

        style -- str
    """
    super().__init__(**kwargs)
    self._table_cache = TableCache()
    self._row_cache = RowCache()
    self.y = None
    self._compute_row_cache()
    if self._do_init:
        if width is not None:
            for _i in range(width):
                self.append(Cell())
        if repeated:
            self.repeated = repeated
        if style is not None:
            self.style = style
        self._compute_row_cache()

append_cell

append_cell(
    cell: Cell | None = None,
    clone: bool = True,
    _repeated: int | None = None,
) -> Cell

Append the given cell at the end of the row. Repeated cells are accepted. If no cell is given, an empty one is created.

Do not use when working on a table, use Table.append_cell().

Args:

cell -- Cell

_repeated -- (optional), repeated value of the row

returns the cell with x and y updated

Source code in odfdo/row.py

def append_cell(
    self,
    cell: Cell | None = None,
    clone: bool = True,
    _repeated: int | None = None,
) -> Cell:
    """Append the given cell at the end of the row. Repeated cells are
    accepted. If no cell is given, an empty one is created.

    Do not use when working on a table, use Table.append_cell().

    Args:

        cell -- Cell

        _repeated -- (optional), repeated value of the row

    returns the cell with x and y updated
    """
    if cell is None:
        cell = Cell()
        clone = False
    if clone:
        cell = cell.clone
    self._append(cell)
    if _repeated is None:
        _repeated = cell.repeated or 1
    self._row_cache.insert_cell_map_once(_repeated)
    cell.x = self.width - 1
    cell.y = self.y
    return cell

clear

clear() -> None

Remove text, children and attributes from the Row.

Source code in odfdo/row.py

def clear(self) -> None:
    """Remove text, children and attributes from the Row."""
    self._Element__element.clear()  # type: ignore[attr-defined]
    self._table_cache = TableCache()
    self._row_cache = RowCache()

delete_cell

delete_cell(x: int | str) -> None

Delete the cell at the given position “x” starting from 0. Alphabetical positions like “D” are accepted.

Cells on the right will be shifted to the left. In a table, other rows remain unaffected.

Args:

x -- int or str

Source code in odfdo/row.py

def delete_cell(self, x: int | str) -> None:
    """Delete the cell at the given position "x" starting from 0.
    Alphabetical positions like "D" are accepted.

    Cells on the right will be shifted to the left. In a table, other
    rows remain unaffected.

    Args:

        x -- int or str
    """
    x = self._translate_x_from_any(x)
    if x >= self.width:
        return
    self._row_cache.delete_cell_in_cache(x, self)

extend_cells

extend_cells(cells: Iterable[Cell] | None = None) -> None

Source code in odfdo/row.py

def extend_cells(self, cells: Iterable[Cell] | None = None) -> None:
    if cells is None:
        cells = []
    self.extend(cells)
    self._compute_row_cache()

force_width

force_width(width: int) -> None

Change the repeated property of the last cell of the row to comply with the required max width.

Args:

width -- int

Source code in odfdo/row.py

def force_width(self, width: int) -> None:
    """Change the repeated property of the last cell of the row to comply
    with the required max width.

    Args:

        width -- int
    """
    cell = self.last_cell()
    if cell is None or not cell.is_empty(aggressive=True):
        return
    repeated = cell.repeated
    if repeated is None:
        return
    # empty repeated cell
    delta = self._current_length() - width
    if delta > 0:
        cell._set_repeated(repeated - delta)
        self._compute_row_cache()

get_cell

get_cell(x: int, clone: bool = True) -> Cell | None

Get the cell at position “x” starting from 0. Alphabetical positions like “D” are accepted.

A copy is returned, use set_cell() to push it back.

Args:

x -- int or str

Returns: Cell | None

Source code in odfdo/row.py

def get_cell(self, x: int, clone: bool = True) -> Cell | None:
    """Get the cell at position "x" starting from 0. Alphabetical positions
    like "D" are accepted.

    A  copy is returned, use set_cell() to push it back.

    Args:

        x -- int or str

    Returns: Cell | None
    """
    x = self._translate_x_from_any(x)
    cell = self._get_cell2(x, clone=clone)
    if not cell:
        return None  # pragma: no cover
    cell.y = self.y
    cell.x = x
    return cell

get_cells

get_cells(
    coord: str | tuple | None = None,
    style: str | None = None,
    content: str | None = None,
    cell_type: str | None = None,
) -> list[Cell]

Get the list of cells matching the criteria.

Filter by cell_type, with cell_type ‘all’ will retrieve cells of any type, aka non empty cells.

Filter by coordinates will retrieve the amount of cells defined by ‘coord’, minus the other filters.

Args:

coord -- str or tuple of int : coordinates

cell_type -- 'boolean', 'float', 'date', 'string', 'time',
             'currency', 'percentage' or 'all'

content -- str regex

style -- str

Returns: list of Cell

Source code in odfdo/row.py

def get_cells(
    self,
    coord: str | tuple | None = None,
    style: str | None = None,
    content: str | None = None,
    cell_type: str | None = None,
) -> list[Cell]:
    """Get the list of cells matching the criteria.

    Filter by cell_type, with cell_type 'all' will retrieve cells of any
    type, aka non empty cells.

    Filter by coordinates will retrieve the amount of cells defined by
    'coord', minus the other filters.

    Args:

        coord -- str or tuple of int : coordinates

        cell_type -- 'boolean', 'float', 'date', 'string', 'time',
                     'currency', 'percentage' or 'all'

        content -- str regex

        style -- str

    Returns: list of Cell
    """
    # fixme : not clones ?
    if coord:
        x, z = self._translate_row_coordinates(coord)
    else:
        x = None
        z = None
    if cell_type:
        cell_type = cell_type.lower().strip()
    cells: list[Cell] = []
    for cell in self.iter_cells(start=x, end=z):
        # Filter the cells by cell_type
        if cell_type:
            ctype = cell.type
            if not ctype or not (ctype == cell_type or cell_type == "all"):
                continue
        # Filter the cells with the regex
        if content and not cell.match(content):
            continue
        # Filter the cells with the style
        if style and style != cell.style:
            continue
        cells.append(cell)
    return cells

get_elements

get_elements(xpath_query: XPath | str) -> list[Element]

Source code in odfdo/row.py

def get_elements(self, xpath_query: XPath | str) -> list[Element]:
    if isinstance(xpath_query, str):
        elements = xpath_return_elements(
            xpath_compile(xpath_query),
            self._Element__element,  # type: ignore[attr-defined]
        )
    else:
        elements = xpath_return_elements(
            xpath_query,
            self._Element__element,  # type: ignore[attr-defined]
        )
    cache = (self._table_cache, self._row_cache)
    return [Element.from_tag_for_clone(e, cache) for e in elements]

get_sub_elements

get_sub_elements() -> list[Any]

Shortcut to get the Elements inside cells in this row.

Missing values are replaced by None. Cell type should be always ‘string’ when using this method, the length of the list is equal to the length of the row.

Returns: list of Elements.

Source code in odfdo/row.py

def get_sub_elements(
    self,
) -> list[Any]:
    """Shortcut to get the Elements inside cells in this row.

    Missing values are replaced by None. Cell type should be always
    'string' when using this method, the length of the list is equal
    to the length of the row.

    Returns: list of Elements.
    """
    return [cell.children for cell in self.iter_cells()]

get_value

get_value(
    x: int | str, get_type: bool = False
) -> Any | tuple[Any, str]

Shortcut to get the value of the cell at position “x”. If get_type is True, returns the tuples (value, ODF type).

If the cell is empty, returns None or (None, None)

See get_cell() and Cell.get_value().

Source code in odfdo/row.py

def get_value(
    self,
    x: int | str,
    get_type: bool = False,
) -> Any | tuple[Any, str]:
    """Shortcut to get the value of the cell at position "x". If get_type
    is True, returns the tuples (value, ODF type).

    If the cell is empty, returns None or (None, None)

    See get_cell() and Cell.get_value().
    """
    if get_type:
        x = self._translate_x_from_any(x)
        cell = self._get_cell2_base(x)
        if cell is None:
            return (None, None)
        return cell.get_value(get_type=get_type)
    x = self._translate_x_from_any(x)
    cell = self._get_cell2_base(x)
    if cell is None:
        return None
    return cell.get_value()

get_values

get_values(
    coord: str | tuple | None = None,
    cell_type: str | None = None,
    complete: bool = False,
    get_type: bool = False,
) -> list[Any | tuple[Any, Any]]

Shortcut to get the cell values in this row.

Filter by cell_type, with cell_type ‘all’ will retrieve cells of any type, aka non empty cells. If cell_type is used and complete is True, missing values are replaced by None. If cell_type is None, complete is always True : with no cell type queried, get_values() returns None for each empty cell, the length of the list is equal to the length of the row (depending on coordinates use).

If get_type is True, returns a tuple (value, ODF type of value), or (None, None) for empty cells if complete is True.

Filter by coordinates will retrieve the amount of cells defined by coordinates with None for empty cells, except when using cell_type.

Args:

coord -- str or tuple of int : coordinates in row

cell_type -- 'boolean', 'float', 'date', 'string', 'time',
             'currency', 'percentage' or 'all'

complete -- boolean

get_type -- boolean

Returns: list of Python types, or list of tuples.

Source code in odfdo/row.py

def get_values(
    self,
    coord: str | tuple | None = None,
    cell_type: str | None = None,
    complete: bool = False,
    get_type: bool = False,
) -> list[Any | tuple[Any, Any]]:
    """Shortcut to get the cell values in this row.

    Filter by cell_type, with cell_type 'all' will retrieve cells of any
    type, aka non empty cells.
    If cell_type is used and complete is True, missing values are
    replaced by None.
    If cell_type is None, complete is always True : with no cell type
    queried, get_values() returns None for each empty cell, the length
    of the list is equal to the length of the row (depending on
    coordinates use).

    If get_type is True, returns a tuple (value, ODF type of value), or
    (None, None) for empty cells if complete is True.

    Filter by coordinates will retrieve the amount of cells defined by
    coordinates with None for empty cells, except when using cell_type.


    Args:

        coord -- str or tuple of int : coordinates in row

        cell_type -- 'boolean', 'float', 'date', 'string', 'time',
                     'currency', 'percentage' or 'all'

        complete -- boolean

        get_type -- boolean

    Returns: list of Python types, or list of tuples.
    """
    if coord:
        x, z = self._translate_row_coordinates(coord)
    else:
        x = None
        z = None
    if cell_type:
        cell_type = cell_type.lower().strip()
        values: list[Any | tuple[Any, Any]] = []
        for cell in self.iter_cells(start=x, end=z):
            # Filter the cells by cell_type
            ctype = cell.type
            if not ctype or not (ctype == cell_type or cell_type == "all"):
                if complete:
                    if get_type:
                        values.append((None, None))
                    else:
                        values.append(None)
                continue
            values.append(cell.get_value(get_type=get_type))
        return values
    else:
        return [
            cell.get_value(get_type=get_type)
            for cell in self.iter_cells(start=x, end=z)
        ]

insert_cell

insert_cell(
    x: int | str,
    cell: Cell | None = None,
    clone: bool = True,
) -> Cell

Insert the given cell at position “x” starting from 0. If no cell is given, an empty one is created.

Alphabetical positions like “D” are accepted.

Do not use when working on a table, use Table.insert_cell().

Args:

x -- int or str

cell -- Cell

returns the cell with x and y updated

Source code in odfdo/row.py

def insert_cell(
    self,
    x: int | str,
    cell: Cell | None = None,
    clone: bool = True,
) -> Cell:
    """Insert the given cell at position "x" starting from 0. If no cell is
    given, an empty one is created.

    Alphabetical positions like "D" are accepted.

    Do not use when working on a table, use Table.insert_cell().

    Args:

        x -- int or str

        cell -- Cell

    returns the cell with x and y updated
    """
    cell_back: Cell
    if cell is None:
        cell = Cell()
    x = self._translate_x_from_any(x)
    # Outside the defined row
    diff = x - self.width
    if diff < 0:
        cell_back = self._row_cache.insert_cell_in_cache(x, cell, self)
        cell_back.x = x
        cell_back.y = self.y
    elif diff == 0:
        cell_back = self.append_cell(cell, clone=clone)
    else:
        self.append_cell(Cell(repeated=diff), _repeated=diff, clone=False)
        cell_back = self.append_cell(cell, clone=clone)
    return cell_back

is_empty

is_empty(aggressive: bool = False) -> bool

Return whether every cell in the row has no value or the value evaluates to False (empty string), and no style.

If aggressive is True, empty cells with style are considered empty.

Args:

aggressive -- bool

Returns: bool

Source code in odfdo/row.py

def is_empty(self, aggressive: bool = False) -> bool:
    """Return whether every cell in the row has no value or the value
    evaluates to False (empty string), and no style.

    If aggressive is True, empty cells with style are considered empty.

    Args:

        aggressive -- bool

    Returns: bool
    """
    return all(cell.is_empty(aggressive=aggressive) for cell in self._get_cells())

iter_cells

iter_cells(
    start: int | None = None, end: int | None = None
) -> Iterator[Cell]

Yield as many cell elements as expected cells in the row, i.e. expand repetitions by returning the same cell as many times as necessary.

Copies are returned, use set_cell() to push them back.

Args:

    start -- int

    end -- int

Source code in odfdo/row.py

def iter_cells(
    self,
    start: int | None = None,
    end: int | None = None,
) -> Iterator[Cell]:
    """Yield as many cell elements as expected cells in the row, i.e.
    expand repetitions by returning the same cell as many times as
    necessary.

    Copies are returned, use set_cell() to push them back.

        Args:

            start -- int

            end -- int
    """
    if start is None:
        start = 0
    start = max(0, start)
    if end is None:
        end = 2**32
    if end < start:
        return
    x: int = -1
    for cell in self._yield_odf_cells():
        x += 1
        if x < start:
            continue
        if x > end:
            return
        cell.x = x
        cell.y = self.y
        yield cell

last_cell

last_cell() -> Cell | None

Return the las cell of the row.

Return Cell | None

Source code in odfdo/row.py

def last_cell(self) -> Cell | None:
    """Return the las cell of the row.

    Return Cell | None
    """
    try:
        return self._get_cells()[-1]
    except IndexError:
        return None

minimized_width

minimized_width() -> int

Return the length of the row if the last repeated sequence is reduced to one.

Returns: int

Source code in odfdo/row.py

def minimized_width(self) -> int:
    """Return the length of the row if the last repeated sequence is
    reduced to one.

    Returns: int
    """
    idx_repeated_seq = self.elements_repeated_sequence(
        _xpath_cell, "table:number-columns-repeated"
    )
    repeated = [item[1] for item in idx_repeated_seq]
    if repeated:
        cell = self.last_cell()
        if cell is not None and cell.is_empty(aggressive=True):
            repeated[-1] = 1
        min_width = sum(repeated)
    else:
        min_width = 1
    self._compute_row_cache()
    self._row_cache.clear_cell_indexes()
    return min_width

rstrip

rstrip(aggressive: bool = False) -> None

Remove in-place empty cells at the right of the row. An empty cell has no value but can have style. If “aggressive” is True, style is ignored.

Args:

aggressive -- bool

Source code in odfdo/row.py

def rstrip(self, aggressive: bool = False) -> None:
    """Remove *in-place* empty cells at the right of the row. An empty cell
    has no value but can have style. If "aggressive" is True, style is
    ignored.

    Args:

        aggressive -- bool
    """
    for cell in reversed(self._get_cells()):
        if not cell.is_empty(aggressive=aggressive):
            break
        self.delete(cell)
    self._compute_row_cache()
    self._row_cache.clear_cell_indexes()

set_cell

set_cell(
    x: int | str,
    cell: Cell | None = None,
    clone: bool = True,
) -> Cell

Push the cell back in the row at position “x” starting from 0. Alphabetical positions like “D” are accepted.

Args:

x -- int or str

returns the cell with x and y updated

Source code in odfdo/row.py

def set_cell(
    self,
    x: int | str,
    cell: Cell | None = None,
    clone: bool = True,
) -> Cell:
    """Push the cell back in the row at position "x" starting from 0.
    Alphabetical positions like "D" are accepted.

    Args:

        x -- int or str

    returns the cell with x and y updated
    """
    cell_back: Cell
    if cell is None:
        cell = Cell()
        repeated = 1
        clone = False
    else:
        repeated = cell.repeated or 1
    x = self._translate_x_from_any(x)
    # Outside the defined row
    diff = x - self.width
    if diff == 0:
        cell_back = self.append_cell(cell, _repeated=repeated, clone=clone)
    elif diff > 0:
        self.append_cell(Cell(repeated=diff), _repeated=diff, clone=False)
        cell_back = self.append_cell(cell, _repeated=repeated, clone=clone)
    else:
        # Inside the defined row
        cell_back = self._row_cache.set_cell_in_cache(x, cell, self, clone=clone)
        cell_back.x = x
        cell_back.y = self.y
    return cell_back

set_cells

set_cells(
    cells: list[Cell] | tuple[Cell] | None = None,
    start: int | str = 0,
    clone: bool = True,
) -> None

Set the cells in the row, from the ‘start’ column. This method does not clear the row, use row.clear() before to start with an empty row.

Args:

cells -- list of cells

start -- int or str

Source code in odfdo/row.py

def set_cells(
    self,
    cells: list[Cell] | tuple[Cell] | None = None,
    start: int | str = 0,
    clone: bool = True,
) -> None:
    """Set the cells in the row, from the 'start' column. This method does
    not clear the row, use row.clear() before to start with an empty row.

    Args:

        cells -- list of cells

        start -- int or str
    """
    if cells is None:
        cells = []
    if start is None:
        start = 0
    else:
        start = self._translate_x_from_any(start)
    if start == 0 and clone is False and (len(cells) >= self.width):
        self.clear()
        self.extend_cells(cells)
    else:
        x = start
        for cell in cells:
            self.set_cell(x, cell, clone=clone)
            if cell:
                x += cell.repeated or 1
            else:
                x += 1

set_value

set_value(
    x: int | str,
    value: Any,
    style: str | None = None,
    cell_type: str | None = None,
    currency: str | None = None,
) -> None

Shortcut to set the value of the cell at position “x”.

Args:

x -- int or str

value -- Python type

cell_type -- 'boolean', 'currency', 'date', 'float', 'percentage',
         'string' or 'time'

currency -- three-letter str

style -- str

See get_cell() and Cell.get_value().

Source code in odfdo/row.py

def set_value(
    self,
    x: int | str,
    value: Any,
    style: str | None = None,
    cell_type: str | None = None,
    currency: str | None = None,
) -> None:
    """Shortcut to set the value of the cell at position "x".

    Args:

        x -- int or str

        value -- Python type

        cell_type -- 'boolean', 'currency', 'date', 'float', 'percentage',
                 'string' or 'time'

        currency -- three-letter str

        style -- str

    See get_cell() and Cell.get_value().
    """
    self.set_cell(
        x,
        Cell(value, style=style, cell_type=cell_type, currency=currency),
        clone=False,
    )

set_values

set_values(
    values: list[Any],
    start: int | str = 0,
    style: str | None = None,
    cell_type: str | None = None,
    currency: str | None = None,
) -> None

Shortcut to set the value of cells in the row, from the ‘start’ column with values. This method does not clear the row, use row.clear() before to start with an empty row.

Args:

values -- list of Python types

start -- int or str

cell_type -- 'boolean', 'float', 'date', 'string', 'time',
             'currency' or 'percentage'

currency -- three-letter str

style -- cell style

Source code in odfdo/row.py

def set_values(
    self,
    values: list[Any],
    start: int | str = 0,
    style: str | None = None,
    cell_type: str | None = None,
    currency: str | None = None,
) -> None:
    """Shortcut to set the value of cells in the row, from the 'start'
    column with values. This method does not clear the row, use row.clear()
    before to start with an empty row.

    Args:

        values -- list of Python types

        start -- int or str

        cell_type -- 'boolean', 'float', 'date', 'string', 'time',
                     'currency' or 'percentage'

        currency -- three-letter str

        style -- cell style
    """
    # fixme : if values n, n+ are same, use repeat
    if start is None:
        start = 0
    else:
        start = self._translate_x_from_any(start)
    if start == 0 and (len(values) >= self.width):
        self.clear()
        cells = [
            Cell(value, style=style, cell_type=cell_type, currency=currency)
            for value in values
        ]
        self.extend_cells(cells)
    else:
        x = start
        for value in values:
            self.set_cell(
                x,
                Cell(value, style=style, cell_type=cell_type, currency=currency),
                clone=False,
            )
            x += 1

RowGroup

Bases: Element

A group of rows with common properties, “table:table-row-group”.

Partial implementation.

The “table:table-row-group” element groups adjacent table rows. Every row group can contain header rows, and nested row groups. A row group can be visible or hidden.

Methods:

Name	Description
__init__	Create a group of rows, “table:table-row-group”, optionally filled

Source code in odfdo/row_group.py

class RowGroup(Element):
    """A group of rows  with common properties, "table:table-row-group".

    Partial implementation.

    The "table:table-row-group" element groups adjacent table rows. Every row
    group can contain header rows, and nested row groups. A row group can be
    visible or hidden.
    """

    # TODO
    _tag = "table:table-row-group"

    def __init__(
        self,
        height: int | None = None,
        width: int | None = None,
        **kwargs: Any,
    ) -> None:
        """Create a group of rows, "table:table-row-group", optionally filled
        with "height" number of rows, of "width" cells each.

        Row group bear style information applied to a series of rows.

        Args:

            height -- int

            width -- int
        """
        super().__init__(**kwargs)
        if self._do_init and height is not None:
            for _i in range(height):
                row = Row(width=width)
                self.append(row)

    def __repr__(self) -> str:
        return f"<{self.__class__.__name__}>"

__init__

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

Create a group of rows, “table:table-row-group”, optionally filled with “height” number of rows, of “width” cells each.

Row group bear style information applied to a series of rows.

Args:

height -- int

width -- int

Source code in odfdo/row_group.py

def __init__(
    self,
    height: int | None = None,
    width: int | None = None,
    **kwargs: Any,
) -> None:
    """Create a group of rows, "table:table-row-group", optionally filled
    with "height" number of rows, of "width" cells each.

    Row group bear style information applied to a series of rows.

    Args:

        height -- int

        width -- int
    """
    super().__init__(**kwargs)
    if self._do_init and height is not None:
        for _i in range(height):
            row = Row(width=width)
            self.append(row)

Section

Bases: Element

Section of the text document, “text:section”.

Methods:

Name	Description
__init__	Section of the text document, “text:section”.
get_formatted_text

Attributes:

Name	Type	Description
name
style

Source code in odfdo/section.py

class Section(Element):
    """Section of the text document, "text:section"."""

    _tag = "text:section"
    _properties = (
        PropDef("style", "text:style-name"),
        PropDef("name", "text:name"),
    )

    def __init__(
        self,
        style: str | None = None,
        name: str | None = None,
        **kwargs: Any,
    ) -> None:
        """Section of the text document, "text:section".

        Args:

            style -- str

            name -- str
        """
        super().__init__(**kwargs)
        if self._do_init:
            if style:
                self.style = style
            if name:
                self.name = name

    def get_formatted_text(self, context: dict | None = None) -> str:
        result = [element.get_formatted_text(context) for element in self.children]
        result.append("\n")
        return "".join(result)

name instance-attribute

name = name

style instance-attribute

style = style

__init__

__init__(
    style: str | None = None,
    name: str | None = None,
    **kwargs: Any,
) -> None

Section of the text document, “text:section”.

Args:

style -- str

name -- str

Source code in odfdo/section.py

def __init__(
    self,
    style: str | None = None,
    name: str | None = None,
    **kwargs: Any,
) -> None:
    """Section of the text document, "text:section".

    Args:

        style -- str

        name -- str
    """
    super().__init__(**kwargs)
    if self._do_init:
        if style:
            self.style = style
        if name:
            self.name = name

get_formatted_text

get_formatted_text(context: dict | None = None) -> str

Source code in odfdo/section.py

def get_formatted_text(self, context: dict | None = None) -> str:
    result = [element.get_formatted_text(context) for element in self.children]
    result.append("\n")
    return "".join(result)

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. Note: It is not an error if the character preceding the element is not a white space character, but it is good practice to use this element only for the second and all following SPACE characters in a sequence.

Methods:

Name	Description
__init__	Representation of several spaces, “text:s”.

Attributes:

Name	Type	Description
length	int
number	str | None
text	str	Get / set the string (spaces).

Source code in odfdo/spacer.py

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.
    Note: It is not an error if the character preceding the element is not a
    white space character, but it is good practice to use this element only for
    the second and all following SPACE characters in a sequence.
    """

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

    def __init__(self, number: int | None = 1, **kwargs: Any) -> None:
        """Representation of several spaces, "text:s".

        Args:

            number -- int
        """
        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 / set the string (spaces)."""
        return " " * self.length

    @text.setter
    def text(self, text: str | None) -> None:
        if text is None:
            text = ""
        self.length = len(text)

    @property
    def length(self) -> int:
        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:
        if value is None or int(value) < 2:
            self._base_attrib_setter("text:c", None)
        else:
            self._base_attrib_setter("text:c", int(value))

length property writable

length: int

number instance-attribute

number: str | None = str(number)

text property writable

text: str

Get / set the string (spaces).

__init__

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

Representation of several spaces, “text:s”.

Args:

number -- int

Source code in odfdo/spacer.py

def __init__(self, number: int | None = 1, **kwargs: Any) -> None:
    """Representation of several spaces, "text:s".

    Args:

        number -- int
    """
    super().__init__(**kwargs)
    if self._do_init:
        if number and number >= 2:
            self.number: str | None = str(number)
        else:
            self.number = None

Span

Bases: MDSpan, MDParagraph, ParaFormattedTextMixin, ParaMixin, Element

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

Methods:

Name	Description
__init__	Create a span element “text:span” of the given style containing the

Attributes:

Name	Type	Description
style
text

Source code in odfdo/span.py

class Span(MDSpan, MDParagraph, ParaFormattedTextMixin, ParaMixin, Element):
    """A span tag (syled text in paragraph), "text:span"."""

    _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 -- str

            style -- str

            formatted -- bool
        """
        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

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.

Args:

text -- str

style -- str

formatted -- bool

Source code in odfdo/span.py

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

        style -- str

        formatted -- bool
    """
    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

Spreadsheet

Bases: NRMixin, Body

Root of the Spreadsheet document content, “office:spreadsheet”.

Source code in odfdo/body.py

class Spreadsheet(NRMixin, Body):
    """Root of the Spreadsheet document content, "office:spreadsheet"."""

    _tag: str = "office:spreadsheet"
    _properties: tuple[PropDef, ...] = ()

Style

Bases: StyleProps

Style class for many ODF tags, “style:style”, “number:date-style”,…

Partial list: “style:style”, “number:date-style”, “number:number-style”, “number:percentage-style”, “number:time-style”, “style:font-face”, “style:page-layout”, “style:presentation-page-layout”, “text:list-style”, “text:outline-style”, “style:tab-stops” …

Methods:

Name	Description
__init__	Create a style of the given family.
get_level_style
set_background	Set the background color of a text style, or the background color or
set_font
set_level_style	Args:

Attributes:

Name	Type	Description
display_name
family	str | None
master_page
name
parent_style

Source code in odfdo/style.py

class Style(StyleProps):
    """Style class for many ODF tags, "style:style", "number:date-style",...

    Partial list:
    "style:style",
    "number:date-style",
    "number:number-style",
    "number:percentage-style",
    "number:time-style",
    "style:font-face",
    "style:page-layout",
    "style:presentation-page-layout",
    "text:list-style",
    "text:outline-style",
    "style:tab-stops"
    ...
    """

    _properties: tuple[PropDef, ...] = (
        PropDef("name", "style:name"),
        PropDef("parent_style", "style:parent-style-name"),
        PropDef("display_name", "style:display-name"),
        PropDef("svg_font_family", "svg:font-family"),
        PropDef("font_family_generic", "style:font-family-generic"),
        PropDef("font_pitch", "style:font-pitch"),
        PropDef("text_style", "text:style-name"),
        PropDef("master_page", "style:master-page-name", "paragraph"),
        # style:tab-stop
        PropDef("style_type", "style:type"),
        PropDef("leader_style", "style:leader-style"),
        PropDef("leader_text", "style:leader-text"),
        PropDef("style_position", "style:position"),
        PropDef("leader_text", "style:position"),
        PropDef("list_style_name", "style:list-style-name"),
        PropDef("style_num_format", "style:num-format"),
    )

    def __new__(cls, *args: Any, **kwargs: Any) -> StyleBase:  # type: ignore[misc]
        family = kwargs.get("family")
        if family is None and args:
            family = args[0]
        if family == "master-page":
            return _new_master_page(*args, **kwargs)
        elif family == "page-layout":
            return _new_page_layout(*args, **kwargs)
        else:
            return super().__new__(cls)

    def __init__(
        self,
        family: str | None = None,
        name: str | None = None,
        display_name: str | None = None,
        parent_style: str | None = None,
        # Where properties apply
        area: str | None = None,
        # For family 'text':
        color: str | tuple | None = None,
        background_color: str | tuple | None = None,
        italic: bool = False,
        bold: bool = False,
        # For family 'paragraph'
        master_page: str | None = None,
        # For family 'table-cell'
        data_style: str | None = None,  # unused
        border: str | None = None,
        border_top: str | None = None,
        border_right: str | None = None,
        border_bottom: str | None = None,
        border_left: str | None = None,
        padding: str | None = None,
        padding_top: str | None = None,
        padding_bottom: str | None = None,
        padding_left: str | None = None,
        padding_right: str | None = None,
        shadow: str | None = None,
        # For family 'table-row'
        height: str | None = None,
        use_optimal_height: bool = False,
        # For family 'table-column'
        break_before: str | None = None,
        break_after: str | None = None,
        # for family 'table'
        align: str | None = None,
        # For family 'table-column' or 'table'
        width: str | None = None,
        # For family 'graphic'
        min_height: str | None = None,
        # For family 'font-face'
        font_name: str | None = None,
        font_family: str | None = None,
        font_family_generic: str | None = None,
        font_pitch: str = "variable",
        # Every other property
        **kwargs: Any,
    ) -> None:
        """Create a style of the given family.

        The name is not mandatory at this
        point but will become required when inserting in a document as a common
        style.

        The display name is the name the user sees in an office application.

        The parent_style is the name of the style this style will inherit from.

        To set properties, pass them as keyword arguments. The area properties
        apply to is optional and defaults to the family.

        Args:

            family -- 'paragraph', 'text', 'section', 'table', 'table-column',
                      'table-row', 'table-cell', 'table-page', 'chart',
                      'drawing-page', 'graphic', 'presentation',
                      'control', 'ruby', 'list', 'number', 'page-layout'
                      'font-face', or 'master-page'

            name -- str

            display_name -- str

            parent_style -- str

            area -- str

        'text' Properties:

            italic -- bool

            bold -- bool

        'paragraph' Properties:

            master_page -- str

        'table-cell' Properties:

            border, border_top, border_right, border_bottom, border_left -- str,
            e.g. "0.002cm solid #000000" or 'none'

            padding, padding_top, padding_right, padding_bottom, padding_left -- str,
            e.g. "0.002cm" or 'none'

            shadow -- str, e.g. "#808080 0.176cm 0.176cm"

        'table-row' Properties:

            height -- str, e.g. '5cm'

            use_optimal_height -- bool

        'table-column' Properties:

            width -- str, e.g. '5cm'

            break_before -- 'page', 'column' or 'auto'

            break_after -- 'page', 'column' or 'auto'

        'table' Properties:

            width -- str, e.g. '5cm'

            align -- 'left', 'center', 'margins' or 'right'
        """
        self._family: str | None = None
        tag_or_elem = kwargs.get("tag_or_elem")
        if tag_or_elem is None:
            family = to_str(family)
            if family in {"master-page", "page-layout"}:
                raise TypeError(f"Wrong initializer for: {family!r}")
            if family not in FAMILY_MAPPING:
                raise ValueError(f"Unknown family value: {family!r}")
            kwargs["tag"] = FAMILY_MAPPING[family]
        super().__init__(**kwargs)
        if self._do_init and family not in SUBCLASSED_STYLES:
            kwargs.pop("tag", None)
            kwargs.pop("tag_or_elem", None)
            self.family = family  # relevant test made by property
            # Common attributes
            if name:
                self.name = name
            if display_name:
                self.display_name = display_name
            if parent_style:
                self.parent_style = parent_style
            # Paragraph
            if family == "paragraph":
                if master_page:
                    self.master_page = master_page
            # Font face
            elif family == "font-face":
                if not font_name:
                    raise ValueError("A font_name is required for 'font-face' style")
                self.set_font(
                    font_name,
                    family=font_family,
                    family_generic=font_family_generic,
                    pitch=font_pitch,
                )
            # Properties
            if area is None:
                area = family
            area = to_str(area)
            # Text
            if area == "text":
                if color:
                    kwargs["fo:color"] = color
                if background_color:
                    kwargs["fo:background-color"] = background_color
                if italic:
                    kwargs["fo:font-style"] = "italic"
                    kwargs["style:font-style-asian"] = "italic"
                    kwargs["style:font-style-complex"] = "italic"
                if bold:
                    kwargs["fo:font-weight"] = "bold"
                    kwargs["style:font-weight-asian"] = "bold"
                    kwargs["style:font-weight-complex"] = "bold"
            # Table cell
            elif area == "table-cell":
                if border:
                    kwargs["fo:border"] = border
                elif border_top or border_right or border_bottom or border_left:
                    kwargs["fo:border-top"] = border_top or "none"
                    kwargs["fo:border-right"] = border_right or "none"
                    kwargs["fo:border-bottom"] = border_bottom or "none"
                    kwargs["fo:border-left"] = border_left or "none"
                else:  # no border_top, ... neither border are defined
                    pass  # left untouched
                if padding:
                    kwargs["fo:padding"] = padding
                elif padding_top or padding_right or padding_bottom or padding_left:
                    kwargs["fo:padding-top"] = padding_top or "none"
                    kwargs["fo:padding-right"] = padding_right or "none"
                    kwargs["fo:padding-bottom"] = padding_bottom or "none"
                    kwargs["fo:padding-left"] = padding_left or "none"
                else:  # no border_top, ... neither border are defined
                    pass  # left untouched
                if shadow:
                    kwargs["style:shadow"] = shadow
                if background_color:
                    kwargs["fo:background-color"] = background_color
            # Table row
            elif area == "table-row":
                if height:
                    kwargs["style:row-height"] = height
                if use_optimal_height:
                    kwargs["style:use-optimal-row-height"] = Boolean.encode(
                        use_optimal_height
                    )
                if background_color:
                    kwargs["fo:background-color"] = background_color
            # Table column
            elif area == "table-column":
                if width:
                    kwargs["style:column-width"] = width
                if break_before:
                    kwargs["fo:break-before"] = break_before
                if break_after:
                    kwargs["fo:break-after"] = break_after
            # Table
            elif area == "table":
                if width:
                    kwargs["style:width"] = width
                if align:
                    if align not in {"center", "left", "margins", "right"}:
                        raise ValueError(f"Invalid align value: {align!r}")
                    kwargs["table:align"] = align
            # Graphic
            elif area == "graphic":
                if min_height:
                    kwargs["fo:min-height"] = min_height
            # Every other properties
            if kwargs:
                self.set_properties(kwargs, area=area)

    @property
    def family(self) -> str | None:
        if self._family is None:
            self._family = FALSE_FAMILY_MAP_REVERSE.get(
                self.tag, self.get_attribute_string("style:family")
            )
        return self._family

    @family.setter
    def family(self, family: str | None) -> None:
        self._family = family
        if family in FAMILY_ODF_STD and self.tag == "style:style":
            self.set_attribute("style:family", family)

    def __repr__(self) -> str:
        return f"<{self.__class__.__name__} family={self.family} name={self.name}>"

    def set_background(
        self,
        color: str | None = None,
        url: str | None = None,
        position: str | None = "center",
        repeat: str | None = None,
        opacity: str | int | None = None,
        filter: str | None = None,  # noqa: A002
    ) -> None:
        """Set the background color of a text style, or the background color or
        image of a paragraph style or page layout.

        With no argument, remove any existing background.

        The values of the position attribute are "left", "center", "right", "top", "bottom", or two white space separated values, that may appear in any order. One of these values is one of: "left", "center" or "right". The other value is one of: "top", "center" or "bottom". The default value for this attribute is "center".

        The repeat value is one of 'no-repeat', 'repeat' or 'stretch'.

        The opacity is a percentage integer (not a string with the '%' sign)

        The filter is an application-specific filter name defined elsewhere.

        Though this method is defined on the base style class, it will raise
        an error if the style type is not compatible.

        Args:

            color -- '#rrggbb'

            url -- str

            position -- str

            repeat -- str

            opacity -- int

            filter -- str
        """
        _set_background(self, color, url, position, repeat, opacity, filter)

    # list-style only:

    def get_level_style(self, level: int) -> Style | None:
        if self.family != "list":
            return None
        level_styles = (
            "(text:list-level-style-number"
            "|text:list-level-style-bullet"
            "|text:list-level-style-image)"
        )
        return self._filtered_element(level_styles, 0, level=level)  # type: ignore

    def set_level_style(
        self,
        level: int,
        num_format: str | None = None,
        bullet_char: str | None = None,
        url: str | None = None,
        display_levels: int | None = None,
        prefix: str | None = None,
        suffix: str | None = None,
        start_value: int | None = None,
        style: str | None = None,
        clone: Style | None = None,
    ) -> Style | None:
        """
        Args:

            level -- int

            num_format (for number) -- int

            bullet_char (for bullet) -- str

            url (for image) -- str

            display_levels -- int

            prefix -- str

            suffix -- str

            start_value -- int

            style -- str

            clone -- List Style

        Returns:
            level_style created
        """
        if self.family != "list":
            return None
        # Expected name
        if num_format is not None:
            level_style_name = "text:list-level-style-number"
        elif bullet_char is not None:
            level_style_name = "text:list-level-style-bullet"
        elif url is not None:
            level_style_name = "text:list-level-style-image"
        elif clone is not None:
            level_style_name = clone.tag
        else:
            raise ValueError("unknown level style type")
        was_created = False
        # Cloning or reusing an existing element
        level_style: Style | None = None
        if clone is not None:
            level_style = clone.clone  # type: ignore
            was_created = True
        else:
            level_style = self.get_level_style(level)
            if level_style is None:
                level_style = Element.from_tag(level_style_name)  # type: ignore
                was_created = True
        if level_style is None:
            return None
        # Transmute if the type changed
        if level_style.tag != level_style_name:
            print("Warn: different style", level_style_name, level_style.tag)
            level_style.tag = level_style_name
        # Set the level
        level_style.set_attribute("text:level", str(level))
        # Set the main attribute
        if num_format is not None:
            level_style.set_attribute("fo:num-format", num_format)
        elif bullet_char is not None:
            level_style.set_attribute("text:bullet-char", bullet_char)
        elif url is not None:
            level_style.set_attribute("xlink:href", url)
        # Set attributes
        if prefix:
            level_style.set_attribute("style:num-prefix", prefix)
        if suffix:
            level_style.set_attribute("style:num-suffix", suffix)
        if display_levels:
            level_style.set_attribute("text:display-levels", str(display_levels))
        if start_value:
            level_style.set_attribute("text:start-value", str(start_value))
        if style:
            level_style.text_style = style  # type: ignore
        # Commit the creation
        if was_created:
            self.append(level_style)
        return level_style

    # font-face only:

    def set_font(
        self,
        name: str,
        family: str | None = None,
        family_generic: str | None = None,
        pitch: str = "variable",
    ) -> None:
        if self.family != "font-face":
            return
        self.name = name
        if family is None:
            family = name
        self.svg_font_family = f'"{family}"'
        if family_generic is not None:
            self.font_family_generic = family_generic
        self.font_pitch = pitch

display_name instance-attribute

display_name = display_name

family property writable

family: str | None

master_page instance-attribute

master_page = master_page

name instance-attribute

name = name

parent_style instance-attribute

parent_style = parent_style

__init__

__init__(
    family: str | None = None,
    name: str | None = None,
    display_name: str | None = None,
    parent_style: str | None = None,
    area: str | None = None,
    color: str | tuple | None = None,
    background_color: str | tuple | None = None,
    italic: bool = False,
    bold: bool = False,
    master_page: str | None = None,
    data_style: str | None = None,
    border: str | None = None,
    border_top: str | None = None,
    border_right: str | None = None,
    border_bottom: str | None = None,
    border_left: str | None = None,
    padding: str | None = None,
    padding_top: str | None = None,
    padding_bottom: str | None = None,
    padding_left: str | None = None,
    padding_right: str | None = None,
    shadow: str | None = None,
    height: str | None = None,
    use_optimal_height: bool = False,
    break_before: str | None = None,
    break_after: str | None = None,
    align: str | None = None,
    width: str | None = None,
    min_height: str | None = None,
    font_name: str | None = None,
    font_family: str | None = None,
    font_family_generic: str | None = None,
    font_pitch: str = "variable",
    **kwargs: Any,
) -> None

Create a style of the given family.

The name is not mandatory at this point but will become required when inserting in a document as a common style.

The display name is the name the user sees in an office application.

The parent_style is the name of the style this style will inherit from.

To set properties, pass them as keyword arguments. The area properties apply to is optional and defaults to the family.

Args:

family -- 'paragraph', 'text', 'section', 'table', 'table-column',
          'table-row', 'table-cell', 'table-page', 'chart',
          'drawing-page', 'graphic', 'presentation',
          'control', 'ruby', 'list', 'number', 'page-layout'
          'font-face', or 'master-page'

name -- str

display_name -- str

parent_style -- str

area -- str

‘text’ Properties:

italic -- bool

bold -- bool

‘paragraph’ Properties:

master_page -- str

‘table-cell’ Properties:

border, border_top, border_right, border_bottom, border_left -- str,
e.g. "0.002cm solid #000000" or 'none'

padding, padding_top, padding_right, padding_bottom, padding_left -- str,
e.g. "0.002cm" or 'none'

shadow -- str, e.g. "#808080 0.176cm 0.176cm"

‘table-row’ Properties:

height -- str, e.g. '5cm'

use_optimal_height -- bool

‘table-column’ Properties:

width -- str, e.g. '5cm'

break_before -- 'page', 'column' or 'auto'

break_after -- 'page', 'column' or 'auto'

‘table’ Properties:

width -- str, e.g. '5cm'

align -- 'left', 'center', 'margins' or 'right'

Source code in odfdo/style.py

def __init__(
    self,
    family: str | None = None,
    name: str | None = None,
    display_name: str | None = None,
    parent_style: str | None = None,
    # Where properties apply
    area: str | None = None,
    # For family 'text':
    color: str | tuple | None = None,
    background_color: str | tuple | None = None,
    italic: bool = False,
    bold: bool = False,
    # For family 'paragraph'
    master_page: str | None = None,
    # For family 'table-cell'
    data_style: str | None = None,  # unused
    border: str | None = None,
    border_top: str | None = None,
    border_right: str | None = None,
    border_bottom: str | None = None,
    border_left: str | None = None,
    padding: str | None = None,
    padding_top: str | None = None,
    padding_bottom: str | None = None,
    padding_left: str | None = None,
    padding_right: str | None = None,
    shadow: str | None = None,
    # For family 'table-row'
    height: str | None = None,
    use_optimal_height: bool = False,
    # For family 'table-column'
    break_before: str | None = None,
    break_after: str | None = None,
    # for family 'table'
    align: str | None = None,
    # For family 'table-column' or 'table'
    width: str | None = None,
    # For family 'graphic'
    min_height: str | None = None,
    # For family 'font-face'
    font_name: str | None = None,
    font_family: str | None = None,
    font_family_generic: str | None = None,
    font_pitch: str = "variable",
    # Every other property
    **kwargs: Any,
) -> None:
    """Create a style of the given family.

    The name is not mandatory at this
    point but will become required when inserting in a document as a common
    style.

    The display name is the name the user sees in an office application.

    The parent_style is the name of the style this style will inherit from.

    To set properties, pass them as keyword arguments. The area properties
    apply to is optional and defaults to the family.

    Args:

        family -- 'paragraph', 'text', 'section', 'table', 'table-column',
                  'table-row', 'table-cell', 'table-page', 'chart',
                  'drawing-page', 'graphic', 'presentation',
                  'control', 'ruby', 'list', 'number', 'page-layout'
                  'font-face', or 'master-page'

        name -- str

        display_name -- str

        parent_style -- str

        area -- str

    'text' Properties:

        italic -- bool

        bold -- bool

    'paragraph' Properties:

        master_page -- str

    'table-cell' Properties:

        border, border_top, border_right, border_bottom, border_left -- str,
        e.g. "0.002cm solid #000000" or 'none'

        padding, padding_top, padding_right, padding_bottom, padding_left -- str,
        e.g. "0.002cm" or 'none'

        shadow -- str, e.g. "#808080 0.176cm 0.176cm"

    'table-row' Properties:

        height -- str, e.g. '5cm'

        use_optimal_height -- bool

    'table-column' Properties:

        width -- str, e.g. '5cm'

        break_before -- 'page', 'column' or 'auto'

        break_after -- 'page', 'column' or 'auto'

    'table' Properties:

        width -- str, e.g. '5cm'

        align -- 'left', 'center', 'margins' or 'right'
    """
    self._family: str | None = None
    tag_or_elem = kwargs.get("tag_or_elem")
    if tag_or_elem is None:
        family = to_str(family)
        if family in {"master-page", "page-layout"}:
            raise TypeError(f"Wrong initializer for: {family!r}")
        if family not in FAMILY_MAPPING:
            raise ValueError(f"Unknown family value: {family!r}")
        kwargs["tag"] = FAMILY_MAPPING[family]
    super().__init__(**kwargs)
    if self._do_init and family not in SUBCLASSED_STYLES:
        kwargs.pop("tag", None)
        kwargs.pop("tag_or_elem", None)
        self.family = family  # relevant test made by property
        # Common attributes
        if name:
            self.name = name
        if display_name:
            self.display_name = display_name
        if parent_style:
            self.parent_style = parent_style
        # Paragraph
        if family == "paragraph":
            if master_page:
                self.master_page = master_page
        # Font face
        elif family == "font-face":
            if not font_name:
                raise ValueError("A font_name is required for 'font-face' style")
            self.set_font(
                font_name,
                family=font_family,
                family_generic=font_family_generic,
                pitch=font_pitch,
            )
        # Properties
        if area is None:
            area = family
        area = to_str(area)
        # Text
        if area == "text":
            if color:
                kwargs["fo:color"] = color
            if background_color:
                kwargs["fo:background-color"] = background_color
            if italic:
                kwargs["fo:font-style"] = "italic"
                kwargs["style:font-style-asian"] = "italic"
                kwargs["style:font-style-complex"] = "italic"
            if bold:
                kwargs["fo:font-weight"] = "bold"
                kwargs["style:font-weight-asian"] = "bold"
                kwargs["style:font-weight-complex"] = "bold"
        # Table cell
        elif area == "table-cell":
            if border:
                kwargs["fo:border"] = border
            elif border_top or border_right or border_bottom or border_left:
                kwargs["fo:border-top"] = border_top or "none"
                kwargs["fo:border-right"] = border_right or "none"
                kwargs["fo:border-bottom"] = border_bottom or "none"
                kwargs["fo:border-left"] = border_left or "none"
            else:  # no border_top, ... neither border are defined
                pass  # left untouched
            if padding:
                kwargs["fo:padding"] = padding
            elif padding_top or padding_right or padding_bottom or padding_left:
                kwargs["fo:padding-top"] = padding_top or "none"
                kwargs["fo:padding-right"] = padding_right or "none"
                kwargs["fo:padding-bottom"] = padding_bottom or "none"
                kwargs["fo:padding-left"] = padding_left or "none"
            else:  # no border_top, ... neither border are defined
                pass  # left untouched
            if shadow:
                kwargs["style:shadow"] = shadow
            if background_color:
                kwargs["fo:background-color"] = background_color
        # Table row
        elif area == "table-row":
            if height:
                kwargs["style:row-height"] = height
            if use_optimal_height:
                kwargs["style:use-optimal-row-height"] = Boolean.encode(
                    use_optimal_height
                )
            if background_color:
                kwargs["fo:background-color"] = background_color
        # Table column
        elif area == "table-column":
            if width:
                kwargs["style:column-width"] = width
            if break_before:
                kwargs["fo:break-before"] = break_before
            if break_after:
                kwargs["fo:break-after"] = break_after
        # Table
        elif area == "table":
            if width:
                kwargs["style:width"] = width
            if align:
                if align not in {"center", "left", "margins", "right"}:
                    raise ValueError(f"Invalid align value: {align!r}")
                kwargs["table:align"] = align
        # Graphic
        elif area == "graphic":
            if min_height:
                kwargs["fo:min-height"] = min_height
        # Every other properties
        if kwargs:
            self.set_properties(kwargs, area=area)

get_level_style

get_level_style(level: int) -> Style | None

Source code in odfdo/style.py

def get_level_style(self, level: int) -> Style | None:
    if self.family != "list":
        return None
    level_styles = (
        "(text:list-level-style-number"
        "|text:list-level-style-bullet"
        "|text:list-level-style-image)"
    )
    return self._filtered_element(level_styles, 0, level=level)  # type: ignore

set_background

set_background(
    color: str | None = None,
    url: str | None = None,
    position: str | None = "center",
    repeat: str | None = None,
    opacity: str | int | None = None,
    filter: str | None = None,
) -> None

Set the background color of a text style, or the background color or image of a paragraph style or page layout.

With no argument, remove any existing background.

The values of the position attribute are “left”, “center”, “right”, “top”, “bottom”, or two white space separated values, that may appear in any order. One of these values is one of: “left”, “center” or “right”. The other value is one of: “top”, “center” or “bottom”. The default value for this attribute is “center”.

The repeat value is one of ‘no-repeat’, ‘repeat’ or ‘stretch’.

The opacity is a percentage integer (not a string with the ‘%’ sign)

The filter is an application-specific filter name defined elsewhere.

Though this method is defined on the base style class, it will raise an error if the style type is not compatible.

Args:

color -- '#rrggbb'

url -- str

position -- str

repeat -- str

opacity -- int

filter -- str

Source code in odfdo/style.py

def set_background(
    self,
    color: str | None = None,
    url: str | None = None,
    position: str | None = "center",
    repeat: str | None = None,
    opacity: str | int | None = None,
    filter: str | None = None,  # noqa: A002
) -> None:
    """Set the background color of a text style, or the background color or
    image of a paragraph style or page layout.

    With no argument, remove any existing background.

    The values of the position attribute are "left", "center", "right", "top", "bottom", or two white space separated values, that may appear in any order. One of these values is one of: "left", "center" or "right". The other value is one of: "top", "center" or "bottom". The default value for this attribute is "center".

    The repeat value is one of 'no-repeat', 'repeat' or 'stretch'.

    The opacity is a percentage integer (not a string with the '%' sign)

    The filter is an application-specific filter name defined elsewhere.

    Though this method is defined on the base style class, it will raise
    an error if the style type is not compatible.

    Args:

        color -- '#rrggbb'

        url -- str

        position -- str

        repeat -- str

        opacity -- int

        filter -- str
    """
    _set_background(self, color, url, position, repeat, opacity, filter)

set_font

set_font(
    name: str,
    family: str | None = None,
    family_generic: str | None = None,
    pitch: str = "variable",
) -> None

Source code in odfdo/style.py

def set_font(
    self,
    name: str,
    family: str | None = None,
    family_generic: str | None = None,
    pitch: str = "variable",
) -> None:
    if self.family != "font-face":
        return
    self.name = name
    if family is None:
        family = name
    self.svg_font_family = f'"{family}"'
    if family_generic is not None:
        self.font_family_generic = family_generic
    self.font_pitch = pitch

set_level_style

set_level_style(
    level: int,
    num_format: str | None = None,
    bullet_char: str | None = None,
    url: str | None = None,
    display_levels: int | None = None,
    prefix: str | None = None,
    suffix: str | None = None,
    start_value: int | None = None,
    style: str | None = None,
    clone: Style | None = None,
) -> Style | None

Args:

level -- int

num_format (for number) -- int

bullet_char (for bullet) -- str

url (for image) -- str

display_levels -- int

prefix -- str

suffix -- str

start_value -- int

style -- str

clone -- List Style

Returns:

Type	Description
Style | None	level_style created

Source code in odfdo/style.py

def set_level_style(
    self,
    level: int,
    num_format: str | None = None,
    bullet_char: str | None = None,
    url: str | None = None,
    display_levels: int | None = None,
    prefix: str | None = None,
    suffix: str | None = None,
    start_value: int | None = None,
    style: str | None = None,
    clone: Style | None = None,
) -> Style | None:
    """
    Args:

        level -- int

        num_format (for number) -- int

        bullet_char (for bullet) -- str

        url (for image) -- str

        display_levels -- int

        prefix -- str

        suffix -- str

        start_value -- int

        style -- str

        clone -- List Style

    Returns:
        level_style created
    """
    if self.family != "list":
        return None
    # Expected name
    if num_format is not None:
        level_style_name = "text:list-level-style-number"
    elif bullet_char is not None:
        level_style_name = "text:list-level-style-bullet"
    elif url is not None:
        level_style_name = "text:list-level-style-image"
    elif clone is not None:
        level_style_name = clone.tag
    else:
        raise ValueError("unknown level style type")
    was_created = False
    # Cloning or reusing an existing element
    level_style: Style | None = None
    if clone is not None:
        level_style = clone.clone  # type: ignore
        was_created = True
    else:
        level_style = self.get_level_style(level)
        if level_style is None:
            level_style = Element.from_tag(level_style_name)  # type: ignore
            was_created = True
    if level_style is None:
        return None
    # Transmute if the type changed
    if level_style.tag != level_style_name:
        print("Warn: different style", level_style_name, level_style.tag)
        level_style.tag = level_style_name
    # Set the level
    level_style.set_attribute("text:level", str(level))
    # Set the main attribute
    if num_format is not None:
        level_style.set_attribute("fo:num-format", num_format)
    elif bullet_char is not None:
        level_style.set_attribute("text:bullet-char", bullet_char)
    elif url is not None:
        level_style.set_attribute("xlink:href", url)
    # Set attributes
    if prefix:
        level_style.set_attribute("style:num-prefix", prefix)
    if suffix:
        level_style.set_attribute("style:num-suffix", suffix)
    if display_levels:
        level_style.set_attribute("text:display-levels", str(display_levels))
    if start_value:
        level_style.set_attribute("text:start-value", str(start_value))
    if style:
        level_style.text_style = style  # type: ignore
    # Commit the creation
    if was_created:
        self.append(level_style)
    return level_style

StyleFooter

Bases: StyleHeader

Content of a footer in a StyleMasterPage, tag “style:footer”.

The “style:display” attribute specifies whether the footer is displayed or not (“true” or “false”). The default value is “true”.

Source code in odfdo/master_page.py

class StyleFooter(StyleHeader):
    """Content of a footer in a StyleMasterPage, tag "style:footer".

    The "style:display" attribute specifies whether the footer is displayed or
    not ("true" or "false"). The default value is "true".
    """

    _tag: str = "style:footer"

StyleFooterLeft

Bases: StyleHeader

Content of a left page footer in a StyleMasterPage, tag “style:footer- left”.

If left page different from the right page in a “style:master-page”.

The “style:display” attribute specifies whether the footer is displayed or not (“true” or “false”). The default value is “true”.

Source code in odfdo/master_page.py

class StyleFooterLeft(StyleHeader):
    """Content of a left page footer in a StyleMasterPage, tag "style:footer-
    left".

    If left page different from the right page in a "style:master-page".

    The "style:display" attribute specifies whether the footer is displayed or
    not ("true" or "false"). The default value is "true".
    """

    _tag: str = "style:footer-left"

StyleHeader

Bases: StyleBase

Content of a header in a StyleMasterPage, tag “style:header”.

The “style:display” attribute specifies whether the header is displayed or not (“true” or “false”). The default value is “true”.

Methods:

Name	Description
__init__

Attributes:

Name	Type	Description
display	bool

Source code in odfdo/master_page.py

class StyleHeader(StyleBase):
    """Content of a header in a StyleMasterPage, tag "style:header".

    The "style:display" attribute specifies whether the header is displayed or
    not ("true" or "false"). The default value is "true".
    """

    _tag: str = "style:header"

    def __init__(
        self,
        display: str | bool | None = True,
        # Every other property
        **kwargs: Any,
    ) -> None:
        super().__init__(**kwargs)
        if self._do_init:
            kwargs.pop("tag", None)
            kwargs.pop("tag_or_elem", None)
            self.display = display

    @property
    def display(self) -> bool:
        return self._get_attribute_bool_default("style:display", True)

    @display.setter
    def display(self, display: bool | str | None) -> None:
        self._set_attribute_bool_default("style:display", display, True)

    def __repr__(self) -> str:
        return f"<{self.__class__.__name__}>"

display property writable

display: bool

__init__

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

Source code in odfdo/master_page.py

def __init__(
    self,
    display: str | bool | None = True,
    # Every other property
    **kwargs: Any,
) -> None:
    super().__init__(**kwargs)
    if self._do_init:
        kwargs.pop("tag", None)
        kwargs.pop("tag_or_elem", None)
        self.display = display

StyleHeaderLeft

Bases: StyleHeader

Content of a left page header in a StyleMasterPage, tag “style:header- left”.

If left page different from the right page in a “style:master-page”.

The “style:display” attribute specifies whether the header is displayed or not (“true” or “false”). The default value is “true”.

Source code in odfdo/master_page.py

class StyleHeaderLeft(StyleHeader):
    """Content of a left page header in a StyleMasterPage, tag "style:header-
    left".

    If left page different from the right page in a "style:master-page".

    The "style:display" attribute specifies whether the header is displayed or
    not ("true" or "false"). The default value is "true".
    """

    _tag: str = "style:header-left"

StyleMasterPage

Bases: StyleBase

Container of headers and footers, “style:master-page”.

In text and spreadsheet documents, the “style:master-page” element contains the content of headers and footers. For these types of documents, consumers may generate a sequence of pages by making use of a single master page or a set of master pages.

In drawing and presentation documents, the “style:master-page” element is used to define master pages as common backgrounds for drawing pages. Each drawing page is directly linked to one master page, which is specified by the draw:master-page-name attribute of the drawing pages style.

Master pages are contained in the “office:master-styles” element.

All documents shall contain at least one master page element.

If a text or spreadsheet document is displayed in a paged layout, master pages are used to generate a sequence of pages containing the document content. When a page is created, an empty page is generated with the properties of the master page and the static content of the master page. The body of the page is then filled with content. A single master pages can be used to created multiple pages within a document.

In text and spreadsheet documents, a master page can be assigned to paragraph and table styles using a style:master-page-name attribute. Each time the paragraph or table style is applied to text, a page break is inserted before the paragraph or table. A page that starts at the page break position uses the specified master page.

In drawings and presentations, master pages can be assigned to drawing pages using a style:parent-style-name attribute.

The “style:master-page” element is usable within the following element: “office:master-styles”.

Methods:

Name	Description
__init__	Create a StyleMasterPage.
get_page_footer	Get the element that contains the footer contents.
get_page_header	Get the element that contains the header contents.
set_font	Not applicable to this class.
set_page_footer	Create or replace the footer by the given content. It can already be
set_page_header	Create or replace the header by the given content. It can already be

Attributes:

Name	Type	Description
display_name
draw_style_name
family	str | None
name
next_style
page_layout

Source code in odfdo/master_page.py

class StyleMasterPage(StyleBase):
    """Container of headers and footers, "style:master-page".

    In text and spreadsheet documents, the "style:master-page" element contains
    the content of headers and footers. For these types of documents, consumers
    may generate a sequence of pages by making use of a single master page or a
    set of master pages.

    In drawing and presentation documents, the "style:master-page" element is
    used to define master pages as common backgrounds for drawing pages. Each
    drawing page is directly linked to one master page, which is specified by
    the draw:master-page-name attribute of the drawing pages style.

    Master pages are contained in the "office:master-styles" element.

    All documents shall contain at least one master page element.

    If a text or spreadsheet document is displayed in a paged layout, master
    pages are used to generate a sequence of pages containing the document
    content. When a page is created, an empty page is generated with the
    properties of the master page and the static content of the master page.
    The body of the page is then filled with content. A single master pages can
    be used to created multiple pages within a document.

    In text and spreadsheet documents, a master page can be assigned to
    paragraph and table styles using a style:master-page-name attribute. Each
    time the paragraph or table style is applied to text, a page break is
    inserted before the paragraph or table. A page that starts at the page
    break position uses the specified master page.

    In drawings and presentations, master pages can be assigned to drawing
    pages using a style:parent-style-name attribute.

    The "style:master-page" element is usable within the following element:
    "office:master-styles".
    """

    # The <style:master-page> element has the following attributes:
    # draw:style-name
    # style:display-name
    # style:name
    # style:next-style-name
    # style:page-layout-name

    _tag: str = "style:master-page"
    _properties: tuple[PropDef, ...] = (
        PropDef("name", "style:name"),
        PropDef("display_name", "style:display-name"),
        PropDef("page_layout", "style:page-layout-name", "master-page"),
        PropDef(
            "next_style",
            "style:next-style-name",
            "master-page",
        ),
        PropDef("draw_style_name", "draw:style-name"),
    )

    def __init__(
        self,
        name: str | None = None,
        display_name: str | None = None,
        page_layout: str | None = None,
        next_style: str | None = None,
        draw_style_name: str | None = None,
        **kwargs: Any,
    ) -> None:
        """Create a StyleMasterPage.

        The name is not mandatory at this point but will become required when inserting in a document as a common style.
        The display name is the name the user sees in an office application.

        To set properties, pass them as keyword arguments.

        Args:

            name -- str

            display_name -- str

            page_layout -- str

            next_style -- str

            draw_style_name -- str
        """
        self._family = "master-page"
        tag_or_elem = kwargs.get("tag_or_elem")
        if tag_or_elem is None:
            kwargs["tag"] = "style:master-page"
        Element.__init__(self, **kwargs)
        if self._do_init:
            # print("_do_init")
            kwargs.pop("tag", None)
            kwargs.pop("tag_or_elem", None)
            if name:
                self.name = name
            if display_name:
                self.display_name = display_name
            if page_layout:
                self.page_layout = page_layout
            if next_style:
                self.next_style = next_style
            if draw_style_name:
                self.draw_style_name = draw_style_name

    @property
    def family(self) -> str | None:
        return self._family

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

    def __repr__(self) -> str:
        return f"<{self.__class__.__name__} family={self.family} name={self.name}>"

    def _set_header_or_footer(
        self,
        text_or_element: str | Element | list[Element | str],
        name: str = "header",
        style: str = "Header",
    ) -> None:
        if name == "header":
            header_or_footer = self.get_page_header()
        else:
            header_or_footer = self.get_page_footer()
        if header_or_footer is None:
            header_or_footer = Element.from_tag("style:" + name)
            self.append(header_or_footer)
        else:
            header_or_footer.clear()
        if (
            isinstance(text_or_element, Element)
            and text_or_element.tag == f"style:{name}"
        ):
            # Already a header or footer?
            self.delete(header_or_footer)
            self.append(text_or_element)
            return
        if isinstance(text_or_element, (Element, str)):
            elem_list: list[Element | str] = [text_or_element]
        else:
            elem_list = text_or_element
        for item in elem_list:
            if isinstance(item, str):
                paragraph = Element.from_tag("text:p")
                paragraph.append_plain_text(item)  # type: ignore
                paragraph.style = style  # type: ignore
                header_or_footer.append(paragraph)
            elif isinstance(item, Element):
                header_or_footer.append(item)

    def get_page_header(self) -> Element | None:
        """Get the element that contains the header contents.

        If None, no header was set.
        """
        return self.get_element("style:header")

    def set_page_header(
        self,
        text_or_element: str | Element | list[Element | str],
    ) -> None:
        """Create or replace the header by the given content. It can already be
        a complete header.

        If you only want to update the existing header, get it and use the
        API.

        Args:

            text_or_element -- str or Element or a list of them
        """
        self._set_header_or_footer(text_or_element)

    def get_page_footer(self) -> Element | None:
        """Get the element that contains the footer contents.

        If None, no footer was set.
        """
        return self.get_element("style:footer")

    def set_page_footer(
        self,
        text_or_element: str | Element | list[Element | str],
    ) -> None:
        """Create or replace the footer by the given content. It can already be
        a complete footer.

        If you only want to update the existing footer, get it and use the
        API.

        Args:

            text_or_element -- str or Element or a list of them
        """
        self._set_header_or_footer(text_or_element, name="footer", style="Footer")

    def set_font(
        self,
        name: str,
        family: str | None = None,
        family_generic: str | None = None,
        pitch: str = "variable",
    ) -> None:
        """Not applicable to this class."""

display_name instance-attribute

display_name = display_name

draw_style_name instance-attribute

draw_style_name = draw_style_name

family property writable

family: str | None

name instance-attribute

name = name

next_style instance-attribute

next_style = next_style

page_layout instance-attribute

page_layout = page_layout

__init__

__init__(
    name: str | None = None,
    display_name: str | None = None,
    page_layout: str | None = None,
    next_style: str | None = None,
    draw_style_name: str | None = None,
    **kwargs: Any,
) -> None

Create a StyleMasterPage.

The name is not mandatory at this point but will become required when inserting in a document as a common style. The display name is the name the user sees in an office application.

To set properties, pass them as keyword arguments.

Args:

name -- str

display_name -- str

page_layout -- str

next_style -- str

draw_style_name -- str

Source code in odfdo/master_page.py

def __init__(
    self,
    name: str | None = None,
    display_name: str | None = None,
    page_layout: str | None = None,
    next_style: str | None = None,
    draw_style_name: str | None = None,
    **kwargs: Any,
) -> None:
    """Create a StyleMasterPage.

    The name is not mandatory at this point but will become required when inserting in a document as a common style.
    The display name is the name the user sees in an office application.

    To set properties, pass them as keyword arguments.

    Args:

        name -- str

        display_name -- str

        page_layout -- str

        next_style -- str

        draw_style_name -- str
    """
    self._family = "master-page"
    tag_or_elem = kwargs.get("tag_or_elem")
    if tag_or_elem is None:
        kwargs["tag"] = "style:master-page"
    Element.__init__(self, **kwargs)
    if self._do_init:
        # print("_do_init")
        kwargs.pop("tag", None)
        kwargs.pop("tag_or_elem", None)
        if name:
            self.name = name
        if display_name:
            self.display_name = display_name
        if page_layout:
            self.page_layout = page_layout
        if next_style:
            self.next_style = next_style
        if draw_style_name:
            self.draw_style_name = draw_style_name

get_page_footer

get_page_footer() -> Element | None

Get the element that contains the footer contents.

If None, no footer was set.

Source code in odfdo/master_page.py

def get_page_footer(self) -> Element | None:
    """Get the element that contains the footer contents.

    If None, no footer was set.
    """
    return self.get_element("style:footer")

get_page_header

get_page_header() -> Element | None

Get the element that contains the header contents.

If None, no header was set.

Source code in odfdo/master_page.py

def get_page_header(self) -> Element | None:
    """Get the element that contains the header contents.

    If None, no header was set.
    """
    return self.get_element("style:header")

set_font

set_font(
    name: str,
    family: str | None = None,
    family_generic: str | None = None,
    pitch: str = "variable",
) -> None

Not applicable to this class.

Source code in odfdo/master_page.py

def set_font(
    self,
    name: str,
    family: str | None = None,
    family_generic: str | None = None,
    pitch: str = "variable",
) -> None:
    """Not applicable to this class."""

set_page_footer

set_page_footer(
    text_or_element: str | Element | list[Element | str],
) -> None

Create or replace the footer by the given content. It can already be a complete footer.

If you only want to update the existing footer, get it and use the API.

Args:

text_or_element -- str or Element or a list of them

Source code in odfdo/master_page.py

def set_page_footer(
    self,
    text_or_element: str | Element | list[Element | str],
) -> None:
    """Create or replace the footer by the given content. It can already be
    a complete footer.

    If you only want to update the existing footer, get it and use the
    API.

    Args:

        text_or_element -- str or Element or a list of them
    """
    self._set_header_or_footer(text_or_element, name="footer", style="Footer")

set_page_header

set_page_header(
    text_or_element: str | Element | list[Element | str],
) -> None

Create or replace the header by the given content. It can already be a complete header.

If you only want to update the existing header, get it and use the API.

Args:

text_or_element -- str or Element or a list of them

Source code in odfdo/master_page.py

def set_page_header(
    self,
    text_or_element: str | Element | list[Element | str],
) -> None:
    """Create or replace the header by the given content. It can already be
    a complete header.

    If you only want to update the existing header, get it and use the
    API.

    Args:

        text_or_element -- str or Element or a list of them
    """
    self._set_header_or_footer(text_or_element)

StylePageLayout

Bases: StyleProps

The “style:page-layout” element represents the styles that specify the formatting properties of a page.

The “style:page-layout” element is usable within the following element: “office:automatic-styles”.

Methods:

Name	Description
__init__	Create a StylePageLayout.
del_properties	Delete the given properties, either by list argument or positional
get_footer_style
get_header_style
get_properties	Get the mapping of page-layout properties of StylePageLayout.
set_background	Set the background color of the page layout.
set_footer_style
set_header_style
set_properties	Set the properties of the page-layout.

Attributes:

Name	Type	Description
family	str | None
name
page_usage	str

Source code in odfdo/page_layout.py

class StylePageLayout(StyleProps):
    """The "style:page-layout" element represents the styles that specify the
    formatting properties of a page.

    The "style:page-layout" element is usable within the following element:
    "office:automatic-styles".
    """

    # The "style:page-layout" element has the following attributes:
    # style:name
    # style:page-usage

    _tag: str = "style:page-layout"
    _properties: tuple[PropDef, ...] = (
        PropDef("name", "style:name"),
        PropDef("page_usage", "style:page-usage"),
    )

    def __init__(
        self,
        name: str | None = None,
        page_usage: str | None = None,
        **kwargs: Any,
    ) -> None:
        """Create a StylePageLayout.

        The name is not mandatory at this point but will become required when inserting in a document as a automatic style.

        The page_usage attribute specifies the type of pages that a page master should generate. Allowed values are: "all" (default), "left", "mirrored", "right".

        To set properties, pass them as keyword arguments.

        Args:

            name -- str

            page_usage -- str
        """
        self._family = "page-layout"
        tag_or_elem = kwargs.get("tag_or_elem")
        if tag_or_elem is None:
            kwargs["tag"] = "style:page-layout"
        Element.__init__(self, **kwargs)
        if self._do_init:
            kwargs.pop("tag", None)
            kwargs.pop("tag_or_elem", None)
            if name:
                self.name = name
            if page_usage:
                self.page_usage = page_usage

    @property
    def family(self) -> str | None:
        return self._family

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

    def __repr__(self) -> str:
        return f"<{self.__class__.__name__} family={self.family} name={self.name}>"

    @property
    def page_usage(self) -> str:
        return self._get_attribute_str_default("style:page-usage", "all")

    @page_usage.setter
    def page_usage(self, page_usage: str | None) -> None:
        self._set_attribute_str_default("style:page-usage", page_usage, "all")

    def get_properties(
        self, area: str | None = "page-layout"
    ) -> dict[str, str | dict] | None:
        """Get the mapping of page-layout properties of StylePageLayout.

        Args:

            area -- str (unused, kept for compatibility)

        Returns: dict
        """
        return super().get_properties(area="page-layout")

    def set_properties(
        self,
        properties: dict[str, str | dict] | None = None,
        style: StyleBase | None = None,
        area: str | None = None,
        **kwargs: Any,
    ) -> None:
        """Set the properties of the page-layout.

        Properties are given either as a dict or as named arguments (or both). The area is identical to the style family by default. If the properties element is missing, it is created.

        Instead of properties, you can pass a style with properties of a page-layout style. These will be copied.

        Args:

            properties -- dict

            style -- StylePageLayout

            area -- "page-layout"
        """
        return super().set_properties(
            properties=properties, style=style, area="page-layout", **kwargs
        )

    def del_properties(
        self,
        properties: list[str] | None = None,
        area: str | None = None,
    ) -> None:
        """Delete the given properties, either by list argument or positional
        argument (or both).

        Args:

            properties -- list

            area -- "page-layout"
        """
        return super().del_properties(properties=properties, area="page-layout")

    def set_background(
        self,
        color: str | None = None,
        url: str | None = None,
        position: str | None = "center",
        repeat: str | None = None,
        opacity: str | int | None = None,
        filter: str | None = None,  # noqa: A002
    ) -> None:
        """Set the background color of the page layout.

        With no argument, remove any existing background.

        The values of the position attribute are "left", "center", "right", "top", "bottom", or two white space separated values, that may appear in any order. One of these values is one of: "left", "center" or "right". The other value is one of: "top", "center" or "bottom". The default value for this attribute is "center".

        The repeat value is one of 'no-repeat', 'repeat' or 'stretch'.

        The opacity is a percentage integer (not a string with the '%' sign)

        The filter is an application-specific filter name defined elsewhere.

        Args:

            color -- '#rrggbb'

            url -- str

            position -- str

            repeat -- str

            opacity -- int

            filter -- str
        """
        _set_background(self, color, url, position, repeat, opacity, filter)

    def get_header_style(self) -> StyleBase | None:
        return self.get_element("style:header-style")  # type: ignore

    def set_header_style(self, new_style: StyleBase) -> None:
        header_style = self.get_header_style()
        if header_style is not None:
            self.delete(header_style)
        self.append(new_style)

    def get_footer_style(self) -> StyleBase | None:
        return self.get_element("style:footer-style")  # type: ignore

    def set_footer_style(self, new_style: StyleBase) -> None:
        footer_style = self.get_footer_style()
        if footer_style is not None:
            self.delete(footer_style)
        self.append(new_style)

family property writable

family: str | None

name instance-attribute

name = name

page_usage property writable

page_usage: str

__init__

__init__(
    name: str | None = None,
    page_usage: str | None = None,
    **kwargs: Any,
) -> None

Create a StylePageLayout.

The name is not mandatory at this point but will become required when inserting in a document as a automatic style.

The page_usage attribute specifies the type of pages that a page master should generate. Allowed values are: “all” (default), “left”, “mirrored”, “right”.

To set properties, pass them as keyword arguments.

Args:

name -- str

page_usage -- str

Source code in odfdo/page_layout.py

def __init__(
    self,
    name: str | None = None,
    page_usage: str | None = None,
    **kwargs: Any,
) -> None:
    """Create a StylePageLayout.

    The name is not mandatory at this point but will become required when inserting in a document as a automatic style.

    The page_usage attribute specifies the type of pages that a page master should generate. Allowed values are: "all" (default), "left", "mirrored", "right".

    To set properties, pass them as keyword arguments.

    Args:

        name -- str

        page_usage -- str
    """
    self._family = "page-layout"
    tag_or_elem = kwargs.get("tag_or_elem")
    if tag_or_elem is None:
        kwargs["tag"] = "style:page-layout"
    Element.__init__(self, **kwargs)
    if self._do_init:
        kwargs.pop("tag", None)
        kwargs.pop("tag_or_elem", None)
        if name:
            self.name = name
        if page_usage:
            self.page_usage = page_usage

del_properties

del_properties(
    properties: list[str] | None = None,
    area: str | None = None,
) -> None

Delete the given properties, either by list argument or positional argument (or both).

Args:

properties -- list

area -- "page-layout"

Source code in odfdo/page_layout.py

def del_properties(
    self,
    properties: list[str] | None = None,
    area: str | None = None,
) -> None:
    """Delete the given properties, either by list argument or positional
    argument (or both).

    Args:

        properties -- list

        area -- "page-layout"
    """
    return super().del_properties(properties=properties, area="page-layout")

get_footer_style

get_footer_style() -> StyleBase | None

Source code in odfdo/page_layout.py

def get_footer_style(self) -> StyleBase | None:
    return self.get_element("style:footer-style")  # type: ignore

get_header_style

get_header_style() -> StyleBase | None

Source code in odfdo/page_layout.py

def get_header_style(self) -> StyleBase | None:
    return self.get_element("style:header-style")  # type: ignore

get_properties

get_properties(
    area: str | None = "page-layout",
) -> dict[str, str | dict] | None

Get the mapping of page-layout properties of StylePageLayout.

Args:

area -- str (unused, kept for compatibility)

Returns: dict

Source code in odfdo/page_layout.py

def get_properties(
    self, area: str | None = "page-layout"
) -> dict[str, str | dict] | None:
    """Get the mapping of page-layout properties of StylePageLayout.

    Args:

        area -- str (unused, kept for compatibility)

    Returns: dict
    """
    return super().get_properties(area="page-layout")

set_background

set_background(
    color: str | None = None,
    url: str | None = None,
    position: str | None = "center",
    repeat: str | None = None,
    opacity: str | int | None = None,
    filter: str | None = None,
) -> None

Set the background color of the page layout.

With no argument, remove any existing background.

The values of the position attribute are “left”, “center”, “right”, “top”, “bottom”, or two white space separated values, that may appear in any order. One of these values is one of: “left”, “center” or “right”. The other value is one of: “top”, “center” or “bottom”. The default value for this attribute is “center”.

The repeat value is one of ‘no-repeat’, ‘repeat’ or ‘stretch’.

The opacity is a percentage integer (not a string with the ‘%’ sign)

The filter is an application-specific filter name defined elsewhere.

Args:

color -- '#rrggbb'

url -- str

position -- str

repeat -- str

opacity -- int

filter -- str

Source code in odfdo/page_layout.py

def set_background(
    self,
    color: str | None = None,
    url: str | None = None,
    position: str | None = "center",
    repeat: str | None = None,
    opacity: str | int | None = None,
    filter: str | None = None,  # noqa: A002
) -> None:
    """Set the background color of the page layout.

    With no argument, remove any existing background.

    The values of the position attribute are "left", "center", "right", "top", "bottom", or two white space separated values, that may appear in any order. One of these values is one of: "left", "center" or "right". The other value is one of: "top", "center" or "bottom". The default value for this attribute is "center".

    The repeat value is one of 'no-repeat', 'repeat' or 'stretch'.

    The opacity is a percentage integer (not a string with the '%' sign)

    The filter is an application-specific filter name defined elsewhere.

    Args:

        color -- '#rrggbb'

        url -- str

        position -- str

        repeat -- str

        opacity -- int

        filter -- str
    """
    _set_background(self, color, url, position, repeat, opacity, filter)

set_footer_style

set_footer_style(new_style: StyleBase) -> None

Source code in odfdo/page_layout.py

def set_footer_style(self, new_style: StyleBase) -> None:
    footer_style = self.get_footer_style()
    if footer_style is not None:
        self.delete(footer_style)
    self.append(new_style)

set_header_style

set_header_style(new_style: StyleBase) -> None

Source code in odfdo/page_layout.py

def set_header_style(self, new_style: StyleBase) -> None:
    header_style = self.get_header_style()
    if header_style is not None:
        self.delete(header_style)
    self.append(new_style)

set_properties

set_properties(
    properties: dict[str, str | dict] | None = None,
    style: StyleBase | None = None,
    area: str | None = None,
    **kwargs: Any,
) -> None

Set the properties of the page-layout.

Properties are given either as a dict or as named arguments (or both). The area is identical to the style family by default. If the properties element is missing, it is created.

Instead of properties, you can pass a style with properties of a page-layout style. These will be copied.

Args:

properties -- dict

style -- StylePageLayout

area -- "page-layout"

Source code in odfdo/page_layout.py

def set_properties(
    self,
    properties: dict[str, str | dict] | None = None,
    style: StyleBase | None = None,
    area: str | None = None,
    **kwargs: Any,
) -> None:
    """Set the properties of the page-layout.

    Properties are given either as a dict or as named arguments (or both). The area is identical to the style family by default. If the properties element is missing, it is created.

    Instead of properties, you can pass a style with properties of a page-layout style. These will be copied.

    Args:

        properties -- dict

        style -- StylePageLayout

        area -- "page-layout"
    """
    return super().set_properties(
        properties=properties, style=style, area="page-layout", **kwargs
    )

Styles

Bases: XmlPart

Representation of the “styles.xml” part.

Methods:

Name	Description
get_master_page
get_style	Return the style uniquely identified by the name/family pair.
get_styles	Return the list of styles in the Styles part, optionally limited to
set_default_styles_language_country	Set the default language in styles, in format “en-US”.

Attributes:

Name	Type	Description
default_language	str	Get or set the default language from styles, in format “en-US”.
default_styles	list[StyleBase]	Return the list of default styles “style:default-styles”.
master_pages	list[StyleMasterPage]
office_automatic_styles	OfficeAutomaticStyles | None
office_master_styles	OfficeMasterStyles | None

Source code in odfdo/styles.py

class Styles(XmlPart):
    """Representation of the "styles.xml" part."""

    def _get_style_contexts(
        self, family: str, automatic: bool = False
    ) -> list[Element]:
        if automatic:
            elems = [self.get_element("//office:automatic-styles")]
        elif family:
            queries = CONTEXT_MAPPING.get(family) or (
                "//office:styles",
                "//office:automatic-styles",
            )
            elems = [self.get_element(query) for query in queries]
        else:
            # All possibilities
            elems = [
                self.get_element("//office:automatic-styles"),
                self.get_element("//office:styles"),
                self.get_element("//office:master-styles"),
                self.get_element("//office:font-face-decls"),
            ]
        return [e for e in elems if isinstance(e, Element)]

    def get_styles(self, family: str = "", automatic: bool = False) -> list[StyleBase]:
        """Return the list of styles in the Styles part, optionally limited to
        the given family, optionally limited to automatic styles.

        Args:

            family -- str

            automatic -- bool

        Returns: list of Style
        """
        result = []
        for context in self._get_style_contexts(family, automatic=automatic):
            if context is None:  # pragma: nocover
                continue
            # print('-ctx----', automatic)
            # print(context.tag)
            # print(context.__class__)
            # print(context.serialize())
            result.extend(context.get_styles(family=family))
        return result

    @property
    def default_styles(self) -> list[StyleBase]:
        """Return the list of default styles "style:default-styles".

        Returns: list of Style
        """
        result: list[StyleBase] = self.get_elements("//style:default-style")  # type: ignore[assignment]

        return result

    def set_default_styles_language_country(self, value: str) -> None:
        """Set the default language in styles, in format "en-US"."""
        language = str(value)
        if not is_RFC3066(language):
            msg = 'Language must be "xx" lang or "xx-YY" lang-COUNTRY code (RFC3066)'
            raise TypeError(msg)
        lc = language.split("-")
        if len(lc) == 2:
            lang, country = lc
        else:
            lang = lc[0]
            country = ""
        styles = [
            s for s in self.default_styles if s.family in {"graphic", "paragraph"}
        ]
        for style in styles:
            props = style.get_properties(area="text") or {}
            props["language"] = lang
            props["country"] = country
            style.set_properties(props, area="text")

    @property
    def default_language(self) -> str:
        """Get or set the default language from styles, in format "en-US"."""
        styles = [s for s in self.default_styles if s.family == "paragraph"]
        if not styles:
            return ""
        style = styles[0]
        props = style.get_properties(area="text") or {}
        lang = str(props.get("fo:language", ""))
        country = str(props.get("fo:country", ""))
        if lang and country:
            return f"{lang}-{country}"
        return lang or country

    @default_language.setter
    def default_language(self, value: str) -> None:
        return self.set_default_styles_language_country(value)

    def get_style(
        self,
        family: str,
        name_or_element: str | StyleBase | None = None,
        display_name: str | None = None,
    ) -> StyleBase | None:
        """Return the style uniquely identified by the name/family pair.

        If the argument is already a style object, it will return it.
        If the name is None, the default style is fetched.
        If the name is not the internal name but the name you gave in the
        desktop application, use display_name instead.

        Args:

            family -- 'paragraph', 'text', 'graphic', 'table', 'list',
                      'number', 'page-layout', 'master-page'

            name_or_element -- str, odf_style or None

            display_name -- str or None

        Returns: odf_style or None if not found
        """
        for context in self._get_style_contexts(family):
            if context is None:
                continue  # pragma: nocover
            style = context.get_style(
                family,
                name_or_element=name_or_element,
                display_name=display_name,
            )
            if style is not None:
                return style
        return None

    @property
    def office_master_styles(self) -> OfficeMasterStyles | None:
        return self.get_element("//office:master-styles")  # type: ignore[return-value]

    @office_master_styles.setter
    def office_master_styles(self, office_master_styles: OfficeMasterStyles) -> None:
        current = self.office_master_styles
        if isinstance(current, OfficeMasterStyles):
            current.delete()
        self.root.append(office_master_styles)

    @property
    def master_pages(self) -> list[StyleMasterPage]:
        master_styles = self.office_master_styles
        if master_styles is None:
            return []
        return [
            e  # type: ignore[misc]
            for e in master_styles.children
            if isinstance(e, StyleBase) and e.tag == "style:master-page"
        ]

    def get_master_page(self, position: int = 0) -> StyleMasterPage | None:
        results = self.master_pages
        try:
            return results[position]
        except IndexError:
            return None

    @property
    def office_automatic_styles(self) -> OfficeAutomaticStyles | None:
        return self.get_element("//office:automatic-styles")  # type: ignore[return-value]

    @office_automatic_styles.setter
    def office_automatic_styles(
        self, office_automatic_styles: OfficeAutomaticStyles
    ) -> None:
        current = self.office_automatic_styles
        if isinstance(current, OfficeAutomaticStyles):
            current.delete()
        self.root.append(office_automatic_styles)

default_language property writable

default_language: str

Get or set the default language from styles, in format “en-US”.

default_styles property

default_styles: list[StyleBase]

Return the list of default styles “style:default-styles”.

Returns: list of Style

master_pages property

master_pages: list[StyleMasterPage]

office_automatic_styles property writable

office_automatic_styles: OfficeAutomaticStyles | None

office_master_styles property writable

office_master_styles: OfficeMasterStyles | None

get_master_page

get_master_page(
    position: int = 0,
) -> StyleMasterPage | None

Source code in odfdo/styles.py

def get_master_page(self, position: int = 0) -> StyleMasterPage | None:
    results = self.master_pages
    try:
        return results[position]
    except IndexError:
        return None

get_style

get_style(
    family: str,
    name_or_element: str | StyleBase | None = None,
    display_name: str | None = None,
) -> StyleBase | None

Return the style uniquely identified by the name/family pair.

If the argument is already a style object, it will return it. If the name is None, the default style is fetched. If the name is not the internal name but the name you gave in the desktop application, use display_name instead.

Args:

family -- 'paragraph', 'text', 'graphic', 'table', 'list',
          'number', 'page-layout', 'master-page'

name_or_element -- str, odf_style or None

display_name -- str or None

Returns: odf_style or None if not found

Source code in odfdo/styles.py

def get_style(
    self,
    family: str,
    name_or_element: str | StyleBase | None = None,
    display_name: str | None = None,
) -> StyleBase | None:
    """Return the style uniquely identified by the name/family pair.

    If the argument is already a style object, it will return it.
    If the name is None, the default style is fetched.
    If the name is not the internal name but the name you gave in the
    desktop application, use display_name instead.

    Args:

        family -- 'paragraph', 'text', 'graphic', 'table', 'list',
                  'number', 'page-layout', 'master-page'

        name_or_element -- str, odf_style or None

        display_name -- str or None

    Returns: odf_style or None if not found
    """
    for context in self._get_style_contexts(family):
        if context is None:
            continue  # pragma: nocover
        style = context.get_style(
            family,
            name_or_element=name_or_element,
            display_name=display_name,
        )
        if style is not None:
            return style
    return None

get_styles

get_styles(
    family: str = "", automatic: bool = False
) -> list[StyleBase]

Return the list of styles in the Styles part, optionally limited to the given family, optionally limited to automatic styles.

Args:

family -- str

automatic -- bool

Returns: list of Style

Source code in odfdo/styles.py

def get_styles(self, family: str = "", automatic: bool = False) -> list[StyleBase]:
    """Return the list of styles in the Styles part, optionally limited to
    the given family, optionally limited to automatic styles.

    Args:

        family -- str

        automatic -- bool

    Returns: list of Style
    """
    result = []
    for context in self._get_style_contexts(family, automatic=automatic):
        if context is None:  # pragma: nocover
            continue
        # print('-ctx----', automatic)
        # print(context.tag)
        # print(context.__class__)
        # print(context.serialize())
        result.extend(context.get_styles(family=family))
    return result

set_default_styles_language_country

set_default_styles_language_country(value: str) -> None

Set the default language in styles, in format “en-US”.

Source code in odfdo/styles.py

def set_default_styles_language_country(self, value: str) -> None:
    """Set the default language in styles, in format "en-US"."""
    language = str(value)
    if not is_RFC3066(language):
        msg = 'Language must be "xx" lang or "xx-YY" lang-COUNTRY code (RFC3066)'
        raise TypeError(msg)
    lc = language.split("-")
    if len(lc) == 2:
        lang, country = lc
    else:
        lang = lc[0]
        country = ""
    styles = [
        s for s in self.default_styles if s.family in {"graphic", "paragraph"}
    ]
    for style in styles:
        props = style.get_properties(area="text") or {}
        props["language"] = lang
        props["country"] = country
        style.set_properties(props, area="text")

TOC

Bases: MDToc, Element

A table of content, “text:table-of-content”.

The “text:table-of-content” element represents a table of contents for a document. The items that can be listed in a table of contents are:

• Headings (as defined by the outline structure of the document), up to a selected level.

• Table of contents index marks.

• Paragraphs formatted with specified paragraph styles.

Methods:

Name	Description
__init__	Create a table of content “text:table-of-content”.
create_toc_source
fill	Fill the TOC with the titles found in the document. A TOC is not
get_formatted_text
get_title
set_toc_title

Attributes:

Name	Type	Description
body	Element | None
name
outline_level	int | None
protected
style

Source code in odfdo/toc.py

class TOC(MDToc, Element):
    """A table of content, "text:table-of-content".

    The "text:table-of-content" element represents a table of contents for a
    document. The items that can be listed in a table of contents are:

      - Headings (as defined by the outline structure of the document), up to
        a selected level.

      - Table of contents index marks.

      - Paragraphs formatted with specified paragraph styles.
    """

    _tag = "text:table-of-content"
    _properties = (
        PropDef("name", "text:name"),
        PropDef("style", "text:style-name"),
        PropDef("xml_id", "xml:id"),
        PropDef("protected", "text:protected"),
        PropDef("protection_key", "text:protection-key"),
        PropDef(
            "protection_key_digest_algorithm", "text:protection-key-digest-algorithm"
        ),
    )

    def __init__(
        self,
        title: str = "Table of Contents",
        name: str | None = None,
        protected: bool = True,
        outline_level: int = 0,
        style: str | None = None,
        title_style: str = "Contents_20_Heading",
        entry_style: str = "Contents_20_%d",
        **kwargs: Any,
    ) -> None:
        """Create a table of content "text:table-of-content".

        Default parameters are what most people use: protected from manual
        modifications and not limited in title levels.

        The name is mandatory and derived automatically from the title if not
        given. Provide one in case of a conflict with other TOCs in the same
        document.

        The "text:table-of-content" element has the following attributes:
        text:name, text:protected, text:protection-key,
        text:protection-key-digest-algorithm, text:style-name and xml:id.

        Args:

            title -- str

            name -- str

            protected -- bool

            outline_level -- int

            style -- str

            title_style -- str

            entry_style -- str
        """
        super().__init__(**kwargs)
        if self._do_init:
            if style:
                self.style = style
            if protected:
                self.protected = protected
            if name is None:
                self.name = f"{title}1"
            # Create the source template
            toc_source = self.create_toc_source(
                title, outline_level, title_style, entry_style
            )
            self.append(toc_source)
            # Create the index body automatically with the index title
            if title:
                # This style is in the template document
                self.set_toc_title(title, text_style=title_style)

    @staticmethod
    def create_toc_source(
        title: str,
        outline_level: int,
        title_style: str,
        entry_style: str,
    ) -> Element:
        toc_source = Element.from_tag("text:table-of-content-source")
        toc_source.set_attribute("text:outline-level", str(outline_level))
        if title:
            title_template = IndexTitleTemplate()
            if title_style:
                # This style is in the template document
                title_template.style = title_style
            title_template.text = title
            toc_source.append(title_template)
        for level in range(1, 11):
            template = TocEntryTemplate(outline_level=level)
            if entry_style:
                template.style = entry_style % level
            toc_source.append(template)
        return toc_source

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

    def get_formatted_text(self, context: dict | None = None) -> str:
        index_body = self.get_element("text:index-body")

        if index_body is None:
            return ""
        if context is None:
            context = {}
        if context.get("rst_mode"):
            return "\n.. contents::\n\n"

        result = []
        for element in index_body.children:
            if element.tag == "text:index-title":
                for child_element in element.children:
                    result.append(child_element.get_formatted_text(context).strip())
            else:
                result.append(element.get_formatted_text(context).strip())
        return "\n".join(x for x in result if x)

    @property
    def outline_level(self) -> int | None:
        source = self.get_element("text:table-of-content-source")
        if source is None:
            return None
        return source.get_attribute_integer("text:outline-level")

    @outline_level.setter
    def outline_level(self, level: int) -> None:
        source = self.get_element("text:table-of-content-source")
        if source is None:
            source = Element.from_tag("text:table-of-content-source")
            self.insert(source, FIRST_CHILD)
        source.set_attribute("text:outline-level", str(level))

    @property
    def body(self) -> Element | None:
        return self.get_element("text:index-body")

    @body.setter
    def body(self, body: Element | None = None) -> Element | None:
        old_body = self.body
        if old_body is not None:
            self.delete(old_body)
        if body is None:
            body = Element.from_tag("text:index-body")
        self.append(body)
        return body

    def get_title(self) -> str:
        index_body = self.body
        if index_body is None:
            return ""
        index_title = index_body.get_element(IndexTitle._tag)
        if index_title is None:
            return ""
        return index_title.text_content

    def set_toc_title(
        self,
        title: str,
        style: str | None = None,
        text_style: str | None = None,
    ) -> None:
        index_body = self.body
        if index_body is None:
            self.body = None
            index_body = self.body
        index_title = index_body.get_element(IndexTitle._tag)  # type: ignore
        if index_title is None:
            name = f"{self.name}_Head"
            index_title = IndexTitle(
                name=name, style=style, title_text=title, text_style=text_style
            )
            index_body.append(index_title)  # type: ignore
        else:
            if style:
                index_title.style = style  # type: ignore
            paragraph = index_title.get_paragraph()
            if paragraph is None:
                paragraph = Paragraph()
                index_title.append(paragraph)
            if text_style:
                paragraph.style = text_style
            paragraph.text = title

    @staticmethod
    def _header_numbering(level_indexes: dict[int, int], level: int) -> str:
        """Return the header hierarchical number (like "1.2.3.")."""
        numbers: list[int] = []
        # before header level
        for idx in range(1, level):
            numbers.append(level_indexes.setdefault(idx, 1))
        # header level
        index = level_indexes.get(level, 0) + 1
        level_indexes[level] = index
        numbers.append(index)
        # after header level
        idx = level + 1
        while idx in level_indexes:
            del level_indexes[idx]
            idx += 1
        return ".".join(str(x) for x in numbers) + "."

    def fill(
        self,
        document: Document | None = None,
        use_default_styles: bool = True,
    ) -> None:
        """Fill the TOC with the titles found in the document. A TOC is not
        contextual so it will catch all titles before and after its insertion.
        If the TOC is not attached to a document, attach it beforehand or
        provide one as argument.

        For having a pretty TOC, let use_default_styles by default.

        Args:

            document -- Document

            use_default_styles -- bool
        """
        # Find the body
        if document is not None:
            body: Element | None = document.body
        else:
            body = self.document_body
        if body is None:
            raise ValueError("The TOC must be related to a document somehow")

        # Save the title
        index_body = self.body
        if index_body is None:
            title = ""
        else:
            title = index_body.get_element("text:index-title")  # type: ignore

        # Clean the old index-body
        self.body = None
        index_body = self.body

        # Restore the title
        if title and str(title):
            index_body.insert(title, position=0)  # type: ignore

        # Insert default TOC style
        if use_default_styles:
            automatic_styles = body.get_element("//office:automatic-styles")
            if isinstance(automatic_styles, Element):  # pragma: nocover
                for level in range(1, 11):
                    if (
                        automatic_styles.get_style(
                            "paragraph", _toc_entry_style_name(level)
                        )
                        is None
                    ):
                        level_style = default_toc_level_style(level)
                        automatic_styles.append(level_style)

        # Auto-fill the index
        outline_level = self.outline_level or 10
        level_indexes: dict[int, int] = {}
        for header in body.headers:
            level = header.get_attribute_integer("text:outline-level") or 0
            if level > outline_level:
                continue
            number_str = self._header_numbering(level_indexes, level)
            # Make the title with "1.2.3. Title" format
            paragraph = Paragraph(f"{number_str} {header}")
            if use_default_styles:
                paragraph.style = _toc_entry_style_name(level)
            index_body.append(paragraph)  # type: ignore

body property writable

body: Element | None

name instance-attribute

name = f'{title}1'

outline_level property writable

outline_level: int | None

protected instance-attribute

protected = protected

style instance-attribute

style = style

__init__

__init__(
    title: str = "Table of Contents",
    name: str | None = None,
    protected: bool = True,
    outline_level: int = 0,
    style: str | None = None,
    title_style: str = "Contents_20_Heading",
    entry_style: str = "Contents_20_%d",
    **kwargs: Any,
) -> None

Create a table of content “text:table-of-content”.

Default parameters are what most people use: protected from manual modifications and not limited in title levels.

The name is mandatory and derived automatically from the title if not given. Provide one in case of a conflict with other TOCs in the same document.

The “text:table-of-content” element has the following attributes: text:name, text:protected, text:protection-key, text:protection-key-digest-algorithm, text:style-name and xml:id.

Args:

title -- str

name -- str

protected -- bool

outline_level -- int

style -- str

title_style -- str

entry_style -- str

Source code in odfdo/toc.py

def __init__(
    self,
    title: str = "Table of Contents",
    name: str | None = None,
    protected: bool = True,
    outline_level: int = 0,
    style: str | None = None,
    title_style: str = "Contents_20_Heading",
    entry_style: str = "Contents_20_%d",
    **kwargs: Any,
) -> None:
    """Create a table of content "text:table-of-content".

    Default parameters are what most people use: protected from manual
    modifications and not limited in title levels.

    The name is mandatory and derived automatically from the title if not
    given. Provide one in case of a conflict with other TOCs in the same
    document.

    The "text:table-of-content" element has the following attributes:
    text:name, text:protected, text:protection-key,
    text:protection-key-digest-algorithm, text:style-name and xml:id.

    Args:

        title -- str

        name -- str

        protected -- bool

        outline_level -- int

        style -- str

        title_style -- str

        entry_style -- str
    """
    super().__init__(**kwargs)
    if self._do_init:
        if style:
            self.style = style
        if protected:
            self.protected = protected
        if name is None:
            self.name = f"{title}1"
        # Create the source template
        toc_source = self.create_toc_source(
            title, outline_level, title_style, entry_style
        )
        self.append(toc_source)
        # Create the index body automatically with the index title
        if title:
            # This style is in the template document
            self.set_toc_title(title, text_style=title_style)

create_toc_source staticmethod

create_toc_source(
    title: str,
    outline_level: int,
    title_style: str,
    entry_style: str,
) -> Element

Source code in odfdo/toc.py

@staticmethod
def create_toc_source(
    title: str,
    outline_level: int,
    title_style: str,
    entry_style: str,
) -> Element:
    toc_source = Element.from_tag("text:table-of-content-source")
    toc_source.set_attribute("text:outline-level", str(outline_level))
    if title:
        title_template = IndexTitleTemplate()
        if title_style:
            # This style is in the template document
            title_template.style = title_style
        title_template.text = title
        toc_source.append(title_template)
    for level in range(1, 11):
        template = TocEntryTemplate(outline_level=level)
        if entry_style:
            template.style = entry_style % level
        toc_source.append(template)
    return toc_source

fill

fill(
    document: Document | None = None,
    use_default_styles: bool = True,
) -> None

Fill the TOC with the titles found in the document. A TOC is not contextual so it will catch all titles before and after its insertion. If the TOC is not attached to a document, attach it beforehand or provide one as argument.

For having a pretty TOC, let use_default_styles by default.

Args:

document -- Document

use_default_styles -- bool

Source code in odfdo/toc.py

def fill(
    self,
    document: Document | None = None,
    use_default_styles: bool = True,
) -> None:
    """Fill the TOC with the titles found in the document. A TOC is not
    contextual so it will catch all titles before and after its insertion.
    If the TOC is not attached to a document, attach it beforehand or
    provide one as argument.

    For having a pretty TOC, let use_default_styles by default.

    Args:

        document -- Document

        use_default_styles -- bool
    """
    # Find the body
    if document is not None:
        body: Element | None = document.body
    else:
        body = self.document_body
    if body is None:
        raise ValueError("The TOC must be related to a document somehow")

    # Save the title
    index_body = self.body
    if index_body is None:
        title = ""
    else:
        title = index_body.get_element("text:index-title")  # type: ignore

    # Clean the old index-body
    self.body = None
    index_body = self.body

    # Restore the title
    if title and str(title):
        index_body.insert(title, position=0)  # type: ignore

    # Insert default TOC style
    if use_default_styles:
        automatic_styles = body.get_element("//office:automatic-styles")
        if isinstance(automatic_styles, Element):  # pragma: nocover
            for level in range(1, 11):
                if (
                    automatic_styles.get_style(
                        "paragraph", _toc_entry_style_name(level)
                    )
                    is None
                ):
                    level_style = default_toc_level_style(level)
                    automatic_styles.append(level_style)

    # Auto-fill the index
    outline_level = self.outline_level or 10
    level_indexes: dict[int, int] = {}
    for header in body.headers:
        level = header.get_attribute_integer("text:outline-level") or 0
        if level > outline_level:
            continue
        number_str = self._header_numbering(level_indexes, level)
        # Make the title with "1.2.3. Title" format
        paragraph = Paragraph(f"{number_str} {header}")
        if use_default_styles:
            paragraph.style = _toc_entry_style_name(level)
        index_body.append(paragraph)  # type: ignore

get_formatted_text

get_formatted_text(context: dict | None = None) -> str

Source code in odfdo/toc.py

def get_formatted_text(self, context: dict | None = None) -> str:
    index_body = self.get_element("text:index-body")

    if index_body is None:
        return ""
    if context is None:
        context = {}
    if context.get("rst_mode"):
        return "\n.. contents::\n\n"

    result = []
    for element in index_body.children:
        if element.tag == "text:index-title":
            for child_element in element.children:
                result.append(child_element.get_formatted_text(context).strip())
        else:
            result.append(element.get_formatted_text(context).strip())
    return "\n".join(x for x in result if x)

get_title

get_title() -> str

Source code in odfdo/toc.py

def get_title(self) -> str:
    index_body = self.body
    if index_body is None:
        return ""
    index_title = index_body.get_element(IndexTitle._tag)
    if index_title is None:
        return ""
    return index_title.text_content

set_toc_title

set_toc_title(
    title: str,
    style: str | None = None,
    text_style: str | None = None,
) -> None

Source code in odfdo/toc.py

def set_toc_title(
    self,
    title: str,
    style: str | None = None,
    text_style: str | None = None,
) -> None:
    index_body = self.body
    if index_body is None:
        self.body = None
        index_body = self.body
    index_title = index_body.get_element(IndexTitle._tag)  # type: ignore
    if index_title is None:
        name = f"{self.name}_Head"
        index_title = IndexTitle(
            name=name, style=style, title_text=title, text_style=text_style
        )
        index_body.append(index_title)  # type: ignore
    else:
        if style:
            index_title.style = style  # type: ignore
        paragraph = index_title.get_paragraph()
        if paragraph is None:
            paragraph = Paragraph()
            index_title.append(paragraph)
        if text_style:
            paragraph.style = text_style
        paragraph.text = title

Tab

Bases: MDTab, Element

Representation of a tabulation, “text:tab”.

This element represents the [UNICODE] tab character (HORIZONTAL TABULATION, U+0009).

The position attribute contains the number of the tab-stop to which a tab character refers. The position 0 marks the start margin of a paragraph. Note: The position attribute is only a hint to help non-layout oriented consumers to determine the tab/tab-stop association. Layout oriented consumers should determine the tab positions based on the style information

Methods:

Name	Description
__init__	Representation of a tabulation, “text:tab”.

Attributes:

Name	Type	Description
position
text	str	Return “\t”.

Source code in odfdo/tab.py

class Tab(MDTab, Element):
    """Representation of a tabulation, "text:tab".

    This element represents the [UNICODE] tab character (HORIZONTAL TABULATION,
    U+0009).

    The position attribute contains the number of the tab-stop to which a tab
    character refers. The position 0 marks the start margin of a paragraph.
    Note: The position attribute is only a hint to help non-layout oriented
    consumers to determine the tab/tab-stop association. Layout oriented
    consumers should determine the tab positions based on the style information
    """

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

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

        Args:

            position -- int
        """
        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:
        """Return "\\t"."""
        return "\t"

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

position instance-attribute

position = str(position)

text property writable

text: str

Return “\t”.

__init__

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

Representation of a tabulation, “text:tab”.

Args:

position -- int

Source code in odfdo/tab.py

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

    Args:

        position -- int
    """
    super().__init__(**kwargs)
    if self._do_init and position is not None and position >= 0:
        self.position = str(position)

TabStopStyle

Bases: Element

Base style for a TOC entryBase style for a TOC entry, “style:tab- stop”.

Methods:

Name	Description
__init__	Create style for a TOC entryBase style for a TOC entry “style:tab-

Attributes:

Name	Type	Description
leader_color
leader_style
leader_text
leader_text_style
leader_type
leader_width
style_char
style_position
style_type

Source code in odfdo/toc.py

class TabStopStyle(Element):
    """Base style for a TOC entryBase style for a TOC entry, "style:tab-
    stop".
    """

    _tag = "style:tab-stop"
    _properties = (
        PropDef("style_char", "style:char"),
        PropDef("leader_color", "style:leader-color"),
        PropDef("leader_style", "style:leader-style"),
        PropDef("leader_text", "style:leader-text"),
        PropDef("leader_text_style", "style:leader-text-style"),
        PropDef("leader_type", "style:leader-type"),
        PropDef("leader_width", "style:leader-width"),
        PropDef("style_position", "style:position"),
        PropDef("style_type", "style:type"),
    )

    def __init__(
        self,
        style_char: str | None = None,
        leader_color: str | None = None,
        leader_style: str | None = None,
        leader_text: str | None = None,
        leader_text_style: str | None = None,
        leader_type: str | None = None,
        leader_width: str | None = None,
        style_position: str | None = None,
        style_type: str | None = None,
        **kwargs: Any,
    ):
        """Create style for a TOC entryBase style for a TOC entry "style:tab-
        stop".
        """
        super().__init__(**kwargs)
        if self._do_init:
            if style_char:
                self.style_char = style_char
            if leader_color:
                self.leader_color = leader_color
            if leader_style:
                self.leader_style = leader_style
            if leader_text:
                self.leader_text = leader_text
            if leader_text_style:
                self.leader_text_style = leader_text_style
            if leader_type:
                self.leader_type = leader_type
            if leader_width:
                self.leader_width = leader_width
            if style_position:
                self.style_position = style_position
            if style_type:
                self.style_type = style_type
        else:
            pass  # pragma: nocover

leader_color instance-attribute

leader_color = leader_color

leader_style instance-attribute

leader_style = leader_style

leader_text instance-attribute

leader_text = leader_text

leader_text_style instance-attribute

leader_text_style = leader_text_style

leader_type instance-attribute

leader_type = leader_type

leader_width instance-attribute

leader_width = leader_width

style_char instance-attribute

style_char = style_char

style_position instance-attribute

style_position = style_position

style_type instance-attribute

style_type = style_type

__init__

__init__(
    style_char: str | None = None,
    leader_color: str | None = None,
    leader_style: str | None = None,
    leader_text: str | None = None,
    leader_text_style: str | None = None,
    leader_type: str | None = None,
    leader_width: str | None = None,
    style_position: str | None = None,
    style_type: str | None = None,
    **kwargs: Any,
)

Create style for a TOC entryBase style for a TOC entry “style:tab- stop”.

Source code in odfdo/toc.py

def __init__(
    self,
    style_char: str | None = None,
    leader_color: str | None = None,
    leader_style: str | None = None,
    leader_text: str | None = None,
    leader_text_style: str | None = None,
    leader_type: str | None = None,
    leader_width: str | None = None,
    style_position: str | None = None,
    style_type: str | None = None,
    **kwargs: Any,
):
    """Create style for a TOC entryBase style for a TOC entry "style:tab-
    stop".
    """
    super().__init__(**kwargs)
    if self._do_init:
        if style_char:
            self.style_char = style_char
        if leader_color:
            self.leader_color = leader_color
        if leader_style:
            self.leader_style = leader_style
        if leader_text:
            self.leader_text = leader_text
        if leader_text_style:
            self.leader_text_style = leader_text_style
        if leader_type:
            self.leader_type = leader_type
        if leader_width:
            self.leader_width = leader_width
        if style_position:
            self.style_position = style_position
        if style_type:
            self.style_type = style_type
    else:
        pass  # pragma: nocover

Table

Bases: MDTable, Element

A table, in a spreadsheet or other document, “table:table”.

Methods:

Name	Description
__init__	Create a table element “table:table”, optionally prefilled with
append	Dispatch .append() call to append_row() or append_column().
append_cell	Append the given cell at the “y” coordinate. Repeated cells are
append_column	Append the column at the end of the table. If no column is given, an
append_named_range	Append the named range to the document.
append_row	Append the row at the end of the table. If no row is given, an empty
clear	Remove text, children and attributes from the Row.
del_span	Delete a Cell Span. ‘area’ is the cell coordinate of the upper left
delete_cell	Delete the cell at the given coordinates, so that next cells are
delete_column	Delete the column at the given position. ODF columns don’t contain
delete_named_range	Delete the Named Range of specified name.
delete_row	Delete the row at the given “y” position.
extend_rows	Append a list of rows at the end of the table.
from_csv	Import the CSV text content into a Table.
get_cell	Get the cell at the given coordinates.
get_cells	Get the cells matching the criteria. If ‘coord’ is None, parse the
get_column	Get the column at the given “x” position.
get_column_cells	Get the list of cells at the given position.
get_column_values	Shortcut to get the list of Python values for the cells at the given
get_columns	Get the list of columns matching the criteria.
get_elements
get_formatted_text
get_named_range	Return the Name Range of the specified name.
get_named_ranges	Return the list of Name Ranges.
get_row	Get the row at the given “y” position.
get_row_sub_elements	Shortcut to get the list of Elements values for the cells of the row
get_row_values	Shortcut to get the list of Python values for the cells of the row
get_rows	Get the list of rows matching the criteria.
get_value	Shortcut to get the Python value of the cell at the given
get_values	Get a matrix of values of the table.
insert_cell	Insert the given cell at the given coordinates. If no cell is given,
insert_column	Insert the column before the given “x” position. If no column is
insert_row	Insert the row before the given “y” position. If no row is given, an
is_column_empty	Return wether every cell in the column at “x” position has no value
is_empty	Return whether every cell in the table has no value or the value
is_row_empty	Return wether every cell in the row at the given “y” position has no
iter_columns	Yield as many column elements as expected columns in the table, i.e.
iter_rows	Yield as many row elements as expected rows in the table, i.e.
iter_values	Yield lines (lists) of Python values of the table.
optimize_width	Remove in-place empty rows below and empty cells at the right of
rstrip	Remove in-place empty rows below and empty cells at the right of
set_cell	Replace a cell of the table at the given coordinates.
set_cell_image	Deprecated, see related recipes to achieve the desired result.
set_cells	Set the cells in the table, from the ‘coord’ position.
set_column	Replace the column at the given “x” position.
set_column_cells	Shortcut to set the list of cells at the given position.
set_column_values	Shortcut to set the list of Python values of cells at the given
set_named_range	Create a Named Range element and insert it in the document.
set_row	Replace the row at the given position with the new one. Repetitions of
set_row_cells	Shortcut to set all the cells of the row at the given “y”
set_row_values	Shortcut to set the values of all cells of the row at the given
set_span	Create a Cell Span : span the first cell of the area on several
set_value	Set the Python value of the cell at the given coordinates.
set_values	Set the value of cells in the table, from the ‘coord’ position with
to_csv	Export the table as CSV.
transpose	Swap in-place rows and columns of the table.

Attributes:

Name	Type	Description
cells	list	Get all cells of the table.
columns	list[Column]	Get the list of all columns matching the criteria.
height	int	Get the current height of the table.
name	str | None	Get / set the name of the table.
print_ranges	list[str]
printable	bool
protected	bool
protection_key	str | None
row_groups	list[RowGroup]	Get the list of all RowGroup.
rows	list[Row]	Get the list of all rows.
set_protection_key
size	tuple[int, int]	Shortcut to get the current width and height of the table.
style	str | None	Get / set the style of the table.
traverse
traverse_columns
width	int	Get the current width of the table, measured on columns.

Source code in odfdo/table.py

class Table(MDTable, Element):
    """A table, in a spreadsheet or other document, "table:table"."""

    _tag = "table:table"
    _append = Element.append

    def __init__(
        self,
        name: str | None = None,
        width: int | str | None = None,
        height: int | str | None = None,
        protected: bool = False,
        protection_key: str | None = None,
        printable: bool = True,
        print_ranges: list[str] | None = None,
        style: str | None = None,
        **kwargs: Any,
    ) -> None:
        """Create a table element "table:table", optionally prefilled with
        "height" rows of "width" cells each.

        The "name" parameter is required and cannot contain []*?:/ or \\
        characters, ' (apostrophe) cannot be the first or last character.

        If the table is to be protected, a protection key must be provided,
        i.e. a hash value of the password.

        If the table must not be printed, set "printable" to False. The table
        will not be printed when it is not displayed, whatever the value of
        this argument.

        Ranges of cells to print can be provided as a list of cell ranges,
        e.g. ['E6:K12', 'P6:R12'] or directly as a raw string, e.g.
        "E6:K12 P6:R12".

        You can access and modify the XML tree manually, but you probably want
        to use the API to access and alter cells. It will save you from
        handling repetitions and the same number of cells for each row.

        If you use both the table API and the XML API, you are on your own for
        ensuring model integrity.

        Args:

            name -- str

            width -- int | str

            height -- int | str

            protected -- bool

            protection_key -- str

            printable -- bool

            print_ranges -- list

            style -- str
        """
        super().__init__(**kwargs)
        self._table_cache = TableCache()
        if self._do_init:
            self.name = name or ""
            if protected:
                self.protected = protected
                self.set_protection_key = protection_key
            if not printable:
                self.printable = printable
            if print_ranges:
                self.print_ranges = print_ranges
            if style:
                self.style = style
            # Prefill the table
            if width is not None or height is not None:
                width = int(width or 1)
                height = int(height or 1)
                # Column groups for style information
                columns = Column(repeated=width)
                self._append(columns)
                for _i in range(height):
                    row = Row(width)
                    self._append(row)
        self._compute_table_cache()

    def __str__(self) -> str:
        def write_content(csv_writer: object) -> None:
            for values in self.iter_values():
                line = []
                for value in values:
                    if value is None:
                        value = ""
                    if isinstance(value, str):
                        value = value.strip()
                    line.append(value)
                csv_writer.writerow(line)  # type: ignore[attr-defined]

        out = StringIO(newline=os.linesep)
        csv_writer = csv.writer(
            out,
            delimiter=" ",
            doublequote=False,
            escapechar="\\",
            lineterminator=os.linesep,
            quotechar='"',
            quoting=csv.QUOTE_NONNUMERIC,
        )
        write_content(csv_writer)
        return out.getvalue()

    def get_elements(self, xpath_query: XPath | str) -> list[Element]:
        if isinstance(xpath_query, str):
            elements = xpath_return_elements(
                xpath_compile(xpath_query),
                self._Element__element,  # type: ignore[attr-defined]
            )
        else:
            elements = xpath_return_elements(
                xpath_query,
                self._Element__element,  # type: ignore[attr-defined]
            )
        cache = (self._table_cache, None)
        return [Element.from_tag_for_clone(e, cache) for e in elements]

    def _copy_cache(self, cache: tuple | None) -> None:
        """Copy cache when cloning."""
        self._table_cache = cache[0]  # type:ignore[index]

    def clear(self) -> None:
        """Remove text, children and attributes from the Row."""
        self._Element__element.clear()  # type:ignore[attr-defined]
        self._table_cache = TableCache()

    def _translate_y_from_any(self, y: str | int) -> int:
        # "3" (counting from 1) -> 2 (counting from 0)
        return translate_from_any(y, self.height, 1)

    def _translate_table_coordinates_list(
        self,
        coord: tuple | list,
    ) -> tuple[int | None, ...]:
        height = self.height
        width = self.width
        # assuming we got int values
        if len(coord) == 1:
            # It is a row
            y = coord[0]
            if y and y < 0:
                y = increment(y, height)
            return (None, y, None, y)
        if len(coord) == 2:
            # It is a row range, not a cell, because context is table
            y = coord[0]
            if y and y < 0:
                y = increment(y, height)
            t = coord[1]
            if t and t < 0:
                t = increment(t, height)
            return (None, y, None, t)
        # should be 4 int
        x, y, z, t = coord
        if x and x < 0:
            x = increment(x, width)
        if y and y < 0:
            y = increment(y, height)
        if z and z < 0:
            z = increment(z, width)
        if t and t < 0:
            t = increment(t, height)
        return (x, y, z, t)

    def _translate_table_coordinates_str(
        self,
        coord_str: str,
    ) -> tuple[int | None, ...]:
        height = self.height
        width = self.width
        coord = convert_coordinates(coord_str)
        if len(coord) == 2:
            x, y = coord
            if x and x < 0:
                x = increment(x, width)
            if y and y < 0:
                y = increment(y, height)
            # extent to an area :
            return (x, y, x, y)
        x, y, z, t = coord
        if x and x < 0:
            x = increment(x, width)
        if y and y < 0:
            y = increment(y, height)
        if z and z < 0:
            z = increment(z, width)
        if t and t < 0:
            t = increment(t, height)
        return (x, y, z, t)

    def _translate_table_coordinates(
        self,
        coord: tuple | list | str,
    ) -> tuple[int | None, ...]:
        if isinstance(coord, str):
            return self._translate_table_coordinates_str(coord)
        return self._translate_table_coordinates_list(coord)

    def _translate_column_coordinates_str(
        self,
        coord_str: str,
    ) -> tuple[int | None, ...]:
        width = self.width
        height = self.height
        coord = convert_coordinates(coord_str)
        if len(coord) == 2:
            x, y = coord
            if x and x < 0:
                x = increment(x, width)
            if y and y < 0:
                y = increment(y, height)
            # extent to an area :
            return (x, y, x, y)
        x, y, z, t = coord
        if x and x < 0:
            x = increment(x, width)
        if y and y < 0:
            y = increment(y, height)
        if z and z < 0:
            z = increment(z, width)
        if t and t < 0:
            t = increment(t, height)
        return (x, y, z, t)

    def _translate_column_coordinates_list(
        self,
        coord: tuple | list,
    ) -> tuple[int | None, ...]:
        width = self.width
        height = self.height
        # assuming we got int values
        if len(coord) == 1:
            # It is a column
            x = coord[0]
            if x and x < 0:
                x = increment(x, width)
            return (x, None, x, None)
        if len(coord) == 2:
            # It is a column range, not a cell, because context is table
            x = coord[0]
            if x and x < 0:
                x = increment(x, width)
            z = coord[1]
            if z and z < 0:
                z = increment(z, width)
            return (x, None, z, None)
        # should be 4 int
        x, y, z, t = coord
        if x and x < 0:
            x = increment(x, width)
        if y and y < 0:
            y = increment(y, height)
        if z and z < 0:
            z = increment(z, width)
        if t and t < 0:
            t = increment(t, height)
        return (x, y, z, t)

    def _translate_column_coordinates(
        self,
        coord: tuple | list | str,
    ) -> tuple[int | None, ...]:
        if isinstance(coord, str):
            return self._translate_column_coordinates_str(coord)
        return self._translate_column_coordinates_list(coord)

    def _translate_cell_coordinates(
        self,
        coord: tuple | list | str,
    ) -> tuple[int | None, int | None]:
        # we want an x,y result
        coord = convert_coordinates(coord)
        if len(coord) == 2:
            x, y = coord
        # If we got an area, take the first cell
        elif len(coord) == 4:
            x, y, _z, _t = coord
        else:
            raise ValueError(str(coord))
        if x and x < 0:
            x = increment(x, self.width)
        if y and y < 0:
            y = increment(y, self.height)
        return (x, y)

    def _compute_table_cache(self) -> None:
        idx_repeated_seq = self.elements_repeated_sequence(
            _XP_ROW, "table:number-rows-repeated"
        )
        self._table_cache.make_row_map(idx_repeated_seq)
        idx_repeated_seq = self.elements_repeated_sequence(
            _XP_COLUMN, "table:number-columns-repeated"
        )
        self._table_cache.make_col_map(idx_repeated_seq)

    def _update_width(self, row: Row) -> None:
        """Synchronize the number of columns if the row is bigger.

        Append, don't insert, not to disturb the current layout.
        """
        diff = row.width - self.width
        if diff > 0:
            self.append_column(Column(repeated=diff))

    def _get_formatted_text_normal(self, context: dict | None) -> str:
        result = []
        for row in self.iter_rows():
            for cell in row.iter_cells():
                value = cell.get_value(try_get_text=False)
                # None ?
                if value is None:
                    # Try with get_formatted_text on the elements
                    value = []
                    for element in cell.children:
                        value.append(element.get_formatted_text(context))
                    value = "".join(value)
                else:
                    value = str(value)
                result.append(value)
                result.append("\n")
            result.append("\n")
        return "".join(result)

    def _get_formatted_text_rst(self, context: dict) -> str:
        context["no_img_level"] += 1
        # Strip the table => We must clone
        table: Table = self.clone  # type: ignore[assignment]
        table.rstrip(aggressive=True)

        # Fill the rows
        rows = []
        cols_nb = 0
        cols_size: dict[int, int] = {}
        for odf_row in table.iter_rows():
            row = []
            for i, cell in enumerate(odf_row.iter_cells()):
                value = cell.get_value(try_get_text=False)
                # None ?
                if value is None:
                    # Try with get_formatted_text on the elements
                    value = []
                    for element in cell.children:
                        value.append(element.get_formatted_text(context))
                    value = "".join(value)
                else:
                    value = str(value)
                value = value.strip()
                # Strip the empty columns
                if value:
                    cols_nb = max(cols_nb, i + 1)
                # Compute the size of each columns (at least 2)
                cols_size[i] = max(cols_size.get(i, 2), len(value))
                # Append
                row.append(value)
            rows.append(row)

        # Nothing ?
        if cols_nb == 0:
            return ""

        # Prevent a crash with empty columns (by example with images)
        for col, size in cols_size.items():
            if size == 0:
                cols_size[col] = 1

        # Update cols_size
        LINE_MAX = 100
        COL_MIN = 16

        free_size = LINE_MAX - (cols_nb - 1) * 3 - 4
        real_size = sum(cols_size[i] for i in range(cols_nb))
        if real_size > free_size:
            factor = float(free_size) / real_size

            for i in range(cols_nb):
                old_size = cols_size[i]

                # The cell is already small
                if old_size <= COL_MIN:
                    continue

                new_size = int(factor * old_size)

                if new_size < COL_MIN:
                    new_size = COL_MIN
                cols_size[i] = new_size

        # Convert !
        result: list[str] = [""]
        # Construct the first/last line
        line: list[str] = []
        for i in range(cols_nb):
            line.append("=" * cols_size[i])
            line.append(" ")
        line_str = "".join(line)

        # Add the lines
        result.append(line_str)
        for row in rows:
            # Wrap the row
            wrapped_row = []
            for i, value in enumerate(row[:cols_nb]):
                wrapped_value = []
                for part in value.split("\n"):
                    # Hack to handle correctly the lists or the directives
                    subsequent_indent = ""
                    part_lstripped = part.lstrip()
                    if part_lstripped.startswith("-") or part_lstripped.startswith(
                        ".."
                    ):
                        subsequent_indent = " " * (len(part) - len(part.lstrip()) + 2)
                    wrapped_part = wrap(
                        part, width=cols_size[i], subsequent_indent=subsequent_indent
                    )
                    if wrapped_part:
                        wrapped_value.extend(wrapped_part)
                    else:
                        wrapped_value.append("")
                wrapped_row.append(wrapped_value)

            # Append!
            for j in range(max([1] + [len(values) for values in wrapped_row])):
                txt_row: list[str] = []
                for i in range(cols_nb):
                    values = wrapped_row[i] if i < len(wrapped_row) else []

                    # An empty cell ?
                    if len(values) - 1 < j or not values[j]:
                        if i == 0 and j == 0:
                            txt_row.append("..")
                            txt_row.append(" " * (cols_size[i] - 1))
                        else:
                            txt_row.append(" " * (cols_size[i] + 1))
                        continue

                    # Not empty
                    value = values[j]
                    txt_row.append(value)
                    txt_row.append(" " * (cols_size[i] - len(value) + 1))
                result.append("".join(txt_row))

        result.append(line_str)
        result.append("")
        result.append("")
        result_str = "\n".join(result)

        context["no_img_level"] -= 1
        return result_str

    def _translate_x_from_any(self, x: str | int) -> int:
        return translate_from_any(x, self.width, 0)

    #
    # Public API
    #

    def append(self, something: Element | str) -> None:
        """Dispatch .append() call to append_row() or append_column()."""
        if isinstance(something, Row):
            self.append_row(something)
        elif isinstance(something, Column):
            self.append_column(something)
        else:
            # probably still an error
            self._append(something)

    @property
    def height(self) -> int:
        """Get the current height of the table.

        Returns: int
        """
        return self._table_cache.height()

    @property
    def width(self) -> int:
        """Get the current width of the table, measured on columns.

        Rows may have different widths, use the Table API to ensure width
        consistency.

        Returns: int
        """
        # Columns are our reference for user expected width
        return self._table_cache.width()

    @property
    def size(self) -> tuple[int, int]:
        """Shortcut to get the current width and height of the table.

        Returns: (int, int)
        """
        return self.width, self.height

    @property
    def name(self) -> str | None:
        """Get / set the name of the table.

        The "name" parameter is required and cannot contain []*?:/ or \\
        characters, ' (apostrophe) cannot be the first or last character.
        """
        return self.get_attribute_string("table:name")

    @name.setter
    def name(self, name: str | None) -> None:
        name = table_name_check(name)
        # first, update named ranges
        # fixme : delete name ranges when deleting table, too.
        for named_range in self.get_named_ranges(table_name=self.name):
            named_range.set_table_name(name)
        self.set_attribute("table:name", name)

    @property
    def protected(self) -> bool:
        return bool(self.get_attribute("table:protected"))

    @protected.setter
    def protected(self, protect: bool) -> None:
        self.set_attribute("table:protected", protect)

    @property
    def protection_key(self) -> str | None:
        return self.get_attribute_string("table:protection-key")

    @protection_key.setter
    def protection_key(self, key: str) -> None:
        self.set_attribute("table:protection-key", key)

    @property
    def printable(self) -> bool:
        printable = self.get_attribute("table:print")
        # Default value
        if printable is None:
            return True
        return bool(printable)

    @printable.setter
    def printable(self, printable: bool) -> None:
        self.set_attribute("table:print", printable)

    @property
    def print_ranges(self) -> list[str]:
        ranges = self.get_attribute_string("table:print-ranges")
        if isinstance(ranges, str):
            return ranges.split()
        return []

    @print_ranges.setter
    def print_ranges(self, ranges: list[str] | None) -> None:
        if isinstance(ranges, (list, tuple)):
            self.set_attribute("table:print-ranges", " ".join(ranges))
        else:
            self.set_attribute("table:print-ranges", ranges)

    @property
    def style(self) -> str | None:
        """Get / set the style of the table.

        Returns: str
        """
        return self.get_attribute_string("table:style-name")

    @style.setter
    def style(self, style: str | Style) -> None:
        self.set_style_attribute("table:style-name", style)

    def get_formatted_text(self, context: dict | None = None) -> str:
        if context and context["rst_mode"]:
            return self._get_formatted_text_rst(context)
        return self._get_formatted_text_normal(context)

    def get_values(
        self,
        coord: tuple | list | str | None = None,
        cell_type: str | None = None,
        complete: bool = True,
        get_type: bool = False,
        flat: bool = False,
    ) -> list:
        """Get a matrix of values of the table.

        Filter by coordinates will parse the area defined by the coordinates.

        If 'cell_type' is used and 'complete' is True (default), missing values
        are replaced by None.
        Filter by ' cell_type = "all" ' will retrieve cells of any
        type, aka non empty cells.

        If 'cell_type' is None, complete is always True : with no cell type
        queried, get_values() returns None for each empty cell, the length
        each lists is equal to the width of the table.

        If get_type is True, returns tuples (value, ODF type of value), or
        (None, None) for empty cells with complete True.

        If flat is True, the methods return a single list of all the values.
        By default, flat is False.

        Args:

            coord -- str or tuple of int : coordinates of area

            cell_type -- 'boolean', 'float', 'date', 'string', 'time',
                         'currency', 'percentage' or 'all'

            complete -- boolean

            get_type -- boolean

        Returns: list of lists of Python types
        """
        if coord:
            x, y, z, t = self._translate_table_coordinates(coord)
        else:
            x = y = z = t = None
        data = []
        for row in self.iter_rows(start=y, end=t):
            if z is None:
                width = self.width
            else:
                width = min(z + 1, self.width)
            if x is not None:
                width -= x
            values = row.get_values(
                (x, z),
                cell_type=cell_type,
                complete=complete,
                get_type=get_type,
            )
            # complete row to match request width
            if complete:
                if get_type:
                    values.extend([(None, None)] * (width - len(values)))
                else:
                    values.extend([None] * (width - len(values)))
            if flat:
                data.extend(values)
            else:
                data.append(values)
        return data

    def iter_values(
        self,
        coord: tuple | list | str | None = None,
        cell_type: str | None = None,
        complete: bool = True,
        get_type: bool = False,
    ) -> Iterator[list]:
        """Yield lines (lists) of Python values of the table.

        Filter by coordinates will parse the area defined by the coordinates.

        cell_type, complete, grt_type : see get_values()



        Args:

            coord -- str or tuple of int : coordinates of area

            cell_type -- 'boolean', 'float', 'date', 'string', 'time',
                         'currency', 'percentage' or 'all'

            complete -- boolean

            get_type -- boolean

        Returns: iterator of lists
        """
        if coord:
            x, y, z, t = self._translate_table_coordinates(coord)
        else:
            x = y = z = t = None
        for row in self.iter_rows(start=y, end=t):
            if z is None:
                width = self.width
            else:
                width = min(z + 1, self.width)
            if x is not None:
                width -= x
            values = row.get_values(
                (x, z),
                cell_type=cell_type,
                complete=complete,
                get_type=get_type,
            )
            # complete row to match column width
            if complete:
                if get_type:
                    values.extend([(None, None)] * (width - len(values)))
                else:
                    values.extend([None] * (width - len(values)))
            yield values

    def set_values(
        self,
        values: list,
        coord: tuple | list | str | None = None,
        style: str | None = None,
        cell_type: str | None = None,
        currency: str | None = None,
    ) -> None:
        """Set the value of cells in the table, from the 'coord' position with
        values.

        'coord' is the coordinate of the upper left cell to be modified by
        values. If 'coord' is None, default to the position (0,0) ("A1").
        If 'coord' is an area (e.g. "A2:B5"), the upper left position of this
        area is used as coordinate.

        The table is *not* cleared before the operation, to reset the table
        before setting values, use table.clear().

        A list of lists is expected, with as many lists as rows, and as many
        items in each sublist as cells to be set. None values in the list
        will create empty cells with no cell type (but eventually a style).

        Args:

            coord -- tuple or str

            values -- list of lists of python types

            cell_type -- 'boolean', 'currency', 'date', 'float', 'percentage',
                         'string' or 'time'

            currency -- three-letter str

            style -- str
        """
        if coord:
            x, y = self._translate_cell_coordinates(coord)
        else:
            x = y = 0
        if y is None:
            y = 0
        if x is None:
            x = 0
        y -= 1
        for row_values in values:
            y += 1
            if not row_values:
                continue
            row = self.get_row(y, clone=True)
            repeated = row.repeated or 1
            if repeated >= 2:
                row.repeated = None
            row.set_values(
                row_values,
                start=x,
                cell_type=cell_type,
                currency=currency,
                style=style,
            )
            self.set_row(y, row, clone=False)
            self._update_width(row)

    def rstrip(self, aggressive: bool = False) -> None:
        """Remove *in-place* empty rows below and empty cells at the right of
        the table. Cells are empty if they contain no value or it evaluates to
        False, and no style.

        If aggressive is True, empty cells with style are removed too.

        Argument:

            aggressive -- bool
        """
        # Step 1: remove empty rows below the table
        for row in reversed(self._get_rows()):
            if row.is_empty(aggressive=aggressive):
                row.parent.delete(row)  # type: ignore[union-attr]
            else:
                break
        # Step 2: rstrip remaining rows
        max_width = 0
        for row in self._get_rows():
            row.rstrip(aggressive=aggressive)
            # keep count of the biggest row
            max_width = max(max_width, row.width)
        # raz cache of rows
        self._table_cache.clear_row_indexes()
        # Step 3: trim columns to match max_width
        columns = self._get_columns()
        repeated_cols: list[EText] = self.xpath(  # type: ignore[assignment]
            "table:table-column/@table:number-columns-repeated"
        )
        if not isinstance(repeated_cols, list):
            raise TypeError
        unrepeated = len(columns) - len(repeated_cols)
        column_width = sum(int(r) for r in repeated_cols) + unrepeated
        diff = column_width - max_width
        if diff > 0:
            for column in reversed(columns):
                repeated = column.repeated or 1
                repeated = repeated - diff
                if repeated > 0:
                    column.repeated = repeated
                    break
                else:
                    column.parent.delete(column)  # type: ignore[union-attr]
                    diff = -repeated
                    if diff == 0:
                        break
        # raz cache of columns
        self._table_cache.clear_col_indexes()
        self._compute_table_cache()

    def optimize_width(self) -> None:
        """Remove *in-place* empty rows below and empty cells at the right of
        the table.

        Keep repeated styles of empty cells but minimize row width.
        """
        self._optimize_width_trim_rows()
        width = self._optimize_width_length()
        self._optimize_width_rstrip_rows(width)
        self._optimize_width_adapt_columns(width)

    def _optimize_width_trim_rows(self) -> None:
        count = -1  # to keep one empty row
        for row in reversed(self._get_rows()):
            if row.is_empty(aggressive=False):
                count += 1
            else:
                break
        if count > 0:
            for row in reversed(self._get_rows()):
                row.parent.delete(row)  # type: ignore[union-attr]
                count -= 1
                if count <= 0:
                    break
        try:
            last_row = self._get_rows()[-1]
            last_row._set_repeated(None)
        except IndexError:
            pass
        # raz cache of rows
        self._table_cache.clear_row_indexes()

    def _optimize_width_length(self) -> int:
        try:
            return max(row.minimized_width() for row in self._get_rows())
        except ValueError:
            return 0

    def _optimize_width_rstrip_rows(self, width: int) -> None:
        for row in self._get_rows():
            row.force_width(width)

    def _optimize_width_adapt_columns(self, width: int) -> None:
        # trim columns to match minimal_width
        columns = self._get_columns()
        repeated_cols: list[EText] = self.xpath(  # type: ignore[assignment]
            "table:table-column/@table:number-columns-repeated"
        )
        if not isinstance(repeated_cols, list):
            raise TypeError
        unrepeated = len(columns) - len(repeated_cols)
        column_width = sum(int(r) for r in repeated_cols) + unrepeated
        diff = column_width - width
        if diff > 0:
            for column in reversed(columns):
                repeated = column.repeated or 1
                repeated = repeated - diff
                if repeated > 0:
                    column.repeated = repeated
                    break
                else:
                    column.parent.delete(column)  # type: ignore[union-attr]
                    diff = -repeated
                    if diff == 0:
                        break
        # raz cache of columns
        self._table_cache.clear_col_indexes()
        self._compute_table_cache()

    def transpose(self, coord: tuple | list | str | None = None) -> None:
        """Swap *in-place* rows and columns of the table.

        If 'coord' is not None, apply transpose only to the area defined by the
        coordinates. Beware, if area is not square, some cells mays be over
        written during the process.

        Args:

            coord -- str or tuple of int : coordinates of area

            start -- int or str
        """
        data = []
        if coord is None:
            for row in self.iter_rows():
                data.append(row.cells)
            transposed_data = zip_longest(*data)
            self.clear()
            # new_rows = []
            for row_cells in transposed_data:
                if not isiterable(row_cells):
                    row_cells = (row_cells,)
                row = Row()
                row.extend_cells(row_cells)
                self.append_row(row, clone=False)
            self._compute_table_cache()
        else:
            x, y, z, t = self._translate_table_coordinates(coord)
            if x is None:
                x = 0
            else:
                x = min(x, self.width - 1)
            if z is None:
                z = self.width - 1
            else:
                z = min(z, self.width - 1)
            if y is None:
                y = 0
            else:
                y = min(y, self.height - 1)
            if t is None:
                t = self.height - 1
            else:
                t = min(t, self.height - 1)
            for row in self.iter_rows(start=y, end=t):
                data.append(list(row.iter_cells(start=x, end=z)))
            transposed_data = zip_longest(*data)
            # clear locally
            w = z - x + 1
            h = t - y + 1
            if w != h:
                nones = [[None] * w for i in range(h)]
                self.set_values(nones, coord=(x, y, z, t))
            # put transposed
            filtered_data: list[tuple[Cell]] = []
            for row_cells in transposed_data:
                if isinstance(row_cells, (list, tuple)):
                    filtered_data.append(row_cells)
                else:
                    filtered_data.append((row_cells,))
            self.set_cells(filtered_data, (x, y, x + h - 1, y + w - 1))
            self._compute_table_cache()

    def is_empty(self, aggressive: bool = False) -> bool:
        """Return whether every cell in the table has no value or the value
        evaluates to False (empty string), and no style.

        If aggressive is True, empty cells with style are considered empty.

        Args:

            aggressive -- bool
        """
        return all(row.is_empty(aggressive=aggressive) for row in self._get_rows())

    #
    # Rows
    #

    @property
    def row_groups(self) -> list[RowGroup]:
        """Get the list of all RowGroup.

        Returns: list of RowGroup
        """
        return self.get_elements(_XP_ROW_GROUP)  # type: ignore[return-value]

    def _get_rows(self) -> list[Row]:
        return self.get_elements(_XP_ROW)  # type: ignore[return-value]

    def iter_rows(
        self,
        start: int | None = None,
        end: int | None = None,
    ) -> Iterator[Row]:
        """Yield as many row elements as expected rows in the table, i.e.
        expand repetitions by returning the same row as many times as
        necessary.

        Copies are returned, use set_row() to push them back.

            Args:

                start -- int

                end -- int
        """
        if start is None:
            start = 0
        start = max(0, start)
        if end is None:
            end = 2**32
        if end < start:
            return
        y = -1
        for row in self._yield_odf_rows():
            y += 1
            if y < start:
                continue
            if y > end:
                return
            row.y = y
            yield row

    traverse = iter_rows

    def get_rows(
        self,
        coord: tuple | list | str | None = None,
        style: str | None = None,
        content: str | None = None,
    ) -> list[Row]:
        """Get the list of rows matching the criteria.

        Filter by coordinates will parse the area defined by the coordinates.

        Args:

            coord -- str or tuple of int : coordinates of rows

            content -- str regex

            style -- str

        Returns: list of rows
        """
        if coord:
            _x, y, _z, t = self._translate_table_coordinates(coord)
        else:
            y = t = None
        # fixme : not clones ?
        if not content and not style:
            return list(self.iter_rows(start=y, end=t))
        rows = []
        for row in self.iter_rows(start=y, end=t):
            if content and not row.match(content):
                continue
            if style and style != row.style:
                continue
            rows.append(row)
        return rows

    @property
    def rows(self) -> list[Row]:
        """Get the list of all rows.

        Returns: list of rows
        """
        # fixme : not clones ?
        return list(self.iter_rows())

    def _yield_odf_rows(self) -> Iterator[Row]:
        for row in self._get_rows():
            if row.repeated is None:
                yield row
            else:
                for _ in range(row.repeated):
                    row_copy = row.clone
                    row_copy.repeated = None
                    yield row_copy

    def _get_row2(self, y: int, clone: bool = True, create: bool = True) -> Row:
        if y >= self.height:
            if create:
                return Row()
            raise ValueError("Row not found")
        row = self._get_row2_base(y)
        if row is None:
            raise ValueError("Row not found")
        if clone:
            return row.clone
        return row

    def _get_row2_base(self, y: int) -> Row | None:
        idx = self._table_cache.row_idx(y)
        if idx is None:
            return None
        row: Row | None = self._table_cache.cached_row(idx)
        if row is None:
            row = self._get_element_idx2(_XP_ROW_IDX, idx)  # type: ignore[assignment]
            if row is None:
                return None
            self._table_cache.store_row(row, idx)
        return row

    def get_row(self, y: int | str, clone: bool = True, create: bool = True) -> Row:
        """Get the row at the given "y" position.

        Position start at 0. So cell A4 is on row 3.

        A copy is returned, use set_cell() to push it back.

        Args:

            y -- int or str

        Returns: Row
        """
        # fixme : keep repeat ? maybe an option to functions : "raw=False"
        y = self._translate_y_from_any(y)
        row = self._get_row2(y, clone=clone, create=create)
        if row is None:
            raise ValueError("Row not found")
        row.y = y
        return row

    def set_row(self, y: int | str, row: Row | None = None, clone: bool = True) -> Row:
        """Replace the row at the given position with the new one. Repetitions of
        the old row will be adjusted.

        If row is None, a new empty row is created.

        Position start at 0. So cell A4 is on row 3.

        Args:

            y -- int or str

            row -- Row

        returns the row, with updated row.y
        """
        if row is None:
            row = Row()
            repeated = 1
            clone = False
        else:
            repeated = row.repeated or 1
        y = self._translate_y_from_any(y)
        row.y = y
        # Outside the defined table ?
        diff = y - self.height
        if diff == 0:
            row_back = self.append_row(row, _repeated=repeated, clone=clone)
        elif diff > 0:
            self.append_row(Row(repeated=diff), _repeated=diff, clone=clone)
            row_back = self.append_row(row, _repeated=repeated, clone=clone)
        else:
            # Inside the defined table
            row_back = self._table_cache.set_row_in_cache(y, row, self, clone=clone)
        # print self.serialize(True)
        # Update width if necessary
        self._update_width(row_back)
        return row_back

    def insert_row(
        self, y: str | int, row: Row | None = None, clone: bool = True
    ) -> Row:
        """Insert the row before the given "y" position. If no row is given, an
        empty one is created.

        Position start at 0. So cell A4 is on row 3.

        If row is None, a new empty row is created.

        Args:

            y -- int or str

            row -- Row

        returns the row, with updated row.y
        """
        if row is None:
            row = Row()
            clone = False
        y = self._translate_y_from_any(y)
        diff = y - self.height
        if diff < 0:
            row_back = self._table_cache.insert_row_in_cache(y, row, self)
        elif diff == 0:
            row_back = self.append_row(row, clone=clone)
        else:
            self.append_row(Row(repeated=diff), _repeated=diff, clone=False)
            row_back = self.append_row(row, clone=clone)
        row_back.y = y
        # Update width if necessary
        self._update_width(row_back)
        return row_back

    def extend_rows(self, rows: list[Row] | None = None) -> None:
        """Append a list of rows at the end of the table.

        Args:

            rows -- list of Row
        """
        if rows is None:
            rows = []
        self.extend(rows)
        self._compute_table_cache()
        # Update width if necessary
        width = self.width
        for row in self.iter_rows():
            if row.width > width:
                width = row.width
        diff = width - self.width
        if diff > 0:
            self.append_column(Column(repeated=diff))

    def append_row(
        self,
        row: Row | None = None,
        clone: bool = True,
        _repeated: int | None = None,
    ) -> Row:
        """Append the row at the end of the table. If no row is given, an empty
        one is created.

        Position start at 0. So cell A4 is on row 3.

        Note the columns are automatically created when the first row is
        inserted in an empty table. So better insert a filled row.

        Args:

            row -- Row

            _repeated -- (optional), repeated value of the row

        returns the row, with updated row.y
        """
        if row is None:
            row = Row()
            _repeated = 1
        elif clone:
            row = row.clone
        # Appending a repeated row accepted
        # Do not insert next to the last row because it could be in a group
        self._append(row)
        if _repeated is None:
            _repeated = row.repeated or 1
        self._table_cache.insert_row_map_once(_repeated)
        row.y = self.height - 1
        # Initialize columns
        if not self._get_columns():
            repeated = row.width
            self.insert(Column(repeated=repeated), position=0)
            self._compute_table_cache()
        # Update width if necessary
        self._update_width(row)
        return row

    def delete_row(self, y: int | str) -> None:
        """Delete the row at the given "y" position.

        Position start at 0. So cell A4 is on row 3.

        Args:

            y -- int or str
        """
        y = self._translate_y_from_any(y)
        # Outside the defined table
        if y >= self.height:
            return
        # Inside the defined table
        self._table_cache.delete_row_in_cache(y, self)

    def get_row_values(
        self,
        y: int | str,
        cell_type: str | None = None,
        complete: bool = True,
        get_type: bool = False,
    ) -> list:
        """Shortcut to get the list of Python values for the cells of the row
        at the given "y" position.

        Position start at 0. So cell A4 is on row 3.

        Filter by cell_type, with cell_type 'all' will retrieve cells of any
        type, aka non empty cells.
        If cell_type and complete is True, replace missing values by None.

        If get_type is True, returns a tuple (value, ODF type of value)

        Args:

            y -- int, str

            cell_type -- 'boolean', 'float', 'date', 'string', 'time',
                         'currency', 'percentage' or 'all'

            complete -- boolean

            get_type -- boolean

        Returns: list of lists of Python types
        """
        values = self.get_row(y, clone=False).get_values(
            cell_type=cell_type, complete=complete, get_type=get_type
        )
        # complete row to match column width
        if complete:
            if get_type:
                values.extend([(None, None)] * (self.width - len(values)))
            else:
                values.extend([None] * (self.width - len(values)))
        return values

    def get_row_sub_elements(self, y: int | str) -> list[Any]:
        """Shortcut to get the list of Elements values for the cells of the row
        at the given "y" position.

        Position start at 0. So cell A4 is on row 3.

        Missing values replaced by None.

        Args:

            y -- int, str

        Returns: list of lists of Elements
        """
        values = self.get_row(y, clone=False).get_sub_elements()
        values.extend([None] * (self.width - len(values)))
        return values

    def set_row_values(
        self,
        y: int | str,
        values: list,
        cell_type: str | None = None,
        currency: str | None = None,
        style: str | None = None,
    ) -> Row:
        """Shortcut to set the values of *all* cells of the row at the given
        "y" position.

        Position start at 0. So cell A4 is on row 3.

        Args:

            y -- int or str

            values -- list of Python types

            cell_type -- 'boolean', 'currency', 'date', 'float', 'percentage',
                         'string' or 'time'

            currency -- three-letter str

            style -- str

        returns the row, with updated row.y
        """
        row = Row()  # needed if clones rows
        row.set_values(values, style=style, cell_type=cell_type, currency=currency)
        return self.set_row(y, row)  # needed if clones rows

    def set_row_cells(self, y: int | str, cells: list | None = None) -> Row:
        """Shortcut to set *all* the cells of the row at the given "y"
        position.

        Position start at 0. So cell A4 is on row 3.

        Args:

            y -- int or str

            cells -- list of Python types

            style -- str

        returns the row, with updated row.y
        """
        if cells is None:
            cells = []
        row = Row()  # needed if clones rows
        row.extend_cells(cells)
        return self.set_row(y, row)  # needed if clones rows

    def is_row_empty(self, y: int | str, aggressive: bool = False) -> bool:
        """Return wether every cell in the row at the given "y" position has no
        value or the value evaluates to False (empty string), and no style.

        Position start at 0. So cell A4 is on row 3.

        If aggressive is True, empty cells with style are considered empty.

        Args:

            y -- int or str

            aggressive -- bool
        """
        return self.get_row(y, clone=False).is_empty(aggressive=aggressive)

    #
    # Cells
    #

    def get_cells(
        self,
        coord: tuple | list | str | None = None,
        cell_type: str | None = None,
        style: str | None = None,
        content: str | None = None,
        flat: bool = False,
    ) -> list:
        """Get the cells matching the criteria. If 'coord' is None, parse the
        whole table, else parse the area defined by 'coord'.

        Filter by  cell_type = "all"  will retrieve cells of any
        type, aka non empty cells.

        If flat is True (default is False), the method return a single list
        of all the values, else a list of lists of cells.

        if cell_type, style and content are None, get_cells() will return
        the exact number of cells of the area, including empty cells.

        Args:

            coordinates -- str or tuple of int : coordinates of area

            cell_type -- 'boolean', 'float', 'date', 'string', 'time',
                         'currency', 'percentage' or 'all'

            content -- str regex

            style -- str

            flat -- boolean

        Returns: list of list of Cell
        """
        if coord:
            x, y, z, t = self._translate_table_coordinates(coord)
        else:
            x = y = z = t = None
        if flat:
            cells: list[Cell] = []
            for row in self.iter_rows(start=y, end=t):
                row_cells = row.get_cells(
                    coord=(x, z),
                    cell_type=cell_type,
                    style=style,
                    content=content,
                )
                cells.extend(row_cells)
            return cells
        else:
            lcells: list[list[Cell]] = []
            for row in self.iter_rows(start=y, end=t):
                row_cells = row.get_cells(
                    coord=(x, z),
                    cell_type=cell_type,
                    style=style,
                    content=content,
                )
                lcells.append(row_cells)
            return lcells

    @property
    def cells(self) -> list:
        """Get all cells of the table.

        Returns: list of list of Cell
        """
        lcells: list[list[Cell]] = []
        for row in self.iter_rows():
            lcells.append(row.cells)
        return lcells

    def get_cell(
        self,
        coord: tuple | list | str,
        clone: bool = True,
        keep_repeated: bool = True,
    ) -> Cell:
        """Get the cell at the given coordinates.

        They are either a 2-tuple of (x, y) starting from 0, or a
        human-readable position like "C4".

        A copy is returned, use ``set_cell`` to push it back.

        Args:

            coord -- (int, int) or str

        Returns: Cell
        """
        x, y = self._translate_cell_coordinates(coord)
        if x is None:
            raise ValueError
        if y is None:
            raise ValueError
        # Outside the defined table
        if y >= self.height:
            cell = Cell()
        else:
            # Inside the defined table
            row = self._get_row2_base(y)
            if row is None:
                raise ValueError
            read_cell = row.get_cell(x, clone=clone)
            if read_cell is None:
                raise ValueError
            cell = read_cell
            if not keep_repeated:
                repeated = cell.repeated or 1
                if repeated >= 2:
                    cell.repeated = None
        cell.x = x
        cell.y = y
        return cell

    def get_value(
        self,
        coord: tuple | list | str,
        get_type: bool = False,
    ) -> Any:
        """Shortcut to get the Python value of the cell at the given
        coordinates.

        If get_type is True, returns the tuples (value, ODF type)

        coord is either a 2-tuple of (x, y) starting from 0, or a
        human-readable position like "C4". If an Area is given, the upper
        left position is used as coord.

        Args:

            coord -- (int, int) or str : coordinate

        Returns: Python type
        """
        x, y = self._translate_cell_coordinates(coord)
        if x is None:
            raise ValueError
        if y is None:
            raise ValueError
        # Outside the defined table
        if y >= self.height:
            if get_type:
                return (None, None)
            return None
        else:
            # Inside the defined table
            row = self._get_row2_base(y)
            if row is None:
                raise ValueError
            cell = row._get_cell2_base(x)
            if cell is None:
                if get_type:
                    return (None, None)
                return None
            return cell.get_value(get_type=get_type)

    def set_cell(
        self,
        coord: tuple | list | str,
        cell: Cell | None = None,
        clone: bool = True,
    ) -> Cell:
        """Replace a cell of the table at the given coordinates.

        They are either a 2-tuple of (x, y) starting from 0, or a
        human-readable position like "C4".

        Args:

            coord -- (int, int) or str : coordinate

            cell -- Cell

        return the cell, with x and y updated
        """
        if cell is None:
            cell = Cell()
            clone = False
        x, y = self._translate_cell_coordinates(coord)
        if x is None:
            raise ValueError
        if y is None:
            raise ValueError
        cell.x = x
        cell.y = y
        if y >= self.height:
            row = Row()
            cell_back = row.set_cell(x, cell, clone=clone)
            self.set_row(y, row, clone=False)
        else:
            row_read = self._get_row2_base(y)
            if row_read is None:
                raise ValueError
            row = row_read
            row.y = y
            repeated = row.repeated or 1
            if repeated > 1:
                row = row.clone
                row.repeated = None
                cell_back = row.set_cell(x, cell, clone=clone)
                self.set_row(y, row, clone=False)
            else:
                cell_back = row.set_cell(x, cell, clone=clone)
                # Update width if necessary, since we don't use set_row
                self._update_width(row)
        return cell_back

    def set_cells(
        self,
        cells: list[list[Cell]] | list[tuple[Cell]],
        coord: tuple | list | str | None = None,
        clone: bool = True,
    ) -> None:
        """Set the cells in the table, from the 'coord' position.

        'coord' is the coordinate of the upper left cell to be modified by
        values. If 'coord' is None, default to the position (0,0) ("A1").
        If 'coord' is an area (e.g. "A2:B5"), the upper left position of this
        area is used as coordinate.

        The table is *not* cleared before the operation, to reset the table
        before setting cells, use table.clear().

        A list of lists is expected, with as many lists as rows to be set, and
        as many cell in each sublist as cells to be set in the row.

        Args:

            cells -- list of list of cells

            coord -- tuple or str

            values -- list of lists of python types
        """
        if coord:
            x, y = self._translate_cell_coordinates(coord)
        else:
            x = y = 0
        if y is None:
            y = 0
        if x is None:
            x = 0
        y -= 1
        for row_cells in cells:
            y += 1
            if not row_cells:
                continue
            row = self.get_row(y, clone=True)
            repeated = row.repeated or 1
            if repeated >= 2:
                row.repeated = None
            row.set_cells(row_cells, start=x, clone=clone)
            self.set_row(y, row, clone=False)
            self._update_width(row)

    def set_value(
        self,
        coord: tuple | list | str,
        value: Any,
        cell_type: str | None = None,
        currency: str | None = None,
        style: str | None = None,
    ) -> None:
        """Set the Python value of the cell at the given coordinates.

        They are either a 2-tuple of (x, y) starting from 0, or a
        human-readable position like "C4".

        Args:

            coord -- (int, int) or str

            value -- Python type

            cell_type -- 'boolean', 'currency', 'date', 'float', 'percentage',
                     'string' or 'time'

            currency -- three-letter str

            style -- str
        """
        self.set_cell(
            coord,
            Cell(value, cell_type=cell_type, currency=currency, style=style),
            clone=False,
        )

    def set_cell_image(
        self,
        coord: tuple | list | str,
        image_frame: Frame,
        doc_type: str | None = None,
    ) -> None:
        """Deprecated, see related recipes to achieve the desired result.

        Do all the magic to display an image in the cell at the given
        coordinates.

        They are either a 2-tuple of (x, y) starting from 0, or a
        human-readable position like "C4".

        The frame element must contain the expected image position and
        dimensions.

        DrawImage insertion depends on the document type, so the type must be
        provided or the table element must be already attached to a document.

        Args:

            coord -- (int, int) or str

            image_frame -- Frame including an image

            doc_type -- 'spreadsheet' or 'text'
        """
        warn("Table.set_cell_image() is deprecated", DeprecationWarning, stacklevel=2)
        # Test document type
        if doc_type is None:
            body = self.document_body
            if body is None:
                raise ValueError("document type not found")
            doc_type = {"office:spreadsheet": "spreadsheet", "office:text": "text"}.get(
                body.tag
            )
            if doc_type is None:
                raise ValueError("document type not supported for images")
        # We need the end address of the image
        x, y = self._translate_cell_coordinates(coord)
        if x is None:
            raise ValueError
        if y is None:
            raise ValueError
        cell = self.get_cell((x, y))
        image_frame = image_frame.clone  # type: ignore[assignment]
        # Remove any previous paragraph, frame, etc.
        for child in cell.children:
            cell.delete(child)
        # Now it all depends on the document type
        if doc_type == "spreadsheet":
            image_frame.anchor_type = "char"
            # The frame needs end coordinates
            width, height = image_frame.size
            image_frame.set_attribute("table:end-x", width)
            image_frame.set_attribute("table:end-y", height)
            # FIXME what happens when the address changes?
            address = f"{self.name}.{digit_to_alpha(x)}{y + 1}"
            image_frame.set_attribute("table:end-cell-address", address)
            # The frame is directly in the cell
            cell.append(image_frame)
        elif doc_type == "text":
            # The frame must be in a paragraph
            cell.set_value("")
            paragraph = cell.get_element("text:p")
            if paragraph is None:
                raise ValueError
            paragraph.append(image_frame)
        self.set_cell(coord, cell)

    def insert_cell(
        self,
        coord: tuple | list | str,
        cell: Cell | None = None,
        clone: bool = True,
    ) -> Cell:
        """Insert the given cell at the given coordinates. If no cell is given,
        an empty one is created.

        Coordinates are either a 2-tuple of (x, y) starting from 0, or a
        human-readable position like "C4".

        Cells on the right are shifted. Other rows remain untouched.

        Args:

            coord -- (int, int) or str

            cell -- Cell

        returns the cell with x and y updated
        """
        if cell is None:
            cell = Cell()
            clone = False
        if clone:
            cell = cell.clone
        x, y = self._translate_cell_coordinates(coord)
        if x is None:
            raise ValueError
        if y is None:
            raise ValueError
        row = self._get_row2(y, clone=True)
        row.y = y
        row.repeated = None
        cell_back = row.insert_cell(x, cell, clone=False)
        self.set_row(y, row, clone=False)
        # Update width if necessary
        self._update_width(row)
        return cell_back

    def append_cell(
        self,
        y: int | str,
        cell: Cell | None = None,
        clone: bool = True,
    ) -> Cell:
        """Append the given cell at the "y" coordinate. Repeated cells are
        accepted. If no cell is given, an empty one is created.

        Position start at 0. So cell A4 is on row 3.

        Other rows remain untouched.

        Args:

            y -- int or str

            cell -- Cell

        returns the cell with x and y updated
        """
        if cell is None:
            cell = Cell()
            clone = False
        if clone:
            cell = cell.clone
        y = self._translate_y_from_any(y)
        row = self._get_row2(y)
        row.y = y
        cell_back = row.append_cell(cell, clone=False)
        self.set_row(y, row)
        # Update width if necessary
        self._update_width(row)
        return cell_back

    def delete_cell(self, coord: tuple | list | str) -> None:
        """Delete the cell at the given coordinates, so that next cells are
        shifted to the left.

        Coordinates are either a 2-tuple of (x, y) starting from 0, or a
        human-readable position like "C4".

        Use set_value() for erasing value.

        Args:

            coord -- (int, int) or str
        """
        x, y = self._translate_cell_coordinates(coord)
        if x is None:
            raise ValueError
        if y is None:
            raise ValueError
        # Outside the defined table
        if y >= self.height:
            return
        # Inside the defined table
        row = self._get_row2_base(y)
        if row is None:
            raise ValueError
        row.delete_cell(x)
        # self.set_row(y, row)

    # Columns

    def _get_columns(self) -> list[Column]:
        return self.get_elements(_XP_COLUMN)  # type: ignore[return-value]

    def iter_columns(
        self,
        start: int | None = None,
        end: int | None = None,
    ) -> Iterator[Column]:
        """Yield as many column elements as expected columns in the table, i.e.
        expand repetitions by returning the same column as many times as
        necessary.

            Args:

                start -- int

                end -- int

        Copies are returned, use set_column() to push them back.
        """
        if start is None:
            start = 0
        start = max(0, start)
        if end is None:
            end = 2**32
        if end < start:
            return
        x = -1
        for column in self._yield_odf_columns():
            x += 1
            if x < start:
                continue
            if x > end:
                return
            column.x = x
            yield column

    traverse_columns = iter_columns

    def _yield_odf_columns(self) -> Iterator[Column]:
        for column in self._get_columns():
            if column.repeated is None:
                yield column
            else:
                for _ in range(column.repeated):
                    column_copy = column.clone
                    column_copy.repeated = None
                    yield column_copy

    def get_columns(
        self,
        coord: tuple | list | str | None = None,
        style: str | None = None,
    ) -> list[Column]:
        """Get the list of columns matching the criteria.

        Copies are returned, use set_column() to push them back.

        Args:

            coord -- str or tuple of int : coordinates of columns

            style -- str

        Returns: list of columns
        """
        if coord:
            x, _y, _z, t = self._translate_column_coordinates(coord)
        else:
            x = t = None
        if not style:
            return list(self.iter_columns(start=x, end=t))
        columns = []
        for column in self.iter_columns(start=x, end=t):
            if style != column.style:
                continue
            columns.append(column)
        return columns

    def _get_column2(self, x: int) -> Column | None:
        # Outside the defined table
        if x >= self.width:
            return Column()
        idx = self._table_cache.col_idx(x)
        if idx is None:
            return None
        column = self._table_cache.cached_col(idx)
        if column is None:
            column = self._get_element_idx2(_XP_COLUMN_IDX, idx)  # type:ignore[assignment]
            if column is None:
                return None
            self._table_cache.store_col(column, idx)
        return column.clone

    @property
    def columns(self) -> list[Column]:
        """Get the list of all columns matching the criteria.

        Copies are returned, use set_column() to push them back.

        Returns: list of columns
        """
        return list(self.iter_columns())

    def get_column(self, x: int | str) -> Column:
        """Get the column at the given "x" position.

        ODF columns don't contain cells, only style information.

        Position start at 0. So cell C4 is on column 2. Alphabetical position
        like "C" is accepted.

        A copy is returned, use set_column() to push it back.

        Args:

            x -- int or str

        Returns: Column
        """
        x = self._translate_x_from_any(x)
        column = self._get_column2(x)
        if column is None:
            raise ValueError
        column.x = x
        return column

    def set_column(
        self,
        x: int | str,
        column: Column | None = None,
    ) -> Column:
        """Replace the column at the given "x" position.

        ODF columns don't contain cells, only style information.

        Position start at 0. So cell C4 is on column 2. Alphabetical position
        like "C" is accepted.

        Args:

            x -- int or str

            column -- Column
        """
        x = self._translate_x_from_any(x)
        if column is None:
            column = Column()
            repeated = 1
        else:
            repeated = column.repeated or 1
        column.x = x
        # Outside the defined table ?
        diff = x - self.width
        if diff == 0:
            column_back = self.append_column(column, _repeated=repeated)
        elif diff > 0:
            self.append_column(Column(repeated=diff), _repeated=diff)
            column_back = self.append_column(column, _repeated=repeated)
        else:
            # Inside the defined table
            column_back = self._table_cache.set_col_in_cache(x, column, self)
        return column_back

    def insert_column(
        self,
        x: int | str,
        column: Column | None = None,
    ) -> Column:
        """Insert the column before the given "x" position. If no column is
        given, an empty one is created.

        ODF columns don't contain cells, only style information.

        Position start at 0. So cell C4 is on column 2. Alphabetical position
        like "C" is accepted.

        Args:

            x -- int or str

            column -- Column
        """
        if column is None:
            column = Column()
        x = self._translate_x_from_any(x)
        diff = x - self.width
        if diff < 0:
            column_back = self._table_cache.insert_col_in_cache(x, column, self)
        elif diff == 0:
            column_back = self.append_column(column.clone)
        else:
            self.append_column(Column(repeated=diff), _repeated=diff)
            column_back = self.append_column(column.clone)
        column_back.x = x
        # Repetitions are accepted
        repeated = column.repeated or 1
        # Update width on every row
        for row in self._get_rows():
            if row.width > x:
                row.insert_cell(x, Cell(repeated=repeated))
            # Shorter rows don't need insert
            # Longer rows shouldn't exist!
        return column_back

    def append_column(
        self,
        column: Column | None = None,
        _repeated: int | None = None,
    ) -> Column:
        """Append the column at the end of the table. If no column is given, an
        empty one is created.

        ODF columns don't contain cells, only style information.

        Position start at 0. So cell C4 is on column 2. Alphabetical position
        like "C" is accepted.

        Args:

            column -- Column

            _repeated -- (optional), repeated value of the column
        """
        if column is None:
            column = Column()
            _repeated = 1
        else:
            column = column.clone
        odf_idx = self._table_cache.col_map_length() - 1
        if odf_idx < 0:
            position = 0
        else:
            last_column = self._get_element_idx2(_XP_COLUMN_IDX, odf_idx)
            if last_column is None:
                raise ValueError
            position = self.index(last_column) + 1
        column.x = self.width
        self.insert(column, position=position)
        # Repetitions are accepted
        if _repeated is None:
            _repeated = column.repeated or 1
        self._table_cache.insert_col_map_once(_repeated)
        # No need to update row widths
        return column

    def delete_column(self, x: int | str) -> None:
        """Delete the column at the given position. ODF columns don't contain
        cells, only style information.

        Position start at 0. So cell C4 is on column 2. Alphabetical position
        like "C" is accepted.

        Args:

            x -- int or str
        """
        x = self._translate_x_from_any(x)
        # Outside the defined table
        if x >= self.width:
            return
        # Inside the defined table
        self._table_cache.delete_col_in_cache(x, self)
        # Update width
        width = self.width
        for row in self._get_rows():
            if row.width >= width:
                row.delete_cell(x)

    def get_column_cells(
        self,
        x: int | str,
        style: str | None = None,
        content: str | None = None,
        cell_type: str | None = None,
        complete: bool = False,
    ) -> list[Cell | None]:
        """Get the list of cells at the given position.

        Position start at 0. So cell C4 is on column 2. Alphabetical position
        like "C" is accepted.

        Filter by cell_type, with cell_type 'all' will retrieve cells of any
        type, aka non empty cells.

        If complete is True, replace missing values by None.

        Args:

            x -- int or str

            cell_type -- 'boolean', 'float', 'date', 'string', 'time',
                         'currency', 'percentage' or 'all'

            content -- str regex

            style -- str

            complete -- boolean

        Returns: list of Cell
        """
        x = self._translate_x_from_any(x)
        if cell_type:
            cell_type = cell_type.lower().strip()
        cells: list[Cell | None] = []
        if not style and not content and not cell_type:
            for row in self.iter_rows():
                cells.append(row.get_cell(x, clone=True))
            return cells
        for row in self.iter_rows():
            cell = row.get_cell(x, clone=True)
            if cell is None:
                raise ValueError
            # Filter the cells by cell_type
            if cell_type:
                ctype = cell.type
                if not ctype or not (ctype == cell_type or cell_type == "all"):
                    if complete:
                        cells.append(None)
                    continue
            # Filter the cells with the regex
            if content and not cell.match(content):
                if complete:
                    cells.append(None)
                continue
            # Filter the cells with the style
            if style and style != cell.style:
                if complete:
                    cells.append(None)
                continue
            cells.append(cell)
        return cells

    def get_column_values(
        self,
        x: int | str,
        cell_type: str | None = None,
        complete: bool = True,
        get_type: bool = False,
    ) -> list[Any]:
        """Shortcut to get the list of Python values for the cells at the given
        position.

        Position start at 0. So cell C4 is on column 2. Alphabetical position
        like "C" is accepted.

        Filter by cell_type, with cell_type 'all' will retrieve cells of any
        type, aka non empty cells.
        If cell_type and complete is True, replace missing values by None.

        If get_type is True, returns a tuple (value, ODF type of value)

        Args:

            x -- int or str

            cell_type -- 'boolean', 'float', 'date', 'string', 'time',
                         'currency', 'percentage' or 'all'

            complete -- boolean

            get_type -- boolean

        Returns: list of Python types
        """
        cells = self.get_column_cells(
            x, style=None, content=None, cell_type=cell_type, complete=complete
        )
        values: list[Any] = []
        for cell in cells:
            if cell is None:
                if complete:
                    if get_type:
                        values.append((None, None))
                    else:
                        values.append(None)
                continue
            if cell_type:
                ctype = cell.type
                if not ctype or not (ctype == cell_type or cell_type == "all"):
                    if complete:
                        if get_type:
                            values.append((None, None))
                        else:
                            values.append(None)
                    continue
            values.append(cell.get_value(get_type=get_type))
        return values

    def set_column_cells(self, x: int | str, cells: list[Cell]) -> None:
        """Shortcut to set the list of cells at the given position.

        Position start at 0. So cell C4 is on column 2. Alphabetical position
        like "C" is accepted.

        The list must have the same length than the table height.

        Args:

            x -- int or str

            cells -- list of Cell
        """
        height = self.height
        if len(cells) != height:
            raise ValueError(f"col mismatch: {height} cells expected")
        cells_iterator = iter(cells)
        for y, row in enumerate(self.iter_rows()):
            row.set_cell(x, next(cells_iterator))
            self.set_row(y, row)

    def set_column_values(
        self,
        x: int | str,
        values: list,
        cell_type: str | None = None,
        currency: str | None = None,
        style: str | None = None,
    ) -> None:
        """Shortcut to set the list of Python values of cells at the given
        position.

        Position start at 0. So cell C4 is on column 2. Alphabetical position
        like "C" is accepted.

        The list must have the same length than the table height.

        Args:

            x -- int or str

            values -- list of Python types

            cell_type -- 'boolean', 'currency', 'date', 'float', 'percentage',
                         'string' or 'time'

            currency -- three-letter str

            style -- str
        """
        cells = [
            Cell(value, cell_type=cell_type, currency=currency, style=style)
            for value in values
        ]
        self.set_column_cells(x, cells)

    def is_column_empty(self, x: int | str, aggressive: bool = False) -> bool:
        """Return wether every cell in the column at "x" position has no value
        or the value evaluates to False (empty string), and no style.

        Position start at 0. So cell C4 is on column 2. Alphabetical position
        like "C" is accepted.

        If aggressive is True, empty cells with style are considered empty.

        Returns: bool
        """
        for cell in self.get_column_cells(x):
            if cell is None:
                continue
            if not cell.is_empty(aggressive=aggressive):
                return False
        return True

    # Named Range
    def _local_named_ranges(self) -> list[NamedRange]:
        """(internal) Return the list of local Name Ranges."""
        named_ranges = self.get_elements(
            "descendant::table:named-expressions/table:named-range"
        )
        return named_ranges  # type: ignore[return-value]

    def _local_named_range(self, name: str) -> NamedRange | None:
        """(internal) Return the local Name Range of the specified name."""
        named_range = self.get_elements(
            f'descendant::table:named-expressions/table:named-range[@table:name="{name}"][1]'
        )
        if named_range:
            return named_range[0]  # type: ignore[return-value]
        else:
            return None

    def _local_append_named_range(self, named_range: NamedRange) -> None:
        """(internal) Append the named range to the current table."""
        named_expressions = self.get_element("table:named-expressions")
        if not named_expressions:
            named_expressions = Element.from_tag("table:named-expressions")
            self._Element__append(named_expressions)  # type: ignore[attr-defined]
        # exists ?
        current = named_expressions.get_element(
            f'table:named-range[@table:name="{named_range.name}"][1]'
        )
        if current:
            named_expressions.delete(current)
        named_expressions._Element__append(named_range)  # type: ignore[attr-defined]

    def _local_set_named_range(
        self, name: str, crange: str | tuple | list, usage: str | None = None
    ) -> None:
        """(internal) Create a Named Range element and insert it in the current
        table.
        """
        named_range = NamedRange(name, crange, self.name, usage)
        self._local_append_named_range(named_range)

    def _local_delete_named_range(self, name: str) -> None:
        """(internal) Delete the Named Range of specified name."""
        named_range = self._local_named_range(name)
        if not named_range:
            return
        named_range.delete()
        named_expressions = self.get_element("table:named-expressions")
        if not named_expressions:
            return
        element = named_expressions._Element__element  # type: ignore[attr-defined]
        children = list(element.iterchildren())
        if not children:
            self.delete(named_expressions)

    def get_named_ranges(
        self,
        table_name: str | list[str] | None = None,
        global_scope: bool = True,
    ) -> list[NamedRange]:
        """Return the list of Name Ranges.

        If "global_scope" is True (default), search in the entire document, else limit search to the current Table. If "table_name" is provided, limits the search to these tables.

        Named ranges can be local to the Table or global. Global named ranges are stored at the body level, thus do not call this method on a cloned table if you need to access to the global named ranges.

        Args:

            table_names -- str or list of str, names of tables

            global_scope -- bool, search in entire document or in the current table.

        Returns : list of NamedRange
        """
        if global_scope:
            body = self.document_body
            if not body or body.tag not in BODY_NR_TAGS:
                return []
            named_ranges = body.get_named_ranges()  # type: ignore[attr-defined]
        else:
            named_ranges = self._local_named_ranges()
        if not table_name:
            return named_ranges  # type: ignore[no-any-return]
        filter_ = []
        if isinstance(table_name, str):
            filter_.append(table_name)
        elif isiterable(table_name):
            filter_.extend(table_name)
        else:
            msg = f"table_name must be string or Iterable, not {type(table_name)!r}"
            raise ValueError(msg)
        return [nr for nr in named_ranges if nr.table_name in filter_]

    def get_named_range(
        self, name: str, global_scope: bool = True
    ) -> NamedRange | None:
        """Return the Name Range of the specified name.

        If "global_scope" is True (default), search in the entire document, else limit search to the current Table.

        Named ranges can be local to the Table or global. Global named ranges are stored at the body level, thus do not call this method on a cloned table if you need to access to the global named ranges.

        Args:

            name -- str, name of the named range object

            global_scope -- bool, search in entire document or in the current table.

        Returns : NamedRange or None
        """
        if global_scope:
            body = self.document_body
            if not body:
                raise ValueError("Table is not inside a document")
            if body.tag not in BODY_NR_TAGS:
                return None
            nr: NamedRange | None = body.get_named_range(name)  # type: ignore[attr-defined]

        else:
            nr = self._local_named_range(name)
        return nr

    def append_named_range(
        self, named_range: NamedRange, global_scope: bool = True
    ) -> None:
        """Append the named range to the document.

        An existing named range of same name is replaced.

        If "global_scope" is True (default), append in the document body, else to the current Table.

        Named ranges can be local to the Table or global. Global named ranges are stored at the body level, thus do not call this method on a cloned table if you need to access to the global named ranges.

        Args:

            named_range --  NamedRange

            global_scope -- bool, search in entire document or in the current table.
        """
        if global_scope:
            body = self.document_body
            if not body:
                raise ValueError("Table is not inside a document")
            if body.tag not in BODY_NR_TAGS:
                msg = (
                    "Document must be of type Chart, Drawing, "
                    "Presentation, Spreadsheet or Text"
                )
                raise TypeError(msg)
            body.append_named_range(named_range)  # type: ignore[attr-defined]
        else:
            self._local_append_named_range(named_range)

    def set_named_range(
        self,
        name: str,
        crange: str | tuple | list,
        table_name: str | None = None,
        usage: str | None = None,
        global_scope: bool = True,
    ) -> None:
        """Create a Named Range element and insert it in the document.

        An existing named range of same name is replaced.

        If "global_scope" is True (default), insert in the document's body, else to the current Table. If "table_name" is None, use current table name.

        Named ranges can be local to the Table or global. Global named ranges are stored at the body level, thus do not call this method on a cloned table if you need to access to the global named ranges.

        Args:

            name -- str, name of the named range

            crange -- str or tuple of int, cell or area coordinate

            table_name -- str or None, name of the table

            usage -- None or 'print-range', 'filter', 'repeat-column', 'repeat-row'

            global_scope -- bool, search in entire document or in the current table.
        """
        name = name.strip()
        if not name:
            raise ValueError("Name required")
        if global_scope:
            body = self.document_body
            if not body:
                raise ValueError("Table is not inside a document")
            if body.tag not in BODY_NR_TAGS:
                msg = (
                    "Document must be of type Chart, Drawing, "
                    "Presentation, Spreadsheet or Text"
                )
                raise TypeError(msg)
            if not table_name:
                table_name = self.name
            body.set_named_range(  # type: ignore[attr-defined]
                name=name,
                crange=crange,
                table_name=table_name,
                usage=usage,
            )
        else:
            self._local_set_named_range(name=name, crange=crange, usage=usage)

    def delete_named_range(self, name: str, global_scope: bool = True) -> None:
        """Delete the Named Range of specified name.

        If "global_scope" is True (default), search in the entire document, else limit search to the current Table.

        Named ranges can be local to the Table or global. Global named ranges are stored at the body level, thus do not call this method on a cloned table if you need to access to the global named ranges.

        Args:

            name -- str

            global_scope -- bool, search in entire document or in the current table.
        """
        name = name.strip()
        if not name:
            raise ValueError("Name required")
        if global_scope:
            body = self.document_body
            if not body:
                raise ValueError("Table is not inside a document")
            if body.tag not in BODY_NR_TAGS:
                msg = (
                    "Document must be of type Chart, Drawing, "
                    "Presentation, Spreadsheet or Text"
                )
                raise TypeError(msg)
            body.delete_named_range(name)  # type: ignore[attr-defined]
        else:
            self._local_delete_named_range(name)

    #
    # Cell span
    #

    def set_span(
        self,
        area: str | tuple | list,
        merge: bool = False,
    ) -> bool:
        """Create a Cell Span : span the first cell of the area on several
        columns and/or rows.

        If merge is True, replace text of the cell by the concatenation of
        existing text in covered cells.
        Beware : if merge is True, old text is changed, if merge is False
        (the default), old text in covered cells is still present but not
        displayed by most GUI.

        If the area defines only one cell, the set span will do nothing.
        It is not allowed to apply set span to an area whose one cell already
        belongs to previous cell span.

        Area can be either one cell (like 'A1') or an area ('A1:B2'). It can
        be provided as an alpha numeric value like "A1:B2' or a tuple like
        (0, 0, 1, 1) or (0, 0).

        Args:

            area -- str or tuple of int, cell or area coordinate

            merge -- boolean
        """
        # get area
        digits = convert_coordinates(area)
        if len(digits) == 4:
            x, y, z, t = digits
        else:
            x, y = digits
            z, t = digits
        start = x, y
        end = z, t
        if start == end:
            # one cell : do nothing
            return False
        if x is None:
            raise ValueError
        if y is None:
            raise ValueError
        if z is None:
            raise ValueError
        if t is None:
            raise ValueError
        # check for previous span
        good = True
        # Check boundaries and empty cells : need to crate non existent cells
        # so don't use get_cells directly, but get_cell
        cells = []
        for yy in range(y, t + 1):
            row_cells = []
            for xx in range(x, z + 1):
                row_cells.append(
                    self.get_cell((xx, yy), clone=True, keep_repeated=False)
                )
            cells.append(row_cells)
        for row in cells:
            for cell in row:
                if cell.is_spanned():
                    good = False
                    break
            if not good:
                break
        if not good:
            return False
        # Check boundaries
        # if z >= self.width or t >= self.height:
        #    self.set_cell(coord = end)
        #    print area, z, t
        #    cells = self.get_cells((x, y, z, t))
        #    print cells
        # do it:
        if merge:
            val_list = []
            for row in cells:
                for cell in row:
                    if cell.is_empty(aggressive=True):
                        continue
                    val = cell.get_value()
                    if val is not None:
                        if isinstance(val, str):
                            val.strip()
                        if val != "":
                            val_list.append(val)
                        cell.clear()
            if val_list:
                if len(val_list) == 1:
                    cells[0][0].set_value(val_list[0])  # type: ignore[arg-type]
                else:
                    value = " ".join([str(v) for v in val_list if v])
                    cells[0][0].set_value(value)
        cols = z - x + 1
        cells[0][0].set_attribute("table:number-columns-spanned", str(cols))
        rows = t - y + 1
        cells[0][0].set_attribute("table:number-rows-spanned", str(rows))
        for cell in cells[0][1:]:
            cell.tag = "table:covered-table-cell"
        for row in cells[1:]:
            for cell in row:
                cell.tag = "table:covered-table-cell"
        # replace cells in table
        self.set_cells(cells, coord=start, clone=False)
        return True

    def del_span(self, area: str | tuple | list) -> bool:
        """Delete a Cell Span. 'area' is the cell coordinate of the upper left
        cell of the spanned area.

        Area can be either one cell (like 'A1') or an area ('A1:B2'). It can
        be provided as an alpha numeric value like "A1:B2' or a tuple like
        (0, 0, 1, 1) or (0, 0). If an area is provided, the upper left cell
        is used.

        Args:

            area -- str or tuple of int, cell or area coordinate
        """
        # get area
        digits = convert_coordinates(area)
        if len(digits) == 4:
            x, y, _z, _t = digits
        else:
            x, y = digits
        if x is None:
            raise ValueError
        if y is None:
            raise ValueError
        start = x, y
        # check for previous span
        cell0 = self.get_cell(start)
        nb_cols = cell0.get_attribute_integer("table:number-columns-spanned")
        if nb_cols is None:
            return False
        nb_rows = cell0.get_attribute_integer("table:number-rows-spanned")
        if nb_rows is None:
            return False
        z = x + nb_cols - 1
        t = y + nb_rows - 1
        cells = self.get_cells((x, y, z, t))
        cells[0][0].del_attribute("table:number-columns-spanned")
        cells[0][0].del_attribute("table:number-rows-spanned")
        for cell in cells[0][1:]:
            cell.tag = "table:table-cell"
        for row in cells[1:]:
            for cell in row:
                cell.tag = "table:table-cell"
        # replace cells in table
        self.set_cells(cells, coord=start, clone=False)
        return True

    # Utilities

    def to_csv(
        self,
        path_or_file: str | Path | None = None,
        dialect: str = "excel",
        **fmtparams: Any,
    ) -> str | None:
        """Export the table as CSV.

        Save the CSV content to the path_or_file path, or return the content
        text if path_or_file is None.

        Args:

            path_or_file -- str or Path or None

            dialect -- str, python csv.dialect, can be 'excel', 'unix'...

            **fmtparams -- names parameters passed to csv.writer method
        """

        def write_content(csv_writer: object) -> None:
            for values in self.iter_values():
                line = []
                for value in values:
                    if value is None:
                        value = ""
                    line.append(value)
                csv_writer.writerow(line)  # type: ignore[attr-defined]

        content = StringIO(newline="")
        csv_writer = csv.writer(content, dialect=dialect, **fmtparams)
        write_content(csv_writer)
        if path_or_file:
            # windows fix: write file as binary
            Path(path_or_file).write_bytes(content.getvalue().encode())
            return None
        return content.getvalue()

    @classmethod
    def from_csv(
        cls,
        content: str,
        name: str,
        style: str | None = None,
        **fmtparams: Any,
    ) -> Table:
        """Import the CSV text content into a Table.

        If the path_or_file parameter is a Path or a string, it is opened as a path. Else a opened file-like is expected.

        CSV format can be autodetected to a certain limit. Use **fmtparams to
        define cvs.reader parameters.

        Args:

          contenr -- str, CSV content

          name -- str, name of the Table

          style -- str, style of the Table

          **fmtparams -- names parameters passed to csv.reader method
        """
        data = content.splitlines(True)
        # Sniff the dialect
        sample = "".join(data[:2048])
        dialect = csv.Sniffer().sniff(sample)
        # Make the rows
        reader = csv.reader(data, dialect=dialect, **fmtparams)
        table = cls(name, style=style)
        encoding = fmtparams.get("encoding", "utf-8")
        for line in reader:
            row = Row()
            # rstrip line
            while line and not line[-1].strip():
                line.pop()
            for value in line:
                cell = Cell(_get_python_value(value, encoding))
                row.append_cell(cell, clone=False)
            table.append_row(row, clone=False)
        return table

cells property

cells: list

Get all cells of the table.

Returns: list of list of Cell

columns property

columns: list[Column]

Get the list of all columns matching the criteria.

Copies are returned, use set_column() to push them back.

Returns: list of columns

height property

height: int

Get the current height of the table.

Returns: int

name property writable

name: str | None

Get / set the name of the table.

The “name” parameter is required and cannot contain []*?:/ or \ characters, ’ (apostrophe) cannot be the first or last character.

print_ranges property writable

print_ranges: list[str]

printable property writable

printable: bool

protected property writable

protected: bool

protection_key property writable

protection_key: str | None

row_groups property

row_groups: list[RowGroup]

Get the list of all RowGroup.

Returns: list of RowGroup

rows property

rows: list[Row]

Get the list of all rows.

Returns: list of rows

set_protection_key instance-attribute

set_protection_key = protection_key

size property

size: tuple[int, int]

Shortcut to get the current width and height of the table.

Returns: (int, int)

style property writable

style: str | None

Get / set the style of the table.

Returns: str

traverse class-attribute instance-attribute

traverse = iter_rows

traverse_columns class-attribute instance-attribute

traverse_columns = iter_columns

width property

width: int

Get the current width of the table, measured on columns.

Rows may have different widths, use the Table API to ensure width consistency.

Returns: int

__init__

__init__(
    name: str | None = None,
    width: int | str | None = None,
    height: int | str | None = None,
    protected: bool = False,
    protection_key: str | None = None,
    printable: bool = True,
    print_ranges: list[str] | None = None,
    style: str | None = None,
    **kwargs: Any,
) -> None

Create a table element “table:table”, optionally prefilled with “height” rows of “width” cells each.

The “name” parameter is required and cannot contain []*?:/ or \ characters, ’ (apostrophe) cannot be the first or last character.

If the table is to be protected, a protection key must be provided, i.e. a hash value of the password.

If the table must not be printed, set “printable” to False. The table will not be printed when it is not displayed, whatever the value of this argument.

Ranges of cells to print can be provided as a list of cell ranges, e.g. [‘E6:K12’, ‘P6:R12’] or directly as a raw string, e.g. “E6:K12 P6:R12”.

You can access and modify the XML tree manually, but you probably want to use the API to access and alter cells. It will save you from handling repetitions and the same number of cells for each row.

If you use both the table API and the XML API, you are on your own for ensuring model integrity.

Args:

name -- str

width -- int | str

height -- int | str

protected -- bool

protection_key -- str

printable -- bool

print_ranges -- list

style -- str

Source code in odfdo/table.py

def __init__(
    self,
    name: str | None = None,
    width: int | str | None = None,
    height: int | str | None = None,
    protected: bool = False,
    protection_key: str | None = None,
    printable: bool = True,
    print_ranges: list[str] | None = None,
    style: str | None = None,
    **kwargs: Any,
) -> None:
    """Create a table element "table:table", optionally prefilled with
    "height" rows of "width" cells each.

    The "name" parameter is required and cannot contain []*?:/ or \\
    characters, ' (apostrophe) cannot be the first or last character.

    If the table is to be protected, a protection key must be provided,
    i.e. a hash value of the password.

    If the table must not be printed, set "printable" to False. The table
    will not be printed when it is not displayed, whatever the value of
    this argument.

    Ranges of cells to print can be provided as a list of cell ranges,
    e.g. ['E6:K12', 'P6:R12'] or directly as a raw string, e.g.
    "E6:K12 P6:R12".

    You can access and modify the XML tree manually, but you probably want
    to use the API to access and alter cells. It will save you from
    handling repetitions and the same number of cells for each row.

    If you use both the table API and the XML API, you are on your own for
    ensuring model integrity.

    Args:

        name -- str

        width -- int | str

        height -- int | str

        protected -- bool

        protection_key -- str

        printable -- bool

        print_ranges -- list

        style -- str
    """
    super().__init__(**kwargs)
    self._table_cache = TableCache()
    if self._do_init:
        self.name = name or ""
        if protected:
            self.protected = protected
            self.set_protection_key = protection_key
        if not printable:
            self.printable = printable
        if print_ranges:
            self.print_ranges = print_ranges
        if style:
            self.style = style
        # Prefill the table
        if width is not None or height is not None:
            width = int(width or 1)
            height = int(height or 1)
            # Column groups for style information
            columns = Column(repeated=width)
            self._append(columns)
            for _i in range(height):
                row = Row(width)
                self._append(row)
    self._compute_table_cache()

append

append(something: Element | str) -> None

Dispatch .append() call to append_row() or append_column().

Source code in odfdo/table.py

def append(self, something: Element | str) -> None:
    """Dispatch .append() call to append_row() or append_column()."""
    if isinstance(something, Row):
        self.append_row(something)
    elif isinstance(something, Column):
        self.append_column(something)
    else:
        # probably still an error
        self._append(something)

append_cell

append_cell(
    y: int | str,
    cell: Cell | None = None,
    clone: bool = True,
) -> Cell

Append the given cell at the “y” coordinate. Repeated cells are accepted. If no cell is given, an empty one is created.

Position start at 0. So cell A4 is on row 3.

Other rows remain untouched.

Args:

y -- int or str

cell -- Cell

returns the cell with x and y updated

Source code in odfdo/table.py

def append_cell(
    self,
    y: int | str,
    cell: Cell | None = None,
    clone: bool = True,
) -> Cell:
    """Append the given cell at the "y" coordinate. Repeated cells are
    accepted. If no cell is given, an empty one is created.

    Position start at 0. So cell A4 is on row 3.

    Other rows remain untouched.

    Args:

        y -- int or str

        cell -- Cell

    returns the cell with x and y updated
    """
    if cell is None:
        cell = Cell()
        clone = False
    if clone:
        cell = cell.clone
    y = self._translate_y_from_any(y)
    row = self._get_row2(y)
    row.y = y
    cell_back = row.append_cell(cell, clone=False)
    self.set_row(y, row)
    # Update width if necessary
    self._update_width(row)
    return cell_back

append_column

append_column(
    column: Column | None = None,
    _repeated: int | None = None,
) -> Column

Append the column at the end of the table. If no column is given, an empty one is created.

ODF columns don’t contain cells, only style information.

Position start at 0. So cell C4 is on column 2. Alphabetical position like “C” is accepted.

Args:

column -- Column

_repeated -- (optional), repeated value of the column

Source code in odfdo/table.py

def append_column(
    self,
    column: Column | None = None,
    _repeated: int | None = None,
) -> Column:
    """Append the column at the end of the table. If no column is given, an
    empty one is created.

    ODF columns don't contain cells, only style information.

    Position start at 0. So cell C4 is on column 2. Alphabetical position
    like "C" is accepted.

    Args:

        column -- Column

        _repeated -- (optional), repeated value of the column
    """
    if column is None:
        column = Column()
        _repeated = 1
    else:
        column = column.clone
    odf_idx = self._table_cache.col_map_length() - 1
    if odf_idx < 0:
        position = 0
    else:
        last_column = self._get_element_idx2(_XP_COLUMN_IDX, odf_idx)
        if last_column is None:
            raise ValueError
        position = self.index(last_column) + 1
    column.x = self.width
    self.insert(column, position=position)
    # Repetitions are accepted
    if _repeated is None:
        _repeated = column.repeated or 1
    self._table_cache.insert_col_map_once(_repeated)
    # No need to update row widths
    return column

append_named_range

append_named_range(
    named_range: NamedRange, global_scope: bool = True
) -> None

Append the named range to the document.

An existing named range of same name is replaced.

If “global_scope” is True (default), append in the document body, else to the current Table.

Named ranges can be local to the Table or global. Global named ranges are stored at the body level, thus do not call this method on a cloned table if you need to access to the global named ranges.

Args:

named_range --  NamedRange

global_scope -- bool, search in entire document or in the current table.

Source code in odfdo/table.py

def append_named_range(
    self, named_range: NamedRange, global_scope: bool = True
) -> None:
    """Append the named range to the document.

    An existing named range of same name is replaced.

    If "global_scope" is True (default), append in the document body, else to the current Table.

    Named ranges can be local to the Table or global. Global named ranges are stored at the body level, thus do not call this method on a cloned table if you need to access to the global named ranges.

    Args:

        named_range --  NamedRange

        global_scope -- bool, search in entire document or in the current table.
    """
    if global_scope:
        body = self.document_body
        if not body:
            raise ValueError("Table is not inside a document")
        if body.tag not in BODY_NR_TAGS:
            msg = (
                "Document must be of type Chart, Drawing, "
                "Presentation, Spreadsheet or Text"
            )
            raise TypeError(msg)
        body.append_named_range(named_range)  # type: ignore[attr-defined]
    else:
        self._local_append_named_range(named_range)

append_row

append_row(
    row: Row | None = None,
    clone: bool = True,
    _repeated: int | None = None,
) -> Row

Append the row at the end of the table. If no row is given, an empty one is created.

Position start at 0. So cell A4 is on row 3.

Note the columns are automatically created when the first row is inserted in an empty table. So better insert a filled row.

Args:

row -- Row

_repeated -- (optional), repeated value of the row

returns the row, with updated row.y

Source code in odfdo/table.py

def append_row(
    self,
    row: Row | None = None,
    clone: bool = True,
    _repeated: int | None = None,
) -> Row:
    """Append the row at the end of the table. If no row is given, an empty
    one is created.

    Position start at 0. So cell A4 is on row 3.

    Note the columns are automatically created when the first row is
    inserted in an empty table. So better insert a filled row.

    Args:

        row -- Row

        _repeated -- (optional), repeated value of the row

    returns the row, with updated row.y
    """
    if row is None:
        row = Row()
        _repeated = 1
    elif clone:
        row = row.clone
    # Appending a repeated row accepted
    # Do not insert next to the last row because it could be in a group
    self._append(row)
    if _repeated is None:
        _repeated = row.repeated or 1
    self._table_cache.insert_row_map_once(_repeated)
    row.y = self.height - 1
    # Initialize columns
    if not self._get_columns():
        repeated = row.width
        self.insert(Column(repeated=repeated), position=0)
        self._compute_table_cache()
    # Update width if necessary
    self._update_width(row)
    return row

clear

clear() -> None

Remove text, children and attributes from the Row.

Source code in odfdo/table.py

def clear(self) -> None:
    """Remove text, children and attributes from the Row."""
    self._Element__element.clear()  # type:ignore[attr-defined]
    self._table_cache = TableCache()

del_span

del_span(area: str | tuple | list) -> bool

Delete a Cell Span. ‘area’ is the cell coordinate of the upper left cell of the spanned area.

Area can be either one cell (like ‘A1’) or an area (‘A1:B2’). It can be provided as an alpha numeric value like “A1:B2’ or a tuple like (0, 0, 1, 1) or (0, 0). If an area is provided, the upper left cell is used.

Args:

area -- str or tuple of int, cell or area coordinate

Source code in odfdo/table.py

def del_span(self, area: str | tuple | list) -> bool:
    """Delete a Cell Span. 'area' is the cell coordinate of the upper left
    cell of the spanned area.

    Area can be either one cell (like 'A1') or an area ('A1:B2'). It can
    be provided as an alpha numeric value like "A1:B2' or a tuple like
    (0, 0, 1, 1) or (0, 0). If an area is provided, the upper left cell
    is used.

    Args:

        area -- str or tuple of int, cell or area coordinate
    """
    # get area
    digits = convert_coordinates(area)
    if len(digits) == 4:
        x, y, _z, _t = digits
    else:
        x, y = digits
    if x is None:
        raise ValueError
    if y is None:
        raise ValueError
    start = x, y
    # check for previous span
    cell0 = self.get_cell(start)
    nb_cols = cell0.get_attribute_integer("table:number-columns-spanned")
    if nb_cols is None:
        return False
    nb_rows = cell0.get_attribute_integer("table:number-rows-spanned")
    if nb_rows is None:
        return False
    z = x + nb_cols - 1
    t = y + nb_rows - 1
    cells = self.get_cells((x, y, z, t))
    cells[0][0].del_attribute("table:number-columns-spanned")
    cells[0][0].del_attribute("table:number-rows-spanned")
    for cell in cells[0][1:]:
        cell.tag = "table:table-cell"
    for row in cells[1:]:
        for cell in row:
            cell.tag = "table:table-cell"
    # replace cells in table
    self.set_cells(cells, coord=start, clone=False)
    return True

delete_cell

delete_cell(coord: tuple | list | str) -> None

Delete the cell at the given coordinates, so that next cells are shifted to the left.

Coordinates are either a 2-tuple of (x, y) starting from 0, or a human-readable position like “C4”.

Use set_value() for erasing value.

Args:

coord -- (int, int) or str

Source code in odfdo/table.py

def delete_cell(self, coord: tuple | list | str) -> None:
    """Delete the cell at the given coordinates, so that next cells are
    shifted to the left.

    Coordinates are either a 2-tuple of (x, y) starting from 0, or a
    human-readable position like "C4".

    Use set_value() for erasing value.

    Args:

        coord -- (int, int) or str
    """
    x, y = self._translate_cell_coordinates(coord)
    if x is None:
        raise ValueError
    if y is None:
        raise ValueError
    # Outside the defined table
    if y >= self.height:
        return
    # Inside the defined table
    row = self._get_row2_base(y)
    if row is None:
        raise ValueError
    row.delete_cell(x)

delete_column

delete_column(x: int | str) -> None

Delete the column at the given position. ODF columns don’t contain cells, only style information.

Position start at 0. So cell C4 is on column 2. Alphabetical position like “C” is accepted.

Args:

x -- int or str

Source code in odfdo/table.py

def delete_column(self, x: int | str) -> None:
    """Delete the column at the given position. ODF columns don't contain
    cells, only style information.

    Position start at 0. So cell C4 is on column 2. Alphabetical position
    like "C" is accepted.

    Args:

        x -- int or str
    """
    x = self._translate_x_from_any(x)
    # Outside the defined table
    if x >= self.width:
        return
    # Inside the defined table
    self._table_cache.delete_col_in_cache(x, self)
    # Update width
    width = self.width
    for row in self._get_rows():
        if row.width >= width:
            row.delete_cell(x)

delete_named_range

delete_named_range(
    name: str, global_scope: bool = True
) -> None

Delete the Named Range of specified name.

If “global_scope” is True (default), search in the entire document, else limit search to the current Table.

Named ranges can be local to the Table or global. Global named ranges are stored at the body level, thus do not call this method on a cloned table if you need to access to the global named ranges.

Args:

name -- str

global_scope -- bool, search in entire document or in the current table.

Source code in odfdo/table.py

def delete_named_range(self, name: str, global_scope: bool = True) -> None:
    """Delete the Named Range of specified name.

    If "global_scope" is True (default), search in the entire document, else limit search to the current Table.

    Named ranges can be local to the Table or global. Global named ranges are stored at the body level, thus do not call this method on a cloned table if you need to access to the global named ranges.

    Args:

        name -- str

        global_scope -- bool, search in entire document or in the current table.
    """
    name = name.strip()
    if not name:
        raise ValueError("Name required")
    if global_scope:
        body = self.document_body
        if not body:
            raise ValueError("Table is not inside a document")
        if body.tag not in BODY_NR_TAGS:
            msg = (
                "Document must be of type Chart, Drawing, "
                "Presentation, Spreadsheet or Text"
            )
            raise TypeError(msg)
        body.delete_named_range(name)  # type: ignore[attr-defined]
    else:
        self._local_delete_named_range(name)

delete_row

delete_row(y: int | str) -> None

Delete the row at the given “y” position.

Position start at 0. So cell A4 is on row 3.

Args:

y -- int or str

Source code in odfdo/table.py

def delete_row(self, y: int | str) -> None:
    """Delete the row at the given "y" position.

    Position start at 0. So cell A4 is on row 3.

    Args:

        y -- int or str
    """
    y = self._translate_y_from_any(y)
    # Outside the defined table
    if y >= self.height:
        return
    # Inside the defined table
    self._table_cache.delete_row_in_cache(y, self)

extend_rows

extend_rows(rows: list[Row] | None = None) -> None

Append a list of rows at the end of the table.

Args:

rows -- list of Row

Source code in odfdo/table.py

def extend_rows(self, rows: list[Row] | None = None) -> None:
    """Append a list of rows at the end of the table.

    Args:

        rows -- list of Row
    """
    if rows is None:
        rows = []
    self.extend(rows)
    self._compute_table_cache()
    # Update width if necessary
    width = self.width
    for row in self.iter_rows():
        if row.width > width:
            width = row.width
    diff = width - self.width
    if diff > 0:
        self.append_column(Column(repeated=diff))

from_csv classmethod

from_csv(
    content: str,
    name: str,
    style: str | None = None,
    **fmtparams: Any,
) -> Table

Import the CSV text content into a Table.

If the path_or_file parameter is a Path or a string, it is opened as a path. Else a opened file-like is expected.

CSV format can be autodetected to a certain limit. Use **fmtparams to define cvs.reader parameters.

Args:

contenr – str, CSV content

name – str, name of the Table

style – str, style of the Table

**fmtparams – names parameters passed to csv.reader method

Source code in odfdo/table.py

@classmethod
def from_csv(
    cls,
    content: str,
    name: str,
    style: str | None = None,
    **fmtparams: Any,
) -> Table:
    """Import the CSV text content into a Table.

    If the path_or_file parameter is a Path or a string, it is opened as a path. Else a opened file-like is expected.

    CSV format can be autodetected to a certain limit. Use **fmtparams to
    define cvs.reader parameters.

    Args:

      contenr -- str, CSV content

      name -- str, name of the Table

      style -- str, style of the Table

      **fmtparams -- names parameters passed to csv.reader method
    """
    data = content.splitlines(True)
    # Sniff the dialect
    sample = "".join(data[:2048])
    dialect = csv.Sniffer().sniff(sample)
    # Make the rows
    reader = csv.reader(data, dialect=dialect, **fmtparams)
    table = cls(name, style=style)
    encoding = fmtparams.get("encoding", "utf-8")
    for line in reader:
        row = Row()
        # rstrip line
        while line and not line[-1].strip():
            line.pop()
        for value in line:
            cell = Cell(_get_python_value(value, encoding))
            row.append_cell(cell, clone=False)
        table.append_row(row, clone=False)
    return table

get_cell

get_cell(
    coord: tuple | list | str,
    clone: bool = True,
    keep_repeated: bool = True,
) -> Cell

Get the cell at the given coordinates.

They are either a 2-tuple of (x, y) starting from 0, or a human-readable position like “C4”.

A copy is returned, use set_cell to push it back.

Args:

coord -- (int, int) or str

Returns: Cell

Source code in odfdo/table.py

def get_cell(
    self,
    coord: tuple | list | str,
    clone: bool = True,
    keep_repeated: bool = True,
) -> Cell:
    """Get the cell at the given coordinates.

    They are either a 2-tuple of (x, y) starting from 0, or a
    human-readable position like "C4".

    A copy is returned, use ``set_cell`` to push it back.

    Args:

        coord -- (int, int) or str

    Returns: Cell
    """
    x, y = self._translate_cell_coordinates(coord)
    if x is None:
        raise ValueError
    if y is None:
        raise ValueError
    # Outside the defined table
    if y >= self.height:
        cell = Cell()
    else:
        # Inside the defined table
        row = self._get_row2_base(y)
        if row is None:
            raise ValueError
        read_cell = row.get_cell(x, clone=clone)
        if read_cell is None:
            raise ValueError
        cell = read_cell
        if not keep_repeated:
            repeated = cell.repeated or 1
            if repeated >= 2:
                cell.repeated = None
    cell.x = x
    cell.y = y
    return cell

get_cells

get_cells(
    coord: tuple | list | str | None = None,
    cell_type: str | None = None,
    style: str | None = None,
    content: str | None = None,
    flat: bool = False,
) -> list

Get the cells matching the criteria. If ‘coord’ is None, parse the whole table, else parse the area defined by ‘coord’.

Filter by cell_type = “all” will retrieve cells of any type, aka non empty cells.

If flat is True (default is False), the method return a single list of all the values, else a list of lists of cells.

if cell_type, style and content are None, get_cells() will return the exact number of cells of the area, including empty cells.

Args:

coordinates -- str or tuple of int : coordinates of area

cell_type -- 'boolean', 'float', 'date', 'string', 'time',
             'currency', 'percentage' or 'all'

content -- str regex

style -- str

flat -- boolean

Returns: list of list of Cell

Source code in odfdo/table.py

def get_cells(
    self,
    coord: tuple | list | str | None = None,
    cell_type: str | None = None,
    style: str | None = None,
    content: str | None = None,
    flat: bool = False,
) -> list:
    """Get the cells matching the criteria. If 'coord' is None, parse the
    whole table, else parse the area defined by 'coord'.

    Filter by  cell_type = "all"  will retrieve cells of any
    type, aka non empty cells.

    If flat is True (default is False), the method return a single list
    of all the values, else a list of lists of cells.

    if cell_type, style and content are None, get_cells() will return
    the exact number of cells of the area, including empty cells.

    Args:

        coordinates -- str or tuple of int : coordinates of area

        cell_type -- 'boolean', 'float', 'date', 'string', 'time',
                     'currency', 'percentage' or 'all'

        content -- str regex

        style -- str

        flat -- boolean

    Returns: list of list of Cell
    """
    if coord:
        x, y, z, t = self._translate_table_coordinates(coord)
    else:
        x = y = z = t = None
    if flat:
        cells: list[Cell] = []
        for row in self.iter_rows(start=y, end=t):
            row_cells = row.get_cells(
                coord=(x, z),
                cell_type=cell_type,
                style=style,
                content=content,
            )
            cells.extend(row_cells)
        return cells
    else:
        lcells: list[list[Cell]] = []
        for row in self.iter_rows(start=y, end=t):
            row_cells = row.get_cells(
                coord=(x, z),
                cell_type=cell_type,
                style=style,
                content=content,
            )
            lcells.append(row_cells)
        return lcells

get_column

get_column(x: int | str) -> Column

Get the column at the given “x” position.

ODF columns don’t contain cells, only style information.

Position start at 0. So cell C4 is on column 2. Alphabetical position like “C” is accepted.

A copy is returned, use set_column() to push it back.

Args:

x -- int or str

Returns: Column

Source code in odfdo/table.py

def get_column(self, x: int | str) -> Column:
    """Get the column at the given "x" position.

    ODF columns don't contain cells, only style information.

    Position start at 0. So cell C4 is on column 2. Alphabetical position
    like "C" is accepted.

    A copy is returned, use set_column() to push it back.

    Args:

        x -- int or str

    Returns: Column
    """
    x = self._translate_x_from_any(x)
    column = self._get_column2(x)
    if column is None:
        raise ValueError
    column.x = x
    return column

get_column_cells

get_column_cells(
    x: int | str,
    style: str | None = None,
    content: str | None = None,
    cell_type: str | None = None,
    complete: bool = False,
) -> list[Cell | None]

Get the list of cells at the given position.

Position start at 0. So cell C4 is on column 2. Alphabetical position like “C” is accepted.

Filter by cell_type, with cell_type ‘all’ will retrieve cells of any type, aka non empty cells.

If complete is True, replace missing values by None.

Args:

x -- int or str

cell_type -- 'boolean', 'float', 'date', 'string', 'time',
             'currency', 'percentage' or 'all'

content -- str regex

style -- str

complete -- boolean

Returns: list of Cell

Source code in odfdo/table.py

def get_column_cells(
    self,
    x: int | str,
    style: str | None = None,
    content: str | None = None,
    cell_type: str | None = None,
    complete: bool = False,
) -> list[Cell | None]:
    """Get the list of cells at the given position.

    Position start at 0. So cell C4 is on column 2. Alphabetical position
    like "C" is accepted.

    Filter by cell_type, with cell_type 'all' will retrieve cells of any
    type, aka non empty cells.

    If complete is True, replace missing values by None.

    Args:

        x -- int or str

        cell_type -- 'boolean', 'float', 'date', 'string', 'time',
                     'currency', 'percentage' or 'all'

        content -- str regex

        style -- str

        complete -- boolean

    Returns: list of Cell
    """
    x = self._translate_x_from_any(x)
    if cell_type:
        cell_type = cell_type.lower().strip()
    cells: list[Cell | None] = []
    if not style and not content and not cell_type:
        for row in self.iter_rows():
            cells.append(row.get_cell(x, clone=True))
        return cells
    for row in self.iter_rows():
        cell = row.get_cell(x, clone=True)
        if cell is None:
            raise ValueError
        # Filter the cells by cell_type
        if cell_type:
            ctype = cell.type
            if not ctype or not (ctype == cell_type or cell_type == "all"):
                if complete:
                    cells.append(None)
                continue
        # Filter the cells with the regex
        if content and not cell.match(content):
            if complete:
                cells.append(None)
            continue
        # Filter the cells with the style
        if style and style != cell.style:
            if complete:
                cells.append(None)
            continue
        cells.append(cell)
    return cells

get_column_values

get_column_values(
    x: int | str,
    cell_type: str | None = None,
    complete: bool = True,
    get_type: bool = False,
) -> list[Any]

Shortcut to get the list of Python values for the cells at the given position.

Position start at 0. So cell C4 is on column 2. Alphabetical position like “C” is accepted.

Filter by cell_type, with cell_type ‘all’ will retrieve cells of any type, aka non empty cells. If cell_type and complete is True, replace missing values by None.

If get_type is True, returns a tuple (value, ODF type of value)

Args:

x -- int or str

cell_type -- 'boolean', 'float', 'date', 'string', 'time',
             'currency', 'percentage' or 'all'

complete -- boolean

get_type -- boolean

Returns: list of Python types

Source code in odfdo/table.py

def get_column_values(
    self,
    x: int | str,
    cell_type: str | None = None,
    complete: bool = True,
    get_type: bool = False,
) -> list[Any]:
    """Shortcut to get the list of Python values for the cells at the given
    position.

    Position start at 0. So cell C4 is on column 2. Alphabetical position
    like "C" is accepted.

    Filter by cell_type, with cell_type 'all' will retrieve cells of any
    type, aka non empty cells.
    If cell_type and complete is True, replace missing values by None.

    If get_type is True, returns a tuple (value, ODF type of value)

    Args:

        x -- int or str

        cell_type -- 'boolean', 'float', 'date', 'string', 'time',
                     'currency', 'percentage' or 'all'

        complete -- boolean

        get_type -- boolean

    Returns: list of Python types
    """
    cells = self.get_column_cells(
        x, style=None, content=None, cell_type=cell_type, complete=complete
    )
    values: list[Any] = []
    for cell in cells:
        if cell is None:
            if complete:
                if get_type:
                    values.append((None, None))
                else:
                    values.append(None)
            continue
        if cell_type:
            ctype = cell.type
            if not ctype or not (ctype == cell_type or cell_type == "all"):
                if complete:
                    if get_type:
                        values.append((None, None))
                    else:
                        values.append(None)
                continue
        values.append(cell.get_value(get_type=get_type))
    return values

get_columns

get_columns(
    coord: tuple | list | str | None = None,
    style: str | None = None,
) -> list[Column]

Get the list of columns matching the criteria.

Copies are returned, use set_column() to push them back.

Args:

coord -- str or tuple of int : coordinates of columns

style -- str

Returns: list of columns

Source code in odfdo/table.py

def get_columns(
    self,
    coord: tuple | list | str | None = None,
    style: str | None = None,
) -> list[Column]:
    """Get the list of columns matching the criteria.

    Copies are returned, use set_column() to push them back.

    Args:

        coord -- str or tuple of int : coordinates of columns

        style -- str

    Returns: list of columns
    """
    if coord:
        x, _y, _z, t = self._translate_column_coordinates(coord)
    else:
        x = t = None
    if not style:
        return list(self.iter_columns(start=x, end=t))
    columns = []
    for column in self.iter_columns(start=x, end=t):
        if style != column.style:
            continue
        columns.append(column)
    return columns

get_elements

get_elements(xpath_query: XPath | str) -> list[Element]

Source code in odfdo/table.py

def get_elements(self, xpath_query: XPath | str) -> list[Element]:
    if isinstance(xpath_query, str):
        elements = xpath_return_elements(
            xpath_compile(xpath_query),
            self._Element__element,  # type: ignore[attr-defined]
        )
    else:
        elements = xpath_return_elements(
            xpath_query,
            self._Element__element,  # type: ignore[attr-defined]
        )
    cache = (self._table_cache, None)
    return [Element.from_tag_for_clone(e, cache) for e in elements]

get_formatted_text

get_formatted_text(context: dict | None = None) -> str

Source code in odfdo/table.py

def get_formatted_text(self, context: dict | None = None) -> str:
    if context and context["rst_mode"]:
        return self._get_formatted_text_rst(context)
    return self._get_formatted_text_normal(context)

get_named_range

get_named_range(
    name: str, global_scope: bool = True
) -> NamedRange | None

Return the Name Range of the specified name.

If “global_scope” is True (default), search in the entire document, else limit search to the current Table.

Named ranges can be local to the Table or global. Global named ranges are stored at the body level, thus do not call this method on a cloned table if you need to access to the global named ranges.

Args:

name -- str, name of the named range object

global_scope -- bool, search in entire document or in the current table.

Returns : NamedRange or None

Source code in odfdo/table.py

def get_named_range(
    self, name: str, global_scope: bool = True
) -> NamedRange | None:
    """Return the Name Range of the specified name.

    If "global_scope" is True (default), search in the entire document, else limit search to the current Table.

    Named ranges can be local to the Table or global. Global named ranges are stored at the body level, thus do not call this method on a cloned table if you need to access to the global named ranges.

    Args:

        name -- str, name of the named range object

        global_scope -- bool, search in entire document or in the current table.

    Returns : NamedRange or None
    """
    if global_scope:
        body = self.document_body
        if not body:
            raise ValueError("Table is not inside a document")
        if body.tag not in BODY_NR_TAGS:
            return None
        nr: NamedRange | None = body.get_named_range(name)  # type: ignore[attr-defined]

    else:
        nr = self._local_named_range(name)
    return nr

get_named_ranges

get_named_ranges(
    table_name: str | list[str] | None = None,
    global_scope: bool = True,
) -> list[NamedRange]

Return the list of Name Ranges.

If “global_scope” is True (default), search in the entire document, else limit search to the current Table. If “table_name” is provided, limits the search to these tables.

Named ranges can be local to the Table or global. Global named ranges are stored at the body level, thus do not call this method on a cloned table if you need to access to the global named ranges.

Args:

table_names -- str or list of str, names of tables

global_scope -- bool, search in entire document or in the current table.

Returns : list of NamedRange

Source code in odfdo/table.py

def get_named_ranges(
    self,
    table_name: str | list[str] | None = None,
    global_scope: bool = True,
) -> list[NamedRange]:
    """Return the list of Name Ranges.

    If "global_scope" is True (default), search in the entire document, else limit search to the current Table. If "table_name" is provided, limits the search to these tables.

    Named ranges can be local to the Table or global. Global named ranges are stored at the body level, thus do not call this method on a cloned table if you need to access to the global named ranges.

    Args:

        table_names -- str or list of str, names of tables

        global_scope -- bool, search in entire document or in the current table.

    Returns : list of NamedRange
    """
    if global_scope:
        body = self.document_body
        if not body or body.tag not in BODY_NR_TAGS:
            return []
        named_ranges = body.get_named_ranges()  # type: ignore[attr-defined]
    else:
        named_ranges = self._local_named_ranges()
    if not table_name:
        return named_ranges  # type: ignore[no-any-return]
    filter_ = []
    if isinstance(table_name, str):
        filter_.append(table_name)
    elif isiterable(table_name):
        filter_.extend(table_name)
    else:
        msg = f"table_name must be string or Iterable, not {type(table_name)!r}"
        raise ValueError(msg)
    return [nr for nr in named_ranges if nr.table_name in filter_]

get_row

get_row(
    y: int | str, clone: bool = True, create: bool = True
) -> Row

Get the row at the given “y” position.

Position start at 0. So cell A4 is on row 3.

A copy is returned, use set_cell() to push it back.

Args:

y -- int or str

Returns: Row

Source code in odfdo/table.py

def get_row(self, y: int | str, clone: bool = True, create: bool = True) -> Row:
    """Get the row at the given "y" position.

    Position start at 0. So cell A4 is on row 3.

    A copy is returned, use set_cell() to push it back.

    Args:

        y -- int or str

    Returns: Row
    """
    # fixme : keep repeat ? maybe an option to functions : "raw=False"
    y = self._translate_y_from_any(y)
    row = self._get_row2(y, clone=clone, create=create)
    if row is None:
        raise ValueError("Row not found")
    row.y = y
    return row

get_row_sub_elements

get_row_sub_elements(y: int | str) -> list[Any]

Shortcut to get the list of Elements values for the cells of the row at the given “y” position.

Position start at 0. So cell A4 is on row 3.

Missing values replaced by None.

Args:

y -- int, str

Returns: list of lists of Elements

Source code in odfdo/table.py

def get_row_sub_elements(self, y: int | str) -> list[Any]:
    """Shortcut to get the list of Elements values for the cells of the row
    at the given "y" position.

    Position start at 0. So cell A4 is on row 3.

    Missing values replaced by None.

    Args:

        y -- int, str

    Returns: list of lists of Elements
    """
    values = self.get_row(y, clone=False).get_sub_elements()
    values.extend([None] * (self.width - len(values)))
    return values

get_row_values

get_row_values(
    y: int | str,
    cell_type: str | None = None,
    complete: bool = True,
    get_type: bool = False,
) -> list

Shortcut to get the list of Python values for the cells of the row at the given “y” position.

Position start at 0. So cell A4 is on row 3.

Filter by cell_type, with cell_type ‘all’ will retrieve cells of any type, aka non empty cells. If cell_type and complete is True, replace missing values by None.

If get_type is True, returns a tuple (value, ODF type of value)

Args:

y -- int, str

cell_type -- 'boolean', 'float', 'date', 'string', 'time',
             'currency', 'percentage' or 'all'

complete -- boolean

get_type -- boolean

Returns: list of lists of Python types

Source code in odfdo/table.py

def get_row_values(
    self,
    y: int | str,
    cell_type: str | None = None,
    complete: bool = True,
    get_type: bool = False,
) -> list:
    """Shortcut to get the list of Python values for the cells of the row
    at the given "y" position.

    Position start at 0. So cell A4 is on row 3.

    Filter by cell_type, with cell_type 'all' will retrieve cells of any
    type, aka non empty cells.
    If cell_type and complete is True, replace missing values by None.

    If get_type is True, returns a tuple (value, ODF type of value)

    Args:

        y -- int, str

        cell_type -- 'boolean', 'float', 'date', 'string', 'time',
                     'currency', 'percentage' or 'all'

        complete -- boolean

        get_type -- boolean

    Returns: list of lists of Python types
    """
    values = self.get_row(y, clone=False).get_values(
        cell_type=cell_type, complete=complete, get_type=get_type
    )
    # complete row to match column width
    if complete:
        if get_type:
            values.extend([(None, None)] * (self.width - len(values)))
        else:
            values.extend([None] * (self.width - len(values)))
    return values

get_rows

get_rows(
    coord: tuple | list | str | None = None,
    style: str | None = None,
    content: str | None = None,
) -> list[Row]

Get the list of rows matching the criteria.

Filter by coordinates will parse the area defined by the coordinates.

Args:

coord -- str or tuple of int : coordinates of rows

content -- str regex

style -- str

Returns: list of rows

Source code in odfdo/table.py

def get_rows(
    self,
    coord: tuple | list | str | None = None,
    style: str | None = None,
    content: str | None = None,
) -> list[Row]:
    """Get the list of rows matching the criteria.

    Filter by coordinates will parse the area defined by the coordinates.

    Args:

        coord -- str or tuple of int : coordinates of rows

        content -- str regex

        style -- str

    Returns: list of rows
    """
    if coord:
        _x, y, _z, t = self._translate_table_coordinates(coord)
    else:
        y = t = None
    # fixme : not clones ?
    if not content and not style:
        return list(self.iter_rows(start=y, end=t))
    rows = []
    for row in self.iter_rows(start=y, end=t):
        if content and not row.match(content):
            continue
        if style and style != row.style:
            continue
        rows.append(row)
    return rows

get_value

get_value(
    coord: tuple | list | str, get_type: bool = False
) -> Any

Shortcut to get the Python value of the cell at the given coordinates.

If get_type is True, returns the tuples (value, ODF type)

coord is either a 2-tuple of (x, y) starting from 0, or a human-readable position like “C4”. If an Area is given, the upper left position is used as coord.

Args:

coord -- (int, int) or str : coordinate

Returns: Python type

Source code in odfdo/table.py

def get_value(
    self,
    coord: tuple | list | str,
    get_type: bool = False,
) -> Any:
    """Shortcut to get the Python value of the cell at the given
    coordinates.

    If get_type is True, returns the tuples (value, ODF type)

    coord is either a 2-tuple of (x, y) starting from 0, or a
    human-readable position like "C4". If an Area is given, the upper
    left position is used as coord.

    Args:

        coord -- (int, int) or str : coordinate

    Returns: Python type
    """
    x, y = self._translate_cell_coordinates(coord)
    if x is None:
        raise ValueError
    if y is None:
        raise ValueError
    # Outside the defined table
    if y >= self.height:
        if get_type:
            return (None, None)
        return None
    else:
        # Inside the defined table
        row = self._get_row2_base(y)
        if row is None:
            raise ValueError
        cell = row._get_cell2_base(x)
        if cell is None:
            if get_type:
                return (None, None)
            return None
        return cell.get_value(get_type=get_type)

get_values

get_values(
    coord: tuple | list | str | None = None,
    cell_type: str | None = None,
    complete: bool = True,
    get_type: bool = False,
    flat: bool = False,
) -> list

Get a matrix of values of the table.

Filter by coordinates will parse the area defined by the coordinates.

If ‘cell_type’ is used and ‘complete’ is True (default), missing values are replaced by None. Filter by ’ cell_type = “all” ’ will retrieve cells of any type, aka non empty cells.

If ‘cell_type’ is None, complete is always True : with no cell type queried, get_values() returns None for each empty cell, the length each lists is equal to the width of the table.

If get_type is True, returns tuples (value, ODF type of value), or (None, None) for empty cells with complete True.

If flat is True, the methods return a single list of all the values. By default, flat is False.

Args:

coord -- str or tuple of int : coordinates of area

cell_type -- 'boolean', 'float', 'date', 'string', 'time',
             'currency', 'percentage' or 'all'

complete -- boolean

get_type -- boolean

Returns: list of lists of Python types

Source code in odfdo/table.py

def get_values(
    self,
    coord: tuple | list | str | None = None,
    cell_type: str | None = None,
    complete: bool = True,
    get_type: bool = False,
    flat: bool = False,
) -> list:
    """Get a matrix of values of the table.

    Filter by coordinates will parse the area defined by the coordinates.

    If 'cell_type' is used and 'complete' is True (default), missing values
    are replaced by None.
    Filter by ' cell_type = "all" ' will retrieve cells of any
    type, aka non empty cells.

    If 'cell_type' is None, complete is always True : with no cell type
    queried, get_values() returns None for each empty cell, the length
    each lists is equal to the width of the table.

    If get_type is True, returns tuples (value, ODF type of value), or
    (None, None) for empty cells with complete True.

    If flat is True, the methods return a single list of all the values.
    By default, flat is False.

    Args:

        coord -- str or tuple of int : coordinates of area

        cell_type -- 'boolean', 'float', 'date', 'string', 'time',
                     'currency', 'percentage' or 'all'

        complete -- boolean

        get_type -- boolean

    Returns: list of lists of Python types
    """
    if coord:
        x, y, z, t = self._translate_table_coordinates(coord)
    else:
        x = y = z = t = None
    data = []
    for row in self.iter_rows(start=y, end=t):
        if z is None:
            width = self.width
        else:
            width = min(z + 1, self.width)
        if x is not None:
            width -= x
        values = row.get_values(
            (x, z),
            cell_type=cell_type,
            complete=complete,
            get_type=get_type,
        )
        # complete row to match request width
        if complete:
            if get_type:
                values.extend([(None, None)] * (width - len(values)))
            else:
                values.extend([None] * (width - len(values)))
        if flat:
            data.extend(values)
        else:
            data.append(values)
    return data

insert_cell

insert_cell(
    coord: tuple | list | str,
    cell: Cell | None = None,
    clone: bool = True,
) -> Cell

Insert the given cell at the given coordinates. If no cell is given, an empty one is created.

Coordinates are either a 2-tuple of (x, y) starting from 0, or a human-readable position like “C4”.

Cells on the right are shifted. Other rows remain untouched.

Args:

coord -- (int, int) or str

cell -- Cell

returns the cell with x and y updated

Source code in odfdo/table.py

def insert_cell(
    self,
    coord: tuple | list | str,
    cell: Cell | None = None,
    clone: bool = True,
) -> Cell:
    """Insert the given cell at the given coordinates. If no cell is given,
    an empty one is created.

    Coordinates are either a 2-tuple of (x, y) starting from 0, or a
    human-readable position like "C4".

    Cells on the right are shifted. Other rows remain untouched.

    Args:

        coord -- (int, int) or str

        cell -- Cell

    returns the cell with x and y updated
    """
    if cell is None:
        cell = Cell()
        clone = False
    if clone:
        cell = cell.clone
    x, y = self._translate_cell_coordinates(coord)
    if x is None:
        raise ValueError
    if y is None:
        raise ValueError
    row = self._get_row2(y, clone=True)
    row.y = y
    row.repeated = None
    cell_back = row.insert_cell(x, cell, clone=False)
    self.set_row(y, row, clone=False)
    # Update width if necessary
    self._update_width(row)
    return cell_back

insert_column

insert_column(
    x: int | str, column: Column | None = None
) -> Column

Insert the column before the given “x” position. If no column is given, an empty one is created.

ODF columns don’t contain cells, only style information.

Position start at 0. So cell C4 is on column 2. Alphabetical position like “C” is accepted.

Args:

x -- int or str

column -- Column

Source code in odfdo/table.py

def insert_column(
    self,
    x: int | str,
    column: Column | None = None,
) -> Column:
    """Insert the column before the given "x" position. If no column is
    given, an empty one is created.

    ODF columns don't contain cells, only style information.

    Position start at 0. So cell C4 is on column 2. Alphabetical position
    like "C" is accepted.

    Args:

        x -- int or str

        column -- Column
    """
    if column is None:
        column = Column()
    x = self._translate_x_from_any(x)
    diff = x - self.width
    if diff < 0:
        column_back = self._table_cache.insert_col_in_cache(x, column, self)
    elif diff == 0:
        column_back = self.append_column(column.clone)
    else:
        self.append_column(Column(repeated=diff), _repeated=diff)
        column_back = self.append_column(column.clone)
    column_back.x = x
    # Repetitions are accepted
    repeated = column.repeated or 1
    # Update width on every row
    for row in self._get_rows():
        if row.width > x:
            row.insert_cell(x, Cell(repeated=repeated))
        # Shorter rows don't need insert
        # Longer rows shouldn't exist!
    return column_back

insert_row

insert_row(
    y: str | int, row: Row | None = None, clone: bool = True
) -> Row

Insert the row before the given “y” position. If no row is given, an empty one is created.

Position start at 0. So cell A4 is on row 3.

If row is None, a new empty row is created.

Args:

y -- int or str

row -- Row

returns the row, with updated row.y

Source code in odfdo/table.py

def insert_row(
    self, y: str | int, row: Row | None = None, clone: bool = True
) -> Row:
    """Insert the row before the given "y" position. If no row is given, an
    empty one is created.

    Position start at 0. So cell A4 is on row 3.

    If row is None, a new empty row is created.

    Args:

        y -- int or str

        row -- Row

    returns the row, with updated row.y
    """
    if row is None:
        row = Row()
        clone = False
    y = self._translate_y_from_any(y)
    diff = y - self.height
    if diff < 0:
        row_back = self._table_cache.insert_row_in_cache(y, row, self)
    elif diff == 0:
        row_back = self.append_row(row, clone=clone)
    else:
        self.append_row(Row(repeated=diff), _repeated=diff, clone=False)
        row_back = self.append_row(row, clone=clone)
    row_back.y = y
    # Update width if necessary
    self._update_width(row_back)
    return row_back

is_column_empty

is_column_empty(
    x: int | str, aggressive: bool = False
) -> bool

Return wether every cell in the column at “x” position has no value or the value evaluates to False (empty string), and no style.

Position start at 0. So cell C4 is on column 2. Alphabetical position like “C” is accepted.

If aggressive is True, empty cells with style are considered empty.

Returns: bool

Source code in odfdo/table.py

def is_column_empty(self, x: int | str, aggressive: bool = False) -> bool:
    """Return wether every cell in the column at "x" position has no value
    or the value evaluates to False (empty string), and no style.

    Position start at 0. So cell C4 is on column 2. Alphabetical position
    like "C" is accepted.

    If aggressive is True, empty cells with style are considered empty.

    Returns: bool
    """
    for cell in self.get_column_cells(x):
        if cell is None:
            continue
        if not cell.is_empty(aggressive=aggressive):
            return False
    return True

is_empty

is_empty(aggressive: bool = False) -> bool

Return whether every cell in the table has no value or the value evaluates to False (empty string), and no style.

If aggressive is True, empty cells with style are considered empty.

Args:

aggressive -- bool

Source code in odfdo/table.py

def is_empty(self, aggressive: bool = False) -> bool:
    """Return whether every cell in the table has no value or the value
    evaluates to False (empty string), and no style.

    If aggressive is True, empty cells with style are considered empty.

    Args:

        aggressive -- bool
    """
    return all(row.is_empty(aggressive=aggressive) for row in self._get_rows())

is_row_empty

is_row_empty(
    y: int | str, aggressive: bool = False
) -> bool

Return wether every cell in the row at the given “y” position has no value or the value evaluates to False (empty string), and no style.

Position start at 0. So cell A4 is on row 3.

If aggressive is True, empty cells with style are considered empty.

Args:

y -- int or str

aggressive -- bool

Source code in odfdo/table.py

def is_row_empty(self, y: int | str, aggressive: bool = False) -> bool:
    """Return wether every cell in the row at the given "y" position has no
    value or the value evaluates to False (empty string), and no style.

    Position start at 0. So cell A4 is on row 3.

    If aggressive is True, empty cells with style are considered empty.

    Args:

        y -- int or str

        aggressive -- bool
    """
    return self.get_row(y, clone=False).is_empty(aggressive=aggressive)

iter_columns

iter_columns(
    start: int | None = None, end: int | None = None
) -> Iterator[Column]

Yield as many column elements as expected columns in the table, i.e. expand repetitions by returning the same column as many times as necessary.

Args:

    start -- int

    end -- int

Copies are returned, use set_column() to push them back.

Source code in odfdo/table.py

def iter_columns(
    self,
    start: int | None = None,
    end: int | None = None,
) -> Iterator[Column]:
    """Yield as many column elements as expected columns in the table, i.e.
    expand repetitions by returning the same column as many times as
    necessary.

        Args:

            start -- int

            end -- int

    Copies are returned, use set_column() to push them back.
    """
    if start is None:
        start = 0
    start = max(0, start)
    if end is None:
        end = 2**32
    if end < start:
        return
    x = -1
    for column in self._yield_odf_columns():
        x += 1
        if x < start:
            continue
        if x > end:
            return
        column.x = x
        yield column

iter_rows

iter_rows(
    start: int | None = None, end: int | None = None
) -> Iterator[Row]

Yield as many row elements as expected rows in the table, i.e. expand repetitions by returning the same row as many times as necessary.

Copies are returned, use set_row() to push them back.

Args:

    start -- int

    end -- int

Source code in odfdo/table.py

def iter_rows(
    self,
    start: int | None = None,
    end: int | None = None,
) -> Iterator[Row]:
    """Yield as many row elements as expected rows in the table, i.e.
    expand repetitions by returning the same row as many times as
    necessary.

    Copies are returned, use set_row() to push them back.

        Args:

            start -- int

            end -- int
    """
    if start is None:
        start = 0
    start = max(0, start)
    if end is None:
        end = 2**32
    if end < start:
        return
    y = -1
    for row in self._yield_odf_rows():
        y += 1
        if y < start:
            continue
        if y > end:
            return
        row.y = y
        yield row

iter_values

iter_values(
    coord: tuple | list | str | None = None,
    cell_type: str | None = None,
    complete: bool = True,
    get_type: bool = False,
) -> Iterator[list]

Yield lines (lists) of Python values of the table.

Filter by coordinates will parse the area defined by the coordinates.

cell_type, complete, grt_type : see get_values()

Args:

coord -- str or tuple of int : coordinates of area

cell_type -- 'boolean', 'float', 'date', 'string', 'time',
             'currency', 'percentage' or 'all'

complete -- boolean

get_type -- boolean

Returns: iterator of lists

Source code in odfdo/table.py

def iter_values(
    self,
    coord: tuple | list | str | None = None,
    cell_type: str | None = None,
    complete: bool = True,
    get_type: bool = False,
) -> Iterator[list]:
    """Yield lines (lists) of Python values of the table.

    Filter by coordinates will parse the area defined by the coordinates.

    cell_type, complete, grt_type : see get_values()



    Args:

        coord -- str or tuple of int : coordinates of area

        cell_type -- 'boolean', 'float', 'date', 'string', 'time',
                     'currency', 'percentage' or 'all'

        complete -- boolean

        get_type -- boolean

    Returns: iterator of lists
    """
    if coord:
        x, y, z, t = self._translate_table_coordinates(coord)
    else:
        x = y = z = t = None
    for row in self.iter_rows(start=y, end=t):
        if z is None:
            width = self.width
        else:
            width = min(z + 1, self.width)
        if x is not None:
            width -= x
        values = row.get_values(
            (x, z),
            cell_type=cell_type,
            complete=complete,
            get_type=get_type,
        )
        # complete row to match column width
        if complete:
            if get_type:
                values.extend([(None, None)] * (width - len(values)))
            else:
                values.extend([None] * (width - len(values)))
        yield values

optimize_width

optimize_width() -> None

Remove in-place empty rows below and empty cells at the right of the table.

Keep repeated styles of empty cells but minimize row width.

Source code in odfdo/table.py

def optimize_width(self) -> None:
    """Remove *in-place* empty rows below and empty cells at the right of
    the table.

    Keep repeated styles of empty cells but minimize row width.
    """
    self._optimize_width_trim_rows()
    width = self._optimize_width_length()
    self._optimize_width_rstrip_rows(width)
    self._optimize_width_adapt_columns(width)

rstrip

rstrip(aggressive: bool = False) -> None

Remove in-place empty rows below and empty cells at the right of the table. Cells are empty if they contain no value or it evaluates to False, and no style.

If aggressive is True, empty cells with style are removed too.

Argument:

aggressive -- bool

Source code in odfdo/table.py

def rstrip(self, aggressive: bool = False) -> None:
    """Remove *in-place* empty rows below and empty cells at the right of
    the table. Cells are empty if they contain no value or it evaluates to
    False, and no style.

    If aggressive is True, empty cells with style are removed too.

    Argument:

        aggressive -- bool
    """
    # Step 1: remove empty rows below the table
    for row in reversed(self._get_rows()):
        if row.is_empty(aggressive=aggressive):
            row.parent.delete(row)  # type: ignore[union-attr]
        else:
            break
    # Step 2: rstrip remaining rows
    max_width = 0
    for row in self._get_rows():
        row.rstrip(aggressive=aggressive)
        # keep count of the biggest row
        max_width = max(max_width, row.width)
    # raz cache of rows
    self._table_cache.clear_row_indexes()
    # Step 3: trim columns to match max_width
    columns = self._get_columns()
    repeated_cols: list[EText] = self.xpath(  # type: ignore[assignment]
        "table:table-column/@table:number-columns-repeated"
    )
    if not isinstance(repeated_cols, list):
        raise TypeError
    unrepeated = len(columns) - len(repeated_cols)
    column_width = sum(int(r) for r in repeated_cols) + unrepeated
    diff = column_width - max_width
    if diff > 0:
        for column in reversed(columns):
            repeated = column.repeated or 1
            repeated = repeated - diff
            if repeated > 0:
                column.repeated = repeated
                break
            else:
                column.parent.delete(column)  # type: ignore[union-attr]
                diff = -repeated
                if diff == 0:
                    break
    # raz cache of columns
    self._table_cache.clear_col_indexes()
    self._compute_table_cache()

set_cell

set_cell(
    coord: tuple | list | str,
    cell: Cell | None = None,
    clone: bool = True,
) -> Cell

Replace a cell of the table at the given coordinates.

They are either a 2-tuple of (x, y) starting from 0, or a human-readable position like “C4”.

Args:

coord -- (int, int) or str : coordinate

cell -- Cell

return the cell, with x and y updated

Source code in odfdo/table.py

def set_cell(
    self,
    coord: tuple | list | str,
    cell: Cell | None = None,
    clone: bool = True,
) -> Cell:
    """Replace a cell of the table at the given coordinates.

    They are either a 2-tuple of (x, y) starting from 0, or a
    human-readable position like "C4".

    Args:

        coord -- (int, int) or str : coordinate

        cell -- Cell

    return the cell, with x and y updated
    """
    if cell is None:
        cell = Cell()
        clone = False
    x, y = self._translate_cell_coordinates(coord)
    if x is None:
        raise ValueError
    if y is None:
        raise ValueError
    cell.x = x
    cell.y = y
    if y >= self.height:
        row = Row()
        cell_back = row.set_cell(x, cell, clone=clone)
        self.set_row(y, row, clone=False)
    else:
        row_read = self._get_row2_base(y)
        if row_read is None:
            raise ValueError
        row = row_read
        row.y = y
        repeated = row.repeated or 1
        if repeated > 1:
            row = row.clone
            row.repeated = None
            cell_back = row.set_cell(x, cell, clone=clone)
            self.set_row(y, row, clone=False)
        else:
            cell_back = row.set_cell(x, cell, clone=clone)
            # Update width if necessary, since we don't use set_row
            self._update_width(row)
    return cell_back

set_cell_image

set_cell_image(
    coord: tuple | list | str,
    image_frame: Frame,
    doc_type: str | None = None,
) -> None

Deprecated, see related recipes to achieve the desired result.

Do all the magic to display an image in the cell at the given coordinates.

They are either a 2-tuple of (x, y) starting from 0, or a human-readable position like “C4”.

The frame element must contain the expected image position and dimensions.

DrawImage insertion depends on the document type, so the type must be provided or the table element must be already attached to a document.

Args:

coord -- (int, int) or str

image_frame -- Frame including an image

doc_type -- 'spreadsheet' or 'text'

Source code in odfdo/table.py

def set_cell_image(
    self,
    coord: tuple | list | str,
    image_frame: Frame,
    doc_type: str | None = None,
) -> None:
    """Deprecated, see related recipes to achieve the desired result.

    Do all the magic to display an image in the cell at the given
    coordinates.

    They are either a 2-tuple of (x, y) starting from 0, or a
    human-readable position like "C4".

    The frame element must contain the expected image position and
    dimensions.

    DrawImage insertion depends on the document type, so the type must be
    provided or the table element must be already attached to a document.

    Args:

        coord -- (int, int) or str

        image_frame -- Frame including an image

        doc_type -- 'spreadsheet' or 'text'
    """
    warn("Table.set_cell_image() is deprecated", DeprecationWarning, stacklevel=2)
    # Test document type
    if doc_type is None:
        body = self.document_body
        if body is None:
            raise ValueError("document type not found")
        doc_type = {"office:spreadsheet": "spreadsheet", "office:text": "text"}.get(
            body.tag
        )
        if doc_type is None:
            raise ValueError("document type not supported for images")
    # We need the end address of the image
    x, y = self._translate_cell_coordinates(coord)
    if x is None:
        raise ValueError
    if y is None:
        raise ValueError
    cell = self.get_cell((x, y))
    image_frame = image_frame.clone  # type: ignore[assignment]
    # Remove any previous paragraph, frame, etc.
    for child in cell.children:
        cell.delete(child)
    # Now it all depends on the document type
    if doc_type == "spreadsheet":
        image_frame.anchor_type = "char"
        # The frame needs end coordinates
        width, height = image_frame.size
        image_frame.set_attribute("table:end-x", width)
        image_frame.set_attribute("table:end-y", height)
        # FIXME what happens when the address changes?
        address = f"{self.name}.{digit_to_alpha(x)}{y + 1}"
        image_frame.set_attribute("table:end-cell-address", address)
        # The frame is directly in the cell
        cell.append(image_frame)
    elif doc_type == "text":
        # The frame must be in a paragraph
        cell.set_value("")
        paragraph = cell.get_element("text:p")
        if paragraph is None:
            raise ValueError
        paragraph.append(image_frame)
    self.set_cell(coord, cell)

set_cells

set_cells(
    cells: list[list[Cell]] | list[tuple[Cell]],
    coord: tuple | list | str | None = None,
    clone: bool = True,
) -> None

Set the cells in the table, from the ‘coord’ position.

‘coord’ is the coordinate of the upper left cell to be modified by values. If ‘coord’ is None, default to the position (0,0) (“A1”). If ‘coord’ is an area (e.g. “A2:B5”), the upper left position of this area is used as coordinate.

The table is not cleared before the operation, to reset the table before setting cells, use table.clear().

A list of lists is expected, with as many lists as rows to be set, and as many cell in each sublist as cells to be set in the row.

Args:

cells -- list of list of cells

coord -- tuple or str

values -- list of lists of python types

Source code in odfdo/table.py

def set_cells(
    self,
    cells: list[list[Cell]] | list[tuple[Cell]],
    coord: tuple | list | str | None = None,
    clone: bool = True,
) -> None:
    """Set the cells in the table, from the 'coord' position.

    'coord' is the coordinate of the upper left cell to be modified by
    values. If 'coord' is None, default to the position (0,0) ("A1").
    If 'coord' is an area (e.g. "A2:B5"), the upper left position of this
    area is used as coordinate.

    The table is *not* cleared before the operation, to reset the table
    before setting cells, use table.clear().

    A list of lists is expected, with as many lists as rows to be set, and
    as many cell in each sublist as cells to be set in the row.

    Args:

        cells -- list of list of cells

        coord -- tuple or str

        values -- list of lists of python types
    """
    if coord:
        x, y = self._translate_cell_coordinates(coord)
    else:
        x = y = 0
    if y is None:
        y = 0
    if x is None:
        x = 0
    y -= 1
    for row_cells in cells:
        y += 1
        if not row_cells:
            continue
        row = self.get_row(y, clone=True)
        repeated = row.repeated or 1
        if repeated >= 2:
            row.repeated = None
        row.set_cells(row_cells, start=x, clone=clone)
        self.set_row(y, row, clone=False)
        self._update_width(row)

set_column

set_column(
    x: int | str, column: Column | None = None
) -> Column

Replace the column at the given “x” position.

ODF columns don’t contain cells, only style information.

Position start at 0. So cell C4 is on column 2. Alphabetical position like “C” is accepted.

Args:

x -- int or str

column -- Column

Source code in odfdo/table.py

def set_column(
    self,
    x: int | str,
    column: Column | None = None,
) -> Column:
    """Replace the column at the given "x" position.

    ODF columns don't contain cells, only style information.

    Position start at 0. So cell C4 is on column 2. Alphabetical position
    like "C" is accepted.

    Args:

        x -- int or str

        column -- Column
    """
    x = self._translate_x_from_any(x)
    if column is None:
        column = Column()
        repeated = 1
    else:
        repeated = column.repeated or 1
    column.x = x
    # Outside the defined table ?
    diff = x - self.width
    if diff == 0:
        column_back = self.append_column(column, _repeated=repeated)
    elif diff > 0:
        self.append_column(Column(repeated=diff), _repeated=diff)
        column_back = self.append_column(column, _repeated=repeated)
    else:
        # Inside the defined table
        column_back = self._table_cache.set_col_in_cache(x, column, self)
    return column_back

set_column_cells

set_column_cells(x: int | str, cells: list[Cell]) -> None

Shortcut to set the list of cells at the given position.

Position start at 0. So cell C4 is on column 2. Alphabetical position like “C” is accepted.

The list must have the same length than the table height.

Args:

x -- int or str

cells -- list of Cell

Source code in odfdo/table.py

def set_column_cells(self, x: int | str, cells: list[Cell]) -> None:
    """Shortcut to set the list of cells at the given position.

    Position start at 0. So cell C4 is on column 2. Alphabetical position
    like "C" is accepted.

    The list must have the same length than the table height.

    Args:

        x -- int or str

        cells -- list of Cell
    """
    height = self.height
    if len(cells) != height:
        raise ValueError(f"col mismatch: {height} cells expected")
    cells_iterator = iter(cells)
    for y, row in enumerate(self.iter_rows()):
        row.set_cell(x, next(cells_iterator))
        self.set_row(y, row)

set_column_values

set_column_values(
    x: int | str,
    values: list,
    cell_type: str | None = None,
    currency: str | None = None,
    style: str | None = None,
) -> None

Shortcut to set the list of Python values of cells at the given position.

Position start at 0. So cell C4 is on column 2. Alphabetical position like “C” is accepted.

The list must have the same length than the table height.

Args:

x -- int or str

values -- list of Python types

cell_type -- 'boolean', 'currency', 'date', 'float', 'percentage',
             'string' or 'time'

currency -- three-letter str

style -- str

Source code in odfdo/table.py

def set_column_values(
    self,
    x: int | str,
    values: list,
    cell_type: str | None = None,
    currency: str | None = None,
    style: str | None = None,
) -> None:
    """Shortcut to set the list of Python values of cells at the given
    position.

    Position start at 0. So cell C4 is on column 2. Alphabetical position
    like "C" is accepted.

    The list must have the same length than the table height.

    Args:

        x -- int or str

        values -- list of Python types

        cell_type -- 'boolean', 'currency', 'date', 'float', 'percentage',
                     'string' or 'time'

        currency -- three-letter str

        style -- str
    """
    cells = [
        Cell(value, cell_type=cell_type, currency=currency, style=style)
        for value in values
    ]
    self.set_column_cells(x, cells)

set_named_range

set_named_range(
    name: str,
    crange: str | tuple | list,
    table_name: str | None = None,
    usage: str | None = None,
    global_scope: bool = True,
) -> None

Create a Named Range element and insert it in the document.

An existing named range of same name is replaced.

If “global_scope” is True (default), insert in the document’s body, else to the current Table. If “table_name” is None, use current table name.

Named ranges can be local to the Table or global. Global named ranges are stored at the body level, thus do not call this method on a cloned table if you need to access to the global named ranges.

Args:

name -- str, name of the named range

crange -- str or tuple of int, cell or area coordinate

table_name -- str or None, name of the table

usage -- None or 'print-range', 'filter', 'repeat-column', 'repeat-row'

global_scope -- bool, search in entire document or in the current table.

Source code in odfdo/table.py

def set_named_range(
    self,
    name: str,
    crange: str | tuple | list,
    table_name: str | None = None,
    usage: str | None = None,
    global_scope: bool = True,
) -> None:
    """Create a Named Range element and insert it in the document.

    An existing named range of same name is replaced.

    If "global_scope" is True (default), insert in the document's body, else to the current Table. If "table_name" is None, use current table name.

    Named ranges can be local to the Table or global. Global named ranges are stored at the body level, thus do not call this method on a cloned table if you need to access to the global named ranges.

    Args:

        name -- str, name of the named range

        crange -- str or tuple of int, cell or area coordinate

        table_name -- str or None, name of the table

        usage -- None or 'print-range', 'filter', 'repeat-column', 'repeat-row'

        global_scope -- bool, search in entire document or in the current table.
    """
    name = name.strip()
    if not name:
        raise ValueError("Name required")
    if global_scope:
        body = self.document_body
        if not body:
            raise ValueError("Table is not inside a document")
        if body.tag not in BODY_NR_TAGS:
            msg = (
                "Document must be of type Chart, Drawing, "
                "Presentation, Spreadsheet or Text"
            )
            raise TypeError(msg)
        if not table_name:
            table_name = self.name
        body.set_named_range(  # type: ignore[attr-defined]
            name=name,
            crange=crange,
            table_name=table_name,
            usage=usage,
        )
    else:
        self._local_set_named_range(name=name, crange=crange, usage=usage)

set_row

set_row(
    y: int | str, row: Row | None = None, clone: bool = True
) -> Row

Replace the row at the given position with the new one. Repetitions of the old row will be adjusted.

If row is None, a new empty row is created.

Position start at 0. So cell A4 is on row 3.

Args:

y -- int or str

row -- Row

returns the row, with updated row.y

Source code in odfdo/table.py

def set_row(self, y: int | str, row: Row | None = None, clone: bool = True) -> Row:
    """Replace the row at the given position with the new one. Repetitions of
    the old row will be adjusted.

    If row is None, a new empty row is created.

    Position start at 0. So cell A4 is on row 3.

    Args:

        y -- int or str

        row -- Row

    returns the row, with updated row.y
    """
    if row is None:
        row = Row()
        repeated = 1
        clone = False
    else:
        repeated = row.repeated or 1
    y = self._translate_y_from_any(y)
    row.y = y
    # Outside the defined table ?
    diff = y - self.height
    if diff == 0:
        row_back = self.append_row(row, _repeated=repeated, clone=clone)
    elif diff > 0:
        self.append_row(Row(repeated=diff), _repeated=diff, clone=clone)
        row_back = self.append_row(row, _repeated=repeated, clone=clone)
    else:
        # Inside the defined table
        row_back = self._table_cache.set_row_in_cache(y, row, self, clone=clone)
    # print self.serialize(True)
    # Update width if necessary
    self._update_width(row_back)
    return row_back

set_row_cells

set_row_cells(
    y: int | str, cells: list | None = None
) -> Row

Shortcut to set all the cells of the row at the given “y” position.

Position start at 0. So cell A4 is on row 3.

Args:

y -- int or str

cells -- list of Python types

style -- str

returns the row, with updated row.y

Source code in odfdo/table.py

def set_row_cells(self, y: int | str, cells: list | None = None) -> Row:
    """Shortcut to set *all* the cells of the row at the given "y"
    position.

    Position start at 0. So cell A4 is on row 3.

    Args:

        y -- int or str

        cells -- list of Python types

        style -- str

    returns the row, with updated row.y
    """
    if cells is None:
        cells = []
    row = Row()  # needed if clones rows
    row.extend_cells(cells)
    return self.set_row(y, row)  # needed if clones rows

set_row_values

set_row_values(
    y: int | str,
    values: list,
    cell_type: str | None = None,
    currency: str | None = None,
    style: str | None = None,
) -> Row

Shortcut to set the values of all cells of the row at the given “y” position.

Position start at 0. So cell A4 is on row 3.

Args:

y -- int or str

values -- list of Python types

cell_type -- 'boolean', 'currency', 'date', 'float', 'percentage',
             'string' or 'time'

currency -- three-letter str

style -- str

returns the row, with updated row.y

Source code in odfdo/table.py

def set_row_values(
    self,
    y: int | str,
    values: list,
    cell_type: str | None = None,
    currency: str | None = None,
    style: str | None = None,
) -> Row:
    """Shortcut to set the values of *all* cells of the row at the given
    "y" position.

    Position start at 0. So cell A4 is on row 3.

    Args:

        y -- int or str

        values -- list of Python types

        cell_type -- 'boolean', 'currency', 'date', 'float', 'percentage',
                     'string' or 'time'

        currency -- three-letter str

        style -- str

    returns the row, with updated row.y
    """
    row = Row()  # needed if clones rows
    row.set_values(values, style=style, cell_type=cell_type, currency=currency)
    return self.set_row(y, row)  # needed if clones rows

set_span

set_span(
    area: str | tuple | list, merge: bool = False
) -> bool

Create a Cell Span : span the first cell of the area on several columns and/or rows.

If merge is True, replace text of the cell by the concatenation of existing text in covered cells. Beware : if merge is True, old text is changed, if merge is False (the default), old text in covered cells is still present but not displayed by most GUI.

If the area defines only one cell, the set span will do nothing. It is not allowed to apply set span to an area whose one cell already belongs to previous cell span.

Area can be either one cell (like ‘A1’) or an area (‘A1:B2’). It can be provided as an alpha numeric value like “A1:B2’ or a tuple like (0, 0, 1, 1) or (0, 0).

Args:

area -- str or tuple of int, cell or area coordinate

merge -- boolean

Source code in odfdo/table.py

def set_span(
    self,
    area: str | tuple | list,
    merge: bool = False,
) -> bool:
    """Create a Cell Span : span the first cell of the area on several
    columns and/or rows.

    If merge is True, replace text of the cell by the concatenation of
    existing text in covered cells.
    Beware : if merge is True, old text is changed, if merge is False
    (the default), old text in covered cells is still present but not
    displayed by most GUI.

    If the area defines only one cell, the set span will do nothing.
    It is not allowed to apply set span to an area whose one cell already
    belongs to previous cell span.

    Area can be either one cell (like 'A1') or an area ('A1:B2'). It can
    be provided as an alpha numeric value like "A1:B2' or a tuple like
    (0, 0, 1, 1) or (0, 0).

    Args:

        area -- str or tuple of int, cell or area coordinate

        merge -- boolean
    """
    # get area
    digits = convert_coordinates(area)
    if len(digits) == 4:
        x, y, z, t = digits
    else:
        x, y = digits
        z, t = digits
    start = x, y
    end = z, t
    if start == end:
        # one cell : do nothing
        return False
    if x is None:
        raise ValueError
    if y is None:
        raise ValueError
    if z is None:
        raise ValueError
    if t is None:
        raise ValueError
    # check for previous span
    good = True
    # Check boundaries and empty cells : need to crate non existent cells
    # so don't use get_cells directly, but get_cell
    cells = []
    for yy in range(y, t + 1):
        row_cells = []
        for xx in range(x, z + 1):
            row_cells.append(
                self.get_cell((xx, yy), clone=True, keep_repeated=False)
            )
        cells.append(row_cells)
    for row in cells:
        for cell in row:
            if cell.is_spanned():
                good = False
                break
        if not good:
            break
    if not good:
        return False
    # Check boundaries
    # if z >= self.width or t >= self.height:
    #    self.set_cell(coord = end)
    #    print area, z, t
    #    cells = self.get_cells((x, y, z, t))
    #    print cells
    # do it:
    if merge:
        val_list = []
        for row in cells:
            for cell in row:
                if cell.is_empty(aggressive=True):
                    continue
                val = cell.get_value()
                if val is not None:
                    if isinstance(val, str):
                        val.strip()
                    if val != "":
                        val_list.append(val)
                    cell.clear()
        if val_list:
            if len(val_list) == 1:
                cells[0][0].set_value(val_list[0])  # type: ignore[arg-type]
            else:
                value = " ".join([str(v) for v in val_list if v])
                cells[0][0].set_value(value)
    cols = z - x + 1
    cells[0][0].set_attribute("table:number-columns-spanned", str(cols))
    rows = t - y + 1
    cells[0][0].set_attribute("table:number-rows-spanned", str(rows))
    for cell in cells[0][1:]:
        cell.tag = "table:covered-table-cell"
    for row in cells[1:]:
        for cell in row:
            cell.tag = "table:covered-table-cell"
    # replace cells in table
    self.set_cells(cells, coord=start, clone=False)
    return True

set_value

set_value(
    coord: tuple | list | str,
    value: Any,
    cell_type: str | None = None,
    currency: str | None = None,
    style: str | None = None,
) -> None

Set the Python value of the cell at the given coordinates.

They are either a 2-tuple of (x, y) starting from 0, or a human-readable position like “C4”.

Args:

coord -- (int, int) or str

value -- Python type

cell_type -- 'boolean', 'currency', 'date', 'float', 'percentage',
         'string' or 'time'

currency -- three-letter str

style -- str

Source code in odfdo/table.py

def set_value(
    self,
    coord: tuple | list | str,
    value: Any,
    cell_type: str | None = None,
    currency: str | None = None,
    style: str | None = None,
) -> None:
    """Set the Python value of the cell at the given coordinates.

    They are either a 2-tuple of (x, y) starting from 0, or a
    human-readable position like "C4".

    Args:

        coord -- (int, int) or str

        value -- Python type

        cell_type -- 'boolean', 'currency', 'date', 'float', 'percentage',
                 'string' or 'time'

        currency -- three-letter str

        style -- str
    """
    self.set_cell(
        coord,
        Cell(value, cell_type=cell_type, currency=currency, style=style),
        clone=False,
    )

set_values

set_values(
    values: list,
    coord: tuple | list | str | None = None,
    style: str | None = None,
    cell_type: str | None = None,
    currency: str | None = None,
) -> None

Set the value of cells in the table, from the ‘coord’ position with values.

‘coord’ is the coordinate of the upper left cell to be modified by values. If ‘coord’ is None, default to the position (0,0) (“A1”). If ‘coord’ is an area (e.g. “A2:B5”), the upper left position of this area is used as coordinate.

The table is not cleared before the operation, to reset the table before setting values, use table.clear().

A list of lists is expected, with as many lists as rows, and as many items in each sublist as cells to be set. None values in the list will create empty cells with no cell type (but eventually a style).

Args:

coord -- tuple or str

values -- list of lists of python types

cell_type -- 'boolean', 'currency', 'date', 'float', 'percentage',
             'string' or 'time'

currency -- three-letter str

style -- str

Source code in odfdo/table.py

def set_values(
    self,
    values: list,
    coord: tuple | list | str | None = None,
    style: str | None = None,
    cell_type: str | None = None,
    currency: str | None = None,
) -> None:
    """Set the value of cells in the table, from the 'coord' position with
    values.

    'coord' is the coordinate of the upper left cell to be modified by
    values. If 'coord' is None, default to the position (0,0) ("A1").
    If 'coord' is an area (e.g. "A2:B5"), the upper left position of this
    area is used as coordinate.

    The table is *not* cleared before the operation, to reset the table
    before setting values, use table.clear().

    A list of lists is expected, with as many lists as rows, and as many
    items in each sublist as cells to be set. None values in the list
    will create empty cells with no cell type (but eventually a style).

    Args:

        coord -- tuple or str

        values -- list of lists of python types

        cell_type -- 'boolean', 'currency', 'date', 'float', 'percentage',
                     'string' or 'time'

        currency -- three-letter str

        style -- str
    """
    if coord:
        x, y = self._translate_cell_coordinates(coord)
    else:
        x = y = 0
    if y is None:
        y = 0
    if x is None:
        x = 0
    y -= 1
    for row_values in values:
        y += 1
        if not row_values:
            continue
        row = self.get_row(y, clone=True)
        repeated = row.repeated or 1
        if repeated >= 2:
            row.repeated = None
        row.set_values(
            row_values,
            start=x,
            cell_type=cell_type,
            currency=currency,
            style=style,
        )
        self.set_row(y, row, clone=False)
        self._update_width(row)

to_csv

to_csv(
    path_or_file: str | Path | None = None,
    dialect: str = "excel",
    **fmtparams: Any,
) -> str | None

Export the table as CSV.

Save the CSV content to the path_or_file path, or return the content text if path_or_file is None.

Args:

path_or_file -- str or Path or None

dialect -- str, python csv.dialect, can be 'excel', 'unix'...

**fmtparams -- names parameters passed to csv.writer method

Source code in odfdo/table.py

def to_csv(
    self,
    path_or_file: str | Path | None = None,
    dialect: str = "excel",
    **fmtparams: Any,
) -> str | None:
    """Export the table as CSV.

    Save the CSV content to the path_or_file path, or return the content
    text if path_or_file is None.

    Args:

        path_or_file -- str or Path or None

        dialect -- str, python csv.dialect, can be 'excel', 'unix'...

        **fmtparams -- names parameters passed to csv.writer method
    """

    def write_content(csv_writer: object) -> None:
        for values in self.iter_values():
            line = []
            for value in values:
                if value is None:
                    value = ""
                line.append(value)
            csv_writer.writerow(line)  # type: ignore[attr-defined]

    content = StringIO(newline="")
    csv_writer = csv.writer(content, dialect=dialect, **fmtparams)
    write_content(csv_writer)
    if path_or_file:
        # windows fix: write file as binary
        Path(path_or_file).write_bytes(content.getvalue().encode())
        return None
    return content.getvalue()

transpose

transpose(coord: tuple | list | str | None = None) -> None

Swap in-place rows and columns of the table.

If ‘coord’ is not None, apply transpose only to the area defined by the coordinates. Beware, if area is not square, some cells mays be over written during the process.

Args:

coord -- str or tuple of int : coordinates of area

start -- int or str

Source code in odfdo/table.py

def transpose(self, coord: tuple | list | str | None = None) -> None:
    """Swap *in-place* rows and columns of the table.

    If 'coord' is not None, apply transpose only to the area defined by the
    coordinates. Beware, if area is not square, some cells mays be over
    written during the process.

    Args:

        coord -- str or tuple of int : coordinates of area

        start -- int or str
    """
    data = []
    if coord is None:
        for row in self.iter_rows():
            data.append(row.cells)
        transposed_data = zip_longest(*data)
        self.clear()
        # new_rows = []
        for row_cells in transposed_data:
            if not isiterable(row_cells):
                row_cells = (row_cells,)
            row = Row()
            row.extend_cells(row_cells)
            self.append_row(row, clone=False)
        self._compute_table_cache()
    else:
        x, y, z, t = self._translate_table_coordinates(coord)
        if x is None:
            x = 0
        else:
            x = min(x, self.width - 1)
        if z is None:
            z = self.width - 1
        else:
            z = min(z, self.width - 1)
        if y is None:
            y = 0
        else:
            y = min(y, self.height - 1)
        if t is None:
            t = self.height - 1
        else:
            t = min(t, self.height - 1)
        for row in self.iter_rows(start=y, end=t):
            data.append(list(row.iter_cells(start=x, end=z)))
        transposed_data = zip_longest(*data)
        # clear locally
        w = z - x + 1
        h = t - y + 1
        if w != h:
            nones = [[None] * w for i in range(h)]
            self.set_values(nones, coord=(x, y, z, t))
        # put transposed
        filtered_data: list[tuple[Cell]] = []
        for row_cells in transposed_data:
            if isinstance(row_cells, (list, tuple)):
                filtered_data.append(row_cells)
            else:
                filtered_data.append((row_cells,))
        self.set_cells(filtered_data, (x, y, x + h - 1, y + w - 1))
        self._compute_table_cache()

Text

Bases: NRMixin, Body

Root of the Text document content, “office:text”.

Source code in odfdo/body.py

class Text(NRMixin, Body):
    """Root of the Text document content, "office:text"."""

    _tag: str = "office:text"
    _properties: tuple[PropDef, ...] = ()

TextChange

Bases: Element

A text change position, “text:change”.

The TextChange “text:change” element marks a position in an empty region where text has been deleted.

Methods:

Name	Description
get_change_element
get_change_info
get_changed_region
get_deleted	Shortcut to get the deleted information stored in the TextDeletion
get_end	Return None.
get_id
get_inserted	Return None.
get_start	Return None.
set_id

Source code in odfdo/tracked_changes.py

class TextChange(Element):
    """A text change position, "text:change".

    The TextChange "text:change" element marks a position in an empty region
    where text has been deleted.
    """

    _tag = "text:change"

    def get_id(self) -> str | None:
        return self.get_attribute_string("text:change-id")

    def set_id(self, idx: str) -> None:
        self.set_attribute("text:change-id", idx)

    def _get_tracked_changes(self) -> Element | None:
        body = self.document_body
        if not body:
            raise ValueError
        return body.get_tracked_changes()

    def get_changed_region(
        self,
        tracked_changes: Element | None = None,
    ) -> Element | None:
        if not tracked_changes:
            tracked_changes = self._get_tracked_changes()
        idx = self.get_id()
        return tracked_changes.get_changed_region(text_id=idx)  # type: ignore

    def get_change_info(
        self,
        tracked_changes: Element | None = None,
    ) -> Element | None:
        changed_region = self.get_changed_region(tracked_changes=tracked_changes)
        if not changed_region:
            return None  # pragma: nocover
        return changed_region.get_change_info()  # type: ignore

    def get_change_element(
        self,
        tracked_changes: Element | None = None,
    ) -> Element | None:
        changed_region = self.get_changed_region(tracked_changes=tracked_changes)
        if not changed_region:
            return None  # pragma: nocover
        return changed_region.get_change_element()  # type: ignore

    def get_deleted(
        self,
        tracked_changes: Element | None = None,
        as_text: bool = False,
        no_header: bool = False,
        clean: bool = True,
    ) -> Element | None:
        """Shortcut to get the deleted information stored in the TextDeletion
        stored in the tracked changes.

        Returns: Paragraph (or None)."
        """
        changed = self.get_change_element(tracked_changes=tracked_changes)
        if not changed:
            return None  # pragma: nocover
        return changed.get_deleted(  # type: ignore
            as_text=as_text,
            no_header=no_header,
        )

    def get_inserted(
        self,
        as_text: bool = False,
        no_header: bool = False,
        clean: bool = True,
    ) -> str | Element | list[Element] | None:
        """Return None."""
        return None

    def get_start(self) -> TextChangeStart | None:
        """Return None."""
        return None

    def get_end(self) -> TextChangeEnd | None:
        """Return None."""
        return None

get_change_element

get_change_element(
    tracked_changes: Element | None = None,
) -> Element | None

Source code in odfdo/tracked_changes.py

def get_change_element(
    self,
    tracked_changes: Element | None = None,
) -> Element | None:
    changed_region = self.get_changed_region(tracked_changes=tracked_changes)
    if not changed_region:
        return None  # pragma: nocover
    return changed_region.get_change_element()  # type: ignore

get_change_info

get_change_info(
    tracked_changes: Element | None = None,
) -> Element | None

Source code in odfdo/tracked_changes.py

def get_change_info(
    self,
    tracked_changes: Element | None = None,
) -> Element | None:
    changed_region = self.get_changed_region(tracked_changes=tracked_changes)
    if not changed_region:
        return None  # pragma: nocover
    return changed_region.get_change_info()  # type: ignore

get_changed_region

get_changed_region(
    tracked_changes: Element | None = None,
) -> Element | None

Source code in odfdo/tracked_changes.py

def get_changed_region(
    self,
    tracked_changes: Element | None = None,
) -> Element | None:
    if not tracked_changes:
        tracked_changes = self._get_tracked_changes()
    idx = self.get_id()
    return tracked_changes.get_changed_region(text_id=idx)  # type: ignore

get_deleted

get_deleted(
    tracked_changes: Element | None = None,
    as_text: bool = False,
    no_header: bool = False,
    clean: bool = True,
) -> Element | None

Shortcut to get the deleted information stored in the TextDeletion stored in the tracked changes.

Returns: Paragraph (or None).”

Source code in odfdo/tracked_changes.py

def get_deleted(
    self,
    tracked_changes: Element | None = None,
    as_text: bool = False,
    no_header: bool = False,
    clean: bool = True,
) -> Element | None:
    """Shortcut to get the deleted information stored in the TextDeletion
    stored in the tracked changes.

    Returns: Paragraph (or None)."
    """
    changed = self.get_change_element(tracked_changes=tracked_changes)
    if not changed:
        return None  # pragma: nocover
    return changed.get_deleted(  # type: ignore
        as_text=as_text,
        no_header=no_header,
    )

get_end

get_end() -> TextChangeEnd | None

Return None.

Source code in odfdo/tracked_changes.py

def get_end(self) -> TextChangeEnd | None:
    """Return None."""
    return None

get_id

get_id() -> str | None

Source code in odfdo/tracked_changes.py

def get_id(self) -> str | None:
    return self.get_attribute_string("text:change-id")

get_inserted

get_inserted(
    as_text: bool = False,
    no_header: bool = False,
    clean: bool = True,
) -> str | Element | list[Element] | None

Return None.

Source code in odfdo/tracked_changes.py

def get_inserted(
    self,
    as_text: bool = False,
    no_header: bool = False,
    clean: bool = True,
) -> str | Element | list[Element] | None:
    """Return None."""
    return None

get_start

get_start() -> TextChangeStart | None

Return None.

Source code in odfdo/tracked_changes.py

def get_start(self) -> TextChangeStart | None:
    """Return None."""
    return None

set_id

set_id(idx: str) -> None

Source code in odfdo/tracked_changes.py

def set_id(self, idx: str) -> None:
    self.set_attribute("text:change-id", idx)

TextChangeEnd

Bases: TextChange

End of a changed region, “text:change-end”.

The TextChangeEnd “text:change-end” element marks the end of a region with content where text has been inserted or the format has been changed.

Methods:

Name	Description
get_deleted	Return None.
get_end	Return self.
get_inserted	Return the content between text:change-start and text:change-end.
get_start	Return the corresponding annotation starting tag or None.

Source code in odfdo/tracked_changes.py

class TextChangeEnd(TextChange):
    """End of a changed region, "text:change-end".

    The TextChangeEnd "text:change-end" element marks the end of a region with
    content where text has been inserted or the format has been changed.
    """

    _tag = "text:change-end"

    def get_start(self) -> TextChangeStart | None:
        """Return the corresponding annotation starting tag or None."""
        idx = self.get_id()
        parent = self.parent
        if parent is None:
            raise ValueError(
                "Can not find end tag: no parent available."
            )  # pragma: nocover
        body: Body | Element = self.document_body or self.root
        return body.get_text_change_start(idx=idx)

    def get_end(self) -> TextChangeEnd | None:
        """Return self."""
        return self

    def get_deleted(self, *args: Any, **kwargs: Any) -> Element | None:
        """Return None."""
        return None

    def get_inserted(
        self,
        as_text: bool = False,
        no_header: bool = False,
        clean: bool = True,
    ) -> str | Element | list[Element] | None:
        """Return the content between text:change-start and text:change-end.

        If no content exists (deletion tag), returns None (or '' if text flag
        is True).
        If as_text is True: returns the text content.
        If clean is True: suppress unwanted tags (deletions marks, ...)
        If no_header is True: existing text:h are changed in text:p
        By default: returns a list of Element, cleaned and with headers

        Args:

            as_text -- boolean

            clean -- boolean

            no_header -- boolean

        Returns: list or Element or text
        """

        # idx = self.get_id()
        start = self.get_start()
        end = self.get_end()
        if end is None or start is None:
            if as_text:
                return ""
            return None
        body: Body | Element = self.document_body or self.root
        return elements_between(
            body, start, end, as_text=as_text, no_header=no_header, clean=clean
        )

get_deleted

get_deleted(*args: Any, **kwargs: Any) -> Element | None

Return None.

Source code in odfdo/tracked_changes.py

def get_deleted(self, *args: Any, **kwargs: Any) -> Element | None:
    """Return None."""
    return None

get_end

get_end() -> TextChangeEnd | None

Return self.

Source code in odfdo/tracked_changes.py

def get_end(self) -> TextChangeEnd | None:
    """Return self."""
    return self

get_inserted

get_inserted(
    as_text: bool = False,
    no_header: bool = False,
    clean: bool = True,
) -> str | Element | list[Element] | None

Return the content between text:change-start and text:change-end.

If no content exists (deletion tag), returns None (or ‘’ if text flag is True). If as_text is True: returns the text content. If clean is True: suppress unwanted tags (deletions marks, …) If no_header is True: existing text:h are changed in text:p By default: returns a list of Element, cleaned and with headers

Args:

as_text -- boolean

clean -- boolean

no_header -- boolean

Returns: list or Element or text

Source code in odfdo/tracked_changes.py

def get_inserted(
    self,
    as_text: bool = False,
    no_header: bool = False,
    clean: bool = True,
) -> str | Element | list[Element] | None:
    """Return the content between text:change-start and text:change-end.

    If no content exists (deletion tag), returns None (or '' if text flag
    is True).
    If as_text is True: returns the text content.
    If clean is True: suppress unwanted tags (deletions marks, ...)
    If no_header is True: existing text:h are changed in text:p
    By default: returns a list of Element, cleaned and with headers

    Args:

        as_text -- boolean

        clean -- boolean

        no_header -- boolean

    Returns: list or Element or text
    """

    # idx = self.get_id()
    start = self.get_start()
    end = self.get_end()
    if end is None or start is None:
        if as_text:
            return ""
        return None
    body: Body | Element = self.document_body or self.root
    return elements_between(
        body, start, end, as_text=as_text, no_header=no_header, clean=clean
    )

get_start

get_start() -> TextChangeStart | None

Return the corresponding annotation starting tag or None.

Source code in odfdo/tracked_changes.py

def get_start(self) -> TextChangeStart | None:
    """Return the corresponding annotation starting tag or None."""
    idx = self.get_id()
    parent = self.parent
    if parent is None:
        raise ValueError(
            "Can not find end tag: no parent available."
        )  # pragma: nocover
    body: Body | Element = self.document_body or self.root
    return body.get_text_change_start(idx=idx)

TextChangeStart

Bases: TextChangeEnd

Start of a changed region, “text:change-start”.

The TextChangeStart “text:change-start” element marks the start of a region with content where text has been inserted or the format has been changed.

Methods:

Name	Description
delete	Delete the given element from the XML tree. If no element is given,
get_end	Return the corresponding change-end tag or None.
get_start	Return self.

Source code in odfdo/tracked_changes.py

class TextChangeStart(TextChangeEnd):
    """Start of a changed region, "text:change-start".

    The TextChangeStart "text:change-start" element marks the start of a region
    with content where text has been inserted or the format has been changed.
    """

    _tag = "text:change-start"

    def get_start(self) -> TextChangeStart:
        """Return self."""
        return self

    def get_end(self) -> TextChangeEnd:
        """Return the corresponding change-end tag or None."""
        idx = self.get_id()
        parent = self.parent
        if parent is None:
            raise ValueError(
                "Can not find end tag: no parent available."
            )  # pragma: nocover
        body: Body | Element = self.document_body or self.root
        return body.get_text_change_end(idx=idx)  # type: ignore

    def delete(
        self,
        child: Element | None = None,
        keep_tail: bool = True,
    ) -> None:
        """Delete the given element from the XML tree. If no element is given,
        "self" is deleted. The XML library may allow to continue to use an
        element now "orphan" as long as you have a reference to it.

        For TextChangeStart : delete also the end tag if exists.

        Args:

            child -- Element

            keep_tail -- boolean (default to True), True for most usages.
        """
        if child is not None:  # act like normal delete
            return super().delete(child, keep_tail)  # pragma: nocover
        idx = self.get_id()
        if self.parent is None:
            raise ValueError("cannot delete the root element")  # pragma: nocover
        body: Body | Element = self.document_body or self.root
        end = body.get_text_change_end(idx=idx)
        if end:  # pragma: nocover
            end.delete()
        # act like normal delete
        super().delete()

delete

delete(
    child: Element | None = None, keep_tail: bool = True
) -> None

Delete the given element from the XML tree. If no element is given, “self” is deleted. The XML library may allow to continue to use an element now “orphan” as long as you have a reference to it.

For TextChangeStart : delete also the end tag if exists.

Args:

child -- Element

keep_tail -- boolean (default to True), True for most usages.

Source code in odfdo/tracked_changes.py

def delete(
    self,
    child: Element | None = None,
    keep_tail: bool = True,
) -> None:
    """Delete the given element from the XML tree. If no element is given,
    "self" is deleted. The XML library may allow to continue to use an
    element now "orphan" as long as you have a reference to it.

    For TextChangeStart : delete also the end tag if exists.

    Args:

        child -- Element

        keep_tail -- boolean (default to True), True for most usages.
    """
    if child is not None:  # act like normal delete
        return super().delete(child, keep_tail)  # pragma: nocover
    idx = self.get_id()
    if self.parent is None:
        raise ValueError("cannot delete the root element")  # pragma: nocover
    body: Body | Element = self.document_body or self.root
    end = body.get_text_change_end(idx=idx)
    if end:  # pragma: nocover
        end.delete()
    # act like normal delete
    super().delete()

get_end

get_end() -> TextChangeEnd

Return the corresponding change-end tag or None.

Source code in odfdo/tracked_changes.py

def get_end(self) -> TextChangeEnd:
    """Return the corresponding change-end tag or None."""
    idx = self.get_id()
    parent = self.parent
    if parent is None:
        raise ValueError(
            "Can not find end tag: no parent available."
        )  # pragma: nocover
    body: Body | Element = self.document_body or self.root
    return body.get_text_change_end(idx=idx)  # type: ignore

get_start

get_start() -> TextChangeStart

Return self.

Source code in odfdo/tracked_changes.py

def get_start(self) -> TextChangeStart:
    """Return self."""
    return self

TextChangedRegion

Bases: Element

A changed region of text, “text:changed-region”.

Each TextChangedRegion “text:changed-region” element contains a single element, one of TextInsertion, TextDeletion or TextFormatChange that corresponds to a change being tracked within the scope of the “text:tracked-changes” element that contains the “text:changed-region” instance. The xml:id attribute of the TextChangedRegion is referenced from the “text:change”, “text:change-start” and “text:change-end” elements that identify where the change applies to markup in the scope of the “text:tracked-changes” element.

Warning :

For this implementation, text:change should be referenced only once in the scope, which is different from ODF 1.2 requirement:

    " A "text:changed-region" can be referenced by more than one
     change, but the corresponding referencing change mark elements
     shall be of the same change type - insertion, format change or
     deletion. "

Methods:

Name	Description
get_change_element	Get the change element child. It can be either: TextInsertion,
get_change_info	Shortcut to get the ChangeInfo element of the change element child.
get_id	Get the “text:id” attribute.
set_change_info	Shortcut to set the ChangeInfo element of the sub change element.
set_id	Set both the “text:id” and “xml:id” attributes with same value.

Source code in odfdo/tracked_changes.py

class TextChangedRegion(Element):
    """A changed region of text, "text:changed-region".

    Each TextChangedRegion "text:changed-region" element contains a single
    element, one of TextInsertion, TextDeletion or TextFormatChange that
    corresponds to a change being tracked within the scope of the
    "text:tracked-changes" element that contains the "text:changed-region"
    instance.
    The xml:id attribute of the TextChangedRegion is referenced
    from the "text:change", "text:change-start" and "text:change-end"
    elements that identify where the change applies to markup in the scope of
    the "text:tracked-changes" element.

    Warning :

    For this implementation, text:change should be referenced only
    once in the scope, which is different from ODF 1.2 requirement:

            " A "text:changed-region" can be referenced by more than one
             change, but the corresponding referencing change mark elements
             shall be of the same change type - insertion, format change or
             deletion. "
    """

    _tag = "text:changed-region"

    def get_change_info(self) -> Element | None:
        """Shortcut to get the ChangeInfo element of the change element child.

        Returns: ChangeInfo element.
        """
        return self.get_element("descendant::office:change-info")

    def set_change_info(
        self,
        change_info: Element | None = None,
        creator: str | None = None,
        date: datetime | None = None,
        comments: Element | list[Element] | None = None,
    ) -> None:
        """Shortcut to set the ChangeInfo element of the sub change element.
        See TextInsertion.set_change_info() for details.

        Args:

             change_info -- ChangeInfo element (or None)

             creator -- str (or None)

             date -- datetime (or None)

             comments -- Paragraph or list of Paragraph elements (or None)
        """
        child = self.get_change_element()
        if not child:
            raise ValueError("Empty TextChangedRegion")
        child.set_change_info(  # type: ignore
            change_info=change_info, creator=creator, date=date, comments=comments
        )

    def get_change_element(self) -> Element | None:
        """Get the change element child. It can be either: TextInsertion,
        TextDeletion, or TextFormatChange as an Element object.

        Returns: Element.
        """
        request = (
            "descendant::text:insertion "
            "| descendant::text:deletion"
            "| descendant::text:format-change"
        )
        return self._filtered_element(request, 0)

    def _get_text_id(self) -> str | None:
        return self.get_attribute_string("text:id")

    def _set_text_id(self, text_id: str) -> None:
        self.set_attribute("text:id", text_id)

    def _get_xml_id(self) -> str | None:
        return self.get_attribute_string("xml:id")

    def _set_xml_id(self, xml_id: str) -> None:
        self.set_attribute("xml:id", xml_id)

    def get_id(self) -> str | None:
        """Get the "text:id" attribute.

        Returns: str
        """
        return self._get_text_id()

    def set_id(self, idx: str) -> None:
        """Set both the "text:id" and "xml:id" attributes with same value."""
        self._set_text_id(idx)
        self._set_xml_id(idx)

get_change_element

get_change_element() -> Element | None

Get the change element child. It can be either: TextInsertion, TextDeletion, or TextFormatChange as an Element object.

Returns: Element.

Source code in odfdo/tracked_changes.py

def get_change_element(self) -> Element | None:
    """Get the change element child. It can be either: TextInsertion,
    TextDeletion, or TextFormatChange as an Element object.

    Returns: Element.
    """
    request = (
        "descendant::text:insertion "
        "| descendant::text:deletion"
        "| descendant::text:format-change"
    )
    return self._filtered_element(request, 0)

get_change_info

get_change_info() -> Element | None

Shortcut to get the ChangeInfo element of the change element child.

Returns: ChangeInfo element.

Source code in odfdo/tracked_changes.py

def get_change_info(self) -> Element | None:
    """Shortcut to get the ChangeInfo element of the change element child.

    Returns: ChangeInfo element.
    """
    return self.get_element("descendant::office:change-info")

get_id

get_id() -> str | None

Get the “text:id” attribute.

Returns: str

Source code in odfdo/tracked_changes.py

def get_id(self) -> str | None:
    """Get the "text:id" attribute.

    Returns: str
    """
    return self._get_text_id()

set_change_info

set_change_info(
    change_info: Element | None = None,
    creator: str | None = None,
    date: datetime | None = None,
    comments: Element | list[Element] | None = None,
) -> None

Shortcut to set the ChangeInfo element of the sub change element. See TextInsertion.set_change_info() for details.

Args:

 change_info -- ChangeInfo element (or None)

 creator -- str (or None)

 date -- datetime (or None)

 comments -- Paragraph or list of Paragraph elements (or None)

Source code in odfdo/tracked_changes.py

def set_change_info(
    self,
    change_info: Element | None = None,
    creator: str | None = None,
    date: datetime | None = None,
    comments: Element | list[Element] | None = None,
) -> None:
    """Shortcut to set the ChangeInfo element of the sub change element.
    See TextInsertion.set_change_info() for details.

    Args:

         change_info -- ChangeInfo element (or None)

         creator -- str (or None)

         date -- datetime (or None)

         comments -- Paragraph or list of Paragraph elements (or None)
    """
    child = self.get_change_element()
    if not child:
        raise ValueError("Empty TextChangedRegion")
    child.set_change_info(  # type: ignore
        change_info=change_info, creator=creator, date=date, comments=comments
    )

set_id

set_id(idx: str) -> None

Set both the “text:id” and “xml:id” attributes with same value.

Source code in odfdo/tracked_changes.py

def set_id(self, idx: str) -> None:
    """Set both the "text:id" and "xml:id" attributes with same value."""
    self._set_text_id(idx)
    self._set_xml_id(idx)

TextDeletion

Bases: TextInsertion

Information on a text deletion, “text:deletion”.

The TextDeletion “text:deletion” contains information that identifies the person responsible for a deletion and the date of that deletion. This information may also contain one or more Paragraph which contains a comment on the deletion. The TextDeletion element may also contain content that was deleted while change tracking was enabled. The position where the text was deleted is marked by a “text:change” element. Deleted text is contained in a paragraph element. To reconstruct the original text, the paragraph containing the deleted text is merged with its surrounding paragraph or heading element. To reconstruct the text before a deletion took place: - If the change mark is inside a paragraph, insert the content that was deleted, but remove all leading start tags up to and including the first “text:p” element and all trailing end tags up to and including the last “/text:p” or “/text:h” element. If the last trailing element is a “/text:h”, change the end tag “/text:p” following this insertion to a “/text:h” element. - If the change mark is inside a heading, insert the content that was deleted, but remove all leading start tags up to and including the first “text:h” element and all trailing end tags up to and including the last “/text:h” or “/text:p” element. If the last trailing element is a “/text:p”, change the end tag “/text:h” following this insertion to a “/text:p” element. - Otherwise, copy the text content of the “text:deletion” element in place of the change mark.

Methods:

Name	Description
get_deleted	Get the deleted information stored in the TextDeletion.
get_inserted	Return None.
set_deleted	Set the deleted information stored in the TextDeletion. An actual

Source code in odfdo/tracked_changes.py

class TextDeletion(TextInsertion):
    """Information on a text deletion, "text:deletion".

    The TextDeletion "text:deletion" contains information that identifies
    the person responsible for a deletion and the date of that deletion.
    This information may also contain one or more Paragraph which contains
    a comment on the deletion. The TextDeletion element may also contain
    content that was deleted while change tracking was enabled. The position
    where the text was deleted is marked by a "text:change" element. Deleted
    text is contained in a paragraph element. To reconstruct the original
    text, the paragraph containing the deleted text is merged with its
    surrounding paragraph or heading element. To reconstruct the text before
    a deletion took place:
      - If the change mark is inside a paragraph, insert the content that was
      deleted, but remove all leading start tags up to and including the
      first "text:p" element and all trailing end tags up to and including
      the last "/text:p" or "/text:h" element. If the last trailing element
      is a "/text:h", change the end tag "/text:p" following this insertion
      to a "/text:h" element.
      - If the change mark is inside a heading, insert the content that was
      deleted, but remove all leading start tags up to and including the
      first "text:h" element and all trailing end tags up to and including
      the last "/text:h" or "/text:p" element. If the last trailing element
      is a "/text:p", change the end tag "/text:h" following this insertion
      to a "/text:p" element.
      - Otherwise, copy the text content of the "text:deletion" element in
      place of the change mark.
    """

    _tag = "text:deletion"

    def get_deleted(
        self,
        as_text: bool = False,
        no_header: bool = False,
    ) -> str | list[Element] | None:
        """Get the deleted information stored in the TextDeletion.
        If as_text is True: returns the text content.
        If no_header is True: existing Heading are changed in Paragraph

        Args:

            as_text -- boolean

            no_header -- boolean

        Returns: Paragraph and Header list
        """
        children = self.children
        inner = [elem for elem in children if elem.tag != "office:change-info"]
        if no_header:  # crude replace t:h by t:p
            print("noheaders")
            new_inner = []
            for element in inner:
                if element.tag == "text:h":
                    children = element.children
                    text = element.text
                    para = Element.from_tag("text:p")
                    para.text = text
                    for child in children:
                        para.append(child)  # pragma: nocover
                    new_inner.append(para)
                else:
                    new_inner.append(element)
            inner = new_inner
        if as_text:
            return "\n".join([elem.get_formatted_text(context=None) for elem in inner])
        return inner

    def set_deleted(self, paragraph_or_list: Element | list[Element]) -> None:
        """Set the deleted information stored in the TextDeletion. An actual
        content that was deleted is expected, embedded in a Paragraph element or
        Header.

        Args:

            paragraph_or_list -- Paragraph or Header element (or list)
        """
        for element in self.get_deleted():  # type: ignore
            self.delete(element)  # type: ignore
        if isinstance(paragraph_or_list, Element):
            paragraph_or_list = [paragraph_or_list]
        for element in paragraph_or_list:
            self.append(element)

    def get_inserted(
        self,
        as_text: bool = False,
        no_header: bool = False,
        clean: bool = True,
    ) -> str | Element | list[Element] | None:
        """Return None."""
        if as_text:
            return ""
        return None

get_deleted

get_deleted(
    as_text: bool = False, no_header: bool = False
) -> str | list[Element] | None

Get the deleted information stored in the TextDeletion. If as_text is True: returns the text content. If no_header is True: existing Heading are changed in Paragraph

Args:

as_text -- boolean

no_header -- boolean

Returns: Paragraph and Header list

Source code in odfdo/tracked_changes.py

def get_deleted(
    self,
    as_text: bool = False,
    no_header: bool = False,
) -> str | list[Element] | None:
    """Get the deleted information stored in the TextDeletion.
    If as_text is True: returns the text content.
    If no_header is True: existing Heading are changed in Paragraph

    Args:

        as_text -- boolean

        no_header -- boolean

    Returns: Paragraph and Header list
    """
    children = self.children
    inner = [elem for elem in children if elem.tag != "office:change-info"]
    if no_header:  # crude replace t:h by t:p
        print("noheaders")
        new_inner = []
        for element in inner:
            if element.tag == "text:h":
                children = element.children
                text = element.text
                para = Element.from_tag("text:p")
                para.text = text
                for child in children:
                    para.append(child)  # pragma: nocover
                new_inner.append(para)
            else:
                new_inner.append(element)
        inner = new_inner
    if as_text:
        return "\n".join([elem.get_formatted_text(context=None) for elem in inner])
    return inner

get_inserted

get_inserted(
    as_text: bool = False,
    no_header: bool = False,
    clean: bool = True,
) -> str | Element | list[Element] | None

Return None.

Source code in odfdo/tracked_changes.py

def get_inserted(
    self,
    as_text: bool = False,
    no_header: bool = False,
    clean: bool = True,
) -> str | Element | list[Element] | None:
    """Return None."""
    if as_text:
        return ""
    return None

set_deleted

set_deleted(
    paragraph_or_list: Element | list[Element],
) -> None

Set the deleted information stored in the TextDeletion. An actual content that was deleted is expected, embedded in a Paragraph element or Header.

Args:

paragraph_or_list -- Paragraph or Header element (or list)

Source code in odfdo/tracked_changes.py

def set_deleted(self, paragraph_or_list: Element | list[Element]) -> None:
    """Set the deleted information stored in the TextDeletion. An actual
    content that was deleted is expected, embedded in a Paragraph element or
    Header.

    Args:

        paragraph_or_list -- Paragraph or Header element (or list)
    """
    for element in self.get_deleted():  # type: ignore
        self.delete(element)  # type: ignore
    if isinstance(paragraph_or_list, Element):
        paragraph_or_list = [paragraph_or_list]
    for element in paragraph_or_list:
        self.append(element)

TextFormatChange

Bases: TextInsertion

A change in text formatting, “text:format-change”.

The TextFormatChange “text:format-change” element represents any change in formatting attributes. The region where the change took place is marked by “text:change-start”, “text:change-end” or “text:change” elements.

Note: This element does not contain formatting changes that have taken place.

Source code in odfdo/tracked_changes.py

class TextFormatChange(TextInsertion):
    """A change in text formatting, "text:format-change".

    The TextFormatChange "text:format-change" element represents any change
    in formatting attributes. The region where the change took place is
    marked by "text:change-start", "text:change-end" or "text:change"
    elements.

    Note: This element does not contain formatting changes that have taken
    place.
    """

    _tag = "text:format-change"

TextInsertion

Bases: Element

Information on a text insertion, “text:insertion”.

The TextInsertion “text:insertion” element contains the information that identifies the person responsible for a change and the date of that change. This information may also contain one or more “text:p” Paragraph which contain a comment on the insertion. The TextInsertion element’s parent “text:changed-region” element has an xml:id or text:id attribute, the value of which binds that parent element to the text:change-id attribute on the “text:change-start” and “text:change-end” elements.

Methods:

Name	Description
get_change_info	Get the ChangeInfo child of the element.
get_deleted	Returns: None.
get_inserted	Shortcut to text:change-start.get_inserted(). Return the content
set_change_info	Set the ChangeInfo element for the change element. If change_info is

Source code in odfdo/tracked_changes.py

class TextInsertion(Element):
    """Information on a text insertion, "text:insertion".

    The TextInsertion "text:insertion" element contains the information that
    identifies the person responsible for a change and the date of that change.
    This information may also contain one or more "text:p" Paragraph which
    contain a comment on the insertion. The TextInsertion element's parent
    "text:changed-region" element has an xml:id or text:id attribute, the value
    of which binds that parent element to the text:change-id attribute on the
    "text:change-start" and "text:change-end" elements.
    """

    _tag = "text:insertion"

    def get_deleted(
        self,
        as_text: bool = False,
        no_header: bool = False,
    ) -> str | list[Element] | None:
        """Returns: None."""
        if as_text:
            return ""
        return None

    def get_inserted(
        self,
        as_text: bool = False,
        no_header: bool = False,
        clean: bool = True,
    ) -> str | Element | list[Element] | None:
        """Shortcut to text:change-start.get_inserted(). Return the content
        between text:change-start and text:change-end.

        If as_text is True: returns the text content.
        If no_header is True: existing Heading are changed in Paragraph
        If no_header is True: existing text:h are changed in text:p
        By default: returns a list of Element, cleaned and with headers

        Args:

            as_text -- boolean

            clean -- boolean

            no_header -- boolean

        Returns: list or Element or text
        """
        current = self.parent  # text:changed-region
        if not isinstance(current, TextChangedRegion):
            raise TypeError("Missing parent TextChangedRegion")
        idx = current.get_id()
        body: Body | Element = self.document_body or self.root
        text_change = body.get_text_change_start(idx=idx)
        if not text_change:
            raise ValueError  # pragma: nocover
        return text_change.get_inserted(
            as_text=as_text, no_header=no_header, clean=clean
        )

    def get_change_info(self) -> Element | None:
        """Get the ChangeInfo child of the element.

        Returns: ChangeInfo element.
        """
        return self.get_element("descendant::office:change-info")

    def set_change_info(
        self,
        change_info: Element | None = None,
        creator: str | None = None,
        date: datetime | None = None,
        comments: Element | list[Element] | None = None,
    ) -> None:
        """Set the ChangeInfo element for the change element. If change_info is
        not provided, creator, date and comments will be used to build a
        suitable change info element. Default for creator is 'Unknown', default
        for date is current time and default for comments is no comment at all.
        The new change info element will replace any existent ChangeInfo.

        Args:

             change_info -- ChangeInfo element (or None)

             cretor -- str (or None)

             date -- datetime (or None)

             comments -- Paragraph or list of Paragraph elements (or None)
        """
        if change_info is None:
            new_change_info = ChangeInfo(creator, date)
            if comments is not None:
                if isinstance(comments, Element):
                    # single paragraph comment
                    comments_list = [comments]
                else:
                    comments_list = comments
                # assume iterable of Paragraph
                for paragraph in comments_list:
                    if not isinstance(paragraph, Paragraph):
                        raise TypeError(f"Not a Paragraph: '{paragraph!r}'")
                    new_change_info.insert(paragraph, xmlposition=LAST_CHILD)
        else:
            if not isinstance(change_info, ChangeInfo):
                raise TypeError(f"Not a ChangeInfo: '{change_info!r}'")
            new_change_info = change_info

        old = self.get_change_info()
        if old is not None:
            self.replace_element(old, new_change_info)
        else:
            self.insert(new_change_info, xmlposition=FIRST_CHILD)

get_change_info

get_change_info() -> Element | None

Get the ChangeInfo child of the element.

Returns: ChangeInfo element.

Source code in odfdo/tracked_changes.py

def get_change_info(self) -> Element | None:
    """Get the ChangeInfo child of the element.

    Returns: ChangeInfo element.
    """
    return self.get_element("descendant::office:change-info")

get_deleted

get_deleted(
    as_text: bool = False, no_header: bool = False
) -> str | list[Element] | None

Returns: None.

Source code in odfdo/tracked_changes.py

def get_deleted(
    self,
    as_text: bool = False,
    no_header: bool = False,
) -> str | list[Element] | None:
    """Returns: None."""
    if as_text:
        return ""
    return None

get_inserted

get_inserted(
    as_text: bool = False,
    no_header: bool = False,
    clean: bool = True,
) -> str | Element | list[Element] | None

Shortcut to text:change-start.get_inserted(). Return the content between text:change-start and text:change-end.

If as_text is True: returns the text content. If no_header is True: existing Heading are changed in Paragraph If no_header is True: existing text:h are changed in text:p By default: returns a list of Element, cleaned and with headers

Args:

as_text -- boolean

clean -- boolean

no_header -- boolean

Returns: list or Element or text

Source code in odfdo/tracked_changes.py

def get_inserted(
    self,
    as_text: bool = False,
    no_header: bool = False,
    clean: bool = True,
) -> str | Element | list[Element] | None:
    """Shortcut to text:change-start.get_inserted(). Return the content
    between text:change-start and text:change-end.

    If as_text is True: returns the text content.
    If no_header is True: existing Heading are changed in Paragraph
    If no_header is True: existing text:h are changed in text:p
    By default: returns a list of Element, cleaned and with headers

    Args:

        as_text -- boolean

        clean -- boolean

        no_header -- boolean

    Returns: list or Element or text
    """
    current = self.parent  # text:changed-region
    if not isinstance(current, TextChangedRegion):
        raise TypeError("Missing parent TextChangedRegion")
    idx = current.get_id()
    body: Body | Element = self.document_body or self.root
    text_change = body.get_text_change_start(idx=idx)
    if not text_change:
        raise ValueError  # pragma: nocover
    return text_change.get_inserted(
        as_text=as_text, no_header=no_header, clean=clean
    )

set_change_info

set_change_info(
    change_info: Element | None = None,
    creator: str | None = None,
    date: datetime | None = None,
    comments: Element | list[Element] | None = None,
) -> None

Set the ChangeInfo element for the change element. If change_info is not provided, creator, date and comments will be used to build a suitable change info element. Default for creator is ‘Unknown’, default for date is current time and default for comments is no comment at all. The new change info element will replace any existent ChangeInfo.

Args:

 change_info -- ChangeInfo element (or None)

 cretor -- str (or None)

 date -- datetime (or None)

 comments -- Paragraph or list of Paragraph elements (or None)

Source code in odfdo/tracked_changes.py

def set_change_info(
    self,
    change_info: Element | None = None,
    creator: str | None = None,
    date: datetime | None = None,
    comments: Element | list[Element] | None = None,
) -> None:
    """Set the ChangeInfo element for the change element. If change_info is
    not provided, creator, date and comments will be used to build a
    suitable change info element. Default for creator is 'Unknown', default
    for date is current time and default for comments is no comment at all.
    The new change info element will replace any existent ChangeInfo.

    Args:

         change_info -- ChangeInfo element (or None)

         cretor -- str (or None)

         date -- datetime (or None)

         comments -- Paragraph or list of Paragraph elements (or None)
    """
    if change_info is None:
        new_change_info = ChangeInfo(creator, date)
        if comments is not None:
            if isinstance(comments, Element):
                # single paragraph comment
                comments_list = [comments]
            else:
                comments_list = comments
            # assume iterable of Paragraph
            for paragraph in comments_list:
                if not isinstance(paragraph, Paragraph):
                    raise TypeError(f"Not a Paragraph: '{paragraph!r}'")
                new_change_info.insert(paragraph, xmlposition=LAST_CHILD)
    else:
        if not isinstance(change_info, ChangeInfo):
            raise TypeError(f"Not a ChangeInfo: '{change_info!r}'")
        new_change_info = change_info

    old = self.get_change_info()
    if old is not None:
        self.replace_element(old, new_change_info)
    else:
        self.insert(new_change_info, xmlposition=FIRST_CHILD)

TocEntryTemplate

Bases: Element

Template for entry of TOC, “text:table-of-content-entry-template”.

Methods:

Name	Description
__init__	Create template for entry of TOC “text:table-of-content-entry-
complete_defaults

Attributes:

Name	Type	Description
outline_level	int | None
style

Source code in odfdo/toc.py

class TocEntryTemplate(Element):
    """Template for entry of TOC, "text:table-of-content-entry-template"."""

    _tag = "text:table-of-content-entry-template"
    _properties = (PropDef("style", "text:style-name"),)

    def __init__(
        self,
        style: str | None = None,
        outline_level: int | None = None,
        **kwargs: Any,
    ) -> None:
        """Create template for entry of TOC "text:table-of-content-entry-
        template".

        Args:

            style -- str
        """
        super().__init__(**kwargs)
        if self._do_init:
            if style:
                self.style = style
            if outline_level:
                self.outline_level = outline_level

    @property
    def outline_level(self) -> int | None:
        return self.get_attribute_integer("text:outline-level")

    @outline_level.setter
    def outline_level(self, level: int) -> None:
        self.set_attribute("text:outline-level", str(level))

    def complete_defaults(self) -> None:
        self.append(Element.from_tag("text:index-entry-chapter"))
        self.append(Element.from_tag("text:index-entry-text"))
        self.append(Element.from_tag("text:index-entry-text"))
        ts = Element.from_tag("text:index-entry-text")
        ts.set_style_attribute("style:type", "right")
        ts.set_style_attribute("style:leader-char", ".")
        self.append(ts)
        self.append(Element.from_tag("text:index-entry-page-number"))

outline_level property writable

outline_level: int | None

style instance-attribute

style = style

__init__

__init__(
    style: str | None = None,
    outline_level: int | None = None,
    **kwargs: Any,
) -> None

Create template for entry of TOC “text:table-of-content-entry- template”.

Args:

style -- str

Source code in odfdo/toc.py

def __init__(
    self,
    style: str | None = None,
    outline_level: int | None = None,
    **kwargs: Any,
) -> None:
    """Create template for entry of TOC "text:table-of-content-entry-
    template".

    Args:

        style -- str
    """
    super().__init__(**kwargs)
    if self._do_init:
        if style:
            self.style = style
        if outline_level:
            self.outline_level = outline_level

complete_defaults

complete_defaults() -> None

Source code in odfdo/toc.py

def complete_defaults(self) -> None:
    self.append(Element.from_tag("text:index-entry-chapter"))
    self.append(Element.from_tag("text:index-entry-text"))
    self.append(Element.from_tag("text:index-entry-text"))
    ts = Element.from_tag("text:index-entry-text")
    ts.set_style_attribute("style:type", "right")
    ts.set_style_attribute("style:leader-char", ".")
    self.append(ts)
    self.append(Element.from_tag("text:index-entry-page-number"))

TrackedChanges

Bases: MDZap, Element

A tracked change, “text:tracked-changes”.

The TrackedChanges “text:tracked-changes” element acts as a container for TextChangedRegion elements that represent changes in a certain scope of an OpenDocument document. This scope is the element in which the TrackedChanges element occurs. Changes in this scope shall be tracked by TextChangedRegion elements contained in the TrackedChanges element in this scope. If a TrackedChanges element is absent, there are no tracked changes in the corresponding scope. In this case, all change mark elements in this scope shall be ignored.

Methods:

Name	Description
get_changed_region
get_changed_regions

Source code in odfdo/tracked_changes.py

class TrackedChanges(MDZap, Element):
    """A tracked change, "text:tracked-changes".

    The TrackedChanges "text:tracked-changes" element acts as a container for
    TextChangedRegion elements that represent changes in a certain scope of an
    OpenDocument document. This scope is the element in which the
    TrackedChanges element occurs. Changes in this scope shall be tracked by
    TextChangedRegion elements contained in the TrackedChanges element in this
    scope. If a TrackedChanges element is absent, there are no tracked changes
    in the corresponding scope. In this case, all change mark elements in this
    scope shall be ignored.
    """

    _tag = "text:tracked-changes"

    def get_changed_regions(
        self,
        creator: str | None = None,
        date: datetime | None = None,
        content: str | None = None,
        role: str | None = None,
    ) -> list[Element]:
        changed_regions = self._filtered_elements(
            "text:changed-region",
            dc_creator=creator,
            dc_date=date,
            content=content,
        )
        if role is None:
            return changed_regions
        result: list[Element] = []
        for region in changed_regions:
            changed = region.get_change_element()  # type: ignore
            if not changed:
                continue  # pragma: nocover
            if changed.tag.endswith(role):
                result.append(region)
        return result

    def get_changed_region(
        self,
        position: int = 0,
        text_id: str | None = None,
        creator: str | None = None,
        date: datetime | None = None,
        content: str | None = None,
    ) -> Element | None:
        return self._filtered_element(
            "text:changed-region",
            position,
            text_id=text_id,
            dc_creator=creator,
            dc_date=date,
            content=content,
        )

get_changed_region

get_changed_region(
    position: int = 0,
    text_id: str | None = None,
    creator: str | None = None,
    date: datetime | None = None,
    content: str | None = None,
) -> Element | None

Source code in odfdo/tracked_changes.py

def get_changed_region(
    self,
    position: int = 0,
    text_id: str | None = None,
    creator: str | None = None,
    date: datetime | None = None,
    content: str | None = None,
) -> Element | None:
    return self._filtered_element(
        "text:changed-region",
        position,
        text_id=text_id,
        dc_creator=creator,
        dc_date=date,
        content=content,
    )

get_changed_regions

get_changed_regions(
    creator: str | None = None,
    date: datetime | None = None,
    content: str | None = None,
    role: str | None = None,
) -> list[Element]

Source code in odfdo/tracked_changes.py

def get_changed_regions(
    self,
    creator: str | None = None,
    date: datetime | None = None,
    content: str | None = None,
    role: str | None = None,
) -> list[Element]:
    changed_regions = self._filtered_elements(
        "text:changed-region",
        dc_creator=creator,
        dc_date=date,
        content=content,
    )
    if role is None:
        return changed_regions
    result: list[Element] = []
    for region in changed_regions:
        changed = region.get_change_element()  # type: ignore
        if not changed:
            continue  # pragma: nocover
        if changed.tag.endswith(role):
            result.append(region)
    return result

UserDefined

Bases: ElementTyped

A user defined field, “text:user-defined”.

Methods:

Name	Description
__init__	Create a user defined field “text:user-defined”.

Attributes:

Name	Type	Description
name
style
text

Source code in odfdo/user_field.py

class UserDefined(ElementTyped):
    """A user defined field, "text:user-defined"."""

    _tag = "text:user-defined"
    _properties = (
        PropDef("name", "text:name"),
        PropDef("style", "style:data-style-name"),
    )

    def __init__(
        self,
        name: str = "",
        value: Any = None,
        value_type: str | None = None,
        text: str | None = None,
        style: str | None = None,
        from_document: Document | None = None,
        **kwargs: Any,
    ) -> None:
        """Create a user defined field "text:user-defined".

        If the current document is provided, try to extract
        the content of the meta user defined field of same name.

        Args:

            name -- str, name of the user defined field

            value -- python typed value, value of the field

            value_type -- str, office:value-type known type

            text -- str

            style -- str

            from_document -- ODF document
        """
        super().__init__(**kwargs)
        if self._do_init:
            if name:
                self.name = name
            if style:
                self.style = style
            if from_document is not None:
                meta_infos = from_document.meta
                content = meta_infos.get_user_defined_metadata_of_name(name)
                if content is not None:
                    value = content.get("value", None)
                    value_type = content.get("value_type", None)
                    text = content.get("text", None)
            text = self.set_value_and_type(
                value=value, value_type=value_type, text=text
            )
            self.text = text

name instance-attribute

name = name

style instance-attribute

style = style

text instance-attribute

text = text

__init__

__init__(
    name: str = "",
    value: Any = None,
    value_type: str | None = None,
    text: str | None = None,
    style: str | None = None,
    from_document: Document | None = None,
    **kwargs: Any,
) -> None

Create a user defined field “text:user-defined”.

If the current document is provided, try to extract the content of the meta user defined field of same name.

Args:

name -- str, name of the user defined field

value -- python typed value, value of the field

value_type -- str, office:value-type known type

text -- str

style -- str

from_document -- ODF document

Source code in odfdo/user_field.py

def __init__(
    self,
    name: str = "",
    value: Any = None,
    value_type: str | None = None,
    text: str | None = None,
    style: str | None = None,
    from_document: Document | None = None,
    **kwargs: Any,
) -> None:
    """Create a user defined field "text:user-defined".

    If the current document is provided, try to extract
    the content of the meta user defined field of same name.

    Args:

        name -- str, name of the user defined field

        value -- python typed value, value of the field

        value_type -- str, office:value-type known type

        text -- str

        style -- str

        from_document -- ODF document
    """
    super().__init__(**kwargs)
    if self._do_init:
        if name:
            self.name = name
        if style:
            self.style = style
        if from_document is not None:
            meta_infos = from_document.meta
            content = meta_infos.get_user_defined_metadata_of_name(name)
            if content is not None:
                value = content.get("value", None)
                value_type = content.get("value_type", None)
                text = content.get("text", None)
        text = self.set_value_and_type(
            value=value, value_type=value_type, text=text
        )
        self.text = text

UserFieldDecl

Bases: ElementTyped

Declaration of a user field, “text:user-field-decl”.

Methods:

Name	Description
__init__	Create a user field “text:user-field-decl”.
set_value

Attributes:

Name	Type	Description
name

Source code in odfdo/user_field.py

class UserFieldDecl(ElementTyped):
    """Declaration of a user field, "text:user-field-decl"."""

    _tag = "text:user-field-decl"
    _properties = (PropDef("name", "text:name"),)

    def __init__(
        self,
        name: str | None = None,
        value: Any = None,
        value_type: str | None = None,
        **kwargs: Any,
    ) -> None:
        """Create a user field "text:user-field-decl"."""
        super().__init__(**kwargs)
        if self._do_init:
            if name:
                self.name = name
            self.set_value_and_type(value=value, value_type=value_type)

    def set_value(self, value: Any) -> None:
        name = self.get_attribute("text:name")
        self.clear()
        self.set_value_and_type(value=value)
        self.set_attribute("text:name", name)

name instance-attribute

name = name

__init__

__init__(
    name: str | None = None,
    value: Any = None,
    value_type: str | None = None,
    **kwargs: Any,
) -> None

Create a user field “text:user-field-decl”.

Source code in odfdo/user_field.py

def __init__(
    self,
    name: str | None = None,
    value: Any = None,
    value_type: str | None = None,
    **kwargs: Any,
) -> None:
    """Create a user field "text:user-field-decl"."""
    super().__init__(**kwargs)
    if self._do_init:
        if name:
            self.name = name
        self.set_value_and_type(value=value, value_type=value_type)

set_value

set_value(value: Any) -> None

Source code in odfdo/user_field.py

def set_value(self, value: Any) -> None:
    name = self.get_attribute("text:name")
    self.clear()
    self.set_value_and_type(value=value)
    self.set_attribute("text:name", name)

UserFieldDecls

Bases: Element

Container of user fields declarations, “text:user-field-decls”.

Source code in odfdo/user_field.py

class UserFieldDecls(Element):
    """Container of user fields declarations, "text:user-field-decls"."""

    _tag = "text:user-field-decls"

UserFieldGet

Bases: ElementTyped

Representation of user field getter, “text:user-field-get”.

Methods:

Name	Description
__init__	Create a user field getter “text:user-field-get”.

Attributes:

Name	Type	Description
name
style
text

Source code in odfdo/user_field.py

class UserFieldGet(ElementTyped):
    """Representation of user field getter, "text:user-field-get"."""

    _tag = "text:user-field-get"
    _properties = (
        PropDef("name", "text:name"),
        PropDef("style", "style:data-style-name"),
    )

    def __init__(
        self,
        name: str | None = None,
        value: Any = None,
        value_type: str | None = None,
        text: str | None = None,
        style: str | None = None,
        **kwargs: Any,
    ) -> None:
        """Create a user field getter "text:user-field-get"."""
        super().__init__(**kwargs)
        if self._do_init:
            if name:
                self.name = name
            text = self.set_value_and_type(
                value=value, value_type=value_type, text=text
            )
            self.text = text

            if style:
                self.style = style

name instance-attribute

name = name

style instance-attribute

style = style

text instance-attribute

text = text

__init__

__init__(
    name: str | None = None,
    value: Any = None,
    value_type: str | None = None,
    text: str | None = None,
    style: str | None = None,
    **kwargs: Any,
) -> None

Create a user field getter “text:user-field-get”.

Source code in odfdo/user_field.py

def __init__(
    self,
    name: str | None = None,
    value: Any = None,
    value_type: str | None = None,
    text: str | None = None,
    style: str | None = None,
    **kwargs: Any,
) -> None:
    """Create a user field getter "text:user-field-get"."""
    super().__init__(**kwargs)
    if self._do_init:
        if name:
            self.name = name
        text = self.set_value_and_type(
            value=value, value_type=value_type, text=text
        )
        self.text = text

        if style:
            self.style = style

UserFieldInput

Bases: UserFieldGet

Representation of user field input, “text:user-field-input”.

Source code in odfdo/user_field.py

class UserFieldInput(UserFieldGet):
    """Representation of user field input, "text:user-field-input"."""

    _tag = "text:user-field-input"

VarChapter

Bases: Element

Variable for a chapter, “text:chapter”.

Methods:

Name	Description
__init__	Create a variable for a chapter “text:chapter”.

Attributes:

Name	Type	Description
DISPLAY_VALUE_CHOICE	ClassVar
display
outline_level

Source code in odfdo/variable.py

class VarChapter(Element):
    """Variable for a chapter, "text:chapter"."""

    _tag = "text:chapter"
    _properties = (
        PropDef("display", "text:display"),
        PropDef("outline_level", "text:outline-level"),
    )
    DISPLAY_VALUE_CHOICE: ClassVar = {
        "number",
        "name",
        "number-and-name",
        "plain-number",
        "plain-number-and-name",
    }

    def __init__(
        self,
        display: str | None = "name",
        outline_level: str | None = None,
        **kwargs: Any,
    ) -> None:
        """Create a variable for a chapter "text:chapter".

        display can be: 'number', 'name', 'number-and-name', 'plain-number' or
        'plain-number-and-name'
        """
        super().__init__(**kwargs)
        if self._do_init:
            if display not in VarChapter.DISPLAY_VALUE_CHOICE:
                raise ValueError(f"Unknown display value: '{display}'")
            self.display = display
            if outline_level is not None:
                self.outline_level = outline_level

DISPLAY_VALUE_CHOICE class-attribute instance-attribute

DISPLAY_VALUE_CHOICE: ClassVar = {
    "number",
    "name",
    "number-and-name",
    "plain-number",
    "plain-number-and-name",
}

display instance-attribute

display = display

outline_level instance-attribute

outline_level = outline_level

__init__

__init__(
    display: str | None = "name",
    outline_level: str | None = None,
    **kwargs: Any,
) -> None

Create a variable for a chapter “text:chapter”.

display can be: ‘number’, ‘name’, ‘number-and-name’, ‘plain-number’ or ‘plain-number-and-name’

Source code in odfdo/variable.py

def __init__(
    self,
    display: str | None = "name",
    outline_level: str | None = None,
    **kwargs: Any,
) -> None:
    """Create a variable for a chapter "text:chapter".

    display can be: 'number', 'name', 'number-and-name', 'plain-number' or
    'plain-number-and-name'
    """
    super().__init__(**kwargs)
    if self._do_init:
        if display not in VarChapter.DISPLAY_VALUE_CHOICE:
            raise ValueError(f"Unknown display value: '{display}'")
        self.display = display
        if outline_level is not None:
            self.outline_level = outline_level

VarCreationDate

Bases: Element

Variable for the creation date, “text:creation-date”.

Methods:

Name	Description
__init__	Create a variable for the creation date “text:creation-date”.

Attributes:

Name	Type	Description
data_style
fixed

Source code in odfdo/variable.py

class VarCreationDate(Element):
    """Variable for the creation date, "text:creation-date"."""

    _tag = "text:creation-date"
    _properties = (
        PropDef("fixed", "text:fixed"),
        PropDef("data_style", "style:data-style-name"),
    )

    def __init__(
        self,
        fixed: bool = False,
        data_style: str | None = None,
        **kwargs: Any,
    ) -> None:
        """Create a variable for the creation date "text:creation-date"."""
        super().__init__(**kwargs)
        if self._do_init:
            if fixed:
                self.fixed = True
            if data_style:
                self.data_style = data_style

data_style instance-attribute

data_style = data_style

fixed instance-attribute

fixed = True

__init__

__init__(
    fixed: bool = False,
    data_style: str | None = None,
    **kwargs: Any,
) -> None

Create a variable for the creation date “text:creation-date”.

Source code in odfdo/variable.py

def __init__(
    self,
    fixed: bool = False,
    data_style: str | None = None,
    **kwargs: Any,
) -> None:
    """Create a variable for the creation date "text:creation-date"."""
    super().__init__(**kwargs)
    if self._do_init:
        if fixed:
            self.fixed = True
        if data_style:
            self.data_style = data_style

VarCreationTime

Bases: Element

Variable for the creation time, “text:creation-time”.

Methods:

Name	Description
__init__	Create a variable for the creation time “text:creation-time”.

Attributes:

Name	Type	Description
data_style
fixed

Source code in odfdo/variable.py

class VarCreationTime(Element):
    """Variable for the creation time, "text:creation-time"."""

    _tag = "text:creation-time"
    _properties = (
        PropDef("fixed", "text:fixed"),
        PropDef("data_style", "style:data-style-name"),
    )

    def __init__(
        self,
        fixed: bool = False,
        data_style: str | None = None,
        **kwargs: Any,
    ) -> None:
        """Create a variable for the creation time "text:creation-time"."""
        super().__init__(**kwargs)
        if self._do_init:
            if fixed:
                self.fixed = True
            if data_style:
                self.data_style = data_style

data_style instance-attribute

data_style = data_style

fixed instance-attribute

fixed = True

__init__

__init__(
    fixed: bool = False,
    data_style: str | None = None,
    **kwargs: Any,
) -> None

Create a variable for the creation time “text:creation-time”.

Source code in odfdo/variable.py

def __init__(
    self,
    fixed: bool = False,
    data_style: str | None = None,
    **kwargs: Any,
) -> None:
    """Create a variable for the creation time "text:creation-time"."""
    super().__init__(**kwargs)
    if self._do_init:
        if fixed:
            self.fixed = True
        if data_style:
            self.data_style = data_style

VarDate

Bases: Element

Variable for a date, “text:date”.

Methods:

Name	Description
__init__	Create avariable for a date “text:date”.

Attributes:

Name	Type	Description
data_style
date
date_adjust
fixed
text

Source code in odfdo/variable.py

class VarDate(Element):
    """Variable for a date, "text:date"."""

    _tag = "text:date"
    _properties = (
        PropDef("date", "text:date-value"),
        PropDef("fixed", "text:fixed"),
        PropDef("data_style", "style:data-style-name"),
        PropDef("date_adjust", "text:date-adjust"),
    )

    def __init__(
        self,
        date: datetime | None = None,
        fixed: bool = False,
        data_style: str | None = None,
        text: str | None = None,
        date_adjust: timedelta | None = None,
        **kwargs: Any,
    ) -> None:
        """Create avariable for a date "text:date"."""
        super().__init__(**kwargs)
        if self._do_init:
            if date:
                self.date = DateTime.encode(date)
            if fixed:
                self.fixed = True
            if data_style is not None:
                self.data_style = data_style
            if text is None and date is not None:
                text = Date.encode(date)
            self.text = text
            if date_adjust is not None:
                self.date_adjust = Duration.encode(date_adjust)

data_style instance-attribute

data_style = data_style

date instance-attribute

date = encode(date)

date_adjust instance-attribute

date_adjust = encode(date_adjust)

fixed instance-attribute

fixed = True

text instance-attribute

text = text

__init__

__init__(
    date: datetime | None = None,
    fixed: bool = False,
    data_style: str | None = None,
    text: str | None = None,
    date_adjust: timedelta | None = None,
    **kwargs: Any,
) -> None

Create avariable for a date “text:date”.

Source code in odfdo/variable.py

def __init__(
    self,
    date: datetime | None = None,
    fixed: bool = False,
    data_style: str | None = None,
    text: str | None = None,
    date_adjust: timedelta | None = None,
    **kwargs: Any,
) -> None:
    """Create avariable for a date "text:date"."""
    super().__init__(**kwargs)
    if self._do_init:
        if date:
            self.date = DateTime.encode(date)
        if fixed:
            self.fixed = True
        if data_style is not None:
            self.data_style = data_style
        if text is None and date is not None:
            text = Date.encode(date)
        self.text = text
        if date_adjust is not None:
            self.date_adjust = Duration.encode(date_adjust)

VarDecl

Bases: Element

A variable declaration, “text:variable-decl”.

Methods:

Name	Description
__init__	Create a variable declaration “text:variable-decl”.

Attributes:

Name	Type	Description
name
value_type

Source code in odfdo/variable.py

class VarDecl(Element):
    """A variable declaration, "text:variable-decl"."""

    _tag = "text:variable-decl"
    _properties = (
        PropDef("name", "text:name"),
        PropDef("value_type", "office:value-type"),
    )

    def __init__(
        self,
        name: str | None = None,
        value_type: str | None = None,
        **kwargs: Any,
    ) -> None:
        """Create a variable declaration "text:variable-decl"."""
        super().__init__(**kwargs)
        if self._do_init:
            if name:
                self.name = name
            if value_type:
                self.value_type = value_type

name instance-attribute

name = name

value_type instance-attribute

value_type = value_type

__init__

__init__(
    name: str | None = None,
    value_type: str | None = None,
    **kwargs: Any,
) -> None

Create a variable declaration “text:variable-decl”.

Source code in odfdo/variable.py

def __init__(
    self,
    name: str | None = None,
    value_type: str | None = None,
    **kwargs: Any,
) -> None:
    """Create a variable declaration "text:variable-decl"."""
    super().__init__(**kwargs)
    if self._do_init:
        if name:
            self.name = name
        if value_type:
            self.value_type = value_type

VarDecls

Bases: Element

Container of variables declarations, “text:variable-decls”.

Source code in odfdo/variable.py

class VarDecls(Element):
    """Container of variables declarations, "text:variable-decls"."""

    _tag = "text:variable-decls"

VarDescription

Bases: VarInitialCreator

Variable for the text description, “text:description”.

Source code in odfdo/variable.py

class VarDescription(VarInitialCreator):
    """Variable for the text description, "text:description"."""

    _tag = "text:description"

VarFileName

Bases: Element

Variable for the file name, “text:file-name”.

Methods:

Name	Description
__init__	Create a variable for the file name “text:file-name”.

Attributes:

Name	Type	Description
DISPLAY_VALUE_CHOICE	ClassVar
display
fixed

Source code in odfdo/variable.py

class VarFileName(Element):
    """Variable for the file name, "text:file-name"."""

    _tag = "text:file-name"
    _properties = (
        PropDef("display", "text:display"),
        PropDef("fixed", "text:fixed"),
    )
    DISPLAY_VALUE_CHOICE: ClassVar = {
        "full",
        "path",
        "name",
        "name-and-extension",
    }

    def __init__(
        self,
        display: str | None = "full",
        fixed: bool = False,
        **kwargs: Any,
    ) -> None:
        """Create a variable for the file name "text:file-name".

        display can be: 'full', 'path', 'name' or 'name-and-extension'
        """
        super().__init__(**kwargs)
        if self._do_init:
            if display not in VarFileName.DISPLAY_VALUE_CHOICE:
                raise ValueError(f"Unknown display value: '{display}'")
            self.display = display
            if fixed:
                self.fixed = True

DISPLAY_VALUE_CHOICE class-attribute instance-attribute

DISPLAY_VALUE_CHOICE: ClassVar = {
    "full",
    "path",
    "name",
    "name-and-extension",
}

display instance-attribute

display = display

fixed instance-attribute

fixed = True

__init__

__init__(
    display: str | None = "full",
    fixed: bool = False,
    **kwargs: Any,
) -> None

Create a variable for the file name “text:file-name”.

display can be: ‘full’, ‘path’, ‘name’ or ‘name-and-extension’

Source code in odfdo/variable.py

def __init__(
    self,
    display: str | None = "full",
    fixed: bool = False,
    **kwargs: Any,
) -> None:
    """Create a variable for the file name "text:file-name".

    display can be: 'full', 'path', 'name' or 'name-and-extension'
    """
    super().__init__(**kwargs)
    if self._do_init:
        if display not in VarFileName.DISPLAY_VALUE_CHOICE:
            raise ValueError(f"Unknown display value: '{display}'")
        self.display = display
        if fixed:
            self.fixed = True

VarGet

Bases: ElementTyped

Representation of a variable getter, “text:variable-get”.

Methods:

Name	Description
__init__	Create a variable getter “text:variable-get”.

Attributes:

Name	Type	Description
name
style
text

Source code in odfdo/variable.py

class VarGet(ElementTyped):
    """Representation of a variable getter, "text:variable-get"."""

    _tag = "text:variable-get"
    _properties = (
        PropDef("name", "text:name"),
        PropDef("style", "style:data-style-name"),
    )

    def __init__(
        self,
        name: str | None = None,
        value: Any = None,
        value_type: str | None = None,
        text: str | None = None,
        style: str | None = None,
        **kwargs: Any,
    ) -> None:
        """Create a variable getter "text:variable-get"."""
        super().__init__(**kwargs)
        if self._do_init:
            if name:
                self.name = name
            if style:
                self.style = style
            text = self.set_value_and_type(
                value=value, value_type=value_type, text=text
            )
            self.text = text

name instance-attribute

name = name

style instance-attribute

style = style

text instance-attribute

text = text

__init__

__init__(
    name: str | None = None,
    value: Any = None,
    value_type: str | None = None,
    text: str | None = None,
    style: str | None = None,
    **kwargs: Any,
) -> None

Create a variable getter “text:variable-get”.

Source code in odfdo/variable.py

def __init__(
    self,
    name: str | None = None,
    value: Any = None,
    value_type: str | None = None,
    text: str | None = None,
    style: str | None = None,
    **kwargs: Any,
) -> None:
    """Create a variable getter "text:variable-get"."""
    super().__init__(**kwargs)
    if self._do_init:
        if name:
            self.name = name
        if style:
            self.style = style
        text = self.set_value_and_type(
            value=value, value_type=value_type, text=text
        )
        self.text = text

VarInitialCreator

Bases: Element

Variable for the initial creator, “text:initial-creator”.

Methods:

Name	Description
__init__	Create a variable for the initial creator “text:initial-creator”.

Attributes:

Name	Type	Description
fixed

Source code in odfdo/variable.py

class VarInitialCreator(Element):
    """Variable for the initial creator, "text:initial-creator"."""

    _tag = "text:initial-creator"
    _properties = (PropDef("fixed", "text:fixed"),)

    def __init__(self, fixed: bool = False, **kwargs: Any) -> None:
        """Create a variable for the initial creator "text:initial-creator"."""
        super().__init__(**kwargs)
        if self._do_init and fixed:
            self.fixed = True

fixed instance-attribute

fixed = True

__init__

__init__(fixed: bool = False, **kwargs: Any) -> None

Create a variable for the initial creator “text:initial-creator”.

Source code in odfdo/variable.py

def __init__(self, fixed: bool = False, **kwargs: Any) -> None:
    """Create a variable for the initial creator "text:initial-creator"."""
    super().__init__(**kwargs)
    if self._do_init and fixed:
        self.fixed = True

VarKeywords

Bases: VarInitialCreator

Variable for the keywords, “text:keywords”.

Source code in odfdo/variable.py

class VarKeywords(VarInitialCreator):
    """Variable for the keywords, "text:keywords"."""

    _tag = "text:keywords"

VarPageCount

Bases: Element

Variable for page count, “text:page-count”.

Source code in odfdo/variable.py

class VarPageCount(Element):
    """Variable for page count, "text:page-count"."""

    _tag = "text:page-count"

VarPageNumber

Bases: Element

Variable for page number, “text:page-number”.

Methods:

Name	Description
__init__	Create a variable for page number “text:page-number”.

Attributes:

Name	Type	Description
page_adjust
select_page

Source code in odfdo/variable.py

class VarPageNumber(Element):
    """Variable for page number, "text:page-number"."""

    _tag = "text:page-number"
    _properties = (
        PropDef("select_page", "text:select-page"),
        PropDef("page_adjust", "text:page-adjust"),
    )

    def __init__(
        self,
        select_page: str | None = None,
        page_adjust: str | None = None,
        **kwargs: Any,
    ) -> None:
        """Create a variable for page number "text:page-number".

        select_page -- string in ('previous', 'current', 'next')

        page_adjust -- int (to add or subtract to the page number)
        """
        super().__init__(**kwargs)
        if self._do_init:
            if select_page is None:
                select_page = "current"
            self.select_page = select_page
            if page_adjust is not None:
                self.page_adjust = page_adjust

page_adjust instance-attribute

page_adjust = page_adjust

select_page instance-attribute

select_page = select_page

__init__

__init__(
    select_page: str | None = None,
    page_adjust: str | None = None,
    **kwargs: Any,
) -> None

Create a variable for page number “text:page-number”.

select_page – string in (‘previous’, ‘current’, ‘next’)

page_adjust – int (to add or subtract to the page number)

Source code in odfdo/variable.py

def __init__(
    self,
    select_page: str | None = None,
    page_adjust: str | None = None,
    **kwargs: Any,
) -> None:
    """Create a variable for page number "text:page-number".

    select_page -- string in ('previous', 'current', 'next')

    page_adjust -- int (to add or subtract to the page number)
    """
    super().__init__(**kwargs)
    if self._do_init:
        if select_page is None:
            select_page = "current"
        self.select_page = select_page
        if page_adjust is not None:
            self.page_adjust = page_adjust

VarSet

Bases: ElementTyped

Representation of a variable setter, “text:variable-set”.

Methods:

Name	Description
__init__	Create a variable setter, “text:variable-set”.
set_value

Attributes:

Name	Type	Description
display
name
style
text

Source code in odfdo/variable.py

class VarSet(ElementTyped):
    """Representation of a variable setter, "text:variable-set"."""

    _tag = "text:variable-set"
    _properties = (
        PropDef("name", "text:name"),
        PropDef("style", "style:data-style-name"),
        PropDef("display", "text:display"),
    )

    def __init__(
        self,
        name: str | None = None,
        value: Any = None,
        value_type: str | None = None,
        display: str | bool = False,
        text: str | None = None,
        style: str | None = None,
        **kwargs: Any,
    ) -> None:
        """Create a variable setter, "text:variable-set"."""
        super().__init__(**kwargs)
        if self._do_init:
            if name:
                self.name = name
            if style:
                self.style = style
            text = self.set_value_and_type(
                value=value, value_type=value_type, text=text
            )
            if not display:
                self.display = "none"
            else:
                self.text = text

    def set_value(self, value: Any) -> None:
        name = self.get_attribute("text:name")
        display = self.get_attribute("text:display")
        style = self.get_attribute("style:data-style-name")
        self.clear()
        text = self.set_value_and_type(value=value)
        self.set_attribute("text:name", name)
        self.set_attribute("style:data-style-name", style)
        if display is not None:
            self.set_attribute("text:display", display)
        if isinstance(text, str):
            self.text = text

display instance-attribute

display = 'none'

name instance-attribute

name = name

style instance-attribute

style = style

text instance-attribute

text = text

__init__

__init__(
    name: str | None = None,
    value: Any = None,
    value_type: str | None = None,
    display: str | bool = False,
    text: str | None = None,
    style: str | None = None,
    **kwargs: Any,
) -> None

Create a variable setter, “text:variable-set”.

Source code in odfdo/variable.py

def __init__(
    self,
    name: str | None = None,
    value: Any = None,
    value_type: str | None = None,
    display: str | bool = False,
    text: str | None = None,
    style: str | None = None,
    **kwargs: Any,
) -> None:
    """Create a variable setter, "text:variable-set"."""
    super().__init__(**kwargs)
    if self._do_init:
        if name:
            self.name = name
        if style:
            self.style = style
        text = self.set_value_and_type(
            value=value, value_type=value_type, text=text
        )
        if not display:
            self.display = "none"
        else:
            self.text = text

set_value

set_value(value: Any) -> None

Source code in odfdo/variable.py

def set_value(self, value: Any) -> None:
    name = self.get_attribute("text:name")
    display = self.get_attribute("text:display")
    style = self.get_attribute("style:data-style-name")
    self.clear()
    text = self.set_value_and_type(value=value)
    self.set_attribute("text:name", name)
    self.set_attribute("style:data-style-name", style)
    if display is not None:
        self.set_attribute("text:display", display)
    if isinstance(text, str):
        self.text = text

VarSubject

Bases: VarInitialCreator

Variable for the subject, “text:subject”.

Source code in odfdo/variable.py

class VarSubject(VarInitialCreator):
    """Variable for the subject, "text:subject"."""

    _tag = "text:subject"

VarTime

Bases: Element

Variable for a time, “text:time”.

Methods:

Name	Description
__init__	Create a variable for a time “text:time”.

Attributes:

Name	Type	Description
data_style
fixed
text
time
time_adjust

Source code in odfdo/variable.py

class VarTime(Element):
    """Variable for a time, "text:time"."""

    _tag = "text:time"
    _properties = (
        PropDef("time", "text:time-value"),
        PropDef("fixed", "text:fixed"),
        PropDef("data_style", "style:data-style-name"),
        PropDef("time_adjust", "text:time-adjust"),
    )

    def __init__(
        self,
        time: datetime | dt_time | None = None,
        fixed: bool = False,
        data_style: str | None = None,
        text: str | None = None,
        time_adjust: timedelta | None = None,
        **kwargs: Any,
    ) -> None:
        """Create a variable for a time "text:time"."""
        super().__init__(**kwargs)
        if self._do_init:
            if time is None:
                time = dt_time()
            if isinstance(time, dt_time):
                # need convert to datetime
                time = datetime(
                    year=1900,
                    month=1,
                    day=1,
                    hour=time.hour,
                    minute=time.minute,
                    second=time.second,
                )
            self.time = DateTime.encode(time)
            if fixed:
                self.fixed = True
            if data_style is not None:
                self.data_style = data_style
            if text is None:
                text = time.strftime("%H:%M:%S")
            self.text = text
            if time_adjust is not None:
                self.time_adjust = Duration.encode(time_adjust)

data_style instance-attribute

data_style = data_style

fixed instance-attribute

fixed = True

text instance-attribute

text = text

time instance-attribute

time = encode(time)

time_adjust instance-attribute

time_adjust = encode(time_adjust)

__init__

__init__(
    time: datetime | time | None = None,
    fixed: bool = False,
    data_style: str | None = None,
    text: str | None = None,
    time_adjust: timedelta | None = None,
    **kwargs: Any,
) -> None

Create a variable for a time “text:time”.

Source code in odfdo/variable.py

def __init__(
    self,
    time: datetime | dt_time | None = None,
    fixed: bool = False,
    data_style: str | None = None,
    text: str | None = None,
    time_adjust: timedelta | None = None,
    **kwargs: Any,
) -> None:
    """Create a variable for a time "text:time"."""
    super().__init__(**kwargs)
    if self._do_init:
        if time is None:
            time = dt_time()
        if isinstance(time, dt_time):
            # need convert to datetime
            time = datetime(
                year=1900,
                month=1,
                day=1,
                hour=time.hour,
                minute=time.minute,
                second=time.second,
            )
        self.time = DateTime.encode(time)
        if fixed:
            self.fixed = True
        if data_style is not None:
            self.data_style = data_style
        if text is None:
            text = time.strftime("%H:%M:%S")
        self.text = text
        if time_adjust is not None:
            self.time_adjust = Duration.encode(time_adjust)

VarTitle

Bases: VarInitialCreator

Variable for the title, “text:title”.

Source code in odfdo/variable.py

class VarTitle(VarInitialCreator):
    """Variable for the title, "text:title"."""

    _tag = "text:title"

XmlPart

Representation of an XML part.

Abstraction of the XML library behind.

Methods:

Name	Description
__init__	Representation of an XML part.
custom_pretty_tree
delete_element
get_element	Returns the first element obtained from the XPath query applied to
get_elements	Returns the elements obtained from the XPath query applied to the
pretty_serialize
serialize
xpath	Apply XPath query to the root of the part and its subtree.

Attributes:

Name	Type	Description
body	Body	Get or set the document body : ‘office:body’
clone	XmlPart
container
part_name
root	Element

Source code in odfdo/xmlpart.py

class XmlPart:
    """Representation of an XML part.

    Abstraction of the XML library behind.
    """

    def __init__(self, part_name: str, container: Container) -> None:
        """Representation of an XML part."""
        self.part_name = part_name
        self.container = container

        # Internal state
        self.__tree: _ElementTree | None = None
        self.__root: Element | None = None

    def _get_tree(self) -> _ElementTree:
        if self.__tree is None:
            part = self.container.get_part(self.part_name)
            self.__tree = parse(BytesIO(part))  # type: ignore[arg-type]
        return self.__tree

    def __repr__(self) -> str:
        return f"<{self.__class__.__name__} part_name={self.part_name}>"

    # Public API

    @property
    def root(self) -> Element:
        if self.__root is None:
            tree = self._get_tree()
            self.__root = Element.from_tag(tree.getroot())
        return self.__root

    def _get_body(self) -> Body:
        body = self.root.document_body
        if not isinstance(body, Element):
            raise TypeError(f"No body found in {self.part_name!r}")
        return body

    @property
    def body(self) -> Body:
        """Get or set the document body : 'office:body'"""
        return self._get_body()

    @body.setter
    def body(self, new_body: Element) -> None:
        body = self._get_body()
        tail = body.tail
        body.clear()
        for item in new_body.children:
            body.append(item)
        if tail:  # pragma: nocover
            body.tail = tail

    def get_elements(self, xpath_query: str) -> list[Element]:
        """Returns the elements obtained from the XPath query applied to the
        root of the XmlPart.

        Return list of Element.
        """
        return self.root.get_elements(xpath_query)

    def get_element(self, xpath_query: str) -> Element | None:
        """Returns the first element obtained from the XPath query applied to
        the root of the XmlPart.

        Return an Element or None.
        """
        return self.root.get_element(xpath_query)

    def delete_element(self, child: Element) -> None:
        child.delete()

    def xpath(self, xpath_query: str) -> list[Element | EText]:
        """Apply XPath query to the root of the part and its subtree.

        Return list of Element or EText instances.
        """
        return self.root.xpath(xpath_query)

    @property
    def clone(self) -> XmlPart:
        clone = object.__new__(self.__class__)
        for name in self.__dict__:
            if name == "container":
                setattr(clone, name, self.container.clone)
            elif name in ("_XmlPart__tree",):
                setattr(clone, name, None)
            else:
                value = getattr(self, name)
                value = deepcopy(value)
                setattr(clone, name, value)
        return clone

    def serialize(self, pretty: bool = False) -> bytes:
        if pretty:
            return self.pretty_serialize()
        xml_header = b'<?xml version="1.0" encoding="UTF-8"?>\n'
        tree = self._get_tree()
        bytes_tree = tostring(tree, encoding="unicode").encode("utf8")
        return xml_header + bytes_tree  # type: ignore[no-any-return]

    def pretty_serialize(self) -> bytes:
        xml_header = b'<?xml version="1.0" encoding="UTF-8"?>\n'
        bytes_tree = tostring(
            self.custom_pretty_tree(),
            encoding="unicode",
        ).encode("utf8")
        return xml_header + bytes_tree  # type: ignore[no-any-return]

    def custom_pretty_tree(self) -> _ElementTree | _Element:
        tree = self._get_tree()
        root = tree.getroot()
        return pretty_indent(root)

body property writable

body: Body

Get or set the document body : ‘office:body’

clone property

clone: XmlPart

container instance-attribute

container = container

part_name instance-attribute

part_name = part_name

root property

root: Element

__init__

__init__(part_name: str, container: Container) -> None

Representation of an XML part.

Source code in odfdo/xmlpart.py

def __init__(self, part_name: str, container: Container) -> None:
    """Representation of an XML part."""
    self.part_name = part_name
    self.container = container

    # Internal state
    self.__tree: _ElementTree | None = None
    self.__root: Element | None = None

custom_pretty_tree

custom_pretty_tree() -> _ElementTree | _Element

Source code in odfdo/xmlpart.py

def custom_pretty_tree(self) -> _ElementTree | _Element:
    tree = self._get_tree()
    root = tree.getroot()
    return pretty_indent(root)

delete_element

delete_element(child: Element) -> None

Source code in odfdo/xmlpart.py

def delete_element(self, child: Element) -> None:
    child.delete()

get_element

get_element(xpath_query: str) -> Element | None

Returns the first element obtained from the XPath query applied to the root of the XmlPart.

Return an Element or None.

Source code in odfdo/xmlpart.py

def get_element(self, xpath_query: str) -> Element | None:
    """Returns the first element obtained from the XPath query applied to
    the root of the XmlPart.

    Return an Element or None.
    """
    return self.root.get_element(xpath_query)

get_elements

get_elements(xpath_query: str) -> list[Element]

Returns the elements obtained from the XPath query applied to the root of the XmlPart.

Return list of Element.

Source code in odfdo/xmlpart.py

def get_elements(self, xpath_query: str) -> list[Element]:
    """Returns the elements obtained from the XPath query applied to the
    root of the XmlPart.

    Return list of Element.
    """
    return self.root.get_elements(xpath_query)

pretty_serialize

pretty_serialize() -> bytes

Source code in odfdo/xmlpart.py

def pretty_serialize(self) -> bytes:
    xml_header = b'<?xml version="1.0" encoding="UTF-8"?>\n'
    bytes_tree = tostring(
        self.custom_pretty_tree(),
        encoding="unicode",
    ).encode("utf8")
    return xml_header + bytes_tree  # type: ignore[no-any-return]

serialize

serialize(pretty: bool = False) -> bytes

Source code in odfdo/xmlpart.py

def serialize(self, pretty: bool = False) -> bytes:
    if pretty:
        return self.pretty_serialize()
    xml_header = b'<?xml version="1.0" encoding="UTF-8"?>\n'
    tree = self._get_tree()
    bytes_tree = tostring(tree, encoding="unicode").encode("utf8")
    return xml_header + bytes_tree  # type: ignore[no-any-return]

xpath

xpath(xpath_query: str) -> list[Element | EText]

Apply XPath query to the root of the part and its subtree.

Return list of Element or EText instances.

Source code in odfdo/xmlpart.py

def xpath(self, xpath_query: str) -> list[Element | EText]:
    """Apply XPath query to the root of the part and its subtree.

    Return list of Element or EText instances.
    """
    return self.root.xpath(xpath_query)

PageBreak

PageBreak() -> Paragraph

Return an empty paragraph with a manual page break.

Using this function requires to register the page break style with

document.add_page_break_style()

Source code in odfdo/paragraph.py

def PageBreak() -> Paragraph:
    """Return an empty paragraph with a manual page break.

    Using this function requires to register the page break style with:
        document.add_page_break_style()
    """
    return Paragraph("", style="odfdopagebreak")

create_table_cell_style

create_table_cell_style(
    border: str | None = None,
    border_top: str | None = None,
    border_bottom: str | None = None,
    border_left: str | None = None,
    border_right: str | None = None,
    padding: str | None = None,
    padding_top: str | None = None,
    padding_bottom: str | None = None,
    padding_left: str | None = None,
    padding_right: str | None = None,
    background_color: str | tuple | None = None,
    shadow: str | None = None,
    color: str | tuple | None = None,
) -> Style

Return a cell style.

The borders arguments must be some style attribute strings or None, see the method ‘make_table_cell_border_string’ to generate them. If the ‘border’ argument as the value ‘default’, the default style “0.06pt solid #000000” is used for the 4 borders. If any value is used for border, it is used for the 4 borders, else any of the 4 borders can be specified by it’s own string. If all the border, border_top, border_bottom, … arguments are None, an empty border is used (ODF value is fo:border=”none”).

Padding arguments are string specifying a length (e.g. “0.5mm”)”. If ‘padding’ is provided, it is used for the 4 sides, else any of the 4 sides padding can be specified by it’s own string. Default padding is no padding.

Args:

border -- str, style string for borders on four sides

border_top -- str, style string for top if no 'border' argument

border_bottom -- str, style string for bottom if no 'border' argument

border_left -- str, style string for left if no 'border' argument

border_right -- str, style string for right if no 'border' argument

padding -- str, style string for padding on four sides

padding_top -- str, style string for top if no 'padding' argument

padding_bottom -- str, style string for bottom if no 'padding' argument

padding_left -- str, style string for left if no 'padding' argument

padding_right -- str, style string for right if no 'padding' argument

background_color -- str or rgb 3-tuple, str is 'black', 'grey', ... or '#012345'

shadow -- str, e.g. "#808080 0.176cm 0.176cm"

color -- str or rgb 3-tuple, str is 'black', 'grey', ... or '#012345'

Return : Style

Source code in odfdo/style.py

def create_table_cell_style(
    border: str | None = None,
    border_top: str | None = None,
    border_bottom: str | None = None,
    border_left: str | None = None,
    border_right: str | None = None,
    padding: str | None = None,
    padding_top: str | None = None,
    padding_bottom: str | None = None,
    padding_left: str | None = None,
    padding_right: str | None = None,
    background_color: str | tuple | None = None,
    shadow: str | None = None,
    color: str | tuple | None = None,
) -> Style:
    """Return a cell style.

    The borders arguments must be some style attribute strings or None, see the
    method 'make_table_cell_border_string' to generate them.
    If the 'border' argument as the value 'default', the default style
    "0.06pt solid #000000" is used for the 4 borders.
    If any value is used for border, it is used for the 4 borders, else any of
    the 4 borders can be specified by it's own string. If all the border,
    border_top, border_bottom, ... arguments are None, an empty border is used
    (ODF value is fo:border="none").

    Padding arguments are string specifying a length (e.g. "0.5mm")". If
    'padding' is provided, it is used for the 4 sides, else any of
    the 4 sides padding can be specified by it's own string. Default padding is
    no padding.

    Args:

        border -- str, style string for borders on four sides

        border_top -- str, style string for top if no 'border' argument

        border_bottom -- str, style string for bottom if no 'border' argument

        border_left -- str, style string for left if no 'border' argument

        border_right -- str, style string for right if no 'border' argument

        padding -- str, style string for padding on four sides

        padding_top -- str, style string for top if no 'padding' argument

        padding_bottom -- str, style string for bottom if no 'padding' argument

        padding_left -- str, style string for left if no 'padding' argument

        padding_right -- str, style string for right if no 'padding' argument

        background_color -- str or rgb 3-tuple, str is 'black', 'grey', ... or '#012345'

        shadow -- str, e.g. "#808080 0.176cm 0.176cm"

        color -- str or rgb 3-tuple, str is 'black', 'grey', ... or '#012345'

    Return : Style
    """
    if border == "default":
        border = make_table_cell_border_string()  # default border
    if border is not None:
        # use the border value for 4 sides.
        border_bottom = border_top = border_left = border_right = None
    if (
        border is None
        and border_bottom is None
        and border_top is None
        and border_left is None
        and border_right is None
    ):
        border = "none"
    if padding is not None:
        # use the padding value for 4 sides.
        padding_bottom = padding_top = padding_left = padding_right = None
    cell_style = Style(
        "table-cell",
        area="table-cell",
        border=border,
        border_top=border_top,
        border_bottom=border_bottom,
        border_left=border_left,
        border_right=border_right,
        padding=padding,
        padding_top=padding_top,
        padding_bottom=padding_bottom,
        padding_left=padding_left,
        padding_right=padding_right,
        background_color=background_color,
        shadow=shadow,
    )
    if color:
        cell_style.set_properties(area="text", color=color)
    return cell_style

default_boolean_style

default_boolean_style() -> Style

Return a default boolean style.

Source code in odfdo/style_defaults.py

def default_boolean_style() -> Style:
    """Return a default boolean style."""
    return Element.from_tag(  # type: ignore[return-value]
        '<number:boolean-style style:name="lpod-default-boolean-style">\n'
        "  <number:boolean/>\n"
        "</number:boolean-style>\n"
    )

default_currency_style

default_currency_style() -> Style

Return a default currency style (€).

Source code in odfdo/style_defaults.py

def default_currency_style() -> Style:
    """Return a default currency style (€)."""
    return Element.from_tag(  # type: ignore[return-value]
        '<number:currency-style style:name="lpod-default-currency-style">\n'
        "  <number:text>-</number:text>\n"
        '  <number:number number:decimal-places="2" '
        'number:min-integer-digits="1" number:grouping="true"/>\n'
        "  <number:text> </number:text>\n"
        '  <number:currency-symbol number:language="fr" '
        'number:country="FR">€</number:currency-symbol>\n'
        "</number:currency-style>\n"
    )

default_date_style

default_date_style() -> Style

Return a default time style Y-M-D.

Source code in odfdo/style_defaults.py

def default_date_style() -> Style:
    """Return a default time style Y-M-D."""
    return Element.from_tag(  # type: ignore[return-value]
        '<number:date-style style:name="lpod-default-date-style">\n'
        '  <number:year number:style="long"/>\n'
        "  <number:text>-</number:text>\n"
        '  <number:month number:style="long"/>\n'
        "  <number:text>-</number:text>\n"
        '  <number:day number:style="long"/>\n'
        "</number:date-style>\n"
    )

default_frame_position_style

default_frame_position_style(
    name: str = "FramePosition",
    horizontal_pos: str = "from-left",
    vertical_pos: str = "from-top",
    horizontal_rel: str = "paragraph",
    vertical_rel: str = "paragraph",
) -> Style

Generate a style for positioning frames in desktop applications.

Default arguments should be enough.

Use the returned Style as the frame style or build a new graphic style with this style as the parent.

Source code in odfdo/frame.py

def default_frame_position_style(
    name: str = "FramePosition",
    horizontal_pos: str = "from-left",
    vertical_pos: str = "from-top",
    horizontal_rel: str = "paragraph",
    vertical_rel: str = "paragraph",
) -> Style:
    """Generate a style for positioning frames in desktop applications.

    Default arguments should be enough.

    Use the returned Style as the frame style or build a new graphic style with
    this style as the parent.
    """
    return Style(
        family="graphic",
        name=name,
        horizontal_pos=horizontal_pos,
        horizontal_rel=horizontal_rel,
        vertical_pos=vertical_pos,
        vertical_rel=vertical_rel,
    )

default_number_style

default_number_style() -> Style

Return a default number style with two decimals.

Source code in odfdo/style_defaults.py

def default_number_style() -> Style:
    """Return a default number style with two decimals."""
    return Element.from_tag(  # type: ignore[return-value]
        '<number:number-style style:name="lpod-default-number-style">\n'
        '  <number:number number:decimal-places="2" '
        'number:min-integer-digits="1"/>\n'
        "</number:number-style>\n"
    )

default_percentage_style

default_percentage_style() -> Style

Return a default percentage style with two decimals.

Source code in odfdo/style_defaults.py

def default_percentage_style() -> Style:
    """Return a default percentage style with two decimals."""
    return Element.from_tag(  # type: ignore[return-value]
        '<number:percentage-style style:name="lpod-default-percentage-style">\n'
        '  <number:number number:decimal-places="2" number:min-integer-digits="1"/>\n'
        "  <number:text>%</number:text>\n"
        "</number:percentage-style>\n"
    )

default_time_style

default_time_style() -> Style

Return a default time style.

Source code in odfdo/style_defaults.py

def default_time_style() -> Style:
    """Return a default time style."""
    return Element.from_tag(  # type: ignore[return-value]
        '<number:time-style style:name="lpod-default-time-style">\n'
        '  <number:hours number:style="long"/>\n'
        "  <number:text>:</number:text>\n"
        '  <number:minutes number:style="long"/>\n'
        "  <number:text>:</number:text>\n"
        '  <number:seconds number:style="long"/>\n'
        "</number:time-style>\n"
    )

default_toc_level_style

default_toc_level_style(level: int) -> Style

Generate an automatic default style for the given TOC level.

Source code in odfdo/toc.py

def default_toc_level_style(level: int) -> Style:
    """Generate an automatic default style for the given TOC level."""
    tab_stop = TabStopStyle(style_type="right", leader_style="dotted", leader_text=".")
    position = 17.5 - (0.5 * level)
    tab_stop.style_position = f"{position}cm"
    tab_stops = Element.from_tag("style:tab-stops")
    tab_stops.append(tab_stop)
    properties = Element.from_tag("style:paragraph-properties")
    properties.append(tab_stops)
    toc_style_level = Style(
        family="paragraph",
        name=_toc_entry_style_name(level),
        parent=f"Contents_20_{level}",
    )
    toc_style_level.append(properties)
    return toc_style_level

hex2rgb

hex2rgb(color: str) -> tuple[int, int, int]

Convert “#RRGGBB” hexadecimal representation into (R, G, B) tuple.

Args:

color -- str

Returns: tuple

Source code in odfdo/utils/color.py

def hex2rgb(color: str) -> tuple[int, int, int]:
    """Convert "#RRGGBB" hexadecimal representation into (R, G, B) tuple.

    Args:

        color -- str

    Returns: tuple
    """
    code = color[1:]
    if not (len(color) == 7 and color[0] == "#" and code.isalnum()):
        raise ValueError(f'"{color}" is not a valid color')
    red = int(code[:2], 16)
    green = int(code[2:4], 16)
    blue = int(code[4:6], 16)
    return (red, green, blue)

hexa_color

hexa_color(
    color: str | tuple[int, int, int] | None = None,
) -> str | None

Safe conversion from color tuple or string to hexadecimal representation.

Empty string is converted to black. None is converted to None.

Args:

color -- str or tuple or None

Returns: str or None

Source code in odfdo/utils/color.py

def hexa_color(color: str | tuple[int, int, int] | None = None) -> str | None:
    """Safe conversion from color tuple or string to hexadecimal
    representation.

    Empty string is converted to black.
    None is converted to None.

    Args:

        color -- str or tuple or None

    Returns: str or None
    """
    if color is None:
        return None
    if isinstance(color, tuple):
        return rgb2hex(color)
    if not isinstance(color, str):
        raise TypeError(f'Invalid color argument "{color!r}"')
    color = color.strip()
    if not color:
        return "#000000"
    if color.startswith("#"):
        return color
    return rgb2hex(color)

make_table_cell_border_string

make_table_cell_border_string(
    thick: str | float | int | None = None,
    line: str | None = None,
    color: str | tuple | None = None,
) -> str

Returns a string for “style:table-cell-properties” “fo:border”.

With default: “0.06pt solid #000000”

Args:

thick -- str or float or int

line -- str

color -- str or rgb 3-tuple, str is 'black', 'grey', ... or '#012345'

Source code in odfdo/style.py

def make_table_cell_border_string(
    thick: str | float | int | None = None,
    line: str | None = None,
    color: str | tuple | None = None,
) -> str:
    """Returns a string for "style:table-cell-properties" "fo:border".

    With default: "0.06pt solid #000000"

    Args:

        thick -- str or float or int

        line -- str

        color -- str or rgb 3-tuple, str is 'black', 'grey', ... or '#012345'
    """
    thick_string = _make_thick_string(thick)
    line_string = _make_line_string(line)
    color_string = hexa_color(color) or "#000000"
    return " ".join((thick_string, line_string, color_string))

rgb2hex

rgb2hex(color: str | tuple[int, int, int]) -> str

Convert color name or (R, G, B) tuple into “#RRGGBB” hexadecimal.

Args:

color -- str or tuple

Returns: str

Examples::

>>> rgb2hex('yellow')
'#FFFF00'
>>> rgb2hex((238, 130, 238))
'#EE82EE'

Source code in odfdo/utils/color.py

def rgb2hex(color: str | tuple[int, int, int]) -> str:
    """Convert color name or (R, G, B) tuple into "#RRGGBB" hexadecimal.

    Args:

        color -- str or tuple

    Returns: str

    Examples::

        >>> rgb2hex('yellow')
        '#FFFF00'
        >>> rgb2hex((238, 130, 238))
        '#EE82EE'
    """
    if isinstance(color, str):
        try:
            code = CSS3_COLORMAP[color.lower()]
        except KeyError as e:
            raise KeyError(f'Color "{color}" is unknown in CSS color list') from e
    elif isinstance(color, tuple):
        if len(color) != 3:
            raise ValueError("Color must be a 3-tuple")
        code = color
    else:
        raise TypeError(f'Invalid color "{color}"')
    for channel in code:
        if not 0 <= channel <= 255:
            raise ValueError(
                f'Invalid color "{color}", channel must be between 0 and 255'
            )
    return f"#{code[0]:02X}{code[1]:02X}{code[2]:02X}"