Support pipe syntax to declare optional fields

Fixes #1928

Author: miguelgrinberg

docs/persistence.rst

@@ -147,16 +147,18 @@ following table:
      - ``Date(format="yyyy-MM-dd", required=True)``
 
 To type a field as optional, the standard ``Optional`` modifier from the Python
-``typing`` package can be used. The ``List`` modifier can be added to a field
-to convert it to an array, similar to using the ``multi=True`` argument on the
-field object.
+``typing`` package can be used. When using Python 3.10 or newer, "pipe" syntax
+can also be used, by adding ``| None`` to a type. The ``List`` modifier can be
+added to a field to convert it to an array, similar to using the ``multi=True``
+argument on the field object.
 
 .. code:: python
 
     from typing import Optional, List
 
     class MyDoc(Document):
         pub_date: Optional[datetime]  # same as pub_date = Date()
+        middle_name: str | None       # same as middle_name = Text()
         authors: List[str]            # same as authors = Text(multi=True, required=True)
         comments: Optional[List[str]] # same as comments = Text(multi=True)
 

elasticsearch_dsl/document_base.py

@@ -28,9 +28,15 @@
     Tuple,
     TypeVar,
     Union,
+    get_args,
     overload,
 )
 
+try:
+    from types import UnionType
+except ImportError:
+    UnionType = None
+
 from typing_extensions import dataclass_transform
 
 from .exceptions import ValidationException
@@ -192,6 +198,14 @@ def __init__(self, name: str, bases: Tuple[type, ...], attrs: Dict[str, Any]):
                         type_ = type_.__args__[0]
                     else:
                         break
+                if type(type_) is UnionType:
+                    # a union given with the pipe syntax
+                    args = get_args(type_)
+                    if len(args) == 2 and args[1] is type(None):
+                        required = False
+                        type_ = type_.__args__[0]
+                    else:
+                        raise TypeError("Unsupported union")
                 field = None
                 field_args: List[Any] = []
                 field_kwargs: Dict[str, Any] = {}

tests/_async/test_document.py

@@ -24,6 +24,7 @@
 import codecs
 import ipaddress
 import pickle
+import sys
 from datetime import datetime
 from hashlib import md5
 from typing import Any, Dict, List, Optional
@@ -783,6 +784,36 @@ class TypedDoc(AsyncDocument):
     }
 
 
+@pytest.mark.skipif(sys.version_info < (3, 10), reason="requires Python 3.10")
+def test_doc_with_pipe_type_hints() -> None:
+    with pytest.raises(TypeError):
+
+        class BadlyTypedDoc(AsyncDocument):
+            s: str
+            f: str | int | None
+
+    class TypedDoc(AsyncDocument):
+        s: str
+        f1: str | None
+        f2: M[int | None]
+        f3: M[datetime | None]
+
+    props = TypedDoc._doc_type.mapping.to_dict()["properties"]
+    assert props == {
+        "s": {"type": "text"},
+        "f1": {"type": "text"},
+        "f2": {"type": "integer"},
+        "f3": {"type": "date"},
+    }
+
+    doc = TypedDoc()
+    with raises(ValidationException) as exc_info:
+        doc.full_clean()
+    assert set(exc_info.value.args[0].keys()) == {"s"}
+    doc.s = "s"
+    doc.full_clean()
+
+
 def test_instrumented_field() -> None:
     class Child(InnerDoc):
         st: M[str]

tests/_sync/test_document.py

@@ -24,6 +24,7 @@
 import codecs
 import ipaddress
 import pickle
+import sys
 from datetime import datetime
 from hashlib import md5
 from typing import Any, Dict, List, Optional
@@ -783,6 +784,36 @@ class TypedDoc(Document):
     }
 
 
+@pytest.mark.skipif(sys.version_info < (3, 10), reason="requires Python 3.10")
+def test_doc_with_pipe_type_hints() -> None:
+    with pytest.raises(TypeError):
+
+        class BadlyTypedDoc(Document):
+            s: str
+            f: str | int | None
+
+    class TypedDoc(Document):
+        s: str
+        f1: str | None
+        f2: M[int | None]
+        f3: M[datetime | None]
+
+    props = TypedDoc._doc_type.mapping.to_dict()["properties"]
+    assert props == {
+        "s": {"type": "text"},
+        "f1": {"type": "text"},
+        "f2": {"type": "integer"},
+        "f3": {"type": "date"},
+    }
+
+    doc = TypedDoc()
+    with raises(ValidationException) as exc_info:
+        doc.full_clean()
+    assert set(exc_info.value.args[0].keys()) == {"s"}
+    doc.s = "s"
+    doc.full_clean()
+
+
 def test_instrumented_field() -> None:
     class Child(InnerDoc):
         st: M[str]