DTOs

matchbox.common.dtos

Data transfer objects for Matchbox API.

Classes:

• OKMessage –

  Generic HTTP OK response.

• BackendCountableType –

  Enumeration of supported backend countable types.

• ModelResultsType –

  Enumeration of supported model results types.

• BackendRetrievableType –

  Enumeration of supported backend retrievable types.

• BackendUploadType –

  Enumeration of supported backend upload types.

• ModelType –

  Enumeration of supported model types.

• CRUDOperation –

  Enumeration of CRUD operations.

• ModelConfig –

  Metadata for a model.

• ModelAncestor –

  A model’s ancestor and its truth value.

• ResolutionOperationStatus –

  Status response for any resolution operation.

• CountResult –

  Response model for count results.

• UploadStatus –

  Response model for any file upload processes.

• NotFoundError –

  API error for a 404 status code.

• DataTypes –

  Enumeration of supported data types.

Attributes:

• SourceResolutionName (TypeAlias) –

  Type alias for source resolution names.

• ModelResolutionName (TypeAlias) –

  Type alias for model resolution names.

• ResolutionName –

  Type alias for resolution names.

SourceResolutionName module-attribute

SourceResolutionName: TypeAlias = str

Type alias for source resolution names.

ModelResolutionName module-attribute

ModelResolutionName: TypeAlias = str

Type alias for model resolution names.

ResolutionName module-attribute

ResolutionName = SourceResolutionName | ModelResolutionName

Type alias for resolution names.

OKMessage

Bases: BaseModel

Generic HTTP OK response.

Attributes:

• status (str) –
• version (str) –

status class-attribute instance-attribute

status: str = Field(default='OK')

version class-attribute instance-attribute

version: str = Field(
    default_factory=lambda: version("matchbox-db")
)

BackendCountableType

Bases: StrEnum

Enumeration of supported backend countable types.

Attributes:

• SOURCES –
• MODELS –
• DATA –
• CLUSTERS –
• CREATES –
• MERGES –
• PROPOSES –

SOURCES class-attribute instance-attribute

SOURCES = 'sources'

MODELS class-attribute instance-attribute

MODELS = 'models'

DATA class-attribute instance-attribute

DATA = 'data'

CLUSTERS class-attribute instance-attribute

CLUSTERS = 'clusters'

CREATES class-attribute instance-attribute

CREATES = 'creates'

MERGES class-attribute instance-attribute

MERGES = 'merges'

PROPOSES class-attribute instance-attribute

PROPOSES = 'proposes'

ModelResultsType

Bases: StrEnum

Enumeration of supported model results types.

Attributes:

• PROBABILITIES –
• CLUSTERS –

PROBABILITIES class-attribute instance-attribute

PROBABILITIES = 'probabilities'

CLUSTERS class-attribute instance-attribute

CLUSTERS = 'clusters'

BackendRetrievableType

Bases: StrEnum

Enumeration of supported backend retrievable types.

Attributes:

• SOURCE –
• RESOLUTION –

SOURCE class-attribute instance-attribute

SOURCE = 'source'

RESOLUTION class-attribute instance-attribute

RESOLUTION = 'resolution'

BackendUploadType

Bases: StrEnum

Enumeration of supported backend upload types.

Attributes:

• INDEX –
• RESULTS –
• schema –

  Get the schema for the upload type.

INDEX class-attribute instance-attribute

INDEX = 'index'

RESULTS class-attribute instance-attribute

RESULTS = 'results'

schema property

schema

Get the schema for the upload type.

ModelType

Bases: StrEnum

Enumeration of supported model types.

Attributes:

• LINKER –
• DEDUPER –

LINKER class-attribute instance-attribute

LINKER = 'linker'

DEDUPER class-attribute instance-attribute

DEDUPER = 'deduper'

CRUDOperation

Bases: StrEnum

Enumeration of CRUD operations.

Attributes:

• CREATE –
• UPDATE –
• DELETE –

CREATE class-attribute instance-attribute

CREATE = 'create'

UPDATE class-attribute instance-attribute

UPDATE = 'update'

DELETE class-attribute instance-attribute

DELETE = 'delete'

ModelConfig

Bases: BaseModel

Metadata for a model.

Attributes:

• name (ModelResolutionName) –
• description (str) –
• type (ModelType) –
• left_resolution (ResolutionName) –
• right_resolution (ResolutionName | None) –

name instance-attribute

name: ModelResolutionName

description instance-attribute

description: str

type instance-attribute

type: ModelType

left_resolution instance-attribute

left_resolution: ResolutionName

right_resolution class-attribute instance-attribute

right_resolution: ResolutionName | None = None

ModelAncestor

Bases: BaseModel

A model’s ancestor and its truth value.

Attributes:

• name (ModelResolutionName) –
• truth (int | None) –

name class-attribute instance-attribute

name: ModelResolutionName = Field(
    ..., description="Name of the ancestor model"
)

truth class-attribute instance-attribute

truth: int | None = Field(
    default=None,
    description="Truth threshold value",
    ge=0,
    le=100,
    strict=True,
)

ResolutionOperationStatus

Bases: BaseModel

Status response for any resolution operation.

Methods:

• status_409_examples –

  Examples for 409 status code.

• status_500_examples –

  Examples for 500 status code.

Attributes:

• success (bool) –
• name (ModelResolutionName) –
• operation (CRUDOperation) –
• details (str | None) –

success instance-attribute

success: bool

name instance-attribute

name: ModelResolutionName

operation instance-attribute

operation: CRUDOperation

details class-attribute instance-attribute

details: str | None = None

status_409_examples classmethod

status_409_examples() -> dict

Examples for 409 status code.

status_500_examples classmethod

status_500_examples() -> dict

Examples for 500 status code.

CountResult

Bases: BaseModel

Response model for count results.

Attributes:

• entities (dict[BackendCountableType, int]) –

entities instance-attribute

entities: dict[BackendCountableType, int]

UploadStatus

Bases: BaseModel

Response model for any file upload processes.

Methods:

• get_http_code –

  Get the HTTP status code for the upload status.

• status_400_examples –

  Examples for 400 status code.

Attributes:

• id (str | None) –
• status (Literal['ready', 'awaiting_upload', 'queued', 'processing', 'complete', 'failed']) –
• details (str | None) –
• entity (BackendUploadType | None) –

id class-attribute instance-attribute

id: str | None = None

status instance-attribute

status: Literal[
    "ready",
    "awaiting_upload",
    "queued",
    "processing",
    "complete",
    "failed",
]

details class-attribute instance-attribute

details: str | None = None

entity class-attribute instance-attribute

entity: BackendUploadType | None = None

get_http_code

get_http_code(status: bool) -> int

Get the HTTP status code for the upload status.

status_400_examples classmethod

status_400_examples() -> dict

Examples for 400 status code.

NotFoundError

Bases: BaseModel

API error for a 404 status code.

Attributes:

• details (str) –
• entity (BackendRetrievableType) –

details instance-attribute

details: str

entity instance-attribute

entity: BackendRetrievableType

DataTypes

Bases: StrEnum

Enumeration of supported data types.

Uses polars datatypes as its backend.

Methods:

• to_dtype –

  Convert enum value to actual polars dtype.

• to_pytype –

  Convert enum value to actual Python type.

• from_dtype –

  Get enum value from a polars dtype.

• from_pytype –

  Get enum value from a Python type.

Attributes:

• BOOLEAN –
• INT8 –
• INT16 –
• INT32 –
• INT64 –
• UINT8 –
• UINT16 –
• UINT32 –
• UINT64 –
• FLOAT32 –
• FLOAT64 –
• DECIMAL –
• STRING –
• BINARY –
• DATE –
• TIME –
• DATETIME –
• DURATION –
• ARRAY –
• LIST –
• OBJECT –
• CATEGORICAL –
• ENUM –
• STRUCT –
• NULL –

BOOLEAN class-attribute instance-attribute

BOOLEAN = 'Boolean'

INT8 class-attribute instance-attribute

INT8 = 'Int8'

INT16 class-attribute instance-attribute

INT16 = 'Int16'

INT32 class-attribute instance-attribute

INT32 = 'Int32'

INT64 class-attribute instance-attribute

INT64 = 'Int64'

UINT8 class-attribute instance-attribute

UINT8 = 'UInt8'

UINT16 class-attribute instance-attribute

UINT16 = 'UInt16'

UINT32 class-attribute instance-attribute

UINT32 = 'UInt32'

UINT64 class-attribute instance-attribute

UINT64 = 'UInt64'

FLOAT32 class-attribute instance-attribute

FLOAT32 = 'Float32'

FLOAT64 class-attribute instance-attribute

FLOAT64 = 'Float64'

DECIMAL class-attribute instance-attribute

DECIMAL = 'Decimal'

STRING class-attribute instance-attribute

STRING = 'String'

BINARY class-attribute instance-attribute

BINARY = 'Binary'

DATE class-attribute instance-attribute

DATE = 'Date'

TIME class-attribute instance-attribute

TIME = 'Time'

DATETIME class-attribute instance-attribute

DATETIME = 'Datetime'

DURATION class-attribute instance-attribute

DURATION = 'Duration'

ARRAY class-attribute instance-attribute

ARRAY = 'Array'

LIST class-attribute instance-attribute

LIST = 'List'

OBJECT class-attribute instance-attribute

OBJECT = 'Object'

CATEGORICAL class-attribute instance-attribute

CATEGORICAL = 'Categorical'

ENUM class-attribute instance-attribute

ENUM = 'Enum'

STRUCT class-attribute instance-attribute

STRUCT = 'Struct'

NULL class-attribute instance-attribute

NULL = 'Null'

to_dtype

to_dtype() -> DataType

Convert enum value to actual polars dtype.

to_pytype

to_pytype() -> type

Convert enum value to actual Python type.

from_dtype classmethod

from_dtype(dtype: DataType) -> DataTypes

Get enum value from a polars dtype.

from_pytype classmethod

from_pytype(pytype: type) -> DataTypes

Get enum value from a Python type.