Merge pull request #1379 from sanders41/meilisearch-1.16

Update for Meilisearch v1.16.0

Author: sanders41

meilisearch_python_sdk/_client.py

@@ -689,6 +689,9 @@ async def multi_search(
                 del q["limit"]
                 del q["offset"]
 
+            if query.media is None:
+                del q["media"]
+
             processed_queries.append(q)
 
         if federation:
@@ -1058,7 +1061,7 @@ async def wait_for_task(
 
         Examples
             >>> from meilisearch_python_sdk import AsyncClient
-            >>> >>> documents = [
+            >>> documents = [
             >>>     {"id": 1, "title": "Movie 1", "genre": "comedy"},
             >>>     {"id": 2, "title": "Movie 2", "genre": "drama"},
             >>> ]
@@ -1075,6 +1078,56 @@ async def wait_for_task(
             raise_for_status=raise_for_status,
         )
 
+    # No cover because it requires multiple instances of Meilisearch
+    async def transfer_documents(  # pragma: no cover
+        self,
+        url: str,
+        *,
+        api_key: str | None = None,
+        payload_size: str | None = None,
+        indexes: JsonMapping | None = None,
+    ) -> TaskInfo:
+        """Transfer settings and documents from one Meilisearch instance to another.
+
+        Args:
+            url: Where to send our settings and documents.
+            api_key: The API key with the rights to send the requests. Usually the master key of
+                the remote machine. Defaults to None.
+            payload_size: Human readable size defining the size of the payloads to send. Defaults
+                to 50 MiB.
+            indexes: A set of patterns of matching the indexes you want to export. Defaults to all
+                indexes without filter.
+
+        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
+            >>> async with Client("http://localhost.com", "masterKey") as client:
+            >>>     await index.transfer_documents(
+            >>>         "https://another-instance.com", api_key="otherMasterKey"
+            >>>     )
+        """
+        payload: JsonDict = {"url": url}
+
+        if api_key:
+            payload["apiKey"] = api_key
+
+        if payload:
+            payload["payloadSize"] = payload_size
+
+        if indexes:
+            payload["indexes"] = indexes
+
+        response = await self._http_requests.post(url, body=payload)
+
+        return TaskInfo(**response.json())
+
 
 class Client(BaseClient):
     """client to connect to the Meilisearch API."""
@@ -1968,7 +2021,7 @@ def wait_for_task(
 
         Examples
             >>> from meilisearch_python_sdk import Client
-            >>> >>> documents = [
+            >>> documents = [
             >>>     {"id": 1, "title": "Movie 1", "genre": "comedy"},
             >>>     {"id": 2, "title": "Movie 2", "genre": "drama"},
             >>> ]
@@ -1985,6 +2038,54 @@ def wait_for_task(
             raise_for_status=raise_for_status,
         )
 
+    # No cover because it requires multiple instances of Meilisearch
+    def transfer_documents(  # pragma: no cover
+        self,
+        url: str,
+        *,
+        api_key: str | None = None,
+        payload_size: str | None = None,
+        indexes: JsonMapping | None = None,
+    ) -> TaskInfo:
+        """Transfer settings and documents from one Meilisearch instance to another.
+
+        Args:
+            url: Where to send our settings and documents.
+            api_key: The API key with the rights to send the requests. Usually the master key of
+                the remote machine. Defaults to None.
+            payload_size: Human readable size defining the size of the payloads to send. Defaults
+                to 50 MiB.
+            indexes: A set of patterns of matching the indexes you want to export. Defaults to all
+                indexes without filter.
+
+        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 Client
+            >>> client = Client("http://localhost.com", "masterKey")
+            >>> index.transfer_documents("https://another-instance.com", api_key="otherMasterKey")
+        """
+        payload: JsonDict = {"url": url}
+
+        if api_key:
+            payload["apiKey"] = api_key
+
+        if payload:
+            payload["payloadSize"] = payload_size
+
+        if indexes:
+            payload["indexes"] = indexes
+
+        response = self._http_requests.post(url, body=payload)
+
+        return TaskInfo(**response.json())
+
 
 def _build_offset_limit_url(base: str, offset: int | None, limit: int | None) -> str:
     if offset is not None and limit is not None:

meilisearch_python_sdk/index.py

@@ -725,6 +725,7 @@ async def search(
         hybrid: Hybrid | None = None,
         locales: list[str] | None = None,
         retrieve_vectors: bool | None = None,
+        media: JsonMapping | None = None,
     ) -> SearchResults:
         """Search the index.
 
@@ -786,6 +787,13 @@ async def search(
             locales: Specifies the languages for the search. This parameter can only be used with
                 Milisearch >= v1.10.0. Defaults to None letting the Meilisearch pick.
             retrieve_vectors: Return document vector data with search result.
+            media: The content of media is used as if it were a document to generate request
+                fragments from the searchFragments parameter. Defaults to None. This parameter can
+                only be used with Meilisearch >= v1.16.0. In order to use this feature in
+                Meilisearch v1.16.0 you first need to enable the feature by sending a PATCH request
+                to /experimental-features with { "multimodal": true }. Because this feature is
+                experimental it may be removed or updated causing breaking changes in this library
+                without a major version bump so use with caution.
 
         Returns:
             Results of the search
@@ -830,6 +838,7 @@ async def search(
             ranking_score_threshold=ranking_score_threshold,
             locales=locales,
             retrieve_vectors=retrieve_vectors,
+            media=media,
         )
         search_url = f"{self._base_url_with_uid}/search"
 
@@ -1349,6 +1358,7 @@ async def get_documents(
         fields: list[str] | None = None,
         filter: Filter | None = None,
         retrieve_vectors: bool = False,
+        sort: str | None = None,
     ) -> DocumentsInfo:
         """Get a batch documents from the index.
 
@@ -1362,6 +1372,7 @@ async def get_documents(
             retrieve_vectors: If set to True the vectors will be returned with each document.
                 Defaults to False. Note: This parameter can only be
                 used with Meilisearch >= v1.13.0
+            sort: Attribute by which to sort the results. Defaults to None.
 
         Returns:
             Documents info.
@@ -1382,6 +1393,9 @@ async def get_documents(
             "limit": limit,
         }
 
+        if sort:
+            parameters["sort"] = sort
+
         if retrieve_vectors:
             parameters["retrieveVectors"] = "true"
 
@@ -5151,6 +5165,7 @@ def search(
         hybrid: Hybrid | None = None,
         locales: list[str] | None = None,
         retrieve_vectors: bool | None = None,
+        media: JsonMapping | None = None,
     ) -> SearchResults:
         """Search the index.
 
@@ -5212,6 +5227,13 @@ def search(
             locales: Specifies the languages for the search. This parameter can only be used with
                 Milisearch >= v1.10.0. Defaults to None letting the Meilisearch pick.
             retrieve_vectors: Return document vector data with search result.
+            media: The content of media is used as if it were a document to generate request
+                fragments from the searchFragments parameter. Defaults to None. This parameter can
+                only be used with Meilisearch >= v1.16.0. In order to use this feature in
+                Meilisearch v1.16.0 you first need to enable the feature by sending a PATCH request
+                to /experimental-features with { "multimodal": true }. Because this feature is
+                experimental it may be removed or updated causing breaking changes in this library
+                without a major version bump so use with caution.
 
         Returns:
             Results of the search
@@ -5256,6 +5278,7 @@ def search(
             ranking_score_threshold=ranking_score_threshold,
             locales=locales,
             retrieve_vectors=retrieve_vectors,
+            media=media,
         )
 
         if self._pre_search_plugins:
@@ -5584,6 +5607,7 @@ def get_documents(
         fields: list[str] | None = None,
         filter: Filter | None = None,
         retrieve_vectors: bool = False,
+        sort: str | None = None,
     ) -> DocumentsInfo:
         """Get a batch documents from the index.
 
@@ -5597,6 +5621,7 @@ def get_documents(
             retrieve_vectors: If set to True the vectors will be returned with each document.
                 Defaults to False. Note: This parameter can only be
                 used with Meilisearch >= v1.13.0
+            sort: Attribute by which to sort the results. Defaults to None.
 
         Returns:
             Documents info.
@@ -5617,6 +5642,9 @@ def get_documents(
             "limit": limit,
         }
 
+        if sort:
+            parameters["sort"] = sort
+
         if retrieve_vectors:
             parameters["retrieveVectors"] = "true"
 
@@ -5633,6 +5661,7 @@ def get_documents(
             parameters["fields"] = fields
 
         parameters["filter"] = filter
+
         response = self._http_requests.post(f"{self._documents_url}/fetch", body=parameters)
 
         return DocumentsInfo(**response.json())
@@ -8390,6 +8419,7 @@ def _process_search_parameters(
     locales: list[str] | None = None,
     retrieve_vectors: bool | None = None,
     exhaustive_facet_count: bool | None = None,
+    media: JsonMapping | None = None,
 ) -> JsonDict:
     if attributes_to_retrieve is None:
         attributes_to_retrieve = ["*"]
@@ -8444,6 +8474,9 @@ def _process_search_parameters(
     if exhaustive_facet_count is not None:
         body["exhaustivefacetCount"] = exhaustive_facet_count
 
+    if media is not None:
+        body["media"] = media
+
     return body
 
 

meilisearch_python_sdk/models/search.py

@@ -6,7 +6,7 @@
 from pydantic import Field, field_validator
 
 from meilisearch_python_sdk.errors import MeilisearchError
-from meilisearch_python_sdk.types import Filter, JsonDict
+from meilisearch_python_sdk.types import Filter, JsonDict, JsonMapping
 
 T = TypeVar("T")
 
@@ -71,6 +71,7 @@ class SearchParams(CamelBase):
     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

meilisearch_python_sdk/models/settings.py

@@ -3,8 +3,8 @@
 from enum import Enum
 from typing import Literal
 
-import pydantic
 from camel_converter.pydantic_base import CamelBase
+from pydantic import field_validator, model_validator
 
 from meilisearch_python_sdk.types import JsonDict
 
@@ -26,7 +26,7 @@ class Faceting(CamelBase):
     max_values_per_facet: int
     sort_facet_values_by: dict[str, str] | None = None
 
-    @pydantic.field_validator("sort_facet_values_by")  # type: ignore[attr-defined]
+    @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
@@ -96,6 +96,15 @@ class RestEmbedder(CamelBase):
     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):

tests/test_async_documents.py

@@ -728,14 +728,14 @@ async def test_get_documents_populated(async_index_with_documents):
 
 async def test_get_documents_offset_optional_params(async_index_with_documents):
     index = await async_index_with_documents()
-    response = await index.get_documents()
-    assert len(response.results) == 20
+    update_response = await index.update_sortable_attributes(["title"])
+    await async_wait_for_task(index.http_client, update_response.task_uid)
     response_offset_limit = await index.get_documents(
-        limit=3, offset=1, fields=["title", "overview"]
+        limit=3, offset=1, fields=["title", "overview"], sort="title:asc"
     )
+
     assert len(response_offset_limit.results) == 3
-    assert response_offset_limit.results[0]["title"] == response.results[1]["title"]
-    assert response_offset_limit.results[0]["overview"] == response.results[1]["overview"]
+    assert ["title", "overview"] == list(response_offset_limit.results[0].keys())
 
 
 async def test_get_documents_filter(async_index_with_documents):

tests/test_documents.py

@@ -648,12 +648,14 @@ def test_get_documents_populated(index_with_documents):
 
 def test_get_documents_offset_optional_params(index_with_documents):
     index = index_with_documents()
-    response = index.get_documents()
-    assert len(response.results) == 20
-    response_offset_limit = index.get_documents(limit=3, offset=1, fields=["title", "overview"])
+    update_response = index.update_sortable_attributes(["title"])
+    wait_for_task(index.http_client, update_response.task_uid)
+    response_offset_limit = index.get_documents(
+        limit=3, offset=1, fields=["title", "overview"], sort="title:asc"
+    )
+
     assert len(response_offset_limit.results) == 3
-    assert response_offset_limit.results[0]["title"] == response.results[1]["title"]
-    assert response_offset_limit.results[0]["overview"] == response.results[1]["overview"]
+    assert ["title", "overview"] == list(response_offset_limit.results[0].keys())
 
 
 def test_get_documents_filter(index_with_documents):

tests/test_index.py

@@ -4,6 +4,7 @@
 from meilisearch_python_sdk._http_requests import HttpRequests
 from meilisearch_python_sdk._task import wait_for_task
 from meilisearch_python_sdk.errors import MeilisearchApiError
+from meilisearch_python_sdk.index import _process_search_parameters
 from meilisearch_python_sdk.models.settings import (
     Embedders,
     Faceting,
@@ -1007,3 +1008,17 @@ def test_reset_prefix_search_opt_out(empty_index):
     result = index.get_settings()
 
     assert result.prefix_search == "indexingTime"
+
+
+def test_process_search_parameters_media():
+    expected = {"test": "test"}
+    result = _process_search_parameters(media=expected)
+
+    assert result.get("media") is not None
+    assert result["media"] == expected
+
+
+def test_process_search_parameters_no_media():
+    result = _process_search_parameters()
+
+    assert "media" not in result.keys()