Internal refactoring to support protocols.

Author: domdfcoding

.travis.yml

@@ -21,7 +21,7 @@ install:
   - pip install coveralls coverage_pyver_pragma
 
 script:
-  - tox
+  - tox -vv
 after_success:
   - coveralls
 
@@ -46,7 +46,6 @@ jobs:
     - python: 'pypy3'
       arch: arm64
 
-
   include:
     - stage: test
       dist: bionic

doc-source/index.rst

@@ -8,7 +8,8 @@ sdjson
 
 .. end short_desc
 
-Based on https://treyhunner.com/2013/09/singledispatch-json-serializer/ and Python's ``json`` module.
+Based on https://treyhunner.com/2013/09/singledispatch-json-serializer/
+and Python's :mod:`json` module.
 
 .. start shields
 

sdjson/__init__.py

@@ -63,7 +63,7 @@
 the given class.
 
 
-TODO: This module does not currently support custom decoders, but might in the future.
+.. TODO:: This module does not currently support custom decoders, but might in the future.
 """
 #
 #  Copyright © 2020 Dominic Davis-Foster <dominic@davis-foster.co.uk>
@@ -75,7 +75,7 @@
 #
 #  This program is distributed in the hope that it will be useful,
 #  but WITHOUT ANY WARRANTY; without even the implied warranty of
-#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 #  GNU Lesser General Public License for more details.
 #
 #  You should have received a copy of the GNU Lesser General Public License
@@ -126,6 +126,7 @@
 __license__ = "LGPLv3+"
 __version__ = "0.2.6"
 __email__ = "dominic@davis-foster.co.uk"
+
 # this package
 from sdjson.core import (
 		JSONDecodeError,

sdjson/core.py

@@ -101,12 +101,20 @@
 
 # stdlib
 import json
+import sys
 from functools import singledispatch
-from typing import IO, Any, Callable, Dict, Iterator, Optional, Tuple, Type, Union
+from typing import IO, Any, Callable, Iterator, Optional, Tuple, Type, TypeVar, Union
 
 # 3rd party
 from domdf_python_tools.doctools import append_docstring_from, is_documented_by, make_sphinx_links
 
+if sys.version_info < (3, 8):  # pragma: no cover (>=py38)
+	# 3rd party
+	from typing_extensions import _ProtocolMeta  # type: ignore
+else:  # pragma: no cover (<py38)
+	# stdlib
+	from typing import _ProtocolMeta  # type: ignore
+
 __all__ = [
 		"load",
 		"loads",
@@ -134,13 +142,13 @@ def allow_unregister(func) -> Callable:
 	"""
 	Decorator to allow removal of custom encoders with ``<sdjson.encoders.unregister(<type>)``,
 	where <type> is the custom type you wish to remove the encoder for.
-
-	From https://stackoverflow.com/a/25951784/3092681
-	Copyright © 2014 Martijn Pieters
-	https://stackoverflow.com/users/100297/martijn-pieters
-	Licensed under CC BY-SA 4.0
 	"""
 
+	# From https://stackoverflow.com/a/25951784/3092681
+	# Copyright © 2014 Martijn Pieters
+	# https://stackoverflow.com/users/100297/martijn-pieters
+	# Licensed under CC BY-SA 4.0
+
 	# build a dictionary mapping names to closure cells
 	closure = dict(zip(func.register.__code__.co_freevars, func.register.__closure__))
 	registry = closure["registry"].cell_contents
@@ -171,17 +179,91 @@ def wrapper(target):
 	return wrapper
 
 
-@allow_unregister
-@singledispatch
 class _Encoders:
-	register: Callable
-	unregister: Callable
-	registry: Dict  # TODO
 
+	def __init__(self):
+		self._registry = allow_unregister(singledispatch(lambda x: None))
+		self._protocol_registry = {}
+		self.registry = self._registry.registry
+
+	def register(self, cls: Type, func: Optional[Callable] = None) -> Callable:
+		"""
+		Registers a new handler for the given type.
+
+		Can be used as a decorator or a regular function:
+
+		.. code-block:: python
+
+			@register_encoder(bytes)
+			def bytes_encoder(obj):
+				return obj.decode("UTF-8")
+
+			def int_encoder(obj):
+				return int(obj)
+
+			register_encoder(int, int_encoder)
+
+
+		:param cls:
+		:param func:
+		"""
+
+		if func is None:
+			return lambda f: self.register(cls, f)
+
+		if isinstance(cls, _ProtocolMeta):
+			if getattr(cls, "_is_runtime_protocol", False):
+				self._protocol_registry[cls] = func
+			else:
+				raise TypeError("Protocols must be @runtime_checkable")
+			return func
+		else:
+			return self._registry.register(cls, func)
 
-encoders = _Encoders
-register_encoder = _Encoders.register  # type: ignore
-unregister_encoder = _Encoders.unregister  # type: ignore
+	def dispatch(self, cls: object) -> Optional[Callable]:
+		"""
+		Returns the best available implementation for the given object.
+
+		:param cls:
+		"""
+
+		if object in self.registry:
+			self.unregister(object)
+
+		handler = self._registry.dispatch(type(cls))
+		if handler is not None:
+			return handler
+		else:
+			for protocol, handler in self._protocol_registry.items():
+				if isinstance(cls, protocol):
+					return handler
+
+		return None
+
+	def unregister(self, cls: Type):
+		"""
+		Unregister the handler for the given type.
+
+		.. code-block:: python
+
+			unregister_encoder(int)
+
+		:param cls:
+
+		:raise KeyError: if no handler is found.
+		"""
+
+		if cls in self.registry:
+			self._registry.unregister(cls)
+		elif cls in self._protocol_registry:
+			del self._protocol_registry[cls]
+		else:
+			raise KeyError
+
+
+encoders = _Encoders()
+register_encoder = encoders.register  # type: ignore
+unregister_encoder = encoders.unregister  # type: ignore
 
 
 @sphinxify_json_docstring()
@@ -314,9 +396,10 @@ def raw_decode(self, *args, **kwargs):
 class _CustomEncoder(JSONEncoder):
 
 	def default(self, obj):
-		for type_, handler in encoders.registry.items():
-			if isinstance(obj, type_) and type_ is not object:
-				return handler(obj)
+		handler = encoders.dispatch(obj)
+		if handler is not None:
+			return handler(obj)
+
 		return super().default(obj)
 
 

sdjson/core.pyi

@@ -38,7 +38,10 @@
 # stdlib
 import json
 from functools import singledispatch
-from typing import IO, Any, Callable, Dict, Iterator, List, Optional, Protocol, Tuple, Type, TypeVar, Union
+from typing import (
+	IO, Any, Callable, Dict, Iterator, List, Mapping, Optional, overload, Protocol, Tuple, Type, TypeVar,
+	Union,
+	)
 
 # 3rd party
 from domdf_python_tools.doctools import append_docstring_from, is_documented_by
@@ -52,31 +55,63 @@ __email__: str
 
 _T_co = TypeVar("_T_co", covariant=True)
 _LoadsString = Union[str, bytes]
+_T = TypeVar("_T")
+
+
+class SingleDispatch(Protocol):
+	"""
+	:class:`~typing.Protocol` representing a function decorated with :func:`functools.singledispatch`.
+	"""
+
+	@overload
+	def register(self, cls: Any) -> Callable[[Callable[..., _T]], Callable[..., _T]]: ...
+
+	@overload
+	def register(self, cls: Any, func: Callable[..., _T]) -> Callable[..., _T]: ...
+
+	def dispatch(self, cls: Any) -> Callable[..., _T]: ...
+
+	def unregister(self, cls: Type) -> Any: ...
+
+	registry: Mapping[Any, Callable[..., _T]]
+
+	def _clear_cache(self) -> None: ...
+
+	def __call__(self, *args: Any, **kwargs: Any) -> _T: ...
+
 
 
 class SupportsRead(Protocol[_T_co]):
 	def read(self, __length: int = ...) -> _T_co: ...
 
 
-def allow_unregister(func) -> Callable: ...
+def allow_unregister(func: SingleDispatch) -> SingleDispatch: ...
 
 
 def sphinxify_json_docstring() -> Callable: ...
 
 
-@allow_unregister
-@singledispatch
 class _Encoders:
-	register: Callable
-	unregister: Callable
+	_registry: SingleDispatch
+	_protocol_registry: Mapping[Any, Callable[..., _T]]
+	registry: Mapping[Any, Callable[..., _T]]
 
+	@overload
+	def register(self, cls: Any) -> Callable[[Callable[..., _T]], Callable[..., _T]]: ...
 
-encoders = _Encoders
-register_encoder = _Encoders.register  # type: ignore
-unregister_encoder = _Encoders.unregister  # type: ignore
+	@overload
+	def register(self, cls: Any, func: Callable[..., _T]) -> Callable[..., _T]: ...
 
+	def dispatch(self, cls: Any) -> Callable[..., _T]: ...
 
+	def unregister(self, cls: Type) -> Any: ...
+
+
+encoders = _Encoders()
+register_encoder = encoders.register  # type: ignore
+unregister_encoder = encoders.unregister  # type: ignore
 def dump(
+
 		obj: Any,
 		 fp: IO[str],
 		 *,