カスタム タイプ

Overview

このガイドでは、PyMongo を使用してカスタム型をエンコードおよびデコードする方法について説明します。

カスタム型のエンコード

ドライバーが理解しないデータ型を保存する場合は、カスタム型を定義する必要がある場合があります。 たとえば、BSON ライブラリの Decimal128型は Python の組み込みDecimal型とは異なります。 PyMongo でDecimalのインスタンスを保存しようとすると、次のコード例に示すように、 InvalidDocumentの例外が発生します。

from decimal import Decimal
num = Decimal("45.321")
db["coll"].insert_one({"num": num})

Traceback (most recent call last):
...
bson.errors.InvalidDocument: cannot encode object: Decimal('45.321'), of
type: <class 'decimal.Decimal'>

次のセクションでは、このDecimal型のカスタムタイプを定義する方法を示します。

from bson.decimal128 import Decimal128
from bson.codec_options import TypeCodec
class DecimalCodec(TypeCodec):
    python_type = Decimal
    bson_type = Decimal128
    def transform_python(self, value):
        return Decimal128(value)
    def transform_bson(self, value):
        return value.to_decimal()

from bson.codec_options import TypeRegistry
decimal_codec = DecimalCodec()
type_registry = TypeRegistry([decimal_codec])

from bson.codec_options import CodecOptions
codec_options = CodecOptions(type_registry=type_registry)
collection = db.get_collection("test", codec_options=codec_options)

import pprint
collection.insert_one({"num": Decimal("45.321")})
my_doc = collection.find_one()
pprint.pprint(my_doc)

{'_id': ObjectId('...'), 'num': Decimal('45.321')}

import pprint
new_collection = db.get_collection("test")
pprint.pprint(new_collection.find_one())

{'_id': ObjectId('...'), 'num': Decimal128('45.321')}

サブタイプのエンコード

また、カスタム型から継承する 1 つ以上の 型 をエンコードする必要がある場合もあります。 値を整数として返すメソッドを含むDecimalクラスの次のサブタイプについて考えてみましょう。

class DecimalInt(Decimal):
    def get_int(self):
        return int(self)

最初にタイプ コーデックを登録せずにDecimalIntクラスのインスタンスを保存しようとすると、PyMongo はエラーを発生させます。

collection.insert_one({"num": DecimalInt("45.321")})

Traceback (most recent call last):
...
bson.errors.InvalidDocument: cannot encode object: Decimal('45.321'),
of type: <class 'decimal.Decimal'>

DecimalIntクラスのインスタンスをエンコードするには、クラスの型コーデックを定義する必要があります。 このタイプのコーデックは、次の例に示すように、親クラスのコーデックDecimalCodecから継承する必要があります。

class DecimalIntCodec(DecimalCodec):
    @property
    def python_type(self):
        # The Python type encoded by this type codec
        return DecimalInt

次に、サブスクライブの型コーデックを型レジストリに追加し、カスタム型のインスタンスをエンコードできます。

import pprint
from bson.codec_options import CodecOptions
decimal_int_codec = DecimalIntCodec()
type_registry = TypeRegistry([decimal_codec, decimal_int_codec])
codec_options = CodecOptions(type_registry=type_registry)
collection = db.get_collection("test", codec_options=codec_options)
collection.insert_one({"num": DecimalInt("45.321")})
my_doc = collection.find_one()
pprint.pprint(my_doc)

{'_id': ObjectId('...'), 'num': Decimal('45.321')}

Define a Fallback Encoder

また、BSON によって認識されず、コーデックが登録されていないタイプをエンコードするための呼び出し可能なフォールバック エンコードを登録することもできます。 フォールバック エンコードは、エンコードできない値をパラメーターとして受け入れ、BSON でエンコード可能な値を返します。

次のフォールバック エンコードは Python のDecimal型をDecimal128にエンコードします。

def fallback_encoder(value):
    if isinstance(value, Decimal):
        return Decimal128(value)
    return value

フォールバック エンコードを宣言したら、次の手順を実行します。

• TypeRegistryクラスの新しいインスタンスを構築します。 フォールバック エンコードでを渡すには、 fallback_encoderキーワード引数を使用します。

• CodecOptionsクラスの新しいインスタンスを構築します。 type_registryキーワード引数を使用してTypeRegistryインスタンスに渡します。

• get_collection()メソッドを呼び出します。 codec_optionsキーワード引数を使用してCodecOptionsインスタンスに渡します。

次のコード例は、このプロセスを示しています。

type_registry = TypeRegistry(fallback_encoder=fallback_encoder)
codec_options = CodecOptions(type_registry=type_registry)
collection = db.get_collection("test", codec_options=codec_options)

次に、このコレクションへの参照を使用して、 Decimalクラスのインスタンスを保存できます。

import pprint
collection.insert_one({"num": Decimal("45.321")})
my_doc = collection.find_one()
pprint.pprint(my_doc)

{'_id': ObjectId('...'), 'num': Decimal128('45.321')}

class MyStringType(object):
    def __init__(self, value):
        self.__value = value
    def __repr__(self):
        return "MyStringType('%s')" % (self.__value,)
class MyNumberType(object):
    def __init__(self, value):
        self.__value = value
    def __repr__(self):
        return "MyNumberType(%s)" % (self.__value,)

import pickle
from bson.binary import Binary, USER_DEFINED_SUBTYPE
from bson.codec_options import TypeDecoder
def fallback_pickle_encoder(value):
    return Binary(pickle.dumps(value), USER_DEFINED_SUBTYPE)
class PickledBinaryDecoder(TypeDecoder):
    bson_type = Binary
    def transform_bson(self, value):
        if value.subtype == USER_DEFINED_SUBTYPE:
            return pickle.loads(value)
        return value

from bson.codec_options import CodecOptions,TypeRegistry
codec_options = CodecOptions(
    type_registry=TypeRegistry(
        [PickledBinaryDecoder()], fallback_encoder=fallback_pickle_encoder
  )
)
collection = db.get_collection("test", codec_options=codec_options)
collection.insert_one(
    {"_id": 1, "str": MyStringType("hello world"), "num": MyNumberType(2)}
)
my_doc = collection.find_one()
print(isinstance(my_doc["str"], MyStringType))
print(isinstance(my_doc["num"], MyNumberType))

True
True

制限

PyMongo 型のコーデックとフォールバック エンコードには次の制限があります。

• intやstrなど、PyMongo がすでに理解している Python 型のエンコード動作をカスタマイズすることはできません。 組み込み型を操作する 1 つ以上のコーデックを使用して型レジストリをインスタンス化しようとすると、PyMongo はTypeErrorを発生させます。 この制限は、標準型のすべてのサブタイプにも適用されます。

• タイプ エンコードを連鎖させることはできません。 コーデックのtransform_python()メソッドによって変換されるカスタム タイプ値は、デフォルトで BSON でエンコード可能な か、 フォールバック エンコード によって BSON でエンコード可能な状態に変換できるタイプになる必要があります。 異なるタイプのコーデックでは 2 回目の変換はできません。

• Database.command()メソッドは、コマンド応答ドキュメントのデコード中にカスタム型デコードを適用しません。

• gridfsクラスは、受信または返すドキュメントに対してカスタム型のエンコードまたはデコードを適用しません。

API ドキュメント

カスタム型のエンコードとデコードの詳細については、次の API ドキュメントを参照してください。

• TypeCodec

• TypeEncoder

• TypeDecoder

• TypeRegistry

• CodecOptions