meilisearch-python-sdk 5.5.0__py3-none-any.whl

meilisearch_python_sdk/json_handler.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import json
+from abc import ABC, abstractmethod
+from typing import Any
+
+try:
+    import orjson
+except ImportError:  # pragma: nocover
+    orjson = None  # type: ignore
+
+try:
+    import ujson
+except ImportError:  # pragma: nocover
+    ujson = None  # type: ignore
+
+
+class _JsonHandler(ABC):
+    @staticmethod
+    @abstractmethod
+    def dumps(obj: Any) -> str: ...
+
+    @staticmethod
+    @abstractmethod
+    def loads(json_string: str | bytes | bytearray) -> Any: ...
+
+
+class BuiltinHandler(_JsonHandler):
+    serializer: type[json.JSONEncoder] | None = None
+
+    def __init__(self, serializer: type[json.JSONEncoder] | None = None) -> None:
+        """Uses the json module from the Python standard library.
+
+        Args:
+            serializer: A custom JSONEncode to handle serializing fields that the build in
+                json.dumps cannot handle, for example UUID and datetime. Defaults to None.
+        """
+        BuiltinHandler.serializer = serializer
+
+    @staticmethod
+    def dumps(obj: Any) -> str:
+        return json.dumps(obj, cls=BuiltinHandler.serializer)
+
+    @staticmethod
+    def loads(json_string: str | bytes | bytearray) -> Any:
+        return json.loads(json_string)
+
+
+class OrjsonHandler(_JsonHandler):
+    def __init__(self) -> None:
+        if orjson is None:  # pragma: no cover
+            raise ValueError("orjson must be installed to use the OrjsonHandler")
+
+    @staticmethod
+    def dumps(obj: Any) -> str:
+        return orjson.dumps(obj).decode("utf-8")
+
+    @staticmethod
+    def loads(json_string: str | bytes | bytearray) -> Any:
+        return orjson.loads(json_string)
+
+
+class UjsonHandler(_JsonHandler):
+    def __init__(self) -> None:
+        if ujson is None:  # pragma: no cover
+            raise ValueError("ujson must be installed to use the UjsonHandler")
+
+    @staticmethod
+    def dumps(obj: Any) -> str:
+        return ujson.dumps(obj)
+
+    @staticmethod
+    def loads(json_string: str | bytes | bytearray) -> Any:
+        return ujson.loads(json_string)

meilisearch_python_sdk/models/batch.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+from camel_converter.pydantic_base import CamelBase
+from pydantic import Field, field_validator
+
+from meilisearch_python_sdk._utils import iso_to_date_time
+from meilisearch_python_sdk.types import JsonDict
+
+
+class BatchId(CamelBase):
+    uid: int
+
+
+class Status(CamelBase):
+    succeeded: int | None = None
+    failed: int | None = None
+    cancelled: int | None = None
+    processing: int | None = None
+    enqueued: int | None = None
+
+
+class Stats(CamelBase):
+    total_nb_tasks: int
+    status: Status
+    batch_types: JsonDict | None = Field(None, alias="types")
+    index_uids: JsonDict | None = None
+    progress_trace: JsonDict | None = None
+    write_channel_congestion: JsonDict | None = None
+    internal_database_sizes: JsonDict | None = None
+
+
+class BatchResult(BatchId):
+    details: JsonDict | None = None
+    progress: JsonDict | None = None
+    stats: Stats
+    duration: str | None = None
+    started_at: datetime | None = None
+    finished_at: datetime | None = None
+
+    @field_validator("started_at", mode="before")  # type: ignore[attr-defined]
+    @classmethod
+    def validate_started_at(cls, v: str) -> datetime | None:
+        return iso_to_date_time(v)
+
+    @field_validator("finished_at", mode="before")  # type: ignore[attr-defined]
+    @classmethod
+    def validate_finished_at(cls, v: str) -> datetime | None:
+        return iso_to_date_time(v)
+
+
+class BatchStatus(CamelBase):
+    results: list[BatchResult]
+    total: int
+    limit: int
+    from_: int | None = Field(None, alias="from")
+    next: int | None = None

meilisearch_python_sdk/models/client.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from datetime import datetime
+
+import pydantic
+from camel_converter.pydantic_base import CamelBase
+
+from meilisearch_python_sdk._utils import iso_to_date_time
+from meilisearch_python_sdk.models.index import IndexStats
+
+
+class ClientStats(CamelBase):
+    database_size: int
+    used_database_size: int | None = None
+    last_update: datetime | None = None
+    indexes: dict[str, IndexStats] | None = None
+
+    @pydantic.field_validator("last_update", mode="before")  # type: ignore[attr-defined]
+    @classmethod
+    def validate_last_update(cls, v: str) -> datetime | None:
+        return iso_to_date_time(v)
+
+
+class _KeyBase(CamelBase):
+    uid: str
+    name: str | None = None
+    description: str | None = None
+    actions: list[str]
+    indexes: list[str]
+    expires_at: datetime | None = None
+
+    model_config = pydantic.ConfigDict(ser_json_timedelta="iso8601")  # type: ignore[typeddict-unknown-key]
+
+    @pydantic.field_validator("expires_at", mode="before")  # type: ignore[attr-defined]
+    @classmethod
+    def validate_expires_at(cls, v: str) -> datetime | None:
+        return iso_to_date_time(v)
+
+
+class Key(_KeyBase):
+    key: str
+    created_at: datetime
+    updated_at: datetime | None = None
+
+    @pydantic.field_validator("created_at", mode="before")  # type: ignore[attr-defined]
+    @classmethod
+    def validate_created_at(cls, v: str) -> datetime:
+        converted = iso_to_date_time(v)
+
+        if not converted:  # pragma: no cover
+            raise ValueError("created_at is required")
+
+        return converted
+
+    @pydantic.field_validator("updated_at", mode="before")  # type: ignore[attr-defined]
+    @classmethod
+    def validate_updated_at(cls, v: str) -> datetime | None:
+        return iso_to_date_time(v)
+
+
+class KeyCreate(CamelBase):
+    name: str | None = None
+    description: str | None = None
+    actions: list[str]
+    indexes: list[str]
+    expires_at: datetime | None = None
+
+    model_config = pydantic.ConfigDict(ser_json_timedelta="iso8601")  # type: ignore[typeddict-unknown-key]
+
+
+class KeyUpdate(CamelBase):
+    key: str
+    name: str | None = None
+    description: str | None = None
+    actions: list[str] | None = None
+    indexes: list[str] | None = None
+    expires_at: datetime | None = None
+
+    model_config = pydantic.ConfigDict(ser_json_timedelta="iso8601")  # type: ignore[typeddict-unknown-key]
+
+
+class KeySearch(CamelBase):
+    results: list[Key]
+    offset: int
+    limit: int
+    total: int
+
+
+class Remote(CamelBase):
+    url: str | None = None
+    search_api_key: str | None = None
+
+
+class Network(CamelBase):
+    self_: str | None = pydantic.Field(None, alias="self")
+    remotes: Mapping[str, Remote] | None = None

meilisearch_python_sdk/models/documents.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from camel_converter.pydantic_base import CamelBase
+
+from meilisearch_python_sdk.types import JsonDict
+
+
+class DocumentsInfo(CamelBase):
+    results: list[JsonDict]
+    offset: int
+    limit: int
+    total: int

meilisearch_python_sdk/models/health.py

@@ -0,0 +1,5 @@
+from camel_converter.pydantic_base import CamelBase
+
+
+class Health(CamelBase):
+    status: str

meilisearch_python_sdk/models/index.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+import pydantic
+from camel_converter.pydantic_base import CamelBase
+
+from meilisearch_python_sdk._utils import iso_to_date_time
+
+
+class IndexBase(CamelBase):
+    uid: str
+    primary_key: str | None = None
+
+
+class IndexInfo(IndexBase):
+    created_at: datetime
+    updated_at: datetime
+
+    @pydantic.field_validator("created_at", mode="before")  # type: ignore[attr-defined]
+    @classmethod
+    def validate_created_at(cls, v: str) -> datetime:
+        converted = iso_to_date_time(v)
+
+        if not converted:  # pragma: no cover
+            raise ValueError("created_at is required")
+
+        return converted
+
+    @pydantic.field_validator("updated_at", mode="before")  # type: ignore[attr-defined]
+    @classmethod
+    def validate_updated_at(cls, v: str) -> datetime:
+        converted = iso_to_date_time(v)
+
+        if not converted:  # pragma: no cover
+            raise ValueError("updated_at is required")
+
+        return converted
+
+
+class IndexStats(CamelBase):
+    number_of_documents: int
+    number_of_embedded_documents: int | None = None
+    number_of_embeddings: int | None = None
+    is_indexing: bool
+    field_distribution: dict[str, int]

meilisearch_python_sdk/models/search.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from typing import Generic, Literal, TypeVar
+
+from camel_converter.pydantic_base import CamelBase
+from pydantic import Field, field_validator
+
+from meilisearch_python_sdk.errors import MeilisearchError
+from meilisearch_python_sdk.types import Filter, JsonDict, JsonMapping
+
+T = TypeVar("T")
+
+
+class FacetHits(CamelBase):
+    value: str
+    count: int
+
+
+class FacetSearchResults(CamelBase):
+    facet_hits: list[FacetHits]
+    facet_query: str | None
+    processing_time_ms: int
+
+
+class Hybrid(CamelBase):
+    semantic_ratio: float
+    embedder: str
+
+
+class MergeFacets(CamelBase):
+    max_values_per_facet: int
+
+
+class Federation(CamelBase):
+    limit: int = 20
+    offset: int = 0
+    facets_by_index: dict[str, list[str]] | None = None
+
+
+class FederationMerged(CamelBase):
+    limit: int = 20
+    offset: int = 0
+    facets_by_index: dict[str, list[str]] | None = None
+    merge_facets: MergeFacets | None
+
+
+class SearchParams(CamelBase):
+    index_uid: str
+    query: str | None = Field(None, alias="q")
+    offset: int = 0
+    limit: int = 20
+    filter: Filter | None = None
+    facets: list[str] | None = None
+    attributes_to_retrieve: list[str] = ["*"]
+    attributes_to_crop: list[str] | None = None
+    crop_length: int = 200
+    attributes_to_highlight: list[str] | None = None
+    sort: list[str] | None = None
+    show_matches_position: bool = False
+    highlight_pre_tag: str = "<em>"
+    highlight_post_tag: str = "</em>"
+    crop_marker: str = "..."
+    matching_strategy: Literal["all", "last", "frequency"] = "last"
+    hits_per_page: int | None = None
+    page: int | None = None
+    attributes_to_search_on: list[str] | None = None
+    show_ranking_score: bool = False
+    show_ranking_score_details: bool = False
+    ranking_score_threshold: float | None = None
+    vector: list[float] | None = None
+    hybrid: Hybrid | None = None
+    locales: list[str] | None = None
+    retrieve_vectors: bool | None = None
+    media: JsonMapping | None = None
+
+    @field_validator("ranking_score_threshold", mode="before")  # type: ignore[attr-defined]
+    @classmethod
+    def validate_ranking_score_threshold(cls, v: float | None) -> float | None:
+        if v and not 0.0 <= v <= 1.0:
+            raise MeilisearchError("ranking_score_threshold must be between 0.0 and 1.0")
+
+        return v
+
+
+class SearchResults(CamelBase, Generic[T]):
+    hits: list[T]
+    offset: int | None = None
+    limit: int | None = None
+    estimated_total_hits: int | None = None
+    processing_time_ms: int
+    query: str
+    facet_distribution: JsonDict | None = None
+    total_pages: int | None = None
+    total_hits: int | None = None
+    page: int | None = None
+    hits_per_page: int | None = None
+    semantic_hit_count: int | None = None
+    query_vector: list[float] | None = None
+
+
+class SearchResultsWithUID(SearchResults, Generic[T]):
+    index_uid: str
+
+
+class SearchResultsFederated(CamelBase, Generic[T]):
+    hits: list[T]
+    offset: int | None = None
+    limit: int | None = None
+    estimated_total_hits: int | None = None
+    processing_time_ms: int
+    facet_distribution: JsonDict | None = None
+    total_pages: int | None = None
+    total_hits: int | None = None
+    page: int | None = None
+    hits_per_page: int | None = None
+    semantic_hit_count: int | None = None
+    facets_by_index: JsonDict | None = None
+
+
+class SimilarSearchResults(CamelBase, Generic[T]):
+    hits: list[T]
+    id: str
+    processing_time_ms: int
+    limit: int | None = None
+    offset: int | None = None
+    estimated_total_hits: int | None = None

meilisearch_python_sdk/models/settings.py

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import Literal
+
+from camel_converter.pydantic_base import CamelBase
+from pydantic import field_validator, model_validator
+
+from meilisearch_python_sdk.types import JsonDict
+
+
+class MinWordSizeForTypos(CamelBase):
+    one_typo: int | None = None
+    two_typos: int | None = None
+
+
+class TypoTolerance(CamelBase):
+    enabled: bool = True
+    disable_on_attributes: list[str] | None = None
+    disable_on_words: list[str] | None = None
+    disable_on_numbers: bool | None = None
+    min_word_size_for_typos: MinWordSizeForTypos | None = None
+
+
+class Faceting(CamelBase):
+    max_values_per_facet: int
+    sort_facet_values_by: dict[str, str] | None = None
+
+    @field_validator("sort_facet_values_by")  # type: ignore[attr-defined]
+    @classmethod
+    def validate_facet_order(cls, v: dict[str, str] | None) -> dict[str, str] | None:
+        if not v:  # pragma: no cover
+            return None
+
+        for _, value in v.items():
+            if value not in ("alpha", "count"):
+                raise ValueError('facet_order must be either "alpha" or "count"')
+
+        return v
+
+
+class Pagination(CamelBase):
+    max_total_hits: int
+
+
+class Distribution(CamelBase):
+    mean: float
+    sigma: float
+
+
+class OpenAiEmbedder(CamelBase):
+    source: str = "openAi"
+    url: str | None = None
+    model: str | None = None
+    dimensions: int | None = None
+    api_key: str | None = None
+    document_template: str | None = None
+    document_template_max_bytes: int | None = None
+    distribution: Distribution | None = None
+    binary_quantized: bool | None = None
+
+
+class HuggingFaceEmbedder(CamelBase):
+    source: str = "huggingFace"
+    model: str | None = None
+    revision: str | None = None
+    document_template: str | None = None
+    document_template_max_bytes: int | None = None
+    distribution: Distribution | None = None
+    dimensions: int | None = None
+    binary_quantized: bool | None = None
+    pooling: Literal["useModel", "forceMean", "forceCls"] | None = None
+
+
+class OllamaEmbedder(CamelBase):
+    source: str = "ollama"
+    url: str | None = None
+    api_key: str | None = None
+    model: str
+    dimensions: int | None = None
+    document_template: str | None = None
+    document_template_max_bytes: int | None = None
+    distribution: Distribution | None = None
+    binary_quantized: bool | None = None
+
+
+class RestEmbedder(CamelBase):
+    source: str = "rest"
+    url: str
+    api_key: str | None = None
+    dimensions: int
+    document_template: str | None = None
+    document_template_max_bytes: int | None = None
+    distribution: Distribution | None = None
+    headers: JsonDict | None = None
+    request: JsonDict
+    response: JsonDict
+    binary_quantized: bool | None = None
+    indexing_fragments: JsonDict | None = None
+    search_fragment: JsonDict | None = None
+
+    @model_validator(mode="after")
+    def check_document_template(self) -> RestEmbedder:
+        if self.indexing_fragments is not None and self.document_template is not None:
+            raise ValueError("document_template must be None when indexing_fragments is set")
+
+        return self
+
+
+class UserProvidedEmbedder(CamelBase):
+    source: str = "userProvided"
+    dimensions: int
+    distribution: Distribution | None = None
+    document_template: str | None = None
+    document_template_max_bytes: int | None = None
+    binary_quantized: bool | None = None
+
+
+class CompositeEmbedder(CamelBase):
+    source: str = "composite"
+    search_embedder: (
+        OpenAiEmbedder | HuggingFaceEmbedder | OllamaEmbedder | RestEmbedder | UserProvidedEmbedder
+    )
+    indexing_embedder: (
+        OpenAiEmbedder | HuggingFaceEmbedder | OllamaEmbedder | RestEmbedder | UserProvidedEmbedder
+    )
+
+
+class Embedders(CamelBase):
+    embedders: dict[
+        str,
+        OpenAiEmbedder
+        | HuggingFaceEmbedder
+        | OllamaEmbedder
+        | RestEmbedder
+        | UserProvidedEmbedder
+        | CompositeEmbedder,
+    ]
+
+
+class ProximityPrecision(str, Enum):
+    BY_WORD = "byWord"
+    BY_ATTRIBUTE = "byAttribute"
+
+
+class LocalizedAttributes(CamelBase):
+    locales: list[str]
+    attribute_patterns: list[str]
+
+
+class Filter(CamelBase):
+    equality: bool
+    comparison: bool
+
+
+class FilterableAttributeFeatures(CamelBase):
+    facet_search: bool
+    filter: Filter
+
+
+class FilterableAttributes(CamelBase):
+    attribute_patterns: list[str]
+    features: FilterableAttributeFeatures
+
+
+class MeilisearchSettings(CamelBase):
+    synonyms: JsonDict | None = None
+    stop_words: list[str] | None = None
+    ranking_rules: list[str] | None = None
+    filterable_attributes: list[str | FilterableAttributes] | None = None
+    distinct_attribute: str | None = None
+    searchable_attributes: list[str] | None = None
+    displayed_attributes: list[str] | None = None
+    sortable_attributes: list[str] | None = None
+    typo_tolerance: TypoTolerance | None = None
+    faceting: Faceting | None = None
+    pagination: Pagination | None = None
+    proximity_precision: ProximityPrecision | None = None
+    separator_tokens: list[str] | None = None
+    non_separator_tokens: list[str] | None = None
+    search_cutoff_ms: int | None = None
+    dictionary: list[str] | None = None
+    embedders: (
+        dict[
+            str,
+            OpenAiEmbedder
+            | HuggingFaceEmbedder
+            | OllamaEmbedder
+            | RestEmbedder
+            | UserProvidedEmbedder
+            | CompositeEmbedder,
+        ]
+        | None
+    ) = None  # Optional[Embedders] = None
+    localized_attributes: list[LocalizedAttributes] | None = None
+    facet_search: bool | None = None
+    prefix_search: Literal["disabled", "indexingTime", "searchTime"] | None = None

meilisearch_python_sdk/models/task.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+import pydantic
+from camel_converter.pydantic_base import CamelBase
+from pydantic import Field
+
+from meilisearch_python_sdk._utils import iso_to_date_time
+from meilisearch_python_sdk.types import JsonDict
+
+
+class TaskId(CamelBase):
+    uid: int
+
+
+class TaskResult(TaskId):
+    index_uid: str | None = None
+    status: str
+    task_type: str | JsonDict = Field(..., alias="type")
+    details: JsonDict | None = None
+    error: JsonDict | None = None
+    canceled_by: int | None = None
+    duration: str | None = None
+    enqueued_at: datetime
+    started_at: datetime | None = None
+    finished_at: datetime | None = None
+    batch_uid: int | None = None
+    custom_metadata: str | None = None
+
+    @pydantic.field_validator("enqueued_at", mode="before")  # type: ignore[attr-defined]
+    @classmethod
+    def validate_enqueued_at(cls, v: str) -> datetime:
+        converted = iso_to_date_time(v)
+
+        if not converted:  # pragma: no cover
+            raise ValueError("enqueued_at is required")
+
+        return converted
+
+    @pydantic.field_validator("started_at", mode="before")  # type: ignore[attr-defined]
+    @classmethod
+    def validate_started_at(cls, v: str) -> datetime | None:
+        return iso_to_date_time(v)
+
+    @pydantic.field_validator("finished_at", mode="before")  # type: ignore[attr-defined]
+    @classmethod
+    def validate_finished_at(cls, v: str) -> datetime | None:
+        return iso_to_date_time(v)
+
+
+class TaskStatus(CamelBase):
+    results: list[TaskResult]
+    total: int
+    limit: int
+    from_: int | None = Field(None, alias="from")
+    next: int | None = None
+
+
+class TaskInfo(CamelBase):
+    task_uid: int
+    index_uid: str | None = None
+    status: str
+    task_type: str | JsonDict = Field(..., alias="type")
+    enqueued_at: datetime
+    batch_uid: int | None = None
+    custom_metadata: str | None = None
+
+    @pydantic.field_validator("enqueued_at", mode="before")  # type: ignore[attr-defined]
+    @classmethod
+    def validate_enqueued_at(cls, v: str) -> datetime:
+        converted = iso_to_date_time(v)
+
+        if not converted:  # pragma: no cover
+            raise ValueError("enqueued_at is required")
+
+        return converted