Add ImportAnnotations configuration option

docs/faq/why-i-get-a-typeerror-requires-a-single-type.rst

@@ -1,28 +1,15 @@
-Why I get a TypeError: requires a single type
-=============================================
+Why do I get a TypeError: requires a single type
+================================================
 
 The full error message looks something like this:
 
 .. code-block::
 
     TypeError: typing.Optional requires a single type. Got Field(name=None,type=None,default=<dataclasses._MISSING_TYPE object at 0x7f79f4b0d700>,default_facto.
 
-The error means the dataclass wrapper can't build the typing annotations for a model
-because the field type is ambiguous. If you are using the code generator make sure you
-are not using the same convention for both field and class names.
+This error means the typing annotations for a model are ambiguous because they collide with a class field. If you use Python 3.7 or later, you can set :code:`PostponedAnnotations` to :code:`true` in the :ref:`GeneratorOutput` section of the :ref:`generator config <Generator Config>` to solve this issue. This will enable Postponed Evaluations of Annotations (`PEP 563 <https://www.python.org/dev/peps/pep-0563/>`_) and the generated bindings will be able to be imported without errors. This feature is not available for Python 3.6 because :code:`annotations` were added to the :code:`__future__` module in Python 3.7.0b1.
 
 **Example**
 
-.. code-block:: python
-
-    @dataclass
-    class unit:
-        pass
-
-
-    @dataclass
-    class element:
-        unit: Optional[unit] = field()
-
-
-Read :ref:`more <Generator Config>`
+.. literalinclude:: /../tests/fixtures/annotations/model.py
+   :language: python

tests/fixtures/annotations/__init__.py

@@ -0,0 +1,11 @@
+from tests.fixtures.annotations.model import (
+    Measurement,
+    Weight,
+)
+from tests.fixtures.annotations.units import unit
+
+__all__ = [
+    "Measurement",
+    "Weight",
+    "unit",
+]

tests/fixtures/annotations/model.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Optional
+from tests.fixtures.annotations.units import unit
+
+__NAMESPACE__ = "http://domain.org/schema/model"
+
+
+@dataclass
+class Measurement:
+    value: Optional[float] = field(
+        default=None,
+        metadata={
+            "required": True,
+        }
+    )
+    unit: Optional[unit] = field(
+        default=None,
+        metadata={
+            "type": "Attribute",
+        }
+    )
+
+
+@dataclass
+class Weight(Measurement):
+    class Meta:
+        namespace = "http://domain.org/schema/model"

tests/fixtures/annotations/model.xsd

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<xs:schema targetNamespace="http://domain.org/schema/model"
+  xmlns="http://domain.org/schema/model"
+  xmlns:xs="http://www.w3.org/2001/XMLSchema"
+  xmlns:utd="http://domain.org/schema/model/units">
+
+  <xs:import schemaLocation="./units.xsd"/>
+
+  <xs:complexType name="Measurement">
+    <xs:simpleContent>
+      <xs:extension base="xs:double">
+        <xs:attribute name="unit" type="utd:unit"/>
+      </xs:extension>
+    </xs:simpleContent>
+  </xs:complexType>
+
+  <xs:element name="Weight" type="Measurement"/>
+</xs:schema>

tests/fixtures/annotations/sample.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Weight unit="kg">2.0</Weight>

tests/fixtures/annotations/units.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+from enum import Enum
+
+__NAMESPACE__ = "http://domain.org/schema/model/units"
+
+
+class unit(Enum):
+    M = "m"
+    KG = "kg"
+    VALUE = "%"
+    NA = "NA"

tests/fixtures/annotations/units.xsd

@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<xs:schema targetNamespace="http://domain.org/schema/model/units"
+	xmlns="http://domain.org/schema/model/units"
+	xmlns:xs="http://www.w3.org/2001/XMLSchema">
+
+	<xs:simpleType name="stdUnit">
+		<xs:restriction base="xs:string">
+			<xs:enumeration value="m"/>
+			<xs:enumeration value="kg"/>
+		</xs:restriction>
+	</xs:simpleType>
+
+	<xs:simpleType name="miscUnit">
+		<xs:restriction base="xs:string">
+			<xs:enumeration value="%"/>
+			<xs:enumeration value="NA"/>
+		</xs:restriction>
+	</xs:simpleType>
+
+	<xs:simpleType name="unit">
+		<xs:union memberTypes="stdUnit miscUnit"/>
+	</xs:simpleType>
+</xs:schema>

tests/fixtures/annotations/xsdata.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Config xmlns="http://pypi.org/project/xsdata" version="22.1">
+  <Output maxLineLength="79">
+    <Package>tests.fixtures.annotations</Package>
+    <Format repr="true" eq="true" order="false" unsafeHash="false" frozen="false" slots="false" kwOnly="false">dataclasses</Format>
+    <Structure>filenames</Structure>
+    <DocstringStyle>reStructuredText</DocstringStyle>
+    <RelativeImports>false</RelativeImports>
+    <CompoundFields defaultName="choice" forceDefaultName="false">true</CompoundFields>
+    <PostponedAnnotations>true</PostponedAnnotations>
+  </Output>
+  <Conventions>
+    <ClassName case="originalCase" safePrefix="type"/>
+    <FieldName case="originalCase" safePrefix="value"/>
+    <ConstantName case="screamingSnakeCase" safePrefix="value"/>
+    <ModuleName case="snakeCase" safePrefix="mod"/>
+    <PackageName case="originalCase" safePrefix="pkg"/>
+  </Conventions>
+  <Substitutions/>
+</Config>

tests/formats/dataclass/test_filters.py

@@ -674,6 +674,14 @@ def test_default_imports_with_module(self):
         expected = "import attrs"
         self.assertEqual(expected, self.filters.default_imports(output))
 
+    def test_default_imports_with_annotations(self):
+        config = GeneratorConfig()
+        config.output.postponed_annotations = True
+        filters = Filters(config)
+
+        expected = "from __future__ import annotations"
+        self.assertEqual(expected, filters.default_imports(""))
+
     def test_format_metadata(self):
         data = dict(
             num=1,

tests/integration/test_annotations.py

@@ -0,0 +1,39 @@
+import os
+import sys
+
+import pytest
+from click.testing import CliRunner
+
+from tests import fixtures_dir
+from tests import root
+from xsdata.cli import cli
+from xsdata.formats.dataclass.context import XmlContext
+from xsdata.formats.dataclass.parsers.xml import XmlParser
+from xsdata.utils.testing import load_class
+
+os.chdir(root)
+
+
+@pytest.mark.skipif(sys.version_info < (3, 7), reason="PEP563 introduced in 3.7")
+def test_annotations():
+    filepath = fixtures_dir.joinpath("annotations")
+    schema = filepath.joinpath("model.xsd")
+    runner = CliRunner()
+    result = runner.invoke(
+        cli, [str(schema), f"--config={str(filepath.joinpath('xsdata.xml'))}"]
+    )
+
+    if result.exception:
+        raise result.exception
+
+    try:
+        Measurement = load_class(result.output, "Measurement")
+        unit = load_class(result.output, "unit")
+    except Exception:
+        pytest.fail("Could not load class with member having the same name as type")
+
+    filename = str(filepath.joinpath("sample.xml"))
+    parser = XmlParser(context=XmlContext())
+    measurement = parser.parse(filename, Measurement)
+    assert measurement.value == 2.0
+    assert measurement.unit == unit.KG

tests/models/test_config.py

@@ -10,6 +10,7 @@
 from xsdata.models.config import GeneratorAlias
 from xsdata.models.config import GeneratorAliases
 from xsdata.models.config import GeneratorConfig
+from xsdata.models.config import GeneratorOutput
 from xsdata.models.config import ObjectType
 from xsdata.models.config import OutputFormat
 
@@ -34,6 +35,7 @@ def test_create(self):
             "    <DocstringStyle>reStructuredText</DocstringStyle>\n"
             "    <RelativeImports>false</RelativeImports>\n"
             '    <CompoundFields defaultName="choice" forceDefaultName="false">false</CompoundFields>\n'
+            "    <PostponedAnnotations>false</PostponedAnnotations>\n"
             "  </Output>\n"
             "  <Conventions>\n"
             '    <ClassName case="pascalCase" safePrefix="type"/>\n'
@@ -89,6 +91,7 @@ def test_read(self):
             "    <DocstringStyle>reStructuredText</DocstringStyle>\n"
             "    <RelativeImports>false</RelativeImports>\n"
             '    <CompoundFields defaultName="choice" forceDefaultName="false">false</CompoundFields>\n'
+            "    <PostponedAnnotations>false</PostponedAnnotations>\n"
             "  </Output>\n"
             "  <Conventions>\n"
             '    <ClassName case="pascalCase" safePrefix="type"/>\n'
@@ -152,6 +155,27 @@ def test_format_kw_only_requires_310(self):
         else:
             self.assertIsNotNone(OutputFormat(kw_only=True))
 
+    def test_postponed_annotations_requires_37(self):
+        # We need to confuse pyupgrade into not discarding Python version checks,
+        # which are needed to know when the warning is triggered or not
+        # Extracting the version in a local variable before performing the check is
+        # sufficient for that purpose.
+        v = sys.version_info
+        if v < (3, 7):
+            with warnings.catch_warnings(record=True) as w:
+                self.assertFalse(
+                    GeneratorOutput(postponed_annotations=True).postponed_annotations
+                )
+                self.assertEqual(
+                    "postponed annotations requires python >= 3.7, reverting...",
+                    str(w[-1].message),
+                )
+
+        if v >= (3, 7):
+            self.assertTrue(
+                GeneratorOutput(postponed_annotations=True).postponed_annotations
+            )
+
     def test_init_config_with_aliases(self):
         config = GeneratorConfig(
             aliases=GeneratorAliases(

tests/test_cli.py

@@ -157,4 +157,4 @@ def test_resolve_source(self):
         self.assertEqual(3, len(list(resolve_source(str(def_xml_path), False))))
 
         actual = list(resolve_source(str(fixtures_dir), True))
-        self.assertEqual(32, len(actual))
+        self.assertEqual(36, len(actual))

xsdata/formats/dataclass/filters.py

@@ -50,6 +50,7 @@ class Filters:
         "docstring_style",
         "max_line_length",
         "relative_imports",
+        "postponed_annotations",
         "format",
         "import_patterns",
     )
@@ -72,6 +73,7 @@ def __init__(self, config: GeneratorConfig):
         self.docstring_style: DocstringStyle = config.output.docstring_style
         self.max_line_length: int = config.output.max_line_length
         self.relative_imports: bool = config.output.relative_imports
+        self.postponed_annotations: bool = config.output.postponed_annotations
         self.format = config.output.format
 
         # Build things
@@ -676,6 +678,10 @@ def literal_value(cls, value: Any) -> str:
     def default_imports(self, output: str) -> str:
         """Generate the default imports for the given package output."""
         result = []
+
+        if self.postponed_annotations:
+            result.append("from __future__ import annotations")
+
         for library, types in self.import_patterns.items():
             names = [
                 name

xsdata/models/config.py

@@ -226,6 +226,8 @@ class GeneratorOutput:
     :param relative_imports: Use relative imports, default: false
     :param compound_fields: Use compound fields for repeatable elements, default: false
     :param max_line_length: Adjust the maximum line length, default: 79
+    :param postponed_annotations: Enable postponed evaluation of annotations,
+        default: false, python>=3.7 Only
     """
 
     package: str = element(default="generated")
@@ -237,6 +239,18 @@ class GeneratorOutput:
     relative_imports: bool = element(default=False)
     compound_fields: CompoundFields = element(default_factory=CompoundFields)
     max_line_length: int = attribute(default=79)
+    postponed_annotations: bool = element(default=False)
+
+    def __post_init__(self):
+        self.validate()
+
+    def validate(self):
+        if self.postponed_annotations and sys.version_info < (3, 7):
+            self.postponed_annotations = False
+            warnings.warn(
+                "postponed annotations requires python >= 3.7, reverting...",
+                CodeGenerationWarning,
+            )
 
     def update(self, **kwargs: Any):
         objects.update(self, **kwargs)