Types
Important
Dataclasses don't validate values when creating a new instances or assigning values to fields. Automatic conversion of values to appropriate python data types occurs only during the parsing process.
The parser handles value/type discrepancies leniently, potentially ignoring the defined field type hint. When such an error arises, the converter issues a ConverterWarning
.
If you prefer to treat conversion warnings as exceptions you need to activate the ParserConfig.fail_on_converter_warnings option.
Collections
PEP-585 type hinting generics in standard collections are also supported.
List
typing.List
Case | Example |
---|---|
List | value: List[str] = field(default_factory=list) |
Optional List | value: Optional[List[str]] = field(default=None) |
List Union | value: List[Union[str, int]] = field(default_factory=list) |
Tokens List | value: List[str] = field(default_factory=list, metadata={"tokens": True}) |
List of Tokens | value: List[List[str]] = field(default_factory=list, metadata={"tokens": True}) |
Tuple
typing.Tuple
can be use in frozen
dataclasses, for immutable instances.
Case | Example |
---|---|
Tuple | value: Tuple[str] = field(default_factory=list) |
Optional Tuple | value: Optional[Tuple[str]] = field(default=None) |
Tuple Union | value: Tuple[Union[str, int]] = field(default_factory=list) |
Tokens Tuple | value: Tuple[str] = field(default_factory=list, metadata={"tokens": True}) |
Tuple of Tokens | value: Tuple[Tuple[str]] = field(default_factory=list, metadata={"tokens": True}) |
Dict
typing.Dict
is reserved for Attributes
type fields to capture any undefined attribute.
Case | Example |
---|---|
Attributes | attrs: Dict[str, str] = field(default_factory=dict, metadata={"type": "Attributes"}) |
Union
typing.Union
Case | Example |
---|---|
Union | value: Union[str, int, float] = field() |
Optional Union | value: Optional[Union[str, int, float]] = field(default=None) |
The order of the types doesn't matter, internally the converter sorts the types by priority:
int
bool
float
Decimal
datetime
date
time
XmlTime
XmlDate
XmlDateTime
XmlDuration
XmlPeriod
QName
str
Standard Types
This is the list of all the supported primitive types.
Boolean
Input | Python | XML | JSON |
---|---|---|---|
"true" | True | "true" | true |
"1" | True | "true" | true |
"false" | False | "false" | false |
"1" | False | "false" | false |
Python Type: bool
XML Type: boolean
Bytes Array
The fields must provide the format
metadata property.
base16
for hexadecimal stringbase64
for base64 encoded bytes-like object or ASCII strings
Python Type: bytes
XML Types: hexBinary, base64Binary
Decimal
Python Type: decimal.Decimal
XML Type: decimal
Float
Python Type: float
Integer
Python Type: int
XML Types:
- int
- nonPositiveInteger
- negativeInteger
- long
- integer
- short
- byte
- nonNegativeInteger
- unsignedLong
- unsignedInt
- unsignedShort
- unsignedByte
- positiveInteger
Object
Python Type: object
XML Type: anySimpleType
QName
Python Type: xml.etree.ElementTree.QName
String
Python Type: str
XML Types:
- string
- anyURI
- normalizedString
- token
- language
- NMTOKEN
- NMTOKENS
- Name
- NCName
- ID
- IDREF
- IDREFS
- ENTITIES
- ENTITY
- anyAtomicType
- error
XmlDate
Python Type: xsdata.models.datatype.XmlDate
XML Type: date
XmlDateTime
Python Type: xsdata.models.datatype.XmlDateTime
XML Types: dateTime, dateTimeStamp
XmlDuration
Python Type: xsdata.models.datatype.XmlDuration
XML Types:
XmlPeriod
Python Type: xsdata.models.datatype.XmlPeriod
XML Types:
XmlTime
Python Type: xsdata.models.datatype.XmlTime
XML Type:: time
Enum
Python Type: enum.Enum
XML Type:: enumeration
User Types
You can register you own custom types as well as long as they are not dataclasses.
>>> from dataclasses import dataclass, field
>>> from xsdata.formats.converter import Converter, converter
>>> from xsdata.formats.dataclass.parsers import XmlParser
>>> from xsdata.formats.dataclass.serializers import XmlSerializer
...
>>> serializer = XmlSerializer()
>>> serializer.config.indent = " "
>>> serializer.config.xml_declaration = False
>>>
>>> class TheGoodFloat(float):
... pass
...
>>> @dataclass
... class Example:
... good: TheGoodFloat = field(metadata=dict(format="{:.2f}"))
... bad: float
...
>>> class TheGoodFloatConverter(Converter):
... def deserialize(self, value: str, **kwargs) -> TheGoodFloat:
... return round(TheGoodFloat(value), 1) # Even nicer
...
... def serialize(self, value: TheGoodFloat, **kwargs) -> str:
... if kwargs["format"]:
... return kwargs["format"].format(value)
... return str(value)
...
>>> converter.register_converter(TheGoodFloat, TheGoodFloatConverter())
>>> output = serializer.render(Example(TheGoodFloat(10.983263748), -9.9827632))
>>> print(output)
<Example>
<good>10.98</good>
<bad>-9.9827632</bad>
</Example>
>>> XmlParser().from_string(output)
Example(good=11.0, bad=-9.9827632)