(de)serialize externally tagged union directly

This example works correctly now

```
@serde
@DataClass
class Foo:
    a: int

@serde
@DataClass
class Bar:
    a: int

bar = Bar(10)
s = to_json(bar)
print(s)
print(from_json(Union[Foo, Bar], s))
```

However, This will introduce a breaking change! The default
behaviour when you pass Union directly was "Untagged", but since
v0.12.0 it is "ExternalTagging".

The following code prints `{"a": 10}` until v0.11.1, but prints
`{"Bar": {"a": 10}}` since v0.12.0
```
print(to_json(bar))
```

Author: yukinarit

docs/en/union.md

@@ -66,3 +66,84 @@ A class declaration with `AdjacentTagging` looks like below. If you serialize `F
 class Foo:
     a: Union[Bar, Baz]
 ```
+
+## (de)serializing Union types directly
+
+New in v0.12.0.
+
+Passing Union types directly in (de)serialize APIs (e.g. to_json, from_json) was partially supported prior to v0.12, but the union type was always treated as untagged. Users had no way to change the union tagging. The following example code wasn't able to correctly deserialize into `Bar` due to untagged.
+
+```python
+@serde
+@dataclass
+class Foo:
+    a: int
+
+@serde
+@dataclass
+class Bar:
+    a: int
+
+bar = Bar(10)
+s = to_json(bar)
+print(s)
+# prints {"a": 10}
+print(from_json(Union[Foo, Bar], s))
+# prints Foo(10)
+```
+
+Since v0.12.0, pyserde can handle union that's passed in (de)serialize APIs a bit nicely. The union type is treated as externally tagged as that is the default tagging in pyserde. So the above example can correctly (de)serialize as `Bar`.
+
+```python
+@serde
+@dataclass
+class Foo:
+    a: int
+
+@serde
+@dataclass
+class Bar:
+    a: int
+
+bar = Bar(10)
+s = to_json(bar)
+print(s)
+# prints {"Bar" {"a": 10}}
+print(from_json(Union[Foo, Bar], s))
+# prints Bar(10)
+```
+
+Also you can change the tagging using `serde.InternalTagging`, `serde.AdjacentTagging` and `serde.Untagged`.
+
+Now try to change the tagging for the above example. You need to pass a new argument `cls` in `to_json`. Also union class must be wrapped in either `InternalTagging`, `AdjacentTaging` or `Untagged` with required parameters.
+
+* InternalTagging
+    ```python
+    from serde import InternalTagging
+
+    s = to_json(bar, cls=InternalTagging("type", Union[Foo, Bar]))
+    print(s)
+    # prints {"type": "Bar", "a": 10}
+    print(from_json(InternalTagging("type", Union[Foo, Bar]), s))
+    # prints Bar(10)
+    ```
+* AdjacentTagging
+    ```python
+    from serde import AdjacentTagging
+
+    s = to_json(bar, cls=AdjacentTagging("type", "content", Union[Foo, Bar]))
+    print(s)
+    # prints {"type": "Bar", "content": {"a": 10}}
+    print(from_json(AdjacentTagging("type", "content", Union[Foo, Bar]), s))
+    # prints Bar(10)
+    ```
+* Untagged
+    ```python
+    from serde import Untagged
+
+    s = to_json(bar, cls=Untagged(Union[Foo, Bar]))
+    print(s)
+    # prints {"a": 10}
+    print(from_json(Untagged(Union[Foo, Bar]), s))
+    # prints Foo(10)
+    ```

examples/runner.py

@@ -40,6 +40,7 @@
 import type_decimal
 import union
 import union_tagging
+import union_directly
 import user_exception
 import variable_length_tuple
 import yamlfile
@@ -73,6 +74,7 @@ def run_all() -> None:
     run(type_decimal)
     run(type_datetime)
     run(union_tagging)
+    run(union_directly)
     run(generics)
     run(generics_nested)
     run(nested)

examples/union_directly.py

@@ -0,0 +1,45 @@
+from dataclasses import dataclass
+from typing import Union
+
+from serde import serde, Untagged, AdjacentTagging, InternalTagging
+from serde.json import from_json, to_json
+
+
+@serde
+@dataclass
+class Bar:
+    b: int
+
+
+@serde
+@dataclass(unsafe_hash=True)
+class Baz:
+    b: int
+
+
+def main() -> None:
+    baz = Baz(10)
+
+    print("# external tagging (default)")
+    a = to_json(baz, cls=Union[Bar, Baz])
+    print("IntoJSON", a)
+    print("FromJSON", from_json(Union[Bar, Baz], a))
+
+    print("# internal tagging")
+    a = to_json(baz, cls=InternalTagging("type", Union[Bar, Baz]))
+    print("IntoJSON", a)
+    print("FromJSON", from_json(InternalTagging("type", Union[Bar, Baz]), a))
+
+    print("# adjacent tagging")
+    a = to_json(baz, cls=AdjacentTagging("type", "content", Union[Bar, Baz]))
+    print("IntoJSON", a)
+    print("FromJSON", from_json(AdjacentTagging("type", "content", Union[Bar, Baz]), a))
+
+    print("# untagged")
+    a = to_json(baz, cls=Untagged(Union[Bar, Baz]))
+    print("IntoJSON", a)
+    print("FromJSON", from_json(Untagged(Union[Bar, Baz]), a))
+
+
+if __name__ == "__main__":
+    main()

serde/compat.py

@@ -114,6 +114,18 @@ def get_np_args(tp: Any) -> Tuple[Any, ...]:
 """ List of datetime types """
 
 
+@dataclasses.dataclass
+class _WithTagging(Generic[T]):
+    """
+    Intermediate data structure for (de)serializaing Union without dataclass.
+    """
+
+    inner: T
+    """ Union type .e.g Union[Foo,Bar] passed in from_obj. """
+    tagging: Any
+    """ Union Tagging """
+
+
 class SerdeError(Exception):
     """
     Serde error class.
@@ -475,6 +487,13 @@ def is_union(typ: Any) -> bool:
     True
     """
 
+    try:
+        # When `_WithTagging` is received, it will check inner type.
+        if isinstance(typ, _WithTagging):
+            return is_union(typ.inner)
+    except Exception:
+        pass
+
     # Python 3.10 Union operator e.g. str | int
     if sys.version_info[:2] >= (3, 10):
         try: