Skip to content

Meta User Defined

MetaUserDefined class for “meta:user-defined” tag.

Classes:

Name Description
MetaUserDefined

Declaration of a user-defined metadata, “meta:user-defined”.

MetaUserDefined

Bases: Element

Declaration of a user-defined metadata, “meta:user-defined”.

Methods:

Name Description
__init__

Initialize a MetaUserDefined element.
as_dict

Return the user-defined metadata as a dictionary.
as_dict_full

Return the user-defined metadata as a detailed dictionary.

Attributes:

Name Type Description
name str

Get the name of the user-defined metadata field.
value Decimal | datetime | date | timedelta | bool | str

Get the Python-typed value of the user-defined metadata field.
value_type str

Get the type of the user-defined value.
Source code in odfdo/meta_user_defined.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
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
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
164
165
166
167
168
169
170
171
172
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
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
class MetaUserDefined(Element):
    """Declaration of a user-defined metadata, "meta:user-defined"."""

    _tag = "meta:user-defined"

    def __init__(
        self,
        name: str | None = None,
        value_type: str | None = None,
        value: int
        | float
        | Decimal
        | datetime
        | dtdate
        | timedelta
        | bool
        | str
        | None = None,
        **kwargs: Any,
    ) -> None:
        """Initialize a MetaUserDefined element.

        This element declares a user-defined metadata field.

        Args:
            name: The name of the user-defined metadata field
                (corresponds to `meta:name` attribute).
            value_type: The type of the value. Must be one of
                "boolean", "date", "float", "time", "string".
            value: The actual value of the user-defined metadata.
            **kwargs: Additional keyword arguments for the parent `Element` class.
        """
        super().__init__(**kwargs)
        if self._do_init:
            self.name = name
            self.value_type = value_type
            self.value = value

    @property
    def name(self) -> str:
        """Get the name of the user-defined metadata field.

        Returns:
            str: The value of the `meta:name` attribute.
        """
        return self.get_attribute_string("meta:name") or ""

    @name.setter
    def name(self, name: str | None) -> None:
        """Set the name of the user-defined metadata field.

        Args:
            name: The new name for the field.

        Raises:
            ValueError: If the provided name is empty.
        """
        if not name:
            raise ValueError('"name" can not be empty')
        self._set_attribute_str_default("meta:name", name)

    @property
    def value_type(self) -> str:
        """Get the type of the user-defined value.

        Returns:
            str: The value of the `meta:value-type` attribute, defaulting to "string".
        """
        return self.get_attribute_string("meta:value-type") or "string"

    @value_type.setter
    def value_type(self, value_type: str | None) -> None:
        """Set the type of the user-defined value.

        Args:
            value_type: The new value type. Must be one of
                "boolean", "date", "float", "time", "string".

        Raises:
            ValueError: If an unknown `value_type` is provided.
        """
        if value_type not in {"boolean", "date", "float", "time", "string"}:
            raise ValueError(f'Unknown "value_type": {value_type!r}')
        self._set_attribute_str_default("meta:value-type", value_type)

    @property
    def value(self) -> Decimal | datetime | dtdate | timedelta | bool | str:
        """Get the Python-typed value of the user-defined metadata field.

        The return type depends on the `meta:value-type` attribute.

        Returns:
            Decimal | datetime | dtdate | timedelta | bool | str: The converted value.

        Raises:
            TypeError: If the `meta:value-type` is unknown.
        """
        value_type = self.get_attribute_string("meta:value-type")
        if value_type is None:
            value_type = "string"
        text = self.text
        if value_type == "boolean":
            return Boolean.decode(text)
        if value_type == "date":
            if "T" in text:
                return DateTime.decode(text)
            else:
                return Date.decode(text)
        if value_type == "float":
            return Decimal(text)
        if value_type == "time":
            return Duration.decode(text)
        if value_type == "string":
            return text
        # should never happen
        raise TypeError(f"Unknown value type: '{value_type!r}'")  # pragma: nocover

    @value.setter
    def value(
        self,
        value: int
        | float
        | Decimal
        | datetime
        | dtdate
        | timedelta
        | bool
        | str
        | None,
    ) -> None:
        """Set the value of the user-defined metadata field.

        The value is converted to a string based on the current `meta:value-type`
        and stored as the element's text content.

        Args:
            value: The value to set.
        """
        value_type = self.get_attribute_string("meta:value-type")
        if value_type == "boolean":
            text: str = "true" if value else "false"
        elif value_type == "date":
            if isinstance(value, datetime):
                text = str(DateTime.encode(value))
            else:
                text = str(Date.encode(value))  # type: ignore[arg-type]
        elif value_type == "float":
            text = str(value or 0)
        elif value_type == "time":
            text = str(Duration.encode(value))  # type: ignore[arg-type]
        else:
            text = str(value or "")
        self.text = text

    @staticmethod
    def _value_to_value_type(
        value: bool | int | float | Decimal | datetime | dtdate | str | timedelta,
    ) -> str:
        """Internal helper to infer the ODF value type from a Python value.

        Args:
            value: The Python value.

        Returns:
            str: The inferred ODF value type ("boolean", "float", "date", "string", or "time").

        Raises:
            TypeError: If the type of the provided value is not supported.
        """
        if isinstance(value, bool):
            return "boolean"
        elif isinstance(value, (int, float, Decimal)):
            return "float"
        elif isinstance(value, (datetime, dtdate)):
            return "date"
        elif isinstance(value, str):
            return "string"
        elif isinstance(value, timedelta):
            return "time"
        else:
            raise TypeError(f'unexpected type "{type(value)}" for value')

    def as_dict(
        self,
    ) -> dict[str, Decimal | datetime | dtdate | timedelta | bool | str]:
        """Return the user-defined metadata as a dictionary.

        Returns:
            dict[str, Decimal | datetime | dtdate | timedelta | bool | str]:
                A dictionary containing "meta:name", "meta:value-type", and "value".
        """
        return {
            "meta:name": self.name,
            "meta:value-type": self.value_type,
            "value": self.value,
        }

    def as_dict_full(
        self,
    ) -> dict[str, Decimal | datetime | dtdate | timedelta | bool | str]:
        """Return the user-defined metadata as a detailed dictionary.

        This includes the name, value type, value, and raw text content.

        Returns:
            dict[str, Decimal | datetime | dtdate | timedelta | bool | str]:
                A dictionary containing "name", "value_type", "value", and "text".
        """
        return {
            "name": self.name,
            "value_type": self.value_type,
            "value": self.value,
            "text": self.text,
        }

_tag class-attribute instance-attribute 

_tag = 'meta:user-defined'

name property writable 

name: str

Get the name of the user-defined metadata field.

Returns:

Name Type Description
str str

The value of the meta:name attribute.

value property writable 

value: Decimal | datetime | date | timedelta | bool | str

Get the Python-typed value of the user-defined metadata field.

The return type depends on the meta:value-type attribute.

Returns:

Type Description
Decimal | datetime | date | timedelta | bool | str

Decimal | datetime | dtdate | timedelta | bool | str: The converted value.

Raises:

Type Description
TypeError

If the meta:value-type is unknown.

value_type property writable 

value_type: str

Get the type of the user-defined value.

Returns:

Name Type Description
str str

The value of the meta:value-type attribute, defaulting to “string”.

__init__ 

__init__(
    name: str | None = None,
    value_type: str | None = None,
    value: int
    | float
    | Decimal
    | datetime
    | date
    | timedelta
    | bool
    | str
    | None = None,
    **kwargs: Any,
) -> None

Initialize a MetaUserDefined element.

This element declares a user-defined metadata field.

Parameters:

Name Type Description Default
name str | None

The name of the user-defined metadata field (corresponds to meta:name attribute).

 None
value_type str | None

The type of the value. Must be one of “boolean”, “date”, “float”, “time”, “string”.

 None
value int | float | Decimal | datetime | date | timedelta | bool | str | None

The actual value of the user-defined metadata.

 None
**kwargs Any

Additional keyword arguments for the parent Element class.

 {}
Source code in odfdo/meta_user_defined.py 
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
def __init__(
    self,
    name: str | None = None,
    value_type: str | None = None,
    value: int
    | float
    | Decimal
    | datetime
    | dtdate
    | timedelta
    | bool
    | str
    | None = None,
    **kwargs: Any,
) -> None:
    """Initialize a MetaUserDefined element.

    This element declares a user-defined metadata field.

    Args:
        name: The name of the user-defined metadata field
            (corresponds to `meta:name` attribute).
        value_type: The type of the value. Must be one of
            "boolean", "date", "float", "time", "string".
        value: The actual value of the user-defined metadata.
        **kwargs: Additional keyword arguments for the parent `Element` class.
    """
    super().__init__(**kwargs)
    if self._do_init:
        self.name = name
        self.value_type = value_type
        self.value = value

_value_to_value_type staticmethod 

_value_to_value_type(
    value: bool
    | int
    | float
    | Decimal
    | datetime
    | date
    | str
    | timedelta,
) -> str

Internal helper to infer the ODF value type from a Python value.

Parameters:

Name Type Description Default
value bool | int | float | Decimal | datetime | date | str | timedelta

The Python value.

 required

Returns:

Name Type Description
str str

The inferred ODF value type (“boolean”, “float”, “date”, “string”, or “time”).

Raises:

Type Description
TypeError

If the type of the provided value is not supported.
Source code in odfdo/meta_user_defined.py 
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
@staticmethod
def _value_to_value_type(
    value: bool | int | float | Decimal | datetime | dtdate | str | timedelta,
) -> str:
    """Internal helper to infer the ODF value type from a Python value.

    Args:
        value: The Python value.

    Returns:
        str: The inferred ODF value type ("boolean", "float", "date", "string", or "time").

    Raises:
        TypeError: If the type of the provided value is not supported.
    """
    if isinstance(value, bool):
        return "boolean"
    elif isinstance(value, (int, float, Decimal)):
        return "float"
    elif isinstance(value, (datetime, dtdate)):
        return "date"
    elif isinstance(value, str):
        return "string"
    elif isinstance(value, timedelta):
        return "time"
    else:
        raise TypeError(f'unexpected type "{type(value)}" for value')

as_dict 

as_dict() -> dict[
    str,
    Decimal | datetime | dtdate | timedelta | bool | str,
]

Return the user-defined metadata as a dictionary.

Returns:

Type Description
dict[str, Decimal | datetime | date | timedelta | bool | str]

dict[str, Decimal | datetime | dtdate | timedelta | bool | str]: A dictionary containing “meta:name”, “meta:value-type”, and “value”.
Source code in odfdo/meta_user_defined.py 
215
216
217
218
219
220
221
222
223
224
225
226
227
228
def as_dict(
    self,
) -> dict[str, Decimal | datetime | dtdate | timedelta | bool | str]:
    """Return the user-defined metadata as a dictionary.

    Returns:
        dict[str, Decimal | datetime | dtdate | timedelta | bool | str]:
            A dictionary containing "meta:name", "meta:value-type", and "value".
    """
    return {
        "meta:name": self.name,
        "meta:value-type": self.value_type,
        "value": self.value,
    }

as_dict_full 

as_dict_full() -> dict[
    str,
    Decimal | datetime | dtdate | timedelta | bool | str,
]

Return the user-defined metadata as a detailed dictionary.

This includes the name, value type, value, and raw text content.

Returns:

Type Description
dict[str, Decimal | datetime | date | timedelta | bool | str]

dict[str, Decimal | datetime | dtdate | timedelta | bool | str]: A dictionary containing “name”, “value_type”, “value”, and “text”.
Source code in odfdo/meta_user_defined.py 
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
def as_dict_full(
    self,
) -> dict[str, Decimal | datetime | dtdate | timedelta | bool | str]:
    """Return the user-defined metadata as a detailed dictionary.

    This includes the name, value type, value, and raw text content.

    Returns:
        dict[str, Decimal | datetime | dtdate | timedelta | bool | str]:
            A dictionary containing "name", "value_type", "value", and "text".
    """
    return {
        "name": self.name,
        "value_type": self.value_type,
        "value": self.value,
        "text": self.text,
    }