Skip to content

User Field Declaration

Classes for ODF document user fields declarations.

This module provides classes for managing user field declarations and their containers within the document content, tags “text:user-field-decls”, “text:user-field-decl”. .

Classes:

Name Description
UserFieldDecl

A declaration of a user field, “text:user-field-decl”.
UserFieldDeclContMixin

Mixin class for elements that can contain user field declarations.
UserFieldDeclMixin

Mixin class for elements that can contain user field declarations.
UserFieldDecls

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

UserFieldDecl

Bases: ElementTyped

A declaration of a user field, “text:user-field-decl”.

This element, typically found within ‘text:user-field-decls’, defines a user-defined field, its name, type, and current value.

Attributes:

Name Type Description
name str

The unique name of the user field.

Methods:

Name Description
__init__

Initialize the UserFieldDecl element.
set_value

Set the value of the user field declaration.
Source code in odfdo/user_field_declaration.py 
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
class UserFieldDecl(ElementTyped):
    """A declaration of a user field, "text:user-field-decl".

    This element, typically found within 'text:user-field-decls', defines a
    user-defined field, its name, type, and current value.

    Attributes:
        name (str): The unique name of the user field.

    """

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

        Args:
            name: The name of the user field.
            value: The initial value of the field.
            value_type: The ODF value type (e.g., 'string',
                'float'). If not provided, it is inferred from the `value`.
            kwargs: Arbitrary keyword arguments for the Element base class.

        """
        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:
        """Set the value of the user field declaration.

        This method updates the value and value type of the declaration,
        preserving its name.

        Args:
            value: The new value for the field.

        """
        name = self.get_attribute("text:name")
        self.clear()
        self.set_value_and_type(value=value)
        self.set_attribute("text:name", name)

_properties class-attribute instance-attribute 

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

_tag class-attribute instance-attribute 

_tag = 'text:user-field-decl'

name instance-attribute 

name = name

__init__ 

__init__(
    name: str | None = None,
    value: Any = None,
    value_type: str | None = None,
    **kwargs: Any,
) -> None

Initialize the UserFieldDecl element.

Parameters:

Name Type Description Default
name str | None

The name of the user field.

 None
value Any

The initial value of the field.

 None
value_type str | None

The ODF value type (e.g., ‘string’, ‘float’). If not provided, it is inferred from the value.

 None
kwargs Any

Arbitrary keyword arguments for the Element base class.

 {}
Source code in odfdo/user_field_declaration.py 
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
def __init__(
    self,
    name: str | None = None,
    value: Any = None,
    value_type: str | None = None,
    **kwargs: Any,
) -> None:
    """Initialize the UserFieldDecl element.

    Args:
        name: The name of the user field.
        value: The initial value of the field.
        value_type: The ODF value type (e.g., 'string',
            'float'). If not provided, it is inferred from the `value`.
        kwargs: Arbitrary keyword arguments for the Element base class.

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

Set the value of the user field declaration.

This method updates the value and value type of the declaration, preserving its name.

Parameters:

Name Type Description Default
value Any

The new value for the field.

 required
Source code in odfdo/user_field_declaration.py 
213
214
215
216
217
218
219
220
221
222
223
224
225
226
def set_value(self, value: Any) -> None:
    """Set the value of the user field declaration.

    This method updates the value and value type of the declaration,
    preserving its name.

    Args:
        value: The new value for the field.

    """
    name = self.get_attribute("text:name")
    self.clear()
    self.set_value_and_type(value=value)
    self.set_attribute("text:name", name)

UserFieldDeclContMixin

Bases: UserFieldDeclMixin

Mixin class for elements that can contain user field declarations.

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

Used by the following classes

UserFieldDecls - “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_user_field_decls

Return the container for user field declarations.
Source code in odfdo/user_field_declaration.py 
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
class UserFieldDeclContMixin(UserFieldDeclMixin):
    """Mixin class for elements that can contain user field declarations.

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

    Used by the following classes:
        UserFieldDecls
        - "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_user_field_decls(self) -> UserFieldDecls:
        """Return the container for user field declarations.

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

        Returns:
            UserFieldDecls: The UserFieldDecls instance (container for
                user field declarations).

        Raises:
            ValueError: If the document body is empty and a new container
                cannot be inserted.

        """
        user_field_decls = self.get_element("//text:user-field-decls")
        if user_field_decls is None:
            body = self.document_body
            if not body:
                msg = "Empty document.body"
                raise ValueError(msg)
            body.insert(Element.from_tag("text:user-field-decls"), FIRST_CHILD)
            user_field_decls = body.get_element("//text:user-field-decls")

        return cast("UserFieldDecls", user_field_decls)

get_user_field_decls 

get_user_field_decls() -> UserFieldDecls

Return the container for user field declarations.

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

Returns:

Name Type Description
UserFieldDecls UserFieldDecls

The UserFieldDecls instance (container for user field declarations).

Raises:

Type Description
ValueError

If the document body is empty and a new container cannot be inserted.
Source code in odfdo/user_field_declaration.py 
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
def get_user_field_decls(self) -> UserFieldDecls:
    """Return the container for user field declarations.

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

    Returns:
        UserFieldDecls: The UserFieldDecls instance (container for
            user field declarations).

    Raises:
        ValueError: If the document body is empty and a new container
            cannot be inserted.

    """
    user_field_decls = self.get_element("//text:user-field-decls")
    if user_field_decls is None:
        body = self.document_body
        if not body:
            msg = "Empty document.body"
            raise ValueError(msg)
        body.insert(Element.from_tag("text:user-field-decls"), FIRST_CHILD)
        user_field_decls = body.get_element("//text:user-field-decls")

    return cast("UserFieldDecls", user_field_decls)

UserFieldDeclMixin

Bases: Element

Mixin class for elements that can contain user field declarations.

This mixin provides methods to access “text:user-field-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”
  • “text:user-field-decls”

Methods:

Name Description
get_user_field_decl

Return a single user field declaration that matches the specified
get_user_field_decl_list

Return all user field declarations as a list.
get_user_field_value

Return the value of the specified user field.
Source code in odfdo/user_field_declaration.py 
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
class UserFieldDeclMixin(Element):
    """Mixin class for elements that can contain user field declarations.

    This mixin provides methods to access "text:user-field-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"
        - "text:user-field-decls"
    """

    def get_user_field_decl_list(self) -> list[UserFieldDecl]:
        """Return all user field declarations as a list.

        Returns:
            list[UserFieldDecl]: A list of all UserFieldDecl instances that
            are descendants of this element.

        """
        return cast(
            "list[UserFieldDecl]",
            self._filtered_elements(
                "descendant::text:user-field-decl",
            ),
        )

    def get_user_field_decl(self, name: str, position: int = 0) -> UserFieldDecl | None:
        """Return a single user field declaration that matches the specified
        criteria.

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

        Returns:
            UserFieldDecl | None: A UserFieldDecl instance, or None if no
            declaration matches the criteria.

        """
        return cast(
            "UserFieldDecl | None",
            self._filtered_element(
                "descendant::text:user-field-decl", position, text_name=name
            ),
        )

    def get_user_field_value(
        self, name: str, value_type: str | None = None
    ) -> CellValue | None:
        """Return the value of the specified user field.

        Args:
            name: The name of the user field to retrieve its value.
            value_type: The expected type of the user field's value.
                Can be 'boolean', 'currency', 'date', 'float',
                'percentage', 'string', 'time', or None for automatic
                type detection.

        Returns:
            bool | str | int | float | Decimal | datetime | timedelta | None:
                The value of the user field, cast to the most appropriate
                Python type, or None if the user field is not found.

        """
        user_field_decl = self.get_user_field_decl(name)
        if user_field_decl is None:
            return None
        return cast("CellValue | None", user_field_decl.get_value(value_type))

get_user_field_decl 

get_user_field_decl(
    name: str, position: int = 0
) -> UserFieldDecl | None

Return a single user field declaration that matches the specified criteria.

Parameters:

Name Type Description Default
name str

The name of the user field declaration to retrieve.

 required
position int

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

 0

Returns:

Type Description
UserFieldDecl | None

UserFieldDecl | None: A UserFieldDecl instance, or None if no
UserFieldDecl | None

declaration matches the criteria.
Source code in odfdo/user_field_declaration.py 
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
def get_user_field_decl(self, name: str, position: int = 0) -> UserFieldDecl | None:
    """Return a single user field declaration that matches the specified
    criteria.

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

    Returns:
        UserFieldDecl | None: A UserFieldDecl instance, or None if no
        declaration matches the criteria.

    """
    return cast(
        "UserFieldDecl | None",
        self._filtered_element(
            "descendant::text:user-field-decl", position, text_name=name
        ),
    )

get_user_field_decl_list 

get_user_field_decl_list() -> list[UserFieldDecl]

Return all user field declarations as a list.

Returns:

Type Description
list[UserFieldDecl]

list[UserFieldDecl]: A list of all UserFieldDecl instances that
list[UserFieldDecl]

are descendants of this element.
Source code in odfdo/user_field_declaration.py 
59
60
61
62
63
64
65
66
67
68
69
70
71
72
def get_user_field_decl_list(self) -> list[UserFieldDecl]:
    """Return all user field declarations as a list.

    Returns:
        list[UserFieldDecl]: A list of all UserFieldDecl instances that
        are descendants of this element.

    """
    return cast(
        "list[UserFieldDecl]",
        self._filtered_elements(
            "descendant::text:user-field-decl",
        ),
    )

get_user_field_value 

get_user_field_value(
    name: str, value_type: str | None = None
) -> CellValue | None

Return the value of the specified user field.

Parameters:

Name Type Description Default
name str

The name of the user field to retrieve its value.

 required
value_type str | None

The expected type of the user field’s value. Can be ‘boolean’, ‘currency’, ‘date’, ‘float’, ‘percentage’, ‘string’, ‘time’, or None for automatic type detection.

 None

Returns:

Type Description
CellValue | None

bool | str | int | float | Decimal | datetime | timedelta | None: The value of the user field, cast to the most appropriate Python type, or None if the user field is not found.
Source code in odfdo/user_field_declaration.py 
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
def get_user_field_value(
    self, name: str, value_type: str | None = None
) -> CellValue | None:
    """Return the value of the specified user field.

    Args:
        name: The name of the user field to retrieve its value.
        value_type: The expected type of the user field's value.
            Can be 'boolean', 'currency', 'date', 'float',
            'percentage', 'string', 'time', or None for automatic
            type detection.

    Returns:
        bool | str | int | float | Decimal | datetime | timedelta | None:
            The value of the user field, cast to the most appropriate
            Python type, or None if the user field is not found.

    """
    user_field_decl = self.get_user_field_decl(name)
    if user_field_decl is None:
        return None
    return cast("CellValue | None", user_field_decl.get_value(value_type))

UserFieldDecls

Bases: UserFieldDeclMixin

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

This element groups all the ‘text:user-field-decl’ elements in the document’s meta information.

Source code in odfdo/user_field_declaration.py 
166
167
168
169
170
171
172
173
class UserFieldDecls(UserFieldDeclMixin):
    """A container for user field declarations, "text:user-field-decls".

    This element groups all the 'text:user-field-decl' elements in the
    document's meta information.
    """

    _tag = "text:user-field-decls"

_tag class-attribute instance-attribute 

_tag = 'text:user-field-decls'