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__

Initializes the UserFieldDecl element.
set_value

Sets the value of the user field declaration.
Source code in odfdo/user_field_declaration.py 
173
174
175
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
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:
        """Initializes 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`.
        """
        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:
        """Sets 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

Initializes 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
Source code in odfdo/user_field_declaration.py 
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
def __init__(
    self,
    name: str | None = None,
    value: Any = None,
    value_type: str | None = None,
    **kwargs: Any,
) -> None:
    """Initializes 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`.
    """
    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

Sets 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 
207
208
209
210
211
212
213
214
215
216
217
218
219
def set_value(self, value: Any) -> None:
    """Sets 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

Returns the container for user field declarations.
Source code in odfdo/user_field_declaration.py 
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
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
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:
        """Returns 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:
                raise ValueError("Empty document.body")
            body.insert(Element.from_tag("text:user-field-decls"), FIRST_CHILD)
            user_field_decls = body.get_element("//text:user-field-decls")

        return cast(UserFieldDecls, user_field_decls)

get_user_field_decls 

get_user_field_decls() -> UserFieldDecls

Returns 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 
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
def get_user_field_decls(self) -> UserFieldDecls:
    """Returns 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:
            raise ValueError("Empty document.body")
        body.insert(Element.from_tag("text:user-field-decls"), FIRST_CHILD)
        user_field_decls = body.get_element("//text:user-field-decls")

    return 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

Returns a single user field declaration that matches the specified
get_user_field_decl_list

Returns all user field declarations as a list.
get_user_field_value

Returns the value of the specified user field.
Source code in odfdo/user_field_declaration.py 
 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
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]:
        """Returns 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:
        """Returns 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(
            None | UserFieldDecl,
            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
    ) -> bool | str | int | float | Decimal | datetime | timedelta | None:
        """Returns 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
        value = user_field_decl.get_value(value_type)
        return value  # type: ignore

get_user_field_decl 

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

Returns 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
def get_user_field_decl(self, name: str, position: int = 0) -> UserFieldDecl | None:
    """Returns 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(
        None | UserFieldDecl,
        self._filtered_element(
            "descendant::text:user-field-decl", position, text_name=name
        ),
    )

get_user_field_decl_list 

get_user_field_decl_list() -> list[UserFieldDecl]

Returns 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 
60
61
62
63
64
65
66
67
68
69
70
71
72
def get_user_field_decl_list(self) -> list[UserFieldDecl]:
    """Returns 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
) -> (
    bool
    | str
    | int
    | float
    | Decimal
    | datetime
    | timedelta
    | None
)

Returns 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
bool | str | int | float | Decimal | datetime | timedelta | 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 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
def get_user_field_value(
    self, name: str, value_type: str | None = None
) -> bool | str | int | float | Decimal | datetime | timedelta | None:
    """Returns 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
    value = user_field_decl.get_value(value_type)
    return value  # type: ignore

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 
163
164
165
166
167
168
169
170
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'