app/database/objectid.py

"""Utilidades para trabajar con ``ObjectId`` de MongoDB."""

from __future__ import annotations

from bson import ObjectId
from bson.errors import InvalidId

from app.exceptions import InvalidIdError


def to_object_id(value: str | ObjectId) -> ObjectId:
    """Convierte un valor a :class:`bson.ObjectId`.

    Args:
        value: Identificador como cadena o ``ObjectId``.

    Returns:
        El ``ObjectId`` correspondiente.

    Raises:
        InvalidIdError: Si el valor no es un ObjectId válido.
    """
    if isinstance(value, ObjectId):
        return value
    try:
        return ObjectId(value)
    except (InvalidId, TypeError) as exc:
        raise InvalidIdError(f"'{value}' no es un identificador válido.") from exc