Link documents with UUIDs

[Mark90]

Hi, thanks @roman-right for a wonderful library and documentation!

Apologies if this isn't worth a 'Show and tell' discussion, but it took me some time to figure out and thought it might be helpful for others.

I wanted to Link Documents together using UUIDs as document id's, instead of mongo's object ID. My first implementation looked something like this:

from uuid import UUID, uuid4

from beanie import Document, Link, init_beanie
from motor.motor_asyncio import AsyncIOMotorClient
from pydantic import Field


class Door(Document):
    id: UUID = Field(default_factory=uuid4)

    height: int = 2
    width: int = 1

    class Settings:
        name = "door"


class House(Document):
    id: UUID = Field(default_factory=uuid4)

    name: str
    doors: list[Link[Door]]

    class Settings:
        name = "house"


async def test():
    client = AsyncIOMotorClient(settings.MONGO_URL)
    db = client.get_database(settings.MONGO_NAME)
    await init_beanie(database=db, document_models=[House, Door])

    await Door.delete_all()
    await House.delete_all()

    door = Door()
    await door.create()
    print(f"Created {door=}")

    house = House(name="my house", doors=[])
    await house.create()
    print(f"Created {house=}")

    house.doors.append(door)
    await house.save()
    print(f"Added door to {house=}")

Running the test() coroutine gives an error;

Created door=Door(id=UUID('2d1b7d53-d7c3-4704-99c4-7ebb0e5b08b3'), revision_id=None, height=2, width=1)
Created house=House(id=UUID('19e56815-dce1-4e13-b1e4-2c60d7d5a34a'), revision_id=None, name='my house', doors=[])
Traceback (most recent call last):
  ...  (ommitted)
  File "/usr/local/lib/python3.11/site-packages/pymongo/message.py", line 692, in _op_msg
    return _op_msg_uncompressed(flags, command, identifier, docs, opts)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/bson/binary.py", line 267, in from_uuid
    raise ValueError(
ValueError: cannot encode native uuid.UUID with UuidRepresentation.UNSPECIFIED. UUIDs can be manually converted to bson.Binary instances using bson.Binary.from_uuid() or a different UuidRepresentation can be configured. See the documentation for UuidRepresentation for more information.

One (the?) solution is to configure 'standard' UUID Representation.

There are 2 different methods to configure this;

1. Set it on initialisation of the AsyncIOMotorClient (or pymongo.MongoClient)

client = AsyncIOMotorClient(
    settings.MONGO_URL, 
    uuidRepresentation="standard",  # <<<<<
)
db = client.get_database(settings.MONGO_NAME)
await init_beanie(database=db, document_models=[House, Door]) 

2. Set it in the bson.CodecOptions (if you already pass any other codec options, this overrides the previous method and you'll be wondering why it isn't working :) )

from bson import CodecOptions, UuidRepresentation

client = AsyncIOMotorClient(settings.MONGO_URL)
db = client.get_database(
    settings.MONGO_NAME,
    codec_options=CodecOptions(uuid_representation=UuidRepresentation.STANDARD),  # <<<<<
)
await init_beanie(database=db, document_models=[House, Door]) 

Now I can have a door in my house!

Created door=Door(id=UUID('fea844fd-06c4-4a37-b3dd-22c75870ad53'), revision_id=None, height=2, width=1)
Created house=House(id=UUID('edd2e28e-f92c-466b-bf3f-d16f29d03f76'), revision_id=None, name='my house', doors=[])
Added door to house=House(id=UUID('edd2e28e-f92c-466b-bf3f-d16f29d03f76'), revision_id=None, name='my house', doors=[Door(id=UUID('fea844fd-06c4-4a37-b3dd-22c75870ad53'), revision_id=None, height=2, width=1)])