5. Utility Features

5.1 Indexes

Butty supports MongoDB index configuration through the IndexedField marker. Identity fields are always indexed by default. Indexes are created during engine initialization and support single-field indexing with optional unique constraints, raising DuplicateKeyError on constraint violations. The current implementation does not support compound indexes. All index operations execute asynchronously during the engine setup phase.

Example of indexed field declaration:

class User(SerialIDDocument):
    login: Annotated[str, IndexedField(unique=True)]

5.2 Hooks

The hook system currently supports only delete operations through a single hook type. Hooks are registered using the @hook decorator, which requires both the document class and hook type parameter.

Hook functions receive the document instance as input and must return it, optionally modifying it in-place. The system executes hooks as part of the delete operation flow, processing them in reverse registration order. For inherited documents, base class hooks execute in reverse Method Resolution Order (MRO).

The available hooks are:

  • before_delete: Executes custom logic immediately before document deletion

Example of hook:

class User(BaseDocument):
    name: str
    image_url: str | None


@hook(User, "before_delete")
async def before_user_delete(user: User) -> User:
    if user.image_url:
        await httpx.delete(user.image_url)
        user.image_url = None
    return user

5.3 Predefined Document Types

Butty provides two base document types, which are not part of the core, primarily for testing and prototyping purposes:

SerialIDDocument

  • Uses auto-incremented integer IDs

  • Implements sequential ID generation via counter collection

  • Serves as example for custom identity providers

  • Requires binding of SerialIDCounter class when manual engine setup is used

OIDDocument

  • Uses MongoDB native ObjectId identifiers

  • Includes required Pydantic configuration for ObjectId handling

  • Demonstrates alias _id and BSON type integration

Both classes are abstract (ABC) and not intended for production use. Applications should define their own base document class with appropriate identity strategy, project-specific model configuration, custom validation rules, etc.