Variable

Classes for ODF document variables and fields.

This module provides classes for various types of document fields that can be automatically updated, such as dates, times, page numbers, and document metadata (e.g., author, title). It also includes classes for declaring and managing custom variables (‘text:variable-set’, ‘text:variable-get’).

Classes:

Name	Description
VarChapter	A chapter field, “text:chapter”.
VarCreationDate	A creation date field, “text:creation-date”.
VarCreationTime	A creation time field, “text:creation-time”.
VarDate	A date field, “text:date”.
VarDescription	A description field, “text:description”.
VarFileName	A file name field, “text:file-name”.
VarGet	A variable getter, “text:variable-get”.
VarInitialCreator	An initial creator field, “text:initial-creator”.
VarKeywords	A keywords field, “text:keywords”.
VarPageCount	A page count field, “text:page-count”.
VarPageNumber	A page number field, “text:page-number”.
VarSet	A variable setter, “text:variable-set”.
VarSubject	A subject field, “text:subject”.
VarTime	A time field, “text:time”.
VarTitle	A title field, “text:title”.

VarChapter

Bases: Element

A chapter field, “text:chapter”.

Displays information about the current chapter, such as its name or number.

Attributes:

Name	Type	Description
display	str	The format for displaying the chapter information (e.g., ‘name’, ‘number’, ‘number-and-name’).
outline_level	str	The heading level to consider for the chapter information.

Methods:

Name	Description
__init__	Initialize the VarChapter element.

Source code in odfdo/variable.py

class VarChapter(Element):
    """A chapter field, "text:chapter".

    Displays information about the current chapter, such as its name or
    number.

    Attributes:
        display (str): The format for displaying the chapter information
            (e.g., 'name', 'number', 'number-and-name').
        outline_level (str): The heading level to consider for the chapter
            information.

    """

    _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:
        """Initialize the VarChapter element.

        Args:
            display: The format for the chapter information.
                Can be 'name' (default), 'number', 'number-and-name', etc.
            outline_level: The heading outline level to use
                for chapter context.
            kwargs: Arbitrary keyword arguments for the Element base class.

        """
        super().__init__(**kwargs)
        if self._do_init:
            if display not in VarChapter.DISPLAY_VALUE_CHOICE:
                msg = f"Unknown display value: {display!r}"
                raise ValueError(msg)
            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",
}

_properties class-attribute instance-attribute

_properties = (
    PropDef("display", "text:display"),
    PropDef("outline_level", "text:outline-level"),
)

_tag class-attribute instance-attribute

_tag = 'text:chapter'

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

Initialize the VarChapter element.

Parameters:

Name	Type	Description	Default
display	str | None	The format for the chapter information. Can be ‘name’ (default), ‘number’, ‘number-and-name’, etc.	'name'
outline_level	str | None	The heading outline level to use for chapter context.	None
kwargs	Any	Arbitrary keyword arguments for the Element base class.	{}

Source code in odfdo/variable.py

def __init__(
    self,
    display: str | None = "name",
    outline_level: str | None = None,
    **kwargs: Any,
) -> None:
    """Initialize the VarChapter element.

    Args:
        display: The format for the chapter information.
            Can be 'name' (default), 'number', 'number-and-name', etc.
        outline_level: The heading outline level to use
            for chapter context.
        kwargs: Arbitrary keyword arguments for the Element base class.

    """
    super().__init__(**kwargs)
    if self._do_init:
        if display not in VarChapter.DISPLAY_VALUE_CHOICE:
            msg = f"Unknown display value: {display!r}"
            raise ValueError(msg)
        self.display = display
        if outline_level is not None:
            self.outline_level = outline_level

VarCreationDate

Bases: Element

A creation date field, “text:creation-date”.

Displays the date the document was created, based on metadata.

Attributes:

Name	Type	Description
fixed	bool	If True, the field is not updated automatically.
data_style	str	The style for formatting the date.

Methods:

Name	Description
__init__	Initialize the VarCreationDate element.

Source code in odfdo/variable.py

class VarCreationDate(Element):
    """A creation date field, "text:creation-date".

    Displays the date the document was created, based on metadata.

    Attributes:
        fixed (bool): If True, the field is not updated automatically.
        data_style (str): The style for formatting the 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:
        """Initialize the VarCreationDate element.

        Args:
            fixed: If True, the field is not updated automatically.
            data_style: The style name for formatting.
            kwargs: Arbitrary keyword arguments for the Element base class.

        """
        super().__init__(**kwargs)
        if self._do_init:
            if fixed:
                self.fixed = True
            if data_style:
                self.data_style = data_style

_properties class-attribute instance-attribute

_properties = (
    PropDef("fixed", "text:fixed"),
    PropDef("data_style", "style:data-style-name"),
)

_tag class-attribute instance-attribute

_tag = 'text:creation-date'

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

Initialize the VarCreationDate element.

Parameters:

Name	Type	Description	Default
fixed	bool	If True, the field is not updated automatically.	False
data_style	str | None	The style name for formatting.	None
kwargs	Any	Arbitrary keyword arguments for the Element base class.	{}

Source code in odfdo/variable.py

def __init__(
    self,
    fixed: bool = False,
    data_style: str | None = None,
    **kwargs: Any,
) -> None:
    """Initialize the VarCreationDate element.

    Args:
        fixed: If True, the field is not updated automatically.
        data_style: The style name for formatting.
        kwargs: Arbitrary keyword arguments for the Element base class.

    """
    super().__init__(**kwargs)
    if self._do_init:
        if fixed:
            self.fixed = True
        if data_style:
            self.data_style = data_style

VarCreationTime

Bases: Element

A creation time field, “text:creation-time”.

Displays the time the document was created, based on metadata.

Attributes:

Name	Type	Description
fixed	bool	If True, the field is not updated automatically.
data_style	str	The style for formatting the time.

Methods:

Name	Description
__init__	Initialize the VarCreationTime element.

Source code in odfdo/variable.py

class VarCreationTime(Element):
    """A creation time field, "text:creation-time".

    Displays the time the document was created, based on metadata.

    Attributes:
        fixed (bool): If True, the field is not updated automatically.
        data_style (str): The style for formatting the 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:
        """Initialize the VarCreationTime element.

        Args:
            fixed: If True, the field is not updated automatically.
            data_style: The style name for formatting.
            kwargs: Arbitrary keyword arguments for the Element base class.

        """
        super().__init__(**kwargs)
        if self._do_init:
            if fixed:
                self.fixed = True
            if data_style:
                self.data_style = data_style

_properties class-attribute instance-attribute

_properties = (
    PropDef("fixed", "text:fixed"),
    PropDef("data_style", "style:data-style-name"),
)

_tag class-attribute instance-attribute

_tag = 'text:creation-time'

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

Initialize the VarCreationTime element.

Parameters:

Name	Type	Description	Default
fixed	bool	If True, the field is not updated automatically.	False
data_style	str | None	The style name for formatting.	None
kwargs	Any	Arbitrary keyword arguments for the Element base class.	{}

Source code in odfdo/variable.py

def __init__(
    self,
    fixed: bool = False,
    data_style: str | None = None,
    **kwargs: Any,
) -> None:
    """Initialize the VarCreationTime element.

    Args:
        fixed: If True, the field is not updated automatically.
        data_style: The style name for formatting.
        kwargs: Arbitrary keyword arguments for the Element base class.

    """
    super().__init__(**kwargs)
    if self._do_init:
        if fixed:
            self.fixed = True
        if data_style:
            self.data_style = data_style

VarDate

Bases: Element

A date field, “text:date”.

Displays a date, which can be fixed or automatically updated.

Attributes:

Name	Type	Description
date	str	The date value in ISO 8601 format.
fixed	bool	If True, the date is not updated automatically.
data_style	str	The style for formatting the date.
date_adjust	str	A duration to add to or subtract from the date.

Methods:

Name	Description
__init__	Initialize the VarDate element.

Source code in odfdo/variable.py

class VarDate(Element):
    """A date field, "text:date".

    Displays a date, which can be fixed or automatically updated.

    Attributes:
        date (str): The date value in ISO 8601 format.
        fixed (bool): If True, the date is not updated automatically.
        data_style (str): The style for formatting the date.
        date_adjust (str): A duration to add to or subtract from the 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:
        """Initialize the VarDate element.

        Args:
            date: The date value. If not provided, the
                field may be updated automatically by a consumer.
            fixed: If True, the date is not updated automatically.
            data_style: The style name for formatting.
            text: The textual representation of the date.
                If not provided, it is generated from `date`.
            date_adjust: A timedelta to adjust the
                date value.
            kwargs: Arbitrary keyword arguments for the Element base class.

        """
        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)

_properties class-attribute instance-attribute

_properties = (
    PropDef("date", "text:date-value"),
    PropDef("fixed", "text:fixed"),
    PropDef("data_style", "style:data-style-name"),
    PropDef("date_adjust", "text:date-adjust"),
)

_tag class-attribute instance-attribute

_tag = 'text:date'

data_style instance-attribute

data_style = data_style

date instance-attribute

date = DateTime.encode(date)

date_adjust instance-attribute

date_adjust = Duration.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

Initialize the VarDate element.

Parameters:

Name	Type	Description	Default
date	datetime | None	The date value. If not provided, the field may be updated automatically by a consumer.	None
fixed	bool	If True, the date is not updated automatically.	False
data_style	str | None	The style name for formatting.	None
text	str | None	The textual representation of the date. If not provided, it is generated from date.	None
date_adjust	timedelta | None	A timedelta to adjust the date value.	None
kwargs	Any	Arbitrary keyword arguments for the Element base class.	{}

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:
    """Initialize the VarDate element.

    Args:
        date: The date value. If not provided, the
            field may be updated automatically by a consumer.
        fixed: If True, the date is not updated automatically.
        data_style: The style name for formatting.
        text: The textual representation of the date.
            If not provided, it is generated from `date`.
        date_adjust: A timedelta to adjust the
            date value.
        kwargs: Arbitrary keyword arguments for the Element base class.

    """
    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)

VarDescription

Bases: VarInitialCreator

A description field, “text:description”.

Displays the document’s description (or comments) from its metadata.

Source code in odfdo/variable.py

class VarDescription(VarInitialCreator):
    """A description field, "text:description".

    Displays the document's description (or comments) from its metadata.
    """

    _tag = "text:description"

_tag class-attribute instance-attribute

_tag = 'text:description'

VarFileName

Bases: Element

A file name field, “text:file-name”.

Displays the file name of the document, with different formatting options.

Attributes:

Name	Type	Description
display	str	The format for the file name (‘full’, ‘path’, ‘name’, ‘name-and-extension’).
fixed	bool	If True, the file name is not updated automatically.

Methods:

Name	Description
__init__	Initialize the VarFileName element.

Source code in odfdo/variable.py

class VarFileName(Element):
    """A file name field, "text:file-name".

    Displays the file name of the document, with different formatting
    options.

    Attributes:
        display (str): The format for the file name ('full', 'path', 'name',
            'name-and-extension').
        fixed (bool): If True, the file name is not updated automatically.

    """

    _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:
        """Initialize the VarFileName element.

        Args:
            display: The format for the file name. Can be
                'full' (default), 'path', 'name', or 'name-and-extension'.
            fixed: If True, the field is not updated automatically.
            kwargs: Arbitrary keyword arguments for the Element base class.

        """
        super().__init__(**kwargs)
        if self._do_init:
            if display not in VarFileName.DISPLAY_VALUE_CHOICE:
                msg = f"Unknown display value: {display!r}"
                raise ValueError(msg)
            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",
}

_properties class-attribute instance-attribute

_properties = (
    PropDef("display", "text:display"),
    PropDef("fixed", "text:fixed"),
)

_tag class-attribute instance-attribute

_tag = 'text:file-name'

display instance-attribute

display = display

fixed instance-attribute

fixed = True

__init__

__init__(
    display: str | None = "full",
    fixed: bool = False,
    **kwargs: Any,
) -> None

Initialize the VarFileName element.

Parameters:

Name	Type	Description	Default
display	str | None	The format for the file name. Can be ‘full’ (default), ‘path’, ‘name’, or ‘name-and-extension’.	'full'
fixed	bool	If True, the field is not updated automatically.	False
kwargs	Any	Arbitrary keyword arguments for the Element base class.	{}

Source code in odfdo/variable.py

def __init__(
    self,
    display: str | None = "full",
    fixed: bool = False,
    **kwargs: Any,
) -> None:
    """Initialize the VarFileName element.

    Args:
        display: The format for the file name. Can be
            'full' (default), 'path', 'name', or 'name-and-extension'.
        fixed: If True, the field is not updated automatically.
        kwargs: Arbitrary keyword arguments for the Element base class.

    """
    super().__init__(**kwargs)
    if self._do_init:
        if display not in VarFileName.DISPLAY_VALUE_CHOICE:
            msg = f"Unknown display value: {display!r}"
            raise ValueError(msg)
        self.display = display
        if fixed:
            self.fixed = True

VarGet

Bases: ElementTyped

A variable getter, “text:variable-get”.

This element displays the current value of a variable at its position in the document.

Attributes:

Name	Type	Description
name	str	The name of the variable to display.
style	str	The data style for formatting the value.

Methods:

Name	Description
__init__	Initialize the VarGet element.

Source code in odfdo/variable.py

class VarGet(ElementTyped):
    """A variable getter, "text:variable-get".

    This element displays the current value of a variable at its position in
    the document.

    Attributes:
        name (str): The name of the variable to display.
        style (str, optional): The data style for formatting the value.

    """

    _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:
        """Initialize the VarGet element.

        Args:
            name: The name of the variable to get.
            value: An initial value to display.
            value_type: The ODF value type.
            text: The textual representation to display.
            style: The data style name for formatting.
            kwargs: Arbitrary keyword arguments for the Element base class.

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

_properties class-attribute instance-attribute

_properties = (
    PropDef("name", "text:name"),
    PropDef("style", "style:data-style-name"),
)

_tag class-attribute instance-attribute

_tag = 'text:variable-get'

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

Initialize the VarGet element.

Parameters:

Name	Type	Description	Default
name	str | None	The name of the variable to get.	None
value	Any	An initial value to display.	None
value_type	str | None	The ODF value type.	None
text	str | None	The textual representation to display.	None
style	str | None	The data style name for formatting.	None
kwargs	Any	Arbitrary keyword arguments for the Element base class.	{}

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:
    """Initialize the VarGet element.

    Args:
        name: The name of the variable to get.
        value: An initial value to display.
        value_type: The ODF value type.
        text: The textual representation to display.
        style: The data style name for formatting.
        kwargs: Arbitrary keyword arguments for the Element base class.

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

An initial creator field, “text:initial-creator”.

Displays the name of the person who initially created the document, based on the document’s metadata.

Attributes:

Name	Type	Description
fixed	bool	If True, the field is not updated automatically.

Methods:

Name	Description
__init__	Initialize the VarInitialCreator element.

Source code in odfdo/variable.py

class VarInitialCreator(Element):
    """An initial creator field, "text:initial-creator".

    Displays the name of the person who initially created the document, based
    on the document's metadata.

    Attributes:
        fixed (bool): If True, the field is not updated automatically.

    """

    _tag = "text:initial-creator"
    _properties = (PropDef("fixed", "text:fixed"),)

    def __init__(self, fixed: bool = False, **kwargs: Any) -> None:
        """Initialize the VarInitialCreator element.

        Args:
            fixed: If True, the field is not updated automatically.
            kwargs: Arbitrary keyword arguments for the Element base class.

        """
        super().__init__(**kwargs)
        if self._do_init and fixed:
            self.fixed = True

_properties class-attribute instance-attribute

_properties = (PropDef('fixed', 'text:fixed'),)

_tag class-attribute instance-attribute

_tag = 'text:initial-creator'

fixed instance-attribute

fixed = True

__init__

__init__(fixed: bool = False, **kwargs: Any) -> None

Initialize the VarInitialCreator element.

Parameters:

Name	Type	Description	Default
fixed	bool	If True, the field is not updated automatically.	False
kwargs	Any	Arbitrary keyword arguments for the Element base class.	{}

Source code in odfdo/variable.py

def __init__(self, fixed: bool = False, **kwargs: Any) -> None:
    """Initialize the VarInitialCreator element.

    Args:
        fixed: If True, the field is not updated automatically.
        kwargs: Arbitrary keyword arguments for the Element base class.

    """
    super().__init__(**kwargs)
    if self._do_init and fixed:
        self.fixed = True

VarKeywords

Bases: VarInitialCreator

A keywords field, “text:keywords”.

Displays the document’s keywords from its metadata.

Source code in odfdo/variable.py

class VarKeywords(VarInitialCreator):
    """A keywords field, "text:keywords".

    Displays the document's keywords from its metadata.
    """

    _tag = "text:keywords"

_tag class-attribute instance-attribute

_tag = 'text:keywords'

VarPageCount

Bases: Element

A page count field, “text:page-count”.

Displays the total number of pages in the document.

Source code in odfdo/variable.py

class VarPageCount(Element):
    """A page count field, "text:page-count".

    Displays the total number of pages in the document.
    """

    _tag = "text:page-count"

_tag class-attribute instance-attribute

_tag = 'text:page-count'

VarPageNumber

Bases: Element

A page number field, “text:page-number”.

Displays the page number, which can be the current, previous, or next page number, with an optional adjustment.

Attributes:

Name	Type	Description
select_page	str	Which page number to display (‘current’, ‘previous’, ‘next’).
page_adjust	str	A numerical value to add to or subtract from the page number.

Methods:

Name	Description
__init__	Initialize the VarPageNumber element.

Source code in odfdo/variable.py

class VarPageNumber(Element):
    """A page number field, "text:page-number".

    Displays the page number, which can be the current, previous, or next
    page number, with an optional adjustment.

    Attributes:
        select_page (str): Which page number to display ('current',
            'previous', 'next').
        page_adjust (str): A numerical value to add to or subtract from the
            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:
        """Initialize the VarPageNumber element.

        Args:
            select_page: The page to select: 'current' (the
                default), 'previous', or 'next'.
            page_adjust: A numerical value to add to or
                subtract from the selected page number.
            kwargs: Arbitrary keyword arguments for the Element base class.

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

_properties class-attribute instance-attribute

_properties = (
    PropDef("select_page", "text:select-page"),
    PropDef("page_adjust", "text:page-adjust"),
)

_tag class-attribute instance-attribute

_tag = 'text:page-number'

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

Initialize the VarPageNumber element.

Parameters:

Name	Type	Description	Default
select_page	str | None	The page to select: ‘current’ (the default), ‘previous’, or ‘next’.	None
page_adjust	str | None	A numerical value to add to or subtract from the selected page number.	None
kwargs	Any	Arbitrary keyword arguments for the Element base class.	{}

Source code in odfdo/variable.py

def __init__(
    self,
    select_page: str | None = None,
    page_adjust: str | None = None,
    **kwargs: Any,
) -> None:
    """Initialize the VarPageNumber element.

    Args:
        select_page: The page to select: 'current' (the
            default), 'previous', or 'next'.
        page_adjust: A numerical value to add to or
            subtract from the selected page number.
        kwargs: Arbitrary keyword arguments for the Element base class.

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

A variable setter, “text:variable-set”.

This element sets the value of a declared variable. It can optionally display the value at its position in the text.

Attributes:

Name	Type	Description
name	str	The name of the variable to set.
style	str	The data style for formatting the displayed value.
display	str	Controls whether the value is displayed (‘none’ or omitted).

Methods:

Name	Description
__init__	Initialize the VarSet element.
set_value	Set the value of the variable.

Source code in odfdo/variable.py

class VarSet(ElementTyped):
    """A variable setter, "text:variable-set".

    This element sets the value of a declared variable. It can optionally
    display the value at its position in the text.

    Attributes:
        name (str): The name of the variable to set.
        style (str, optional): The data style for formatting the displayed
            value.
        display (str): Controls whether the value is displayed ('none' or
            omitted).

    """

    _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:
        """Initialize the VarSet element.

        Args:
            name: The name of the variable to set.
            value: The value to assign to the variable.
            value_type: The ODF value type.
            display: If False or 'none', the value is not
                displayed. Otherwise, it is. Defaults to False.
            text: The textual representation of the value.
            style: The data style name for formatting.
            kwargs: Arbitrary keyword arguments for the Element base class.

        """
        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:
        """Set the value of the variable.

        This method updates the value and value type, preserving other
        attributes like name, style, and display setting.

        Args:
            value: The new value for the variable.

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

_properties class-attribute instance-attribute

_properties = (
    PropDef("name", "text:name"),
    PropDef("style", "style:data-style-name"),
    PropDef("display", "text:display"),
)

_tag class-attribute instance-attribute

_tag = 'text:variable-set'

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

Initialize the VarSet element.

Parameters:

Name	Type	Description	Default
name	str | None	The name of the variable to set.	None
value	Any	The value to assign to the variable.	None
value_type	str | None	The ODF value type.	None
display	str | bool	If False or ‘none’, the value is not displayed. Otherwise, it is. Defaults to False.	False
text	str | None	The textual representation of the value.	None
style	str | None	The data style name for formatting.	None
kwargs	Any	Arbitrary keyword arguments for the Element base class.	{}

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:
    """Initialize the VarSet element.

    Args:
        name: The name of the variable to set.
        value: The value to assign to the variable.
        value_type: The ODF value type.
        display: If False or 'none', the value is not
            displayed. Otherwise, it is. Defaults to False.
        text: The textual representation of the value.
        style: The data style name for formatting.
        kwargs: Arbitrary keyword arguments for the Element base class.

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

Set the value of the variable.

This method updates the value and value type, preserving other attributes like name, style, and display setting.

Parameters:

Name	Type	Description	Default
value	Any	The new value for the variable.	required

Source code in odfdo/variable.py

def set_value(self, value: Any) -> None:
    """Set the value of the variable.

    This method updates the value and value type, preserving other
    attributes like name, style, and display setting.

    Args:
        value: The new value for the variable.

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

A subject field, “text:subject”.

Displays the document’s subject from its metadata.

Source code in odfdo/variable.py

class VarSubject(VarInitialCreator):
    """A subject field, "text:subject".

    Displays the document's subject from its metadata.
    """

    _tag = "text:subject"

_tag class-attribute instance-attribute

_tag = 'text:subject'

VarTime

Bases: Element

A time field, “text:time”.

Displays a time, which can be fixed or automatically updated.

Attributes:

Name	Type	Description
time	str	The time value in ISO 8601 format.
fixed	bool	If True, the time is not updated automatically.
data_style	str	The style for formatting the time.
time_adjust	str	A duration to add to or subtract from the time.

Methods:

Name	Description
__init__	Initialize the VarTime element.

Source code in odfdo/variable.py

class VarTime(Element):
    """A time field, "text:time".

    Displays a time, which can be fixed or automatically updated.

    Attributes:
        time (str): The time value in ISO 8601 format.
        fixed (bool): If True, the time is not updated automatically.
        data_style (str): The style for formatting the time.
        time_adjust (str): A duration to add to or subtract from the 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:
        """Initialize the VarTime element.

        Args:
            time: The time value. Defaults to
                the current time.
            fixed: If True, the time is not updated automatically.
            data_style: The style name for formatting.
            text: The textual representation of the time.
                If not provided, it is generated from `time`.
            time_adjust: A timedelta to adjust the
                time value.
            kwargs: Arbitrary keyword arguments for the Element base class.

        """
        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)

_properties class-attribute instance-attribute

_properties = (
    PropDef("time", "text:time-value"),
    PropDef("fixed", "text:fixed"),
    PropDef("data_style", "style:data-style-name"),
    PropDef("time_adjust", "text:time-adjust"),
)

_tag class-attribute instance-attribute

_tag = 'text:time'

data_style instance-attribute

data_style = data_style

fixed instance-attribute

fixed = True

text instance-attribute

text = text

time instance-attribute

time = DateTime.encode(time)

time_adjust instance-attribute

time_adjust = Duration.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

Initialize the VarTime element.

Parameters:

Name	Type	Description	Default
time	datetime | time | None	The time value. Defaults to the current time.	None
fixed	bool	If True, the time is not updated automatically.	False
data_style	str | None	The style name for formatting.	None
text	str | None	The textual representation of the time. If not provided, it is generated from time.	None
time_adjust	timedelta | None	A timedelta to adjust the time value.	None
kwargs	Any	Arbitrary keyword arguments for the Element base class.	{}

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:
    """Initialize the VarTime element.

    Args:
        time: The time value. Defaults to
            the current time.
        fixed: If True, the time is not updated automatically.
        data_style: The style name for formatting.
        text: The textual representation of the time.
            If not provided, it is generated from `time`.
        time_adjust: A timedelta to adjust the
            time value.
        kwargs: Arbitrary keyword arguments for the Element base class.

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

A title field, “text:title”.

Displays the document’s title from its metadata.

Source code in odfdo/variable.py

class VarTitle(VarInitialCreator):
    """A title field, "text:title".

    Displays the document's title from its metadata.
    """

    _tag = "text:title"

_tag class-attribute instance-attribute

_tag = 'text:title'