Skip to content

database

Classes:

  • BaseRecord –

    The base for labox's core database classes.

  • ContentRecord –

    A record describing where and how a piece of content was saved.

  • ManifestRecord –

    A record acting as a manifest for a storable object.

  • RawJson –

    A type decorator for JSON where values are given and returned as a string.

  • SerializerTypeEnum –

    An enumeration of the types of serializers.

Attributes:

  • ColumnComparator –

    A function that constrains a column to a specific value.

  • DateTimeTZ –

    A datetime column with timezone information.

  • JSON_OR_JSONB –

    Uses JSONB in PostgreSQL and falls back to JSON in other databases.

  • NEVER –

    A timestamp representing never.

ColumnComparator module-attribute 

ColumnComparator = Callable[
    [ColumnElement, Any], ColumnElement[bool]
]

A function that constrains a column to a specific value.

DateTimeTZ module-attribute 

DateTimeTZ = Annotated[
    datetime, mapped_column(DateTime(timezone=True))
]

A datetime column with timezone information.

JSON_OR_JSONB module-attribute 

JSON_OR_JSONB = with_variant(JSONB(), 'postgresql')

Uses JSONB in PostgreSQL and falls back to JSON in other databases.

NEVER module-attribute 

NEVER = replace(tzinfo=UTC)

A timestamp representing never.

There is no way to represent an infinite datetime in Python so we resort to using the largest representable value. Some databases have support for infinite datetimes but this is not a universal feature. If it's desireable to map datetime.max to infinity you may be able to register an extension with your driver of choice in order to do so. For example, psycopg3 allows you to implement a custom dumper/loader for datetimes: https://www.psycopg.org/psycopg3/docs/advanced/adapt.html#example-handling-infinity-date

BaseRecord

Bases: MappedAsDataclass, DeclarativeBase

The base for labox's core database classes.

Methods:

  • create_all –

    Create all tables for the database.

create_all async classmethod 

create_all(engine: AsyncEngine) -> None

Create all tables for the database.

ContentRecord

Bases: _StrMixin, BaseRecord

A record describing where and how a piece of content was saved.

Methods:

  • create_all –

    Create all tables for the database.

Attributes:

content_encoding class-attribute instance-attribute 

content_encoding: Mapped[str | None] = mapped_column()

The encoding of the data.

content_hash class-attribute instance-attribute 

content_hash: Mapped[str] = mapped_column()

The hash of the data.

content_hash_algorithm class-attribute instance-attribute 

content_hash_algorithm: Mapped[str] = mapped_column()

The algorithm used to hash the data.

content_key class-attribute instance-attribute 

content_key: Mapped[str] = mapped_column()

A string that uniquely identifies the content within the manifest.

content_size class-attribute instance-attribute 

content_size: Mapped[int] = mapped_column(BIGINT())

The size of the data in bytes

content_type class-attribute instance-attribute 

content_type: Mapped[str] = mapped_column()

The MIME type of the data.

created_at class-attribute instance-attribute 

created_at: Mapped[DateTimeTZ] = mapped_column(
    default=now()
)

The timestamp when the content was created.

id class-attribute instance-attribute 

id: Mapped[UUID] = mapped_column(
    default_factory=uuid4, primary_key=True
)

The ID of the content.

manifest_id class-attribute instance-attribute 

manifest_id: Mapped[UUID] = mapped_column(ForeignKey(id))

The ID of the manifest that the content belongs to.

serializer_config class-attribute instance-attribute 

serializer_config: Mapped[str] = mapped_column(RawJson)

The configuration used to serialize the data.

serializer_name class-attribute instance-attribute 

serializer_name: Mapped[str] = mapped_column()

The name of the serializer used to serialize the data.

serializer_type class-attribute instance-attribute 

serializer_type: Mapped[SerializerTypeEnum] = (
    mapped_column()
)

The type of the serializer used to serialize the data.

storage_config class-attribute instance-attribute 

storage_config: Mapped[str] = mapped_column(RawJson)

The information needed to load data from the storage.

storage_name class-attribute instance-attribute 

storage_name: Mapped[str] = mapped_column()

The name of the storage backend used to store the data.

create_all async classmethod 

create_all(engine: AsyncEngine) -> None

Create all tables for the database.

ManifestRecord

Bases: _StrMixin, BaseRecord

A record acting as a manifest for a storable object.

Methods:

  • create_all –

    Create all tables for the database.

Attributes:

  • class_id (Mapped[UUID]) –

    An ID that uniquely identifies the type that was stored.

  • contents (Mapped[Sequence[ContentRecord]]) –

    The contents of the object.

  • created_at (Mapped[DateTimeTZ]) –

    The timestamp when the manifest was created.

  • id (Mapped[UUID]) –

    The ID of the manifest record.

  • tags (Mapped[TagMap | None]) –

    User defined tags associated with the object.

  • unpacker_name (Mapped[str]) –

    The name of the unpacker used to decompose the object into its constituent parts.

class_id class-attribute instance-attribute 

class_id: Mapped[UUID] = mapped_column()

An ID that uniquely identifies the type that was stored.

contents class-attribute instance-attribute 

contents: Mapped[Sequence[ContentRecord]] = relationship(
    default=(), collection_class=list
)

The contents of the object.

created_at class-attribute instance-attribute 

created_at: Mapped[DateTimeTZ] = mapped_column(
    default=now()
)

The timestamp when the manifest was created.

id class-attribute instance-attribute 

id: Mapped[UUID] = mapped_column(
    default_factory=uuid4, primary_key=True
)

The ID of the manifest record.

tags class-attribute instance-attribute 

tags: Mapped[TagMap | None] = mapped_column(JSON_OR_JSONB)

User defined tags associated with the object.

unpacker_name class-attribute instance-attribute 

unpacker_name: Mapped[str] = mapped_column()

The name of the unpacker used to decompose the object into its constituent parts.

create_all async classmethod 

create_all(engine: AsyncEngine) -> None

Create all tables for the database.

RawJson

Bases: TypeDecorator[str]

A type decorator for JSON where values are given and returned as a string.

Methods:

  • bind_expression –

    Return a bind expression that passes the value to the database as a string.

  • bind_processor –

    Return a function that passes the value to the database as a string.

  • column_expression –

    Return the column expression for the type decorator.

bind_expression 

bind_expression(
    bindparam: BindParameter[str],
) -> ColumnElement[str] | None

Return a bind expression that passes the value to the database as a string.

bind_processor 

bind_processor(dialect: Dialect) -> _BindProcessorType

Return a function that passes the value to the database as a string.

column_expression 

column_expression(
    column: ColumnElement,
) -> ColumnElement[str]

Return the column expression for the type decorator.

SerializerTypeEnum

Bases: IntEnum

An enumeration of the types of serializers.

Attributes:

Serializer class-attribute instance-attribute 

Serializer = 1

A content serializer.

StreamSerializer class-attribute instance-attribute 

StreamSerializer = 2

A content stream serializer.