Skip to content

Variable Declaration

Classes for ODF document variables declarations.

This module provides classes for managing variable declaration “text:variable-decl” and variable declaration container “text:variable-decls”.

Classes:

Name Description
VarDecl

A variable declaration, “text:variable-decl”.
VarDeclMixin

Mixin class for elements that can contain variable declarations.
VarDecls

A container for variable declarations, “text:variable-decls”.

VarDecl

Bases: Element

A variable declaration, “text:variable-decl”.

This element defines a variable by its name and value type.

Attributes:

Name Type Description
name str

The unique name of the variable.
value_type str

The ODF value type (e.g., ‘string’, ‘float’).

Methods:

Name Description
__init__

Initializes the VarDecl element.
Source code in odfdo/variable_declaration.py 
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
class VarDecl(Element):
    """A variable declaration, "text:variable-decl".

    This element defines a variable by its name and value type.

    Attributes:
        name (str): The unique name of the variable.
        value_type (str): The ODF value type (e.g., 'string', 'float').
    """

    _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:
        """Initializes the VarDecl element.

        Args:
            name: The name of the variable.
            value_type: The ODF value type.
        """
        super().__init__(**kwargs)
        if self._do_init:
            if name:
                self.name = name
            if value_type:
                self.value_type = value_type

_properties class-attribute instance-attribute 

_properties = (
    PropDef("name", "text:name"),
    PropDef("value_type", "office:value-type"),
)

_tag class-attribute instance-attribute 

_tag = 'text:variable-decl'

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

Initializes the VarDecl element.

Parameters:

Name Type Description Default
name str | None

The name of the variable.

 None
value_type str | None

The ODF value type.

 None
Source code in odfdo/variable_declaration.py 
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
def __init__(
    self,
    name: str | None = None,
    value_type: str | None = None,
    **kwargs: Any,
) -> None:
    """Initializes the VarDecl element.

    Args:
        name: The name of the variable.
        value_type: The ODF value type.
    """
    super().__init__(**kwargs)
    if self._do_init:
        if name:
            self.name = name
        if value_type:
            self.value_type = value_type

VarDeclMixin

Bases: Element

Mixin class for elements that can contain variable declarations.

This mixin provides methods to access and manipulate “text:variable-decls” and “text:variable-decl”.

Used by the following classes
  • “office:chart”
  • “office:drawing”
  • “office:presentation”
  • “office:spreadsheet”
  • “office:text”
  • “style:footer”
  • “style:footer-first”
  • “style:footer-left”
  • “style:header”
  • “style:header-first”
  • “style:header-left”

Methods:

Name Description
get_variable_decl

Returns a single variable declaration that matches the specified criteria.
get_variable_decl_list

Returns all variable declarations as a list.
get_variable_decls

Returns the container for variable declarations.
Source code in odfdo/variable_declaration.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
class VarDeclMixin(Element):
    """Mixin class for elements that can contain variable declarations.

    This mixin provides methods to access and manipulate "text:variable-decls"
    and "text:variable-decl".

    Used by the following classes:
        - "office:chart"
        - "office:drawing"
        - "office:presentation"
        - "office:spreadsheet"
        - "office:text"
        - "style:footer"
        - "style:footer-first"
        - "style:footer-left"
        - "style:header"
        - "style:header-first"
        - "style:header-left"
    """

    def get_variable_decls(self) -> VarDecls:
        """Returns the container for variable declarations.

        If the container is not found, it is created within the document body.

        Returns:
            VarDecls: The VarDecls instance (container for variable declarations).

        Raises:
            ValueError: If the document body is empty and a new container cannot be inserted.
        """
        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 cast(VarDecls, variable_decls)

    def get_variable_decl_list(self) -> list[VarDecls]:
        """Returns all variable declarations as a list.

        Returns:
            list[VarDecls]: A list of all VarDecls instances that are descendants of this element.
        """
        return cast(
            list[VarDecls], self._filtered_elements("descendant::text:variable-decl")
        )

    def get_variable_decl(self, name: str, position: int = 0) -> VarDecls | None:
        """Returns a single variable declaration that matches the specified criteria.

        Args:
            name: The name of the variable declaration to retrieve.
            position: The 0-based index of the matching variable declaration to return.

        Returns:
            VarDecls | None: A VarDecls instance, or None if no declaration matches the criteria.
        """
        return cast(
            None | VarDecls,
            self._filtered_element(
                "descendant::text:variable-decl", position, text_name=name
            ),
        )

get_variable_decl 

get_variable_decl(
    name: str, position: int = 0
) -> VarDecls | None

Returns a single variable declaration that matches the specified criteria.

Parameters:

Name Type Description Default
name str

The name of the variable declaration to retrieve.

 required
position int

The 0-based index of the matching variable declaration to return.

 0

Returns:

Type Description
VarDecls | None

VarDecls | None: A VarDecls instance, or None if no declaration matches the criteria.
Source code in odfdo/variable_declaration.py 
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
def get_variable_decl(self, name: str, position: int = 0) -> VarDecls | None:
    """Returns a single variable declaration that matches the specified criteria.

    Args:
        name: The name of the variable declaration to retrieve.
        position: The 0-based index of the matching variable declaration to return.

    Returns:
        VarDecls | None: A VarDecls instance, or None if no declaration matches the criteria.
    """
    return cast(
        None | VarDecls,
        self._filtered_element(
            "descendant::text:variable-decl", position, text_name=name
        ),
    )

get_variable_decl_list 

get_variable_decl_list() -> list[VarDecls]

Returns all variable declarations as a list.

Returns:

Type Description
list[VarDecls]

list[VarDecls]: A list of all VarDecls instances that are descendants of this element.
Source code in odfdo/variable_declaration.py 
74
75
76
77
78
79
80
81
82
def get_variable_decl_list(self) -> list[VarDecls]:
    """Returns all variable declarations as a list.

    Returns:
        list[VarDecls]: A list of all VarDecls instances that are descendants of this element.
    """
    return cast(
        list[VarDecls], self._filtered_elements("descendant::text:variable-decl")
    )

get_variable_decls 

get_variable_decls() -> VarDecls

Returns the container for variable declarations.

If the container is not found, it is created within the document body.

Returns:

Name Type Description
VarDecls VarDecls

The VarDecls instance (container for variable declarations).

Raises:

Type Description
ValueError

If the document body is empty and a new container cannot be inserted.
Source code in odfdo/variable_declaration.py 
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
def get_variable_decls(self) -> VarDecls:
    """Returns the container for variable declarations.

    If the container is not found, it is created within the document body.

    Returns:
        VarDecls: The VarDecls instance (container for variable declarations).

    Raises:
        ValueError: If the document body is empty and a new container cannot be inserted.
    """
    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 cast(VarDecls, variable_decls)

VarDecls

Bases: Element

A container for variable declarations, “text:variable-decls”.

This element groups all the ‘text:variable-decl’ elements in the document.

Source code in odfdo/variable_declaration.py 
102
103
104
105
106
107
108
109
class VarDecls(Element):
    """A container for variable declarations, "text:variable-decls".

    This element groups all the 'text:variable-decl' elements in the
    document.
    """

    _tag = "text:variable-decls"

_tag class-attribute instance-attribute 

_tag = 'text:variable-decls'