Tipos personalizados

Visão geral

Este guia explica como usar o PyMongo para codificar e decodificar tipos personalizados.

Codificar um tipo personalizado

Talvez seja necessário definir um tipo personalizado se quiser armazenar um tipo de dados que o driver não entenda. Por exemplo, o tipo Decimal128 da biblioteca BSON é diferente do tipo Decimal integrado do Python. Tentar salvar uma instância do Decimal com PyMongo resulta em uma exceção do InvalidDocument , como mostrado no seguinte exemplo de código:

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'>

As seções seguintes mostram como definir um tipo personalizado para este tipo do 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')}

Codificar um subtipo

Talvez você também precise codificar um ou mais tipos que herdam do seu tipo personalizado. Considere o seguinte subtipo da classe Decimal , que contém um método para retornar seu valor como um número inteiro:

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

Se você tentar salvar uma instância da classe DecimalInt sem primeiro registrar um codec de tipo para ela, o PyMongo chamará um erro:

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'>

Para codificar uma instância da classe DecimalInt , você deve definir um codec de tipo para a classe. Esse codec de tipo deve herdar do codec da classe pai, DecimalCodec, conforme mostrado no exemplo a seguir:

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

Você pode então adicionar o codec do tipo sublcass ao tipo de registro e codificar instâncias do tipo personalizado:

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')}

Definir um codificador de contingência

Você também pode registrar um codificador de contingência, um chamável para codificar tipos não reconhecidos pelo BSON e para os quais nenhum codec de tipo foi registrado. O codificador fallback aceita um valor não codificado como parâmetro e retorna um valor codificado por BSON.

O seguinte codificador de contingência codifica o tipo Decimal do Python para Decimal128:

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

Depois de declarar um codificador de contingência, execute as seguintes etapas:

• Construa uma nova instância da classe TypeRegistry . Use o argumento de palavra-chave fallback_encoder para passar o codificador de contingência.

• Construa uma nova instância da classe CodecOptions . Use o argumento da palavra-chave type_registry para passar na instância do TypeRegistry .

• Chame o método get_collection() . Use o argumento da palavra-chave codec_options para passar na instância do CodecOptions .

O seguinte exemplo de código mostra este processo:

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

Você pode então usar esta referência a uma coleção para armazenar instâncias da classe 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

Limitações

Os codecs do tipo PyMongo e codificadores de contingência têm as seguintes limitações:

• Você não pode personalizar o comportamento de codificação dos tipos de Python que o PyMongo já entende, como int e str. Se você tentar instanciar um registro de tipo com um ou mais codecs que agem em um tipo integrado, o PyMongo gerará um TypeError. Esta limitação também se aplica a todos os subtipos dos tipos padrão.

• Você não pode encadear codificadores de tipo. Um valor de tipo personalizado, uma vez transformado pelo método transform_python() de um codec, deve resultar em um tipo que seja codificado por BSON por padrão, ou possa ser transformado pelo codificador de fallback em algo codificado por BSON. Não pode ser transformado uma segunda vez por um codec de tipo diferente.

• O método Database.command() não aplica decodificadores de tipo personalizado ao decodificar o documento de resposta do comando.

• A classe gridfs não aplica codificação ou decodificação de tipo personalizado a nenhum documento que recebe ou retorna.

Documentação da API

Para obter mais informações sobre codificação e decodificação de tipos personalizados, consulte a seguinte documentação da API:

• TypeCodec

• TypeEncoder

• TypeDecoder

• TypeRegistry

• CodecOptions