PYTHON-1769 Re-define TypeCodecBase as an AbstractBaseClass

Author: prashantmital

bson/codec_options.py

@@ -16,9 +16,10 @@
 
 import datetime
 
+from abc import abstractmethod
 from collections import namedtuple
 
-from bson.py3compat import abc, string_type
+from bson.py3compat import ABC, abc, abstractproperty, string_type
 from bson.binary import (ALL_UUID_REPRESENTATIONS,
  PYTHON_LEGACY,
  UUID_REPRESENTATION_NAMES)
@@ -33,33 +34,53 @@ def _raw_document_class(document_class):
  return marker == _RAW_BSON_DOCUMENT_MARKER
 
 
-class TypeCodecBase(object):
+class TypeEncoder(ABC):
  """Base class for defining type codec classes which describe how a
- custom type can be transformed to/from one of the types BSON already
- understands, and can encode/decode.
+ custom type can be transformed to one of the types BSON understands.
 
- Codec classes must implement the ``python_type`` property, and the
- ``transform_python`` method to support encoding, or the ``bson_type``
- property and ``transform_bson`` method to support decoding. Note that a
- single codec class may support both encoding and decoding.
+ Codec classes must implement the ``python_type`` attribute, and the
+ ``transform_python`` method to support encoding.
  """
- @property
+ @abstractproperty
  def python_type(self):
  """The Python type to be converted into something serializable."""
- raise NotImplementedError
+ pass
+
+ @abstractmethod
+ def transform_python(self, value):
+ """Convert the given Python object into something serializable."""
+ pass
 
- @property
+
+class TypeDecoder(ABC):
+ """Base class for defining type codec classes which describe how a
+ BSON type can be transformed to a custom type.
+
+ Codec classes must implement the ``bson_type`` attribute, and the
+ ``transform_bson`` method to support decoding.
+ """
+ @abstractproperty
  def bson_type(self):
  """The BSON type to be converted into our own type."""
- raise NotImplementedError
+ pass
 
+ @abstractmethod
  def transform_bson(self, value):
  """Convert the given BSON value into our own type."""
- raise NotImplementedError
+ pass
 
- def transform_python(self, value):
- """Convert the given Python object into something serializable."""
- raise NotImplementedError
+
+class TypeCodec(TypeEncoder, TypeDecoder):
+ """Base class for defining type codec classes which describe how a
+ custom type can be transformed to/from one of the types BSON already
+ understands, and can encode/decode.
+
+ Codec classes must implement the ``python_type`` attribute, and the
+ ``transform_python`` method to support encoding, as well as the
+ ``bson_type`` attribute, and the ``transform_bson`` method to support
+ decoding.
+ """
+ pass
 
 
 class TypeRegistry(object):
@@ -95,23 +116,18 @@ def __init__(self, type_codecs=None, fallback_encoder=None):
  fallback_encoder))
 
  for codec in self.__type_codecs:
- if not isinstance(codec, TypeCodecBase):
+ is_valid_codec = False
+ if isinstance(codec, TypeEncoder):
+ is_valid_codec = True
+ self._encoder_map[codec.python_type] = codec.transform_python
+ if isinstance(codec, TypeDecoder):
+ is_valid_codec = True
+ self._decoder_map[codec.bson_type] = codec.transform_bson
+ if not is_valid_codec:
  raise TypeError(
- "Expected an instance of %s, got %r instead" % (
- TypeCodecBase.__name__, codec))
- try:
- python_type = codec.python_type
- except NotImplementedError:
- pass
- else:
- self._encoder_map[python_type] = codec.transform_python
-
- try:
- bson_type = codec.bson_type
- except NotImplementedError:
- pass
- else:
- self._decoder_map[bson_type] = codec.transform_bson
+ "Expected an instance of %s, %s, or %s, got %r instead" % (
+ TypeEncoder.__name__, TypeDecoder.__name__,
+ TypeCodec.__name__, codec))
 
  def __repr__(self):
  return ('%s(type_codecs=%r, fallback_encoder=%r)' % (

bson/py3compat.py

@@ -22,8 +22,12 @@
  import codecs
  import collections.abc as abc
  import _thread as thread
+ from abc import ABC, abstractmethod
  from io import BytesIO as StringIO
 
+ def abstractproperty(func):
+ return property(abstractmethod(func))
+
  MAXSIZE = sys.maxsize
 
  imap = map
@@ -60,13 +64,16 @@ def _unicode(s):
 else:
  import collections as abc
  import thread
+ from abc import ABCMeta, abstractproperty
 
  from itertools import imap
  try:
  from cStringIO import StringIO
  except ImportError:
  from StringIO import StringIO
 
+ ABC = ABCMeta('ABC', (object,), {})
+
  MAXSIZE = sys.maxint
 
  def b(s):

doc/examples/custom_type.rst

@@ -2,7 +2,7 @@ Custom Type Example
 ===================
 
 This is an example of using a custom type with PyMongo. The example here shows
-how to subclass :class:`~bson.codec_options.TypeCodecBase` to write a type
+how to subclass :class:`~bson.codec_options.TypeCodec` to write a type
 codec, which is used to populate a :class:`~bson.codec_options.TypeRegistry`.
 The type registry can then be used to create a custom-type-aware
 :class:`~pymongo.collection.Collection`. Read and write operations
@@ -51,39 +51,39 @@ The Type Codec
 
 In order to encode custom types, we must first define a **type codec** for our
 type. A type codec describes how an instance of a custom type can be
-*transformed* to/from one of the types :mod:`~bson` already understands, and
-can encode/decode. Type codecs must inherit from
-:class:`~bson.codec_options.TypeCodecBase`. In order to encode a custom type,
-a codec must implement the ``python_type`` property and the
-``transform_python`` method. Similarly, in order to decode a custom type,
-a codec must implement the ``bson_type`` property and the ``transform_bson``
-method. Note that a type codec need not support both encoding and decoding.
+*transformed* to and/or from one of the types :mod:`~bson` already understands.
+Depending on the desired functionality, users must choose from the following
+base classes when defining type codecs:
+
+* :class:`~bson.codec_options.TypeEncoder`: subclass this to define a codec that
+ encodes a custom Python type to a known BSON type. Users must implement the
+ ``python_type`` property/attribute and the ``transform_python`` method.
+* :class:`~bson.codec_options.TypeDecoder`: subclass this to define a codec that
+ decodes a specified BSON type into a custom Python type. Users must implement
+ the ``bson_type`` property/attribute and the ``transform_bson`` method.
+* :class:`~bson.codec_options.TypeCodec`: subclass this to define a codec that
+ can both encode from and decode to a custom type. Users must implement the
+ ``python_type`` and ``bson_type`` properties/attributes, as well as the
+ ``transform_python`` and ``transform_bson`` methods.
 
 
 The type codec for our custom type simply needs to define how a
 :py:class:`~decimal.Decimal` instance can be converted into a
-:class:`~bson.decimal128.Decimal128` instance and vice-versa:
+:class:`~bson.decimal128.Decimal128` instance and vice-versa. Since we are
+interested in both encoding and decoding our custom type, we use the
+``TypeCodec`` base class to define our codec:
 
 .. doctest::
 
  >>> from bson.decimal128 import Decimal128
- >>> from bson.codec_options import TypeCodecBase
- >>> class DecimalCodec(TypeCodecBase):
- ... @property
- ... def python_type(self):
- ... """The Python type acted upon by this type codec."""
- ... return Decimal
- ...
+ >>> from bson.codec_options import TypeCodec
+ >>> class DecimalCodec(TypeCodec):
+ ... python_type = Decimal # the Python type acted upon by this type codec
+ ... bson_type = Decimal128 # the BSON type acted upon by this type codec
  ... def transform_python(self, value):
  ... """Function that transforms a custom type value into a type
  ... that BSON can encode."""
  ... return Decimal128(value)
- ...
- ... @property
- ... def bson_type(self):
- ... """The BSON type acted upon by this type codec."""
- ... return Decimal128
- ...
  ... def transform_bson(self, value):
  ... """Function that transforms a vanilla BSON type value into our
  ... custom type."""

test/test_bson.py

@@ -34,14 +34,13 @@
  Regex)
 from bson.binary import Binary, UUIDLegacy
 from bson.code import Code
-from bson.codec_options import CodecOptions, TypeCodecBase, TypeRegistry
+from bson.codec_options import CodecOptions
 from bson.int64 import Int64
 from bson.objectid import ObjectId
 from bson.dbref import DBRef
 from bson.py3compat import abc, iteritems, PY3, StringIO, text_type
 from bson.son import SON
 from bson.timestamp import Timestamp
-from bson.tz_util import FixedOffset
 from bson.errors import (InvalidBSON,
  InvalidDocument,
  InvalidStringData)
@@ -906,121 +905,6 @@ def test_bad_id_keys(self):
  BSON.encode({"_id": {'$oid': "52d0b971b3ba219fdeb4170e"}})
 
 
-class TestTypeRegistry(unittest.TestCase):
- @classmethod
- def setUpClass(cls):
- class MyIntType(object):
- def __init__(self, x):
- assert isinstance(x, int)
- self.x = x
-
- class MyStrType(object):
- def __init__(self, x):
- assert isinstance(x, str)
- self.x = x
-
- class MyIntCodec(TypeCodecBase):
- @property
- def python_type(self):
- return MyIntType
-
- @property
- def bson_type(self):
- return int
-
- def transform_python(self, value):
- return value.x
-
- def transform_bson(self, value):
- return MyIntType(value)
-
- class MyStrCodec(TypeCodecBase):
- @property
- def python_type(self):
- return MyStrType
-
- @property
- def bson_type(self):
- return str
-
- def transform_python(self, value):
- return value.x
-
- def transform_bson(self, value):
- return MyStrType(value)
-
- def fallback_encoder(value):
- return value
-
- cls.types = (MyIntType, MyStrType)
- cls.codecs = (MyIntCodec, MyStrCodec)
- cls.fallback_encoder = fallback_encoder
-
- def test_simple(self):
- codec_instances = [codec() for codec in self.codecs]
- def assert_proper_initialization(type_registry, codec_instances):
- self.assertEqual(type_registry._encoder_map, {
- self.types[0]: codec_instances[0].transform_python,
- self.types[1]: codec_instances[1].transform_python})
- self.assertEqual(type_registry._decoder_map, {
- int: codec_instances[0].transform_bson,
- str: codec_instances[1].transform_bson})
- self.assertEqual(
- type_registry._fallback_encoder, self.fallback_encoder)
-
- type_registry = TypeRegistry(codec_instances, self.fallback_encoder)
- assert_proper_initialization(type_registry, codec_instances)
-
- type_registry = TypeRegistry(
- fallback_encoder=self.fallback_encoder, type_codecs=codec_instances)
- assert_proper_initialization(type_registry, codec_instances)
-
- # Ensure codec list held by the type registry doesn't change if we
- # mutate the initial list.
- codec_instances_copy = list(codec_instances)
- codec_instances.pop(0)
- self.assertListEqual(
- type_registry._TypeRegistry__type_codecs, codec_instances_copy)
-
- def test_initialize_fail(self):
- err_msg = "Expected an instance of TypeCodecBase, got .* instead"
- with self.assertRaisesRegex(TypeError, err_msg):
- TypeRegistry(self.codecs)
-
- with self.assertRaisesRegex(TypeError, err_msg):
- TypeRegistry([type('AnyType', (object,), {})()])
-
- err_msg = "fallback_encoder %r is not a callable" % (True,)
- with self.assertRaisesRegex(TypeError, err_msg):
- TypeRegistry([], True)
-
- err_msg = "fallback_encoder %r is not a callable" % ('hello',)
- with self.assertRaisesRegex(TypeError, err_msg):
- TypeRegistry(fallback_encoder='hello')
-
- def test_not_implemented(self):
- type_registry = TypeRegistry([type("codec1", (TypeCodecBase, ), {})(),
- type("codec2", (TypeCodecBase, ), {})()])
- self.assertEqual(type_registry._encoder_map, {})
- self.assertEqual(type_registry._decoder_map, {})
-
- def test_type_registry_repr(self):
- codec_instances = [codec() for codec in self.codecs]
- type_registry = TypeRegistry(codec_instances)
- r = ("TypeRegistry(type_codecs=%r, fallback_encoder=%r)" % (
- codec_instances, None))
- self.assertEqual(r, repr(type_registry))
-
- def test_type_registry_eq(self):
- codec_instances = [codec() for codec in self.codecs]
- self.assertEqual(
- TypeRegistry(codec_instances), TypeRegistry(codec_instances))
-
- codec_instances_2 = [codec() for codec in self.codecs]
- self.assertNotEqual(
- TypeRegistry(codec_instances), TypeRegistry(codec_instances_2))
-
-
 class TestCodecOptions(unittest.TestCase):
  def test_document_class(self):
  self.assertRaises(TypeError, CodecOptions, document_class=object)