Skip to content

User Field

Classes related to user-defined fields in ODF documents.

This module provides classes for managing user field declarations content within the document, “text:user-defined”, text:user-field-get”, “text:user-field-input”.

Classes:

Name Description
UserDefined

A user-defined field instance, “text:user-defined”.
UserDefinedMixin

Mixin class for classes containing user defined fields.
UserFieldGet

A getter for a user field value, “text:user-field-get”.
UserFieldInput

An input field for a user-defined field, “text:user-field-input”.

UserDefined

Bases: ElementTyped

A user-defined field instance, “text:user-defined”.

This element is similar to ‘text:user-field-get’ but is often used in contexts like headers or footers. It can be initialized directly with a value or can pull its value from a corresponding user-defined metadata field in the document’s meta section.

Attributes:

Name Type Description
name str

The name of the user field.
style str

The data style to apply for formatting.

Methods:

Name Description
__init__

Initialize the UserDefined element.
Source code in odfdo/user_field.py 
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
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
class UserDefined(ElementTyped):
    """A user-defined field instance, "text:user-defined".

    This element is similar to 'text:user-field-get' but is often used in
    contexts like headers or footers. It can be initialized directly with
    a value or can pull its value from a corresponding user-defined metadata
    field in the document's meta section.

    Attributes:
        name (str): The name of the user field.
        style (str, optional): The data style to apply for formatting.

    """

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

    def __init__(
        self,
        name: str = "",
        value: Any = None,
        value_type: str | None = None,
        text: str | None = None,
        style: str | None = None,
        from_document: Document | None = None,
        **kwargs: Any,
    ) -> None:
        """Initialize the UserDefined element.

        If a document is provided via `from_document`, the element will be
        populated with the value of the meta user-defined field of the same
        name from that document.

        Args:
            name: The name of the user-defined field.
            value: The value of the field.
            value_type: The ODF value type (e.g., 'string').
            text: The textual representation of the value.
            style: The data style name for formatting.
            from_document: A document from which to load
                the field's value from the meta section.
            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
            if from_document is not None:
                meta_infos = from_document.meta
                content = meta_infos.get_user_defined_metadata_of_name(name)
                if content is not None:
                    value = content.get("value", None)
                    value_type = content.get("value_type", None)
                    text = content.get("text", None)
            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:user-defined'

name instance-attribute 

name = name

style instance-attribute 

style = style

text instance-attribute 

text = text

__init__ 

__init__(
    name: str = "",
    value: Any = None,
    value_type: str | None = None,
    text: str | None = None,
    style: str | None = None,
    from_document: Document | None = None,
    **kwargs: Any,
) -> None

Initialize the UserDefined element.

If a document is provided via from_document, the element will be populated with the value of the meta user-defined field of the same name from that document.

Parameters:

Name Type Description Default
name str

The name of the user-defined field.

 ''
value Any

The value of the field.

 None
value_type str | None

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

 None
text str | None

The textual representation of the value.

 None
style str | None

The data style name for formatting.

 None
from_document Document | None

A document from which to load the field’s value from the meta section.

 None
kwargs Any

Arbitrary keyword arguments for the Element base class.

 {}
Source code in odfdo/user_field.py 
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
def __init__(
    self,
    name: str = "",
    value: Any = None,
    value_type: str | None = None,
    text: str | None = None,
    style: str | None = None,
    from_document: Document | None = None,
    **kwargs: Any,
) -> None:
    """Initialize the UserDefined element.

    If a document is provided via `from_document`, the element will be
    populated with the value of the meta user-defined field of the same
    name from that document.

    Args:
        name: The name of the user-defined field.
        value: The value of the field.
        value_type: The ODF value type (e.g., 'string').
        text: The textual representation of the value.
        style: The data style name for formatting.
        from_document: A document from which to load
            the field's value from the meta section.
        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
        if from_document is not None:
            meta_infos = from_document.meta
            content = meta_infos.get_user_defined_metadata_of_name(name)
            if content is not None:
                value = content.get("value", None)
                value_type = content.get("value_type", None)
                text = content.get("text", None)
        text = self.set_value_and_type(
            value=value, value_type=value_type, text=text
        )
        self.text = text

UserDefinedMixin

Bases: Element

Mixin class for classes containing user defined fields.

Used by the following classes
  • “text:a”
  • “text:h”
  • “text:meta”
  • “text:meta-field”
  • “text:p”
  • “text:ruby-base”
  • “text:span”

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

Methods:

Name Description
get_user_defined

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

Return all user-defined field declarations as a list.
get_user_defined_value

Return the value of the specified user-defined field.

Attributes:

Name Type Description
user_defined_list list[UserDefined]

Returns all user-defined field declarations as a list.
Source code in odfdo/user_field.py 
 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
117
118
119
120
121
122
123
124
125
126
127
class UserDefinedMixin(Element):
    """Mixin class for classes containing user defined fields.

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

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

    def get_user_defined_list(self) -> list[UserDefined]:
        """Return all user-defined field declarations as a list.

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

        """
        return cast(
            "list[UserDefined]",
            self._filtered_elements(
                "descendant::text:user-defined",
            ),
        )

    @property
    def user_defined_list(self) -> list[UserDefined]:
        """Returns all user-defined field declarations as a list.

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

        """
        return self.get_user_defined_list()

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

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

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

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

    def get_user_defined_value(
        self, name: str, value_type: str | None = None
    ) -> bool | str | int | float | Decimal | datetime | timedelta | None:
        """Return the value of the specified user-defined field.

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

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

        """
        user_defined = self.get_user_defined(name)
        if user_defined is None:
            return None
        return user_defined.get_value(value_type)  # ty: ignore[invalid-return-type]

user_defined_list property 

user_defined_list: list[UserDefined]

Returns all user-defined field declarations as a list.

Returns:

Type Description
list[UserDefined]

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

get_user_defined 

get_user_defined(
    name: str, position: int = 0
) -> UserDefined | None

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

Parameters:

Name Type Description Default
name str

The name of the user-defined field to retrieve.

 required
position int

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

 0

Returns:

Type Description
UserDefined | None

UserDefined | None: A UserDefined instance, or None if no declaration matches the criteria.
Source code in odfdo/user_field.py 
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
def get_user_defined(self, name: str, position: int = 0) -> UserDefined | None:
    """Return a single user-defined field declaration that matches the specified criteria.

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

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

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

get_user_defined_list 

get_user_defined_list() -> list[UserDefined]

Return all user-defined field declarations as a list.

Returns:

Type Description
list[UserDefined]

list[UserDefined]: A list of all UserDefined instances that are descendants of this element.
Source code in odfdo/user_field.py 
65
66
67
68
69
70
71
72
73
74
75
76
77
def get_user_defined_list(self) -> list[UserDefined]:
    """Return all user-defined field declarations as a list.

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

    """
    return cast(
        "list[UserDefined]",
        self._filtered_elements(
            "descendant::text:user-defined",
        ),
    )

get_user_defined_value 

get_user_defined_value(
    name: str, value_type: str | None = None
) -> (
    bool
    | str
    | int
    | float
    | Decimal
    | datetime
    | timedelta
    | None
)

Return the value of the specified user-defined field.

Parameters:

Name Type Description Default
name str

The name of the user-defined field to retrieve its value.

 required
value_type str | None

The expected type of the user-defined field’s value. Can be ‘boolean’, ‘date’, ‘float’, ‘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-defined field, cast to the most appropriate Python type, or None if the user-defined field is not found.
Source code in odfdo/user_field.py 
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
def get_user_defined_value(
    self, name: str, value_type: str | None = None
) -> bool | str | int | float | Decimal | datetime | timedelta | None:
    """Return the value of the specified user-defined field.

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

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

    """
    user_defined = self.get_user_defined(name)
    if user_defined is None:
        return None
    return user_defined.get_value(value_type)  # ty: ignore[invalid-return-type]

UserFieldGet

Bases: ElementTyped

A getter for a user field value, “text:user-field-get”.

This element displays the current value of a user-defined field at a specific position in the document content.

Attributes:

Name Type Description
name str

The name of the user field to display.
style str

The data style to apply for formatting the displayed value.

Methods:

Name Description
__init__

Initialize the UserFieldGet element.
Source code in odfdo/user_field.py 
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
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
class UserFieldGet(ElementTyped):
    """A getter for a user field value, "text:user-field-get".

    This element displays the current value of a user-defined field at a
    specific position in the document content.

    Attributes:
        name (str): The name of the user field to display.
        style (str, optional): The data style to apply for formatting the
            displayed value.

    """

    _tag = "text:user-field-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 UserFieldGet element.

        Args:
            name: The name of the user field to get.
            value: An initial value to display.
            value_type: The ODF value type.
            text: The textual representation to display. If
                not provided, it's generated from `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
            text = self.set_value_and_type(
                value=value, value_type=value_type, text=text
            )
            self.text = text

            if style:
                self.style = style

_properties class-attribute instance-attribute 

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

_tag class-attribute instance-attribute 

_tag = 'text:user-field-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 UserFieldGet element.

Parameters:

Name Type Description Default
name str | None

The name of the user field 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. If not provided, it’s generated from 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/user_field.py 
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
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 UserFieldGet element.

    Args:
        name: The name of the user field to get.
        value: An initial value to display.
        value_type: The ODF value type.
        text: The textual representation to display. If
            not provided, it's generated from `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
        text = self.set_value_and_type(
            value=value, value_type=value_type, text=text
        )
        self.text = text

        if style:
            self.style = style

UserFieldInput

Bases: UserFieldGet

An input field for a user-defined field, “text:user-field-input”.

This element allows the user to interactively modify the value of a user-defined field within the document.

Source code in odfdo/user_field.py 
186
187
188
189
190
191
192
193
class UserFieldInput(UserFieldGet):
    """An input field for a user-defined field, "text:user-field-input".

    This element allows the user to interactively modify the value of a
    user-defined field within the document.
    """

    _tag = "text:user-field-input"

_tag class-attribute instance-attribute 

_tag = 'text:user-field-input'