Annotation

Annotation class for “office:annotation” tag.

Classes:

Name	Description
Annotation	An annotation (private note), “office:annotation”.
AnnotationEnd	End of annotation marker, “office:annotation-end”.
AnnotationMixin	Mixin class for classes containing Annotations.

Functions:

Name	Description
get_unique_office_name	Provide an autogenerated unique “office:name” for the document.

Annotation

Bases: MDTail, ListMixin, LinkMixin, Element, DcCreatorMixin, DcDateMixin

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

This element contains the content of a comment or annotation, along with metadata such as the creator and date.

Attributes:

Name	Type	Description
name	str	The unique name of the annotation.
note_id	str	The ID of the note.
creator	str	The creator of the annotation.
date	datetime	The date of the annotation.
note_body	str or Element	The body content of the annotation.

Methods:

Name	Description
__init__	Create an Annotation element.
__str__
check_validity	Checks the validity of the Annotation.
delete	Delete the element from the XML tree.
get_annotated	Returns the annotated content from an annotation.

Source code in odfdo/annotation.py

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

    This element contains the content of a comment or annotation, along with
    metadata such as the creator and date.

    Attributes:
        name (str): The unique name of the annotation.
        note_id (str): The ID of the note.
        creator (str): The creator of the annotation.
        date (datetime): The date of the annotation.
        note_body (str or Element): The body content of the 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:
        """Create an Annotation element.

        An annotation is a private note, represented by "office:annotation".
        This element is credited to a creator and contains text content,
        optionally dated (current date by default).

        If 'name' is not provided and a 'parent' is given, the name will be
        autogenerated to be unique within the document.

        Args:
            text_or_element: The content of the annotation, which can be a
                string or another ODF element.
            creator: The name of the person who created the annotation.
            date: The date and time when the annotation was created. Defaults
                to the current time if not provided.
            name: A unique name for the annotation. If not provided, a unique
                name is generated.
            parent: The parent element to which this annotation will be
                associated for name generation.
        """
        # 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
        if hasattr(body, "get_annotation_end"):
            return cast(None | AnnotationEnd, body.get_annotation_end(name=name))
        return None

    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 (e.g., single position annotation or if the
        annotation-end tag is not found), it returns an empty list or an
        empty string if 'as_text' is True.

        Args:
            as_text: If True, returns the text content as a string. Defaults
                to False.
            no_header: If True, converts 'text:h' elements to 'text:p'.
                Defaults to True.
            clean: If True, suppresses unwanted tags such as deletion marks.
                Defaults to True.

        Returns:
            Element | list | str | None: The content of the annotation, which
            can be a single element, a list of elements, a string, or None if
            the end tag is missing.
        """
        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 element from the XML tree.

        If a child element is provided, it is deleted. If no child is given,
        the annotation itself and its corresponding "annotation-end" tag
        (if it exists) are deleted.

        Args:
            child: The child element to delete. If None,
                the annotation itself is deleted. Defaults to None.
            keep_tail: This argument is not used in this context but is
                kept for compatibility. Defaults to True.
        """
        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:
        """Checks the validity of the Annotation."""
        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}"

_properties class-attribute instance-attribute

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

_tag class-attribute instance-attribute

_tag = 'office:annotation'

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

Create an Annotation element.

An annotation is a private note, represented by “office:annotation”. This element is credited to a creator and contains text content, optionally dated (current date by default).

If ‘name’ is not provided and a ‘parent’ is given, the name will be autogenerated to be unique within the document.

Parameters:

Name	Type	Description	Default
text_or_element	Element | str | None	The content of the annotation, which can be a string or another ODF element.	None
creator	str | None	The name of the person who created the annotation.	None
date	datetime | None	The date and time when the annotation was created. Defaults to the current time if not provided.	None
name	str | None	A unique name for the annotation. If not provided, a unique name is generated.	None
parent	Element | None	The parent element to which this annotation will be associated for name generation.	None

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:
    """Create an Annotation element.

    An annotation is a private note, represented by "office:annotation".
    This element is credited to a creator and contains text content,
    optionally dated (current date by default).

    If 'name' is not provided and a 'parent' is given, the name will be
    autogenerated to be unique within the document.

    Args:
        text_or_element: The content of the annotation, which can be a
            string or another ODF element.
        creator: The name of the person who created the annotation.
        date: The date and time when the annotation was created. Defaults
            to the current time if not provided.
        name: A unique name for the annotation. If not provided, a unique
            name is generated.
        parent: The parent element to which this annotation will be
            associated for name generation.
    """
    # 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

__str__

__str__() -> str

Source code in odfdo/annotation.py

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

check_validity

check_validity() -> None

Checks the validity of the Annotation.

Source code in odfdo/annotation.py

def check_validity(self) -> None:
    """Checks the validity of the Annotation."""
    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 element from the XML tree.

If a child element is provided, it is deleted. If no child is given, the annotation itself and its corresponding “annotation-end” tag (if it exists) are deleted.

Parameters:

Name	Type	Description	Default
child	Element | None	The child element to delete. If None, the annotation itself is deleted. Defaults to None.	None
keep_tail	bool	This argument is not used in this context but is kept for compatibility. Defaults to True.	True

Source code in odfdo/annotation.py

def delete(self, child: Element | None = None, keep_tail: bool = True) -> None:
    """Delete the element from the XML tree.

    If a child element is provided, it is deleted. If no child is given,
    the annotation itself and its corresponding "annotation-end" tag
    (if it exists) are deleted.

    Args:
        child: The child element to delete. If None,
            the annotation itself is deleted. Defaults to None.
        keep_tail: This argument is not used in this context but is
            kept for compatibility. Defaults to True.
    """
    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 (e.g., single position annotation or if the annotation-end tag is not found), it returns an empty list or an empty string if ‘as_text’ is True.

Parameters:

Name	Type	Description	Default
as_text	bool	If True, returns the text content as a string. Defaults to False.	False
no_header	bool	If True, converts ‘text:h’ elements to ‘text:p’. Defaults to True.	True
clean	bool	If True, suppresses unwanted tags such as deletion marks. Defaults to True.	True

Returns:

Type	Description
Element | list | str | None	Element | list | str | None: The content of the annotation, which
Element | list | str | None	can be a single element, a list of elements, a string, or None if
Element | list | str | None	the end tag is missing.

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 (e.g., single position annotation or if the
    annotation-end tag is not found), it returns an empty list or an
    empty string if 'as_text' is True.

    Args:
        as_text: If True, returns the text content as a string. Defaults
            to False.
        no_header: If True, converts 'text:h' elements to 'text:p'.
            Defaults to True.
        clean: If True, suppresses unwanted tags such as deletion marks.
            Defaults to True.

    Returns:
        Element | list | str | None: The content of the annotation, which
        can be a single element, a list of elements, a string, or None if
        the end tag is missing.
    """
    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”.

The “office:annotation-end” element is used to define the end of a text range that is being annotated, especially when the content spans across element boundaries. It must be preceded by an “office:annotation” element with the same ‘office:name’ attribute.

If an “office:annotation-end” element does not have a matching preceding “office:annotation” element, it is ignored.

Attributes:

Name	Type	Description
name	str	The name of the annotation this element is closing. This name must match the ‘office:name’ of a preceding “office:annotation” element.

Methods:

Name	Description
__init__	Create an AnnotationEnd element.

Source code in odfdo/annotation.py

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

    The "office:annotation-end" element is used to define the end of a text
    range that is being annotated, especially when the content spans across
    element boundaries. It must be preceded by an "office:annotation" element
    with the same 'office:name' attribute.

    If an "office:annotation-end" element does not have a matching preceding
    "office:annotation" element, it is ignored.

    Attributes:
        name (str): The name of the annotation this element is closing. This
                    name must match the 'office:name' of a preceding
                    "office:annotation" element.
    """

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

    def __init__(
        self,
        annotation: Annotation | None = None,
        name: str | None = None,
        **kwargs: Any,
    ) -> None:
        """Create an AnnotationEnd element.

        This element marks the end of an annotation. It must be associated
        with an existing "office:annotation" element, either by passing the
        annotation object directly or by providing a matching name.

        Args:
            annotation: The "office:annotation" element
                that this "annotation-end" is closing. If provided, the 'name'
                attribute will be taken from this annotation.
            name: The name of the annotation to close. This is
                required if 'annotation' is not provided.
        """
        # 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
        if hasattr(body, "get_annotation"):  # pragma: nocover
            return cast(None | Annotation, body.get_annotation(name=name))
        return None  # pragma: nocover

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

_properties class-attribute instance-attribute

_properties = (PropDef('name', 'office:name'),)

_tag class-attribute instance-attribute

_tag = 'office:annotation-end'

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

Create an AnnotationEnd element.

This element marks the end of an annotation. It must be associated with an existing “office:annotation” element, either by passing the annotation object directly or by providing a matching name.

Parameters:

Name	Type	Description	Default
annotation	Annotation | None	The “office:annotation” element that this “annotation-end” is closing. If provided, the ‘name’ attribute will be taken from this annotation.	None
name	str | None	The name of the annotation to close. This is required if ‘annotation’ is not provided.	None

Source code in odfdo/annotation.py

def __init__(
    self,
    annotation: Annotation | None = None,
    name: str | None = None,
    **kwargs: Any,
) -> None:
    """Create an AnnotationEnd element.

    This element marks the end of an annotation. It must be associated
    with an existing "office:annotation" element, either by passing the
    annotation object directly or by providing a matching name.

    Args:
        annotation: The "office:annotation" element
            that this "annotation-end" is closing. If provided, the 'name'
            attribute will be taken from this annotation.
        name: The name of the annotation to close. This is
            required if 'annotation' is not provided.
    """
    # 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

AnnotationMixin

Bases: Element

Mixin class for classes containing Annotations.

Used by the following classes

• “table:covered-table-cell”
• “table:table-cell”
• “text:a”
• “text:h”
• “text:meta”
• “text:meta-field”
• “text:p”
• “text:ruby-base”
• “text:span”

and “office:text”, “office:spreadsheet” for compatibility with previous versions.

Methods:

Name	Description
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.

Source code in odfdo/annotation.py

class AnnotationMixin(Element):
    """Mixin class for classes containing Annotations.

    Used by the following classes:
        - "table:covered-table-cell"
        - "table:table-cell"
        - "text:a"
        - "text:h"
        - "text:meta"
        - "text:meta-field"
        - "text:p"
        - "text:ruby-base"
        - "text:span"

    and "office:text", "office:spreadsheet" for compatibility with previous
    versions.
    """

    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: The creator of the annotation.
            start_date: The start date for filtering.
            end_date: The end date for filtering.
            content: A regex to match in the content.

        Returns:
            list[Annotation]: A list of matching Annotation elements.
        """
        annotations: list[Annotation] = []
        for annotation in cast(
            list[Annotation],
            self._filtered_elements("descendant::office:annotation", content=content),
        ):
            if creator is not None and creator != annotation.dc_creator:
                continue
            date = annotation.date
            # 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)
        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: The position of the annotation to return.
            creator: The creator of the annotation.
            start_date: The start date for filtering.
            end_date: The end date for filtering.
            content: A regex to match in the content.
            name: The name of the annotation.

        Returns:
            Annotation or None: The matching Annotation element, or None if not found.
        """
        if name is not None:
            return cast(
                None | Annotation,
                self._filtered_element(
                    "descendant::office:annotation", 0, office_name=name
                ),
            )
        annotations: list[Annotation] = cast(
            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[AnnotationEnd]: A list of AnnotationEnd elements.
        """
        return cast(
            list[AnnotationEnd],
            self._filtered_elements(
                "descendant::office:annotation-end",
            ),
        )

    def get_annotation_end(
        self,
        position: int = 0,
        name: str | None = None,
    ) -> AnnotationEnd | None:
        """Return the annotation end that matches the criteria.

        Args:
            position: The position of the annotation end to return.
            name: The name of the annotation end.

        Returns:
            AnnotationEnd or None: The matching AnnotationEnd element, or
                None if not found.
        """
        return cast(
            None | AnnotationEnd,
            self._filtered_element(
                "descendant::office:annotation-end", position, office_name=name
            ),
        )

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.

Parameters:

Name	Type	Description	Default
position	int	The position of the annotation to return.	0
creator	str | None	The creator of the annotation.	None
start_date	datetime | None	The start date for filtering.	None
end_date	datetime | None	The end date for filtering.	None
content	str | None	A regex to match in the content.	None
name	str | None	The name of the annotation.	None

Returns:

Type	Description
Annotation | None	Annotation or None: The matching Annotation element, or None if not found.

Source code in odfdo/annotation.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: The position of the annotation to return.
        creator: The creator of the annotation.
        start_date: The start date for filtering.
        end_date: The end date for filtering.
        content: A regex to match in the content.
        name: The name of the annotation.

    Returns:
        Annotation or None: The matching Annotation element, or None if not found.
    """
    if name is not None:
        return cast(
            None | Annotation,
            self._filtered_element(
                "descendant::office:annotation", 0, office_name=name
            ),
        )
    annotations: list[Annotation] = cast(
        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.

Parameters:

Name	Type	Description	Default
position	int	The position of the annotation end to return.	0
name	str | None	The name of the annotation end.	None

Returns:

Type	Description
AnnotationEnd | None	AnnotationEnd or None: The matching AnnotationEnd element, or None if not found.

Source code in odfdo/annotation.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: The position of the annotation end to return.
        name: The name of the annotation end.

    Returns:
        AnnotationEnd or None: The matching AnnotationEnd element, or
            None if not found.
    """
    return cast(
        None | AnnotationEnd,
        self._filtered_element(
            "descendant::office:annotation-end", position, office_name=name
        ),
    )

get_annotation_ends

get_annotation_ends() -> list[AnnotationEnd]

Return all the annotation ends.

Returns:

Type	Description
list[AnnotationEnd]	list[AnnotationEnd]: A list of AnnotationEnd elements.

Source code in odfdo/annotation.py

def get_annotation_ends(self) -> list[AnnotationEnd]:
    """Return all the annotation ends.

    Returns:
        list[AnnotationEnd]: A list of AnnotationEnd elements.
    """
    return cast(
        list[AnnotationEnd],
        self._filtered_elements(
            "descendant::office:annotation-end",
        ),
    )

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.

Parameters:

Name	Type	Description	Default
creator	str | None	The creator of the annotation.	None
start_date	datetime | None	The start date for filtering.	None
end_date	datetime | None	The end date for filtering.	None
content	str | None	A regex to match in the content.	None

Returns:

Type	Description
list[Annotation]	list[Annotation]: A list of matching Annotation elements.

Source code in odfdo/annotation.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: The creator of the annotation.
        start_date: The start date for filtering.
        end_date: The end date for filtering.
        content: A regex to match in the content.

    Returns:
        list[Annotation]: A list of matching Annotation elements.
    """
    annotations: list[Annotation] = []
    for annotation in cast(
        list[Annotation],
        self._filtered_elements("descendant::office:annotation", content=content),
    ):
        if creator is not None and creator != annotation.dc_creator:
            continue
        date = annotation.date
        # 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)
    return annotations

get_unique_office_name

get_unique_office_name(
    element: Element | None = None,
) -> str

Provide an autogenerated unique “office:name” for the document.

Parameters:

Name	Type	Description	Default
element	Element | None	The element to which the annotation is related.	None

Returns:

Name	Type	Description
str	str	A unique name.

Source code in odfdo/annotation.py

def get_unique_office_name(element: Element | None = None) -> str:
    """Provide an autogenerated unique "office:name" for the document.

    Args:
        element: The element to which the annotation is related.

    Returns:
        str: A unique name.
    """
    if element is not None:
        body = element.document_body
    else:
        body = None
    if body:
        used = set(body.get_office_names())
    else:
        used = set()
    # unplugged current paragraph:
    if element is not None:
        used.update(element.get_office_names())
    indice = 1
    while True:
        name = f"__Fieldmark__lpod_{indice}"
        if name in used:
            indice += 1
            continue
        break
    return name