Skip to content

# native

## `xsdata.formats.dataclass.serializers.writers.native`

### `XmlEventWriter`

Bases: `XmlWriter`

Xml event writer based on `xml.sax.saxutils.XMLGenerator`.

The writer converts sax events directly to xml output without storing any intermediate results in memory.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`config` | `SerializerConfig` | The serializer config instance | required
`output` | `TextIOBase` | The output stream to write the result | required
`ns_map` | `dict` | A user defined namespace prefix-URI map | required

Attributes:

Name | Type | Description
--- | --- | ---
`handler` |  | The content handler instance
`in_tail` |  | Specifies whether the text content has been written
`tail` | `str | None` | The current element tail content
`attrs` | `dict` | The current element attributes
`ns_context` | `list[dict]` | The namespace context queue
`pending_tag` | `tuple | None` | The pending element namespace, name tuple
`pending_prefixes` | `list[list]` | The pending element namespace prefixes

Source code in `xsdata/formats/dataclass/serializers/writers/native.py`

      8
      9
     10
     11
     12
     13
     14
     15
     16
     17
     18
     19
     20
     21
     22
     23
     24
     25
     26
     27
     28
     29
     30
     31
     32
     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

    class XmlEventWriter(XmlWriter):
        """Xml event writer based on `xml.sax.saxutils.XMLGenerator`.

        The writer converts sax events directly to xml output
        without storing any intermediate results in memory.

        Args:
            config: The serializer config instance
            output: The output stream to write the result
            ns_map: A user defined namespace prefix-URI map

        Attributes:
            handler: The content handler instance
            in_tail: Specifies whether the text content has been written
            tail: The current element tail content
            attrs: The current element attributes
            ns_context: The namespace context queue
            pending_tag: The pending element namespace, name tuple
            pending_prefixes: The pending element namespace prefixes
        """

        __slots__ = ("current_level", "pending_end_element")

        def __init__(self, config: SerializerConfig, output: TextIOBase, ns_map: dict):
            """Initialize the writer."""
            super().__init__(config, output, ns_map)

            self.current_level = 0
            self.pending_end_element = False

        def build_handler(self) -> XMLGenerator:
            """Build the content handler instance.

            Returns:
                A xml generator content handler instance.
            """
            return XMLGenerator(
                out=self.output,
                encoding=self.config.encoding,
                short_empty_elements=True,
            )

        def start_tag(self, qname: str) -> None:
            """Start tag notification receiver.

            The receiver will flush the start of any pending element, create
            new namespaces context and queue the current tag for generation.

            The receiver will also write the necessary whitespace if
            pretty print is enabled.

            Args:
                qname: The qualified name of the starting element
            """
            super().start_tag(qname)

            if self.config.indent:
                if self.current_level:
                    self.handler.ignorableWhitespace("\n")
                    self.handler.ignorableWhitespace(
                        self.config.indent * self.current_level
                    )

                self.current_level += 1
                self.pending_end_element = False

        def end_tag(self, qname: str) -> None:
            """End tag notification receiver.

            The receiver will flush if pending the start of the element, end
            the element, its tail content and its namespaces prefix mapping
            and current context.

            The receiver will also write the necessary whitespace if
            pretty print is enabled.

            Args:
                qname: The qualified name of the element
            """
            if not self.config.indent:
                super().end_tag(qname)
                return

            self.current_level -= 1
            if self.pending_end_element:
                self.handler.ignorableWhitespace("\n")
                self.handler.ignorableWhitespace(self.config.indent * self.current_level)

            super().end_tag(qname)

            self.pending_end_element = True
            if not self.current_level:
                self.handler.ignorableWhitespace("\n")

#### `__init__(config, output, ns_map)`

Initialize the writer.

Source code in `xsdata/formats/dataclass/serializers/writers/native.py`

    31
    32
    33
    34
    35
    36

    def __init__(self, config: SerializerConfig, output: TextIOBase, ns_map: dict):
        """Initialize the writer."""
        super().__init__(config, output, ns_map)

        self.current_level = 0
        self.pending_end_element = False

#### `build_handler()`

Build the content handler instance.

Returns:

Type | Description
--- | ---
`XMLGenerator` | A xml generator content handler instance.

Source code in `xsdata/formats/dataclass/serializers/writers/native.py`

    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48

    def build_handler(self) -> XMLGenerator:
        """Build the content handler instance.

        Returns:
            A xml generator content handler instance.
        """
        return XMLGenerator(
            out=self.output,
            encoding=self.config.encoding,
            short_empty_elements=True,
        )

#### `start_tag(qname)`

Start tag notification receiver.

The receiver will flush the start of any pending element, create new namespaces context and queue the current tag for generation.

The receiver will also write the necessary whitespace if pretty print is enabled.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`qname` | `str` | The qualified name of the starting element | required

Source code in `xsdata/formats/dataclass/serializers/writers/native.py`

    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72

    def start_tag(self, qname: str) -> None:
        """Start tag notification receiver.

        The receiver will flush the start of any pending element, create
        new namespaces context and queue the current tag for generation.

        The receiver will also write the necessary whitespace if
        pretty print is enabled.

        Args:
            qname: The qualified name of the starting element
        """
        super().start_tag(qname)

        if self.config.indent:
            if self.current_level:
                self.handler.ignorableWhitespace("\n")
                self.handler.ignorableWhitespace(
                    self.config.indent * self.current_level
                )

            self.current_level += 1
            self.pending_end_element = False

#### `end_tag(qname)`

End tag notification receiver.

The receiver will flush if pending the start of the element, end the element, its tail content and its namespaces prefix mapping and current context.

The receiver will also write the necessary whitespace if pretty print is enabled.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`qname` | `str` | The qualified name of the element | required

Source code in `xsdata/formats/dataclass/serializers/writers/native.py`

     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

    def end_tag(self, qname: str) -> None:
        """End tag notification receiver.

        The receiver will flush if pending the start of the element, end
        the element, its tail content and its namespaces prefix mapping
        and current context.

        The receiver will also write the necessary whitespace if
        pretty print is enabled.

        Args:
            qname: The qualified name of the element
        """
        if not self.config.indent:
            super().end_tag(qname)
            return

        self.current_level -= 1
        if self.pending_end_element:
            self.handler.ignorableWhitespace("\n")
            self.handler.ignorableWhitespace(self.config.indent * self.current_level)

        super().end_tag(qname)

        self.pending_end_element = True
        if not self.current_level:
            self.handler.ignorableWhitespace("\n")