Merge pull request #256 from dapper91/doc/misc

dapper91 · web-flow · commit c73c38f16918 · 2025-04-20T14:48:12.000+05:00
- document type declaration example added.
- sub-model namespace inheritance documented.
diff --git a/docs/source/pages/data-binding/elements.rst b/docs/source/pages/data-binding/elements.rst
@@ -153,6 +153,39 @@ The namespace and namespace mapping can be declared for a model. In that case al
                     :start-after: json-start
                     :end-before: json-end
 
+.. note::
+    **Pay attention** to the namespace inheritance rule: namespace and namespace mapping
+    are only inherited by primitive types not sub-models. If your sub-model share
+    the namespace with the parent model you must define it explicitly:
+
+    .. code-block:: python
+
+        from pydantic_xml import BaseXmlModel, element
+
+        NSMAP = {
+            'co': 'http://www.company.com/co',
+        }
+
+        class SubModel(BaseXmlModel, ns='co', nsmap=NSMAP):  # define ns and nsmap explicitly
+            field2: str = element(tag='element1')
+
+        class Model(BaseXmlModel, ns='co', nsmap=NSMAP):
+            field1: str = element(tag='element1')  # ns "co" is inherited by the element
+            sub: SubModel  # ns and nsmap are not inherited by the SubModel
+
+        model = Model(field1="value1", sub=SubModel(field2="value2"))
+        print(model.to_xml(pretty_print=True).decode())
+
+
+    .. code-block:: xml
+
+        <co:Model xmlns:co="http://www.company.com/co">
+          <co:element1>value1</co:element1>
+          <co:sub>
+            <co:element1>value2</co:element1>
+          </co:sub>
+        </co:Model>
+
 
 The namespace and namespace mapping can be also applied to model types passing ``ns`` and ``nsmap``
 to :py:func:`pydantic_xml.element`. If they are omitted the model namespace and namespace mapping is used:
diff --git a/docs/source/pages/misc.rst b/docs/source/pages/misc.rst
@@ -277,6 +277,68 @@ Field specification syntax is similar to ``pydantic`` one. For more information
 see the `documentation <https://docs.pydantic.dev/latest/concepts/models/#dynamic-model-creation>`_.
 
 
+Document type declaration
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A document type declaration is an instruction that associates a particular XML document
+with a document type definition (DTD).
+
+DTD is supported by ``lxml`` backend only so the library doesn't provide an api for that natively,
+but it can be easily implemented by your hand:
+
+.. code-block:: python
+
+    from typing import Any, ClassVar, Union
+
+    import pydantic_xml as pxml
+    import lxml.etree
+
+
+    class DTDXmlModel(pxml.BaseXmlModel):
+        DOC_PUBLIC_ID: ClassVar[str]
+        DOC_SYSTEM_URL: ClassVar[str]
+
+        def to_xml(
+                self,
+                *,
+                skip_empty: bool = False,
+                exclude_none: bool = False,
+                exclude_unset: bool = False,
+                **kwargs: Any,
+        ) -> Union[str, bytes]:
+            root = self.to_xml_tree(skip_empty=skip_empty, exclude_none=exclude_none, exclude_unset=exclude_unset)
+            tree = lxml.etree.ElementTree(root)
+            tree.docinfo.public_id = self.DOC_PUBLIC_ID
+            tree.docinfo.system_url = self.DOC_SYSTEM_URL
+
+            return lxml.etree.tostring(tree, **kwargs)
+
+
+    class Html(DTDXmlModel, tag='html'):
+        DOC_PUBLIC_ID: ClassVar[str] = '-//W3C//DTD HTML 4.01//EN'
+        DOC_SYSTEM_URL: ClassVar[str] = 'http://www.w3.org/TR/html4/strict.dtd'
+
+        title: str = pxml.wrapped('head', pxml.element())
+        body: str = pxml.element()
+
+
+    html_doc = Html(title="This is a title", body="Hello world!")
+    xml = html_doc.to_xml(pretty_print=True)
+
+    print(xml.decode())
+
+
+.. code-block:: xml
+
+    <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+    <html>
+      <head>
+        <title>This is a title</title>
+      </head>
+      <body>Hello world!</body>
+    </html>
+
+
 Mypy
 ~~~~
 
