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

meilisearch_python_sdk/_task.py

@@ -0,0 +1,358 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from datetime import datetime
+from typing import TYPE_CHECKING
+from urllib.parse import urlencode
+
+from httpx import AsyncClient as HttpxAsyncClient
+from httpx import Client as HttpxClient
+
+from meilisearch_python_sdk._http_requests import AsyncHttpRequests, HttpRequests
+from meilisearch_python_sdk.errors import MeilisearchTaskFailedError, MeilisearchTimeoutError
+from meilisearch_python_sdk.models.task import TaskInfo, TaskResult, TaskStatus
+
+if TYPE_CHECKING:
+    from meilisearch_python_sdk._client import AsyncClient, Client  # pragma: no cover
+
+
+async def async_cancel_tasks(
+    client: HttpxAsyncClient | AsyncClient,
+    *,
+    uids: list[str] | None = None,
+    index_uids: list[str] | None = None,
+    statuses: list[str] | None = None,
+    types: list[str] | None = None,
+    before_enqueued_at: datetime | None = None,
+    after_enqueued_at: datetime | None = None,
+    before_started_at: datetime | None = None,
+    after_finished_at: datetime | None = None,
+) -> TaskInfo:
+    """Cancel a list of enqueued or processing tasks.
+
+    Defaults to cancelling all tasks.
+
+    Args:
+
+        client: An httpx HttpxAsyncClient or meilisearch_python_sdk AsyncClient instance.
+        uids: A list of task UIDs to cancel.
+        index_uids: A list of index UIDs for which to cancel tasks.
+        statuses: A list of statuses to cancel.
+        types: A list of types to cancel.
+        before_enqueued_at: Cancel tasks that were enqueued before the specified date time.
+        after_enqueued_at: Cancel tasks that were enqueued after the specified date time.
+        before_started_at: Cancel tasks that were started before the specified date time.
+        after_finished_at: Cancel tasks that were finished after the specified date time.
+
+    Returns:
+
+        The details of the task
+
+    Raises:
+
+        MeilisearchCommunicationError: If there was an error communicating with the server.
+        MeilisearchApiError: If the Meilisearch API returned an error.
+        MeilisearchTimeoutError: If the connection times out.
+
+    Examples:
+
+        >>> from meilisearch_python_sdk import AsyncClient
+        >>> from meilisearch_python_sdk.task import cancel_tasks
+        >>>
+        >>> async with AsyncClient("http://localhost.com", "masterKey") as client:
+        >>>     await cancel_tasks(client, uids=[1, 2])
+    """
+    parameters = _process_params(
+        uids,
+        index_uids,
+        statuses,
+        types,
+        before_enqueued_at,
+        after_enqueued_at,
+        before_started_at,
+        after_finished_at,
+    )
+
+    if not parameters:
+        # Cancel all tasks if no parmaeters provided
+        parameters["statuses"] = "enqueued,processing"
+
+    url = f"tasks/cancel?{urlencode(parameters)}"
+    client_ = _get_async_client(client)
+    response = await client_.post(url)
+
+    return TaskInfo(**response.json())
+
+
+async def async_delete_tasks(
+    client: HttpxAsyncClient | AsyncClient,
+    *,
+    uids: list[str] | None = None,
+    index_uids: list[str] | None = None,
+    statuses: list[str] | None = None,
+    types: list[str] | None = None,
+    before_enqueued_at: datetime | None = None,
+    after_enqueued_at: datetime | None = None,
+    before_started_at: datetime | None = None,
+    after_finished_at: datetime | None = None,
+) -> TaskInfo:
+    parameters = _process_params(
+        uids,
+        index_uids,
+        statuses,
+        types,
+        before_enqueued_at,
+        after_enqueued_at,
+        before_started_at,
+        after_finished_at,
+    )
+
+    if not parameters:
+        # delete all tasks if no parmaeters provided
+        parameters["statuses"] = "canceled,enqueued,failed,processing,succeeded"
+
+    url = f"tasks?{urlencode(parameters)}"
+    client_ = _get_async_client(client)
+    response = await client_.delete(url)
+
+    return TaskInfo(**response.json())
+
+
+async def async_get_task(client: HttpxAsyncClient | AsyncClient, task_id: int) -> TaskResult:
+    client_ = _get_async_client(client)
+    response = await client_.get(f"tasks/{task_id}")
+
+    return TaskResult(**response.json())
+
+
+async def async_get_tasks(
+    client: HttpxAsyncClient | AsyncClient,
+    *,
+    index_ids: list[str] | None = None,
+    types: str | list[str] | None = None,
+) -> TaskStatus:
+    url = f"tasks?indexUids={','.join(index_ids)}" if index_ids else "tasks"
+    if types:
+        formatted_types = ",".join(types) if isinstance(types, list) else types
+        url = f"{url}&types={formatted_types}" if "?" in url else f"{url}?types={formatted_types}"
+    client_ = _get_async_client(client)
+    response = await client_.get(url)
+
+    return TaskStatus(**response.json())
+
+
+async def async_wait_for_task(
+    client: HttpxAsyncClient | AsyncClient,
+    task_id: int,
+    *,
+    timeout_in_ms: int | None = 5000,
+    interval_in_ms: int = 50,
+    raise_for_status: bool = False,
+) -> TaskResult:
+    client_ = _get_async_client(client)
+    url = f"tasks/{task_id}"
+    http_requests = AsyncHttpRequests(client_)
+    start_time = datetime.now()
+    elapsed_time = 0.0
+
+    if timeout_in_ms:
+        while elapsed_time < timeout_in_ms:
+            response = await http_requests.get(url)
+            status = TaskResult(**response.json())
+            if status.status in ("succeeded", "failed"):
+                if raise_for_status and status.status == "failed":
+                    raise MeilisearchTaskFailedError(f"Task {task_id} failed")
+                return status
+            await asyncio.sleep(interval_in_ms / 1000)
+            time_delta = datetime.now() - start_time
+            elapsed_time = time_delta.seconds * 1000 + time_delta.microseconds / 1000
+        raise MeilisearchTimeoutError(
+            f"timeout of {timeout_in_ms}ms has exceeded on process {task_id} when waiting for pending update to resolve."
+        )
+    else:
+        while True:
+            response = await http_requests.get(url)
+            status = TaskResult(**response.json())
+            if status.status in ("succeeded", "failed"):
+                if raise_for_status and status.status == "failed":
+                    raise MeilisearchTaskFailedError(f"Task {task_id} failed")
+                return status
+            await asyncio.sleep(interval_in_ms / 1000)
+
+
+def cancel_tasks(
+    client: HttpxClient | Client,
+    *,
+    uids: list[str] | None = None,
+    index_uids: list[str] | None = None,
+    statuses: list[str] | None = None,
+    types: list[str] | None = None,
+    before_enqueued_at: datetime | None = None,
+    after_enqueued_at: datetime | None = None,
+    before_started_at: datetime | None = None,
+    after_finished_at: datetime | None = None,
+) -> TaskInfo:
+    parameters = _process_params(
+        uids,
+        index_uids,
+        statuses,
+        types,
+        before_enqueued_at,
+        after_enqueued_at,
+        before_started_at,
+        after_finished_at,
+    )
+
+    if not parameters:
+        # Cancel all tasks if no parmaeters provided
+        parameters["statuses"] = "enqueued,processing"
+
+    url = f"tasks/cancel?{urlencode(parameters)}"
+    client_ = _get_client(client)
+    response = client_.post(url)
+
+    return TaskInfo(**response.json())
+
+
+def delete_tasks(
+    client: HttpxClient | Client,
+    *,
+    uids: list[str] | None = None,
+    index_uids: list[str] | None = None,
+    statuses: list[str] | None = None,
+    types: list[str] | None = None,
+    before_enqueued_at: datetime | None = None,
+    after_enqueued_at: datetime | None = None,
+    before_started_at: datetime | None = None,
+    after_finished_at: datetime | None = None,
+) -> TaskInfo:
+    parameters = _process_params(
+        uids,
+        index_uids,
+        statuses,
+        types,
+        before_enqueued_at,
+        after_enqueued_at,
+        before_started_at,
+        after_finished_at,
+    )
+
+    if not parameters:
+        # delete all tasks if no parmaeters provided
+        parameters["statuses"] = "canceled,enqueued,failed,processing,succeeded"
+
+    url = f"tasks?{urlencode(parameters)}"
+    client_ = _get_client(client)
+    response = client_.delete(url)
+
+    return TaskInfo(**response.json())
+
+
+def get_task(client: HttpxClient | Client, task_id: int) -> TaskResult:
+    client_ = _get_client(client)
+    response = client_.get(f"tasks/{task_id}")
+
+    return TaskResult(**response.json())
+
+
+def get_tasks(
+    client: HttpxClient | Client,
+    *,
+    index_ids: list[str] | None = None,
+    types: str | list[str] | None = None,
+) -> TaskStatus:
+    url = f"tasks?indexUids={','.join(index_ids)}" if index_ids else "tasks"
+    if types:
+        formatted_types = ",".join(types) if isinstance(types, list) else types
+        url = f"{url}&types={formatted_types}" if "?" in url else f"{url}?types={formatted_types}"
+    client_ = _get_client(client)
+    response = client_.get(url)
+
+    return TaskStatus(**response.json())
+
+
+def wait_for_task(
+    client: HttpxClient | Client,
+    task_id: int,
+    *,
+    timeout_in_ms: int | None = 5000,
+    interval_in_ms: int = 50,
+    raise_for_status: bool = False,
+) -> TaskResult:
+    client_ = _get_client(client)
+    url = f"tasks/{task_id}"
+    http_requests = HttpRequests(client_)
+    start_time = datetime.now()
+    elapsed_time = 0.0
+
+    if timeout_in_ms:
+        while elapsed_time < timeout_in_ms:
+            response = http_requests.get(url)
+            status = TaskResult(**response.json())
+            if status.status in ("succeeded", "failed"):
+                if raise_for_status and status.status == "failed":
+                    raise MeilisearchTaskFailedError(f"Task {task_id} failed")
+                return status
+            time.sleep(interval_in_ms / 1000)
+            time_delta = datetime.now() - start_time
+            elapsed_time = time_delta.seconds * 1000 + time_delta.microseconds / 1000
+        raise MeilisearchTimeoutError(
+            f"timeout of {timeout_in_ms}ms has exceeded on process {task_id} when waiting for pending update to resolve."
+        )
+    else:
+        while True:
+            response = http_requests.get(url)
+            status = TaskResult(**response.json())
+            if status.status in ("succeeded", "failed"):
+                if raise_for_status and status.status == "failed":
+                    raise MeilisearchTaskFailedError(f"Task {task_id} failed")
+                return status
+            time.sleep(interval_in_ms / 1000)
+
+
+def _get_async_client(client: AsyncClient | HttpxAsyncClient) -> HttpxAsyncClient:
+    if isinstance(client, HttpxAsyncClient):
+        return client
+
+    return client.http_client
+
+
+def _get_client(
+    client: Client | HttpxClient,
+) -> HttpxClient:
+    if isinstance(client, HttpxClient):
+        return client
+
+    return client.http_client
+
+
+def _process_params(
+    uids: list[str] | None = None,
+    index_uids: list[str] | None = None,
+    statuses: list[str] | None = None,
+    types: list[str] | None = None,
+    before_enqueued_at: datetime | None = None,
+    after_enqueued_at: datetime | None = None,
+    before_started_at: datetime | None = None,
+    after_finished_at: datetime | None = None,
+) -> dict[str, str]:
+    parameters = {}
+    if uids:
+        parameters["uids"] = ",".join([str(x) for x in uids])
+    if index_uids:
+        parameters["indexUids"] = ",".join([str(x) for x in index_uids])
+    if statuses:
+        parameters["statuses"] = ",".join(statuses)
+    if types:
+        parameters["types"] = ",".join(types)
+    if before_enqueued_at:
+        parameters["beforeEnqueuedAt"] = f"{before_enqueued_at.isoformat()}Z"
+    if after_enqueued_at:
+        parameters["afterEnqueuedAt"] = f"{after_enqueued_at.isoformat()}Z"
+    if before_started_at:
+        parameters["beforeStartedAt"] = f"{before_started_at.isoformat()}Z"
+    if after_finished_at:
+        parameters["afterFinishedAt"] = f"{after_finished_at.isoformat()}Z"
+
+    return parameters

meilisearch_python_sdk/_utils.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import sys
+from datetime import datetime
+from functools import lru_cache
+
+import pydantic
+
+
+@lru_cache(maxsize=1)
+def is_pydantic_2() -> bool:
+    try:
+        # __version__ was added with Pydantic 2 so we know if this errors the version is < 2.
+        # Still check the version as a fail safe incase __version__ gets added to verion 1.
+        if int(pydantic.__version__[:1]) >= 2:  # type: ignore[attr-defined]
+            return True
+        else:  # pragma: no cover
+            # Raise an AttributeError to match the AttributeError on __version__ because in either
+            # case we need to get to the same place.
+            raise AttributeError
+    except AttributeError:  # pragma: no cover
+        return False
+
+
+def iso_to_date_time(iso_date: datetime | str | None) -> datetime | None:
+    """Handle conversion of iso string to datetime.
+
+    The microseconds from Meilisearch are sometimes too long for python to convert so this
+    strips off the last digits to shorten it when that happens.
+    """
+    if not iso_date:
+        return None
+
+    if isinstance(iso_date, datetime):
+        return iso_date
+
+    try:
+        return datetime.strptime(iso_date, "%Y-%m-%dT%H:%M:%S.%fZ")
+    except ValueError:
+        split = iso_date.split(".")
+        if len(split) < 2:
+            raise
+        reduce = len(split[1]) - 6
+        reduced = f"{split[0]}.{split[1][:-reduce]}Z"
+        return datetime.strptime(reduced, "%Y-%m-%dT%H:%M:%S.%fZ")
+
+
+@lru_cache(maxsize=1)
+def use_task_groups() -> bool:
+    return True if sys.version_info >= (3, 11) else False

meilisearch_python_sdk/_version.py

@@ -0,0 +1 @@
+VERSION = "2.0.0"

meilisearch_python_sdk/errors.py

@@ -0,0 +1,71 @@
+from httpx import Response
+
+
+class InvalidDocumentError(Exception):
+    """Error for documents that are not in a valid format for Meilisearch."""
+
+    pass
+
+
+class InvalidRestriction(Exception):
+    pass
+
+
+class MeilisearchError(Exception):
+    """Generic class for Meilisearch error handling."""
+
+    def __init__(self, message: str) -> None:
+        self.message = message
+        super().__init__(self.message)
+
+    def __str__(self) -> str:
+        return f"MeilisearchError. Error message: {self.message}."
+
+
+class MeilisearchApiError(MeilisearchError):
+    """Error sent by Meilisearch API."""
+
+    def __init__(self, error: str, response: Response) -> None:
+        self.status_code = response.status_code
+        self.code = ""
+        self.message = ""
+        self.link = ""
+        self.error_type = ""
+        if response.content:
+            self.message = f"Error message: {response.json().get('message') or ''}"
+            self.code = f"{response.json().get('code') or ''}"
+            self.error_type = f"{response.json().get('type') or ''}"
+            self.link = f"Error documentation: {response.json().get('link') or ''}"
+        else:
+            self.message = error
+        super().__init__(self.message)
+
+    def __str__(self) -> str:
+        return f"MeilisearchApiError.{self.code} {self.message} {self.error_type} {self.link}"
+
+
+class MeilisearchCommunicationError(MeilisearchError):
+    """Error when connecting to Meilisearch."""
+
+    def __str__(self) -> str:
+        return f"MeilisearchCommunicationError, {self.message}"
+
+
+class MeilisearchTaskFailedError(MeilisearchError):
+    """Error when a task is in the failed status."""
+
+    def __str__(self) -> str:
+        return f"MeilisearchTaskFailedError, {self.message}"
+
+
+class MeilisearchTimeoutError(MeilisearchError):
+    """Error when Meilisearch operation takes longer than expected."""
+
+    def __str__(self) -> str:
+        return f"MeilisearchTimeoutError, {self.message}"
+
+
+class PayloadTooLarge(Exception):
+    """Error when the payload is larger than the allowed payload size."""
+
+    pass

meilisearch_python_sdk/models/client.py

@@ -0,0 +1,159 @@
+from datetime import datetime
+from typing import Dict, List, Optional, Union
+
+import pydantic
+from camel_converter.pydantic_base import CamelBase
+
+from meilisearch_python_sdk._utils import is_pydantic_2, iso_to_date_time
+from meilisearch_python_sdk.models.index import IndexStats
+
+
+class ClientStats(CamelBase):
+    database_size: int
+    last_update: Optional[datetime] = None
+    indexes: Optional[Dict[str, IndexStats]] = None
+
+    if is_pydantic_2():
+
+        @pydantic.field_validator("last_update", mode="before")  # type: ignore[attr-defined]
+        @classmethod
+        def validate_last_update(cls, v: str) -> Union[datetime, None]:
+            return iso_to_date_time(v)
+
+    else:  # pragma: no cover
+
+        @pydantic.validator("last_update", pre=True)
+        @classmethod
+        def validate_last_update(cls, v: str) -> Union[datetime, None]:
+            return iso_to_date_time(v)
+
+
+class _KeyBase(CamelBase):
+    uid: str
+    name: Optional[str] = None
+    description: str
+    actions: List[str]
+    indexes: List[str]
+    expires_at: Optional[datetime] = None
+
+    if is_pydantic_2():
+        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) -> Union[datetime, None]:
+            return iso_to_date_time(v)
+
+    else:  # pragma: no cover
+
+        @pydantic.validator("expires_at", pre=True)
+        @classmethod
+        def validate_expires_at(cls, v: str) -> Union[datetime, None]:
+            return iso_to_date_time(v)
+
+        class Config:
+            json_encoders = {
+                datetime: lambda v: None
+                if not v
+                else (
+                    f"{str(v).split('+')[0].replace(' ', 'T')}Z"
+                    if "+" in str(v)
+                    else f"{str(v).replace(' ', 'T')}Z"
+                )
+            }
+
+
+class Key(_KeyBase):
+    key: str
+    created_at: datetime
+    updated_at: Optional[datetime] = None
+
+    if is_pydantic_2():
+
+        @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) -> Union[datetime, None]:
+            return iso_to_date_time(v)
+
+    else:  # pragma: no cover
+
+        @pydantic.validator("created_at", pre=True)
+        @classmethod
+        def validate_created_at(cls, v: str) -> datetime:
+            converted = iso_to_date_time(v)
+
+            if not converted:
+                raise ValueError("created_at is required")
+
+            return converted
+
+        @pydantic.validator("updated_at", pre=True)
+        @classmethod
+        def validate_updated_at(cls, v: str) -> Union[datetime, None]:
+            return iso_to_date_time(v)
+
+
+class KeyCreate(CamelBase):
+    name: Optional[str] = None
+    description: str
+    actions: List[str]
+    indexes: List[str]
+    expires_at: Optional[datetime] = None
+
+    if is_pydantic_2():
+        model_config = pydantic.ConfigDict(ser_json_timedelta="iso8601")  # type: ignore[typeddict-unknown-key]
+
+    else:  # pragma: no cover
+
+        class Config:
+            json_encoders = {
+                datetime: lambda v: None
+                if not v
+                else (
+                    f"{str(v).split('+')[0].replace(' ', 'T')}Z"
+                    if "+" in str(v)
+                    else f"{str(v).replace(' ', 'T')}Z"
+                )
+            }
+
+
+class KeyUpdate(CamelBase):
+    key: str
+    name: Optional[str] = None
+    description: Optional[str] = None
+    actions: Optional[List[str]] = None
+    indexes: Optional[List[str]] = None
+    expires_at: Optional[datetime] = None
+
+    if is_pydantic_2():
+        model_config = pydantic.ConfigDict(ser_json_timedelta="iso8601")  # type: ignore[typeddict-unknown-key]
+
+    else:  # pragma: no cover
+
+        class Config:
+            json_encoders = {
+                datetime: lambda v: None
+                if not v
+                else (
+                    f"{str(v).split('+')[0].replace(' ', 'T')}Z"
+                    if "+" in str(v)
+                    else f"{str(v).replace(' ', 'T')}Z"
+                )
+            }
+
+
+class KeySearch(CamelBase):
+    results: List[Key]
+    offset: int
+    limit: int
+    total: int

meilisearch_python_sdk/models/documents.py

@@ -0,0 +1,10 @@
+from typing import Any, Dict, List
+
+from camel_converter.pydantic_base import CamelBase
+
+
+class DocumentsInfo(CamelBase):
+    results: List[Dict[str, Any]]
+    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