fix: typehints

Signed-off-by: Jan Kowalleck <[email protected]>

Author: jkowalleck

serializable/__init__.py

@@ -16,28 +16,43 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 # Copyright (c) Paul Horton. All Rights Reserved.
+
 import enum
 import inspect
 import json
 import logging
 import os
 import re
-import typing  # noqa: F401
 import warnings
 from copy import copy
 from decimal import Decimal
 from io import StringIO, TextIOWrapper
 from json import JSONEncoder
 from sys import version_info
-from typing import Any, Callable, Dict, Iterable, List, Optional, Set, Tuple, Type, TypeVar, Union, cast
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Iterable,
+    List,
+    Literal,
+    Optional,
+    Set,
+    Tuple,
+    Type,
+    TypeVar,
+    Union,
+    cast,
+    overload,
+)
 from xml.etree.ElementTree import Element, SubElement
 
 from defusedxml import ElementTree as SafeElementTree  # type: ignore
 
 if version_info >= (3, 8):
     from typing import Protocol
 else:
-    from typing_extensions import Protocol  # type: ignore
+    from typing_extensions import Protocol  # type: ignore[assignment]
 
 from .formatters import BaseNameFormatter, CurrentFormatter
 from .helpers import BaseHelper
@@ -61,6 +76,37 @@ class _Klass(Protocol):
 ViewType = _Klass
 
 
+class XmlSerializable(Protocol):
+
+    @overload
+    def as_xml(self: _T, view_: Optional[Type[_T]], as_string: Literal[True],
+               element_name: Optional[str], xmlns: Optional[str]) -> str:
+        ...
+
+    @overload
+    def as_xml(self: _T, view_: Optional[Type[_T]], as_string: Literal[False],
+               element_name: Optional[str], xmlns: Optional[str]) -> Element:
+        ...
+
+    def as_xml(self: _T, view_: Optional[Type[_T]] = None, as_string: Literal[True, False] = True,
+               element_name: Optional[str] = None, xmlns: Optional[str] = None) -> Union[Element, str]:
+        return _as_xml(self, view_, as_string, element_name, xmlns)
+
+    @classmethod
+    def from_xml(cls: Type[_T], data: Union[TextIOWrapper, Element],
+                 default_namespace: Optional[str] = None) -> Optional[_T]:
+        return _from_xml(cls, data, default_namespace)
+
+
+class JsonSerializable(Protocol):
+    def as_json(self: _T, view_: Optional[Type[Any]] = None) -> str:
+        return _as_json(self, view_)
+
+    @classmethod
+    def from_json(cls: Type[_T], data: Dict[str, Any]) -> Optional[_T]:
+        return _from_json(cls, data)
+
+
 @enum.unique
 class SerializationType(str, enum.Enum):
     """
@@ -230,7 +276,7 @@ def _as_json(self: _T, view_: Optional[Type[Any]] = None) -> str:
     return json.dumps(self, cls=_SerializableJsonEncoder, view_=view_)
 
 
-def _from_json(cls: Type[_T], data: Dict[str, Any]) -> object:
+def _from_json(cls: Type[_T], data: Dict[str, Any]) -> Optional[_T]:
     """
     Internal function that is injected into Classes that are annotated for serialization and deserialization by
     ``serializable``.
@@ -318,7 +364,20 @@ def _from_json(cls: Type[_T], data: Dict[str, Any]) -> object:
     return cls(**_data)
 
 
-def _as_xml(self: _T, view_: Optional[Type[_T]] = None, as_string: bool = True, element_name: Optional[str] = None,
+@overload
+def _as_xml(self: _T, view_: Optional[Type[_T]], as_string: Literal[True],
+            element_name: Optional[str], xmlns: Optional[str]) -> str:
+    ...
+
+
+@overload
+def _as_xml(self: _T, view_: Optional[Type[_T]], as_string: Literal[False],
+            element_name: Optional[str], xmlns: Optional[str]) -> Element:
+    ...
+
+
+def _as_xml(self: _T, view_: Optional[Type[_T]] = None,
+            as_string: Literal[True, False] = True, element_name: Optional[str] = None,
             xmlns: Optional[str] = None) -> Union[Element, str]:
     logging.debug(f'Dumping {self} to XML with view {view_}...')
 
@@ -443,7 +502,7 @@ def _as_xml(self: _T, view_: Optional[Type[_T]] = None, as_string: bool = True,
 
 
 def _from_xml(cls: Type[_T], data: Union[TextIOWrapper, Element],
-              default_namespace: Optional[str] = None) -> object:
+              default_namespace: Optional[str] = None) -> Optional[_T]:
     logging.debug(f'Rendering XML from {type(data)} to {cls}...')
     klass = ObjectMetadataLibrary.klass_mappings.get(f'{cls.__module__}.{cls.__qualname__}', None)
     if klass is None:
@@ -638,7 +697,7 @@ def __init__(self, *, klass: Any, custom_name: Optional[str] = None,
             if serialization_types is None:
                 serialization_types = _DEFAULT_SERIALIZATION_TYPES
             self._serialization_types = serialization_types
-            self._ignore_during_deserialization = set(ignore_during_deserialization or {})
+            self._ignore_during_deserialization = set(ignore_during_deserialization or [])
 
         @property
         def name(self) -> str:
@@ -957,9 +1016,10 @@ def register_enum(cls, klass: _T) -> _T:
         return klass
 
     @classmethod
-    def register_klass(cls, klass: _T, custom_name: Optional[str],
+    def register_klass(cls, klass: Type[_T], custom_name: Optional[str],
                        serialization_types: Iterable[SerializationType],
-                       ignore_during_deserialization: Optional[Iterable[str]] = None) -> _T:
+                       ignore_during_deserialization: Optional[Iterable[str]] = None
+                       ) -> Type[Union[_T, JsonSerializable, XmlSerializable]]:
         if cls.is_klass_serializable(klass=klass):
             return klass
 
@@ -1001,12 +1061,12 @@ def register_klass(cls, klass: _T, custom_name: Optional[str],
             })
 
         if SerializationType.JSON in serialization_types:
-            klass.as_json = _as_json  # type: ignore
-            klass.from_json = classmethod(_from_json)  # type: ignore
+            klass.as_json = _as_json  # type:ignore[attr-defined]
+            klass.from_json = classmethod(_from_json)  # type:ignore[attr-defined]
 
         if SerializationType.XML in serialization_types:
-            klass.as_xml = _as_xml  # type: ignore
-            klass.from_xml = classmethod(_from_xml)  # type: ignore
+            klass.as_xml = _as_xml  # type:ignore[attr-defined]
+            klass.from_xml = classmethod(_from_xml)  # type:ignore[attr-defined]
 
         # Handle any deferred Properties depending on this class
         if klass.__qualname__ in ObjectMetadataLibrary._deferred_property_type_parsing:
@@ -1091,6 +1151,22 @@ def decorate(kls: Type[_T]) -> Type[_T]:
     return decorate(cls)
 
 
+@overload
+def serializable_class(cls: Literal[None], *, name: Optional[str] = None,
+                       serialization_types: Optional[Iterable[SerializationType]] = None,
+                       ignore_during_deserialization: Optional[Iterable[str]] = None
+                       ) -> Callable[[Type[_T]], Type[Union[_T, JsonSerializable, XmlSerializable]]]:
+    ...
+
+
+@overload
+def serializable_class(cls: Type[_T], *, name: Optional[str] = None,
+                       serialization_types: Optional[Iterable[SerializationType]] = None,
+                       ignore_during_deserialization: Optional[Iterable[str]] = None
+                       ) -> Type[Union[_T, JsonSerializable, XmlSerializable]]:
+    ...
+
+
 def serializable_class(cls: Optional[Any] = None, *, name: Optional[str] = None,
                        serialization_types: Optional[Iterable[SerializationType]] = None,
                        ignore_during_deserialization: Optional[Iterable[str]] = None
@@ -1107,9 +1183,9 @@ def serializable_class(cls: Optional[Any] = None, *, name: Optional[str] = None,
     if serialization_types is None:
         serialization_types = _DEFAULT_SERIALIZATION_TYPES
 
-    def decorate(kls: Type[_T]) -> Type[_T]:
+    def decorate(kls: Type[_T]) -> Type[Union[_T, JsonSerializable, XmlSerializable]]:
         ObjectMetadataLibrary.register_klass(
-            klass=kls, custom_name=name, serialization_types=serialization_types or {},
+            klass=kls, custom_name=name, serialization_types=serialization_types or [],
             ignore_during_deserialization=ignore_during_deserialization
         )
         return kls