# XML Binding

All binding modules rely on a `XmlContext` instance to cache model metadata and binding information.

It’s recommended to either reuse the same parser/serializer instance or reuse the context instance.

    from xsdata.formats.dataclass.context import XmlContext
    from xsdata.formats.dataclass.parsers import XmlParser
    from xsdata.formats.dataclass.serializers import XmlSerializer

    context = XmlContext()
    parser = XmlParser(context=context)
    serializer = XmlSerializer(context=context)

## Parse from xml filename

    >>> from xsdata.formats.dataclass.context import XmlContext
    >>> from xsdata.formats.dataclass.parsers import XmlParser
    >>> from tests import fixtures_dir # pathlib.Path
    >>> from tests.fixtures.primer import PurchaseOrder, Usaddress
    ...
    >>> filename = str(fixtures_dir.joinpath("primer/sample.xml"))
    >>> parser = XmlParser(context=XmlContext())
    >>> order = parser.parse(filename, PurchaseOrder)
    >>> order.bill_to
    Usaddress(name='Robert Smith', street='8 Oak Avenue', city='Old Town', state='PA', zip=Decimal('95819'), country='US')

## Parse from xml file object

    >>> xml_path = fixtures_dir.joinpath("primer/sample.xml")
    >>> with xml_path.open("rb") as fp:
    ...     order = parser.parse(fp, PurchaseOrder)
    >>> order.bill_to.street
    '8 Oak Avenue'

## Parse from xml stream

    >>> import io
    >>> order = parser.parse(io.BytesIO(xml_path.read_bytes()), PurchaseOrder)
    >>> order.bill_to.street
    '8 Oak Avenue'

## Parse from xml string

    >>> order = parser.from_string(xml_path.read_text(), PurchaseOrder)
    >>> order.bill_to.street
    '8 Oak Avenue'

## Parse from xml bytes

    >>> order = parser.from_bytes(xml_path.read_bytes(), PurchaseOrder)
    >>> order.bill_to.street
    '8 Oak Avenue'

## Parse from xml Path

    >>> order = parser.from_path(xml_path, PurchaseOrder)
    >>> order.bill_to.street
    '8 Oak Avenue'

## Parse from Element or ElementTree

For selective parsing you can use an Element or ElementTree as source. This way you can modify the dom or pick from which node to start binding data.

Using lxml and `LxmlEventHandler`

    >>> import lxml
    >>> from xsdata.formats.dataclass.parsers.handlers import LxmlEventHandler
    ...
    >>> parser = XmlParser(handler=LxmlEventHandler)
    >>> tree = lxml.etree.parse(str(xml_path))
    >>> bill_to = parser.parse(tree.find('.//billTo'), Usaddress)
    >>> bill_to
    Usaddress(name='Robert Smith', street='8 Oak Avenue', city='Old Town', state='PA', zip=Decimal('95819'), country='US')

Using the xml module and `XmlEventHandler`

    >>> from xml.etree import ElementTree as ET
    >>> from xsdata.formats.dataclass.parsers.handlers import XmlEventHandler
    ...
    >>> parser = XmlParser(handler=XmlEventHandler)
    >>> tree = ET.parse(str(xml_path))
    >>> ship_to = parser.parse(tree.find('.//shipTo'), Usaddress)
    >>> ship_to
    Usaddress(name='Alice Smith', street='123 Maple Street', city='Mill Valley', state='CA', zip=Decimal('90952'), country='US')

Note

The `xml.etree.ElementTree` api doesn’t preserve the namespace prefixes, the handler will auto generate new ones.

## Parse with unknown xml target type

It’s optimal to provide the target model but completely optional. The parser can scan all the imported modules to find a matching dataclass.

    >>> order = parser.from_bytes(xml_path.read_bytes())
    >>> type(order)
    <class 'tests.fixtures.primer.order.PurchaseOrder'>

## Parser Config

The configuration allows to enable/disable various features and failures.

    >>> from xsdata.formats.dataclass.parsers.config import ParserConfig
    ...
    >>> config = ParserConfig(
    ...     base_url=None,
    ...     process_xinclude=False,
    ...     fail_on_unknown_properties=False,
    ...     fail_on_unknown_attributes=False,
    ... )
    >>> parser = XmlParser(config=config)
    >>> order = parser.from_bytes(xml_path.read_bytes())
    >>> order.bill_to.street
    '8 Oak Avenue'

API Reference.

## Parse xml with alternative handlers

XmlHandlers read the xml source and push build events to create the target class. xsData ships with multiple handlers based on lxml and native python that vary in performance and features.

Hint

If you installed xsdata with lxml the default handler is set to `LxmlEventHandler` otherwise `XmlEventHandler` will be used.

    >>> from xsdata.formats.dataclass.parsers.handlers import XmlEventHandler
    ...
    >>> parser = XmlParser(handler=XmlEventHandler)
    >>> order = parser.from_path(xml_path)
    >>> order.bill_to.street
    '8 Oak Avenue'

Hint

It’s recommended to give all of them a try, based on your use case you might get different results.

You can also extend one of them if you want to do any optimizations or customize the default behaviour.

Read more…

## Parse xml with xinclude statements

The `LxmlEventHandler` and `XmlEventHandler` both support processing xinclude directives.

If you are parsing from memory you need to specify the base url in the config in order to load the children documents.

    >>> from xsdata.formats.dataclass.parsers.handlers import XmlEventHandler
    ...
    >>> xml = """<?xml version="1.0" encoding="UTF-8"?>
    ... <brk:books xmlns:brk="urn:books" xmlns:xi="http://www.w3.org/2001/XInclude">
    ...   <xi:include href="bk001.xml"/>
    ...   <xi:include href="bk002.xml"/>
    ... </brk:books>"""
    >>> base_url = fixtures_dir.joinpath("books/books-xinclude.xml")
    >>> config = ParserConfig(process_xinclude=True, base_url=str(base_url))
    >>> parser = XmlParser(config=config)
    >>> books = parser.from_string(xml)
    >>> print(books.book[1])
    BookForm(author='Nagata, Suanne', title='Becoming Somebody', genre='Biography', price=33.95, pub_date=XmlDate(2001, 1, 10), review='A masterpiece of the fine art of gossiping.', id='bk002', lang='en')

## Serialize xml to string

    >>> from tests.fixtures.books import Books, BookForm
    >>> from xsdata.formats.dataclass.serializers import XmlSerializer
    >>> from xsdata.formats.dataclass.serializers.config import SerializerConfig
    ...
    >>> books = Books(
    ...     book=[
    ...         BookForm(
    ...             id="bk001",
    ...             author="Hightower, Kim",
    ...             title="The First Book",
    ...             genre="Fiction",
    ...             price=44.95,
    ...             pub_date="2000-10-01",
    ...             review="An amazing story of nothing.",
    ...         )
    ...     ]
    ... )
    ...
    >>> config = SerializerConfig(pretty_print=True)
    >>> serializer = XmlSerializer(config=config)
    >>> print(serializer.render(books))
    <?xml version="1.0" encoding="UTF-8"?>
    <ns0:books xmlns:ns0="urn:books">
      <book id="bk001" lang="en">
        <author>Hightower, Kim</author>
        <title>The First Book</title>
        <genre>Fiction</genre>
        <price>44.95</price>
        <pub_date>2000-10-01</pub_date>
        <review>An amazing story of nothing.</review>
      </book>
    </ns0:books>

## Serialize xml with custom namespace prefixes

    >>> print(serializer.render(books, ns_map={"bk": "urn:books"}))
    <?xml version="1.0" encoding="UTF-8"?>
    <bk:books xmlns:bk="urn:books">
      <book id="bk001" lang="en">
        <author>Hightower, Kim</author>
        <title>The First Book</title>
        <genre>Fiction</genre>
        <price>44.95</price>
        <pub_date>2000-10-01</pub_date>
        <review>An amazing story of nothing.</review>
      </book>
    </bk:books>

## Serialize xml with default namespace

    >>> print(serializer.render(books, ns_map={None: "urn:books"}))
    <?xml version="1.0" encoding="UTF-8"?>
    <books xmlns="urn:books">
      <book xmlns="" id="bk001" lang="en">
        <author>Hightower, Kim</author>
        <title>The First Book</title>
        <genre>Fiction</genre>
        <price>44.95</price>
        <pub_date>2000-10-01</pub_date>
        <review>An amazing story of nothing.</review>
      </book>
    </books>

## Serialize xml to stream

    >>> from pathlib import Path
    ...
    >>> path = Path("output.xml")
    >>> with path.open("w") as fp:
    ...     serializer.write(fp, books)
    ...
    >>> print(path.read_text())
    <?xml version="1.0" encoding="UTF-8"?>
    <ns0:books xmlns:ns0="urn:books">
      <book id="bk001" lang="en">
        <author>Hightower, Kim</author>
        <title>The First Book</title>
        <genre>Fiction</genre>
        <price>44.95</price>
        <pub_date>2000-10-01</pub_date>
        <review>An amazing story of nothing.</review>
      </book>
    </ns0:books>

    >>> path.unlink()

## Serialize xml with alternative writers

xsData ships with multiple writers based on lxml and native python that may vary in performance in some cases. The output of all them is consistent with a few exceptions when handling mixed content with `pretty_print=True`.

Hint

If you installed xsdata with lxml the default writer is set to `LxmlEventWriter` otherwise `XmlEventWriter` will be used.

    >>> from xsdata.formats.dataclass.serializers.writers import XmlEventWriter
    ...
    >>> serializer = XmlSerializer(config=config, writer=XmlEventWriter)
    >>> print(serializer.render(books))
    <?xml version="1.0" encoding="UTF-8"?>
    <ns0:books xmlns:ns0="urn:books">
      <book id="bk001" lang="en">
        <author>Hightower, Kim</author>
        <title>The First Book</title>
        <genre>Fiction</genre>
        <price>44.95</price>
        <pub_date>2000-10-01</pub_date>
        <review>An amazing story of nothing.</review>
      </book>
    </ns0:books>

Read more…

## Serialize with omit default attributes

Attributes are allowed to have default or fixed values and be marked as optional. The default behaviour is to write them explicitly during serialization but you can disable them through config.

    >>> from xsdata.formats.dataclass.serializers.config import SerializerConfig
    ...
    >>> serializer = XmlSerializer(config=SerializerConfig(
    ...     pretty_print=True,
    ...     xml_declaration=False,
    ...     ignore_default_attributes=True,
    ...     schema_location="urn books.xsd",
    ...     no_namespace_schema_location=None,
    ... ))
    >>> print(serializer.render(books))
    <ns0:books xmlns:ns0="urn:books" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn books.xsd">
      <book id="bk001">
        <author>Hightower, Kim</author>
        <title>The First Book</title>
        <genre>Fiction</genre>
        <price>44.95</price>
        <pub_date>2000-10-01</pub_date>
        <review>An amazing story of nothing.</review>
      </book>
    </ns0:books>

Read more…