meilisearch-python-sdk 3.0.1__tar.gz → 3.2.0__tar.gz

{meilisearch_python_sdk-3.0.1 → meilisearch_python_sdk-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: meilisearch-python-sdk
-Version: 3.0.1
+Version: 3.2.0
 Summary: A Python client providing both async and sync support for the Meilisearch API
 Home-page: https://github.com/sanders41/meilisearch-python-sdk
 License: MIT

{meilisearch_python_sdk-3.0.1 → meilisearch_python_sdk-3.2.0}/meilisearch_python_sdk/_client.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from datetime import datetime, timezone
 from ssl import SSLContext
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 import jwt
 from httpx import AsyncClient as HttpxAsyncClient
@@ -27,12 +27,13 @@ from meilisearch_python_sdk.models.settings import MeilisearchSettings
 from meilisearch_python_sdk.models.task import TaskInfo, TaskResult, TaskStatus
 from meilisearch_python_sdk.models.version import Version
 from meilisearch_python_sdk.plugins import AsyncIndexPlugins, IndexPlugins
+from meilisearch_python_sdk.types import JsonDict
 
 if TYPE_CHECKING:  # pragma: no cover
     import sys
     from types import TracebackType
 
-    from meilisearch_python_sdk.types import JsonDict, JsonMapping
+    from meilisearch_python_sdk.types import JsonMapping
 
     if sys.version_info >= (3, 11):
         from typing import Self
@@ -219,6 +220,7 @@ class AsyncClient(BaseClient):
         wait: bool = True,
         timeout_in_ms: int | None = None,
         plugins: AsyncIndexPlugins | None = None,
+        hits_type: Any = JsonDict,
     ) -> AsyncIndex:
         """Creates a new index.
 
@@ -238,6 +240,8 @@ class AsyncClient(BaseClient):
                 MeilisearchTimeoutError. `None` can also be passed to wait indefinitely. Be aware that
                 if the `None` option is used the wait time could be very long. Defaults to None.
             plugins: Optional plugins can be provided to extend functionality.
+            hits_type: Allows for a custom type to be passed to use for hits. Defaults to
+                JsonDict
 
         Returns:
 
@@ -263,6 +267,7 @@ class AsyncClient(BaseClient):
             timeout_in_ms=timeout_in_ms,
             plugins=plugins,
             json_handler=self.json_handler,
+            hits_type=hits_type,
         )
 
     async def create_snapshot(self) -> TaskInfo:
@@ -436,7 +441,12 @@ class AsyncClient(BaseClient):
         return ClientStats(**response.json())
 
     async def get_or_create_index(
-        self, uid: str, primary_key: str | None = None, *, plugins: AsyncIndexPlugins | None = None
+        self,
+        uid: str,
+        primary_key: str | None = None,
+        *,
+        plugins: AsyncIndexPlugins | None = None,
+        hits_type: Any = JsonDict,
     ) -> AsyncIndex:
         """Get an index, or create it if it doesn't exist.
 
@@ -445,6 +455,8 @@ class AsyncClient(BaseClient):
             uid: The index's unique identifier.
             primary_key: The primary key of the documents. Defaults to None.
             plugins: Optional plugins can be provided to extend functionality.
+            hits_type: Allows for a custom type to be passed to use for hits. Defaults to
+                JsonDict
 
         Returns:
 
@@ -467,7 +479,9 @@ class AsyncClient(BaseClient):
         except MeilisearchApiError as err:
             if "index_not_found" not in err.code:
                 raise
-            index_instance = await self.create_index(uid, primary_key, plugins=plugins)
+            index_instance = await self.create_index(
+                uid, primary_key, plugins=plugins, hits_type=hits_type
+            )
         return index_instance
 
     async def create_key(self, key: KeyCreate) -> Key:
@@ -618,12 +632,16 @@ class AsyncClient(BaseClient):
 
         return Key(**response.json())
 
-    async def multi_search(self, queries: list[SearchParams]) -> list[SearchResultsWithUID]:
+    async def multi_search(
+        self, queries: list[SearchParams], *, hits_type: Any = JsonDict
+    ) -> list[SearchResultsWithUID]:
         """Multi-index search.
 
         Args:
 
             queries: List of SearchParameters
+            hits_type: Allows for a custom type to be passed to use for hits. Defaults to
+                JsonDict
 
         Returns:
 
@@ -651,7 +669,7 @@ class AsyncClient(BaseClient):
             body={"queries": [x.model_dump(by_alias=True) for x in queries]},  # type: ignore[attr-defined]
         )
 
-        return [SearchResultsWithUID(**x) for x in response.json()["results"]]
+        return [SearchResultsWithUID[hits_type](**x) for x in response.json()["results"]]
 
     async def get_raw_index(self, uid: str) -> IndexInfo | None:
         """Gets the index and returns all the index information rather than an AsyncIndex instance.
@@ -1083,6 +1101,7 @@ class Client(BaseClient):
         wait: bool = True,
         timeout_in_ms: int | None = None,
         plugins: IndexPlugins | None = None,
+        hits_type: Any = JsonDict,
     ) -> Index:
         """Creates a new index.
 
@@ -1102,6 +1121,8 @@ class Client(BaseClient):
                 MeilisearchTimeoutError. `None` can also be passed to wait indefinitely. Be aware that
                 if the `None` option is used the wait time could be very long. Defaults to None.
             plugins: Optional plugins can be provided to extend functionality.
+            hits_type: Allows for a custom type to be passed to use for hits. Defaults to
+                JsonDict
 
         Returns:
 
@@ -1127,6 +1148,7 @@ class Client(BaseClient):
             timeout_in_ms=timeout_in_ms,
             plugins=plugins,
             json_handler=self.json_handler,
+            hits_type=hits_type,
         )
 
     def create_snapshot(self) -> TaskInfo:
@@ -1296,7 +1318,12 @@ class Client(BaseClient):
         return ClientStats(**response.json())
 
     def get_or_create_index(
-        self, uid: str, primary_key: str | None = None, *, plugins: IndexPlugins | None = None
+        self,
+        uid: str,
+        primary_key: str | None = None,
+        *,
+        plugins: IndexPlugins | None = None,
+        hits_type: Any = JsonDict,
     ) -> Index:
         """Get an index, or create it if it doesn't exist.
 
@@ -1305,6 +1332,8 @@ class Client(BaseClient):
             uid: The index's unique identifier.
             primary_key: The primary key of the documents. Defaults to None.
             plugins: Optional plugins can be provided to extend functionality.
+            hits_type: Allows for a custom type to be passed to use for hits. Defaults to
+                JsonDict
 
         Returns:
 
@@ -1327,7 +1356,9 @@ class Client(BaseClient):
         except MeilisearchApiError as err:
             if "index_not_found" not in err.code:
                 raise
-            index_instance = self.create_index(uid, primary_key, plugins=plugins)
+            index_instance = self.create_index(
+                uid, primary_key, plugins=plugins, hits_type=hits_type
+            )
         return index_instance
 
     def create_key(self, key: KeyCreate) -> Key:
@@ -1478,12 +1509,16 @@ class Client(BaseClient):
 
         return Key(**response.json())
 
-    def multi_search(self, queries: list[SearchParams]) -> list[SearchResultsWithUID]:
+    def multi_search(
+        self, queries: list[SearchParams], *, hits_type: Any = JsonDict
+    ) -> list[SearchResultsWithUID]:
         """Multi-index search.
 
         Args:
 
             queries: List of SearchParameters
+            hits_type: Allows for a custom type to be passed to use for hits. Defaults to
+                JsonDict
 
         Returns:
 
@@ -1511,7 +1546,7 @@ class Client(BaseClient):
             body={"queries": [x.model_dump(by_alias=True) for x in queries]},  # type: ignore[attr-defined]
         )
 
-        return [SearchResultsWithUID(**x) for x in response.json()["results"]]
+        return [SearchResultsWithUID[hits_type](**x) for x in response.json()["results"]]
 
     def get_raw_index(self, uid: str) -> IndexInfo | None:
         """Gets the index and returns all the index information rather than an Index instance.

meilisearch_python_sdk-3.2.0/meilisearch_python_sdk/_version.py

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

{meilisearch_python_sdk-3.0.1 → meilisearch_python_sdk-3.2.0}/meilisearch_python_sdk/index.py

@@ -52,11 +52,12 @@ from meilisearch_python_sdk.plugins import (
     Plugin,
     PostSearchPlugin,
 )
+from meilisearch_python_sdk.types import JsonDict
 
 if TYPE_CHECKING:  # pragma: no cover
     import sys
 
-    from meilisearch_python_sdk.types import Filter, JsonDict, JsonMapping
+    from meilisearch_python_sdk.types import Filter, JsonMapping
 
     if sys.version_info >= (3, 11):
         from typing import Self
@@ -72,11 +73,13 @@ class _BaseIndex:
         created_at: str | datetime | None = None,
         updated_at: str | datetime | None = None,
         json_handler: BuiltinHandler | OrjsonHandler | UjsonHandler | None = None,
+        hits_type: Any = JsonDict,
     ):
         self.uid = uid
         self.primary_key = primary_key
         self.created_at: datetime | None = iso_to_date_time(created_at)
         self.updated_at: datetime | None = iso_to_date_time(updated_at)
+        self.hits_type = hits_type
         self._base_url = "indexes/"
         self._base_url_with_uid = f"{self._base_url}{self.uid}"
         self._documents_url = f"{self._base_url_with_uid}/documents"
@@ -113,6 +116,8 @@ class AsyncIndex(_BaseIndex):
         updated_at: str | datetime | None = None,
         plugins: AsyncIndexPlugins | None = None,
         json_handler: BuiltinHandler | OrjsonHandler | UjsonHandler | None = None,
+        *,
+        hits_type: Any = JsonDict,
     ):
         """Class initializer.
 
@@ -129,8 +134,17 @@ class AsyncIndex(_BaseIndex):
                 (uses the json module from the standard library), OrjsonHandler (uses orjson), or
                 UjsonHandler (uses ujson). Note that in order use orjson or ujson the corresponding
                 extra needs to be included. Default: BuiltinHandler.
+            hits_type: Allows for a custom type to be passed to use for hits. Defaults to
+                JsonDict
         """
-        super().__init__(uid, primary_key, created_at, updated_at, json_handler=json_handler)
+        super().__init__(
+            uid=uid,
+            primary_key=primary_key,
+            created_at=created_at,
+            updated_at=updated_at,
+            json_handler=json_handler,
+            hits_type=hits_type,
+        )
         self.http_client = http_client
         self._http_requests = AsyncHttpRequests(http_client, json_handler=self._json_handler)
         self.plugins = plugins
@@ -639,6 +653,7 @@ class AsyncIndex(_BaseIndex):
         timeout_in_ms: int | None = None,
         plugins: AsyncIndexPlugins | None = None,
         json_handler: BuiltinHandler | OrjsonHandler | UjsonHandler | None = None,
+        hits_type: Any = JsonDict,
     ) -> Self:
         """Creates a new index.
 
@@ -667,6 +682,8 @@ class AsyncIndex(_BaseIndex):
                 (uses the json module from the standard library), OrjsonHandler (uses orjson), or
                 UjsonHandler (uses ujson). Note that in order use orjson or ujson the corresponding
                 extra needs to be included. Default: BuiltinHandler.
+            hits_type: Allows for a custom type to be passed to use for hits. Defaults to
+                JsonDict
 
         Returns:
 
@@ -708,6 +725,7 @@ class AsyncIndex(_BaseIndex):
             updated_at=index_dict["updatedAt"],
             plugins=plugins,
             json_handler=json_handler,
+            hits_type=hits_type,
         )
 
         if settings:
@@ -763,6 +781,7 @@ class AsyncIndex(_BaseIndex):
         hits_per_page: int | None = None,
         page: int | None = None,
         attributes_to_search_on: list[str] | None = None,
+        distinct: str | None = None,
         show_ranking_score: bool = False,
         show_ranking_score_details: bool = False,
         ranking_score_threshold: float | None = None,
@@ -797,6 +816,9 @@ class AsyncIndex(_BaseIndex):
             page: Sets the specific results page to fetch.
             attributes_to_search_on: List of field names. Allow search over a subset of searchable
                 attributes without modifying the index settings. Defaults to None.
+            distinct: If set the distinct value will return at most one result for the
+                filterable attribute. Note that a filterable attributes must be set for this work.
+                Defaults to None.
             show_ranking_score: If set to True the ranking score will be returned with each document
                 in the search. Defaults to False.
             show_ranking_score_details: If set to True the ranking details will be returned with
@@ -863,6 +885,7 @@ class AsyncIndex(_BaseIndex):
             hits_per_page=hits_per_page,
             page=page,
             attributes_to_search_on=attributes_to_search_on,
+            distinct=distinct,
             show_ranking_score=show_ranking_score,
             show_ranking_score_details=show_ranking_score_details,
             vector=vector,
@@ -893,6 +916,7 @@ class AsyncIndex(_BaseIndex):
                 hits_per_page=hits_per_page,
                 page=page,
                 attributes_to_search_on=attributes_to_search_on,
+                distinct=distinct,
                 show_ranking_score=show_ranking_score,
                 show_ranking_score_details=show_ranking_score_details,
                 vector=vector,
@@ -925,6 +949,7 @@ class AsyncIndex(_BaseIndex):
                                 hits_per_page=hits_per_page,
                                 page=page,
                                 attributes_to_search_on=attributes_to_search_on,
+                                distinct=distinct,
                                 show_ranking_score=show_ranking_score,
                                 show_ranking_score_details=show_ranking_score_details,
                                 vector=vector,
@@ -934,7 +959,7 @@ class AsyncIndex(_BaseIndex):
                 concurrent_tasks.append(self._http_requests.post(search_url, body=body))
 
                 responses = await asyncio.gather(*concurrent_tasks)
-                result = SearchResults(**responses[-1].json())
+                result = SearchResults[self.hits_type](**responses[-1].json())  # type: ignore[name-defined]
                 if self._post_search_plugins:
                     post = await AsyncIndex._run_plugins(
                         self._post_search_plugins, AsyncEvent.POST, search_results=result
@@ -968,6 +993,7 @@ class AsyncIndex(_BaseIndex):
                                 hits_per_page=hits_per_page,
                                 page=page,
                                 attributes_to_search_on=attributes_to_search_on,
+                                distinct=distinct,
                                 show_ranking_score=show_ranking_score,
                                 show_ranking_score_details=show_ranking_score_details,
                                 vector=vector,
@@ -977,7 +1003,7 @@ class AsyncIndex(_BaseIndex):
                 response_coroutine = tg.create_task(self._http_requests.post(search_url, body=body))
 
             response = await response_coroutine
-            result = SearchResults(**response.json())
+            result = SearchResults[self.hits_type](**response.json())  # type: ignore[name-defined]
             if self._post_search_plugins:
                 post = await AsyncIndex._run_plugins(
                     self._post_search_plugins, AsyncEvent.POST, search_results=result
@@ -988,7 +1014,7 @@ class AsyncIndex(_BaseIndex):
             return result
 
         response = await self._http_requests.post(search_url, body=body)
-        result = SearchResults(**response.json())
+        result = SearchResults[self.hits_type](**response.json())  # type: ignore[name-defined]
 
         if self._post_search_plugins:
             post = await AsyncIndex._run_plugins(
@@ -1324,7 +1350,7 @@ class AsyncIndex(_BaseIndex):
             f"{self._base_url_with_uid}/similar", body=payload
         )
 
-        return SimilarSearchResults(**response.json())
+        return SimilarSearchResults[self.hits_type](**response.json())  # type: ignore[name-defined]
 
     async def get_document(self, document_id: str) -> JsonDict:
         """Get one document with given document identifier.
@@ -4516,6 +4542,8 @@ class Index(_BaseIndex):
         updated_at: str | datetime | None = None,
         plugins: IndexPlugins | None = None,
         json_handler: BuiltinHandler | OrjsonHandler | UjsonHandler | None = None,
+        *,
+        hits_type: Any = JsonDict,
     ):
         """Class initializer.
 
@@ -4532,8 +4560,17 @@ class Index(_BaseIndex):
                 (uses the json module from the standard library), OrjsonHandler (uses orjson), or
                 UjsonHandler (uses ujson). Note that in order use orjson or ujson the corresponding
                 extra needs to be included. Default: BuiltinHandler.
+            hits_type: Allows for a custom type to be passed to use for hits. Defaults to
+                JsonDict
         """
-        super().__init__(uid, primary_key, created_at, updated_at, json_handler=json_handler)
+        super().__init__(
+            uid=uid,
+            primary_key=primary_key,
+            created_at=created_at,
+            updated_at=updated_at,
+            json_handler=json_handler,
+            hits_type=hits_type,
+        )
         self.http_client = http_client
         self._http_requests = HttpRequests(http_client, json_handler=self._json_handler)
         self.plugins = plugins
@@ -4916,6 +4953,7 @@ class Index(_BaseIndex):
         timeout_in_ms: int | None = None,
         plugins: IndexPlugins | None = None,
         json_handler: BuiltinHandler | OrjsonHandler | UjsonHandler | None = None,
+        hits_type: Any = JsonDict,
     ) -> Self:
         """Creates a new index.
 
@@ -4944,6 +4982,8 @@ class Index(_BaseIndex):
                 (uses the json module from the standard library), OrjsonHandler (uses orjson), or
                 UjsonHandler (uses ujson). Note that in order use orjson or ujson the corresponding
                 extra needs to be included. Default: BuiltinHandler.
+            hits_type: Allows for a custom type to be passed to use for hits. Defaults to
+                JsonDict
 
         Returns:
 
@@ -4980,6 +5020,7 @@ class Index(_BaseIndex):
             updated_at=index_dict["updatedAt"],
             plugins=plugins,
             json_handler=json_handler,
+            hits_type=hits_type,
         )
 
         if settings:
@@ -5033,6 +5074,7 @@ class Index(_BaseIndex):
         hits_per_page: int | None = None,
         page: int | None = None,
         attributes_to_search_on: list[str] | None = None,
+        distinct: str | None = None,
         show_ranking_score: bool = False,
         show_ranking_score_details: bool = False,
         ranking_score_threshold: float | None = None,
@@ -5067,6 +5109,9 @@ class Index(_BaseIndex):
             page: Sets the specific results page to fetch.
             attributes_to_search_on: List of field names. Allow search over a subset of searchable
                 attributes without modifying the index settings. Defaults to None.
+            distinct: If set the distinct value will return at most one result for the
+                filterable attribute. Note that a filterable attributes must be set for this work.
+                Defaults to None.
             show_ranking_score: If set to True the ranking score will be returned with each document
                 in the search. Defaults to False.
             show_ranking_score_details: If set to True the ranking details will be returned with
@@ -5133,6 +5178,7 @@ class Index(_BaseIndex):
             hits_per_page=hits_per_page,
             page=page,
             attributes_to_search_on=attributes_to_search_on,
+            distinct=distinct,
             show_ranking_score=show_ranking_score,
             show_ranking_score_details=show_ranking_score_details,
             vector=vector,
@@ -5162,6 +5208,7 @@ class Index(_BaseIndex):
                 hits_per_page=hits_per_page,
                 page=page,
                 attributes_to_search_on=attributes_to_search_on,
+                distinct=distinct,
                 show_ranking_score=show_ranking_score,
                 show_ranking_score_details=show_ranking_score_details,
                 vector=vector,
@@ -5169,7 +5216,7 @@ class Index(_BaseIndex):
             )
 
         response = self._http_requests.post(f"{self._base_url_with_uid}/search", body=body)
-        result = SearchResults(**response.json())
+        result = SearchResults[self.hits_type](**response.json())  # type: ignore[name-defined]
         if self._post_search_plugins:
             post = Index._run_plugins(self._post_search_plugins, Event.POST, search_results=result)
             if post.get("search_result"):
@@ -5408,7 +5455,7 @@ class Index(_BaseIndex):
 
         response = self._http_requests.post(f"{self._base_url_with_uid}/similar", body=payload)
 
-        return SimilarSearchResults(**response.json())
+        return SimilarSearchResults[self.hits_type](**response.json())  # type: ignore[name-defined]
 
     def get_document(self, document_id: str) -> JsonDict:
         """Get one document with given document identifier.
@@ -8204,6 +8251,7 @@ def _process_search_parameters(
     hits_per_page: int | None = None,
     page: int | None = None,
     attributes_to_search_on: list[str] | None = None,
+    distinct: str | None = None,
     show_ranking_score: bool = False,
     show_ranking_score_details: bool = False,
     ranking_score_threshold: float | None = None,
@@ -8242,6 +8290,9 @@ def _process_search_parameters(
     if facet_query:
         body["facetQuery"] = facet_query
 
+    if distinct:
+        body["distinct"] = distinct
+
     if show_ranking_score_details:
         body["showRankingScoreDetails"] = show_ranking_score_details
 

{meilisearch_python_sdk-3.0.1 → meilisearch_python_sdk-3.2.0}/meilisearch_python_sdk/models/search.py

@@ -1,13 +1,15 @@
 from __future__ import annotations
 
-from typing import Literal
+from typing import Generic, Literal, TypeVar
 
-import pydantic
 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
 
+T = TypeVar("T")
+
 
 class FacetHits(CamelBase):
     value: str
@@ -27,7 +29,7 @@ class Hybrid(CamelBase):
 
 class SearchParams(CamelBase):
     index_uid: str
-    query: str | None = pydantic.Field(None, alias="q")
+    query: str | None = Field(None, alias="q")
     offset: int = 0
     limit: int = 20
     filter: Filter | None = None
@@ -51,7 +53,7 @@ class SearchParams(CamelBase):
     vector: list[float] | None = None
     hybrid: Hybrid | None = None
 
-    @pydantic.field_validator("ranking_score_threshold", mode="before")  # type: ignore[attr-defined]
+    @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:
@@ -60,8 +62,8 @@ class SearchParams(CamelBase):
         return v
 
 
-class SearchResults(CamelBase):
-    hits: list[JsonDict]
+class SearchResults(CamelBase, Generic[T]):
+    hits: list[T]
     offset: int | None = None
     limit: int | None = None
     estimated_total_hits: int | None = None
@@ -75,12 +77,12 @@ class SearchResults(CamelBase):
     semantic_hit_count: int | None = None
 
 
-class SearchResultsWithUID(SearchResults):
+class SearchResultsWithUID(SearchResults, Generic[T]):
     index_uid: str
 
 
-class SimilarSearchResults(CamelBase):
-    hits: list[JsonDict]
+class SimilarSearchResults(CamelBase, Generic[T]):
+    hits: list[T]
     id: str
     processing_time_ms: int
     limit: int | None = None

{meilisearch_python_sdk-3.0.1 → meilisearch_python_sdk-3.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "meilisearch-python-sdk"
-version = "3.0.1"
+version = "3.2.0"
 description = "A Python client providing both async and sync support for the Meilisearch API"
 authors = ["Paul Sanders <psanders1@gmail.com>"]
 license = "MIT"
@@ -40,15 +40,15 @@ all = ["orjson", "ujson"]
 
 [tool.poetry.group.dev.dependencies]
 mkdocs = "1.6.0"
-mkdocs-material = "9.5.30"
+mkdocs-material = "9.5.31"
 mkdocstrings = {version = "0.25.2", extras = ["python"]}
-mypy = "1.11.0"
+mypy = "1.11.1"
 pre-commit = "3.8.0"
 pytest = "8.3.2"
 pytest-cov = "5.0.0"
 pytest-asyncio = "0.23.8"
 pytest-xdist = "3.6.1"
-ruff = "0.5.5"
+ruff = "0.6.1"
 tomli = {version = "2.0.1", python = "<3.11"}
 types-aiofiles = "24.1.0.20240626"
 typing-extensions = "4.12.2"

meilisearch_python_sdk-3.0.1/meilisearch_python_sdk/_version.py

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