Merge pull request #738 from sanders41/decorators

Change decorator connection parameters

Author: sanders41

meilisearch_python_sdk/decorators.py

@@ -2,18 +2,27 @@
 
 import asyncio
 from functools import wraps
-from typing import Any, Callable
+from typing import Any, Callable, NamedTuple
 
 from meilisearch_python_sdk import AsyncClient, Client
 from meilisearch_python_sdk._utils import use_task_groups
 
 
+class ConnectionInfo(NamedTuple):
+    """Infomation on how to connect to Meilisearch.
+
+    url: URL for the Meilisearch server.
+    api_key: The API key for the server.
+    """
+
+    url: str
+    api_key: str
+
+
 def async_add_documments(
     *,
     index_name: str,
-    async_client: AsyncClient | None = None,
-    url: str | None = None,
-    api_token: str | None = None,
+    connection_info: AsyncClient | ConnectionInfo,
     batch_size: int | None = None,
     primary_key: str | None = None,
     wait_for_task: bool = False,
@@ -25,10 +34,8 @@ def async_add_documments(
     Args:
 
         index_name: The name of the index to which the documents should be added.
-        async_client: An AsyncClient instance. Default = None.
-        url: URL for the Meilisearch server. Default = None.
-        api_token: The API key for the server. This key needs to have permission to add documents
-            to the index, and create the index if it does not already exist. Default = None.
+        connection_info: Either an AsyncClient instance ConnectionInfo with informtaion on how to
+            connect to Meilisearch.
         batch_size: If provided the documents will be sent in batches of the specified size.
             Otherwise all documents are sent at once. Default = None.
         primary_key: The primary key of the documents. This will be ignored if already set.
@@ -48,9 +55,21 @@ def async_add_documments(
 
     Examples:
 
-        >>> from meilisearch_python_sdk.decorators import async_add_documents
+        >>> from meilisearch_python_sdk import AsyncClient
+        >>> from meilisearch_python_sdk.decorators import async_add_documents, ConnectionInfo
+        >>>
+        >>>
+        >>> # with `AsyncClient`
+        >>> client = AsyncClient(url="http://localhost:7700", api_key="masterKey")
+        >>> @async_add_documents(index_name="movies", connection_info=client)
+        >>> async def my_function() -> list[dict[str, Any]]:
+        >>>     return [{"id": 1, "title": "Test 1"}, {"id": 2, "title": "Test 2"}]
         >>>
-        >>> @async_add_documents(index_name="movies", url="http://localhost:7700", api_token="masterKey")
+        >>> # with `ConnectionInfo`
+        >>> @async_add_documents(
+                index_name="movies",
+                connection_info=ConnectionInfo(url="http://localhost:7700", api_key="masterKey",
+            )
         >>> async def my_function() -> list[dict[str, Any]]:
         >>>     return [{"id": 1, "title": "Test 1"}, {"id": 2, "title": "Test 2"}]
     """
@@ -59,16 +78,18 @@ def decorator(func: Callable) -> Callable:
         @wraps(func)
         async def wrapper(*args: Any, **kwargs: Any) -> Any:
             result = await func(*args, **kwargs)
-            if async_client:
+            if isinstance(connection_info, AsyncClient):
                 await _async_add_documents(
-                    async_client, index_name, result, batch_size, primary_key, wait_for_task
+                    connection_info,
+                    index_name,
+                    result,
+                    batch_size,
+                    primary_key,
+                    wait_for_task,
                 )
                 return result
 
-            if not url:
-                raise ValueError("Either an async_client or url is required")
-
-            async with AsyncClient(url, api_token) as client:
+            async with AsyncClient(connection_info.url, connection_info.api_key) as client:
                 await _async_add_documents(
                     client, index_name, result, batch_size, primary_key, wait_for_task
                 )
@@ -83,9 +104,7 @@ async def wrapper(*args: Any, **kwargs: Any) -> Any:
 def add_documments(
     *,
     index_name: str,
-    client: Client | None = None,
-    url: str | None = None,
-    api_token: str | None = None,
+    connection_info: Client | ConnectionInfo,
     batch_size: int | None = None,
     primary_key: str | None = None,
     wait_for_task: bool = False,
@@ -97,10 +116,8 @@ def add_documments(
     Args:
 
         index_name: The name of the index to which the documents should be added.
-        client: An Client instance. Default = None.
-        url: URL for the Meilisearch server. Default = None.
-        api_token: The API key for the server. This key needs to have permission to add documents
-            to the index, and create the index if it does not already exist. Default = None.
+        connection_info: Either an Client instance ConnectionInfo with informtaion on how to
+            connect to Meilisearch.
         batch_size: If provided the documents will be sent in batches of the specified size.
             Otherwise all documents are sent at once. Default = None.
         primary_key: The primary key of the documents. This will be ignored if already set.
@@ -120,9 +137,21 @@ def add_documments(
 
     Examples:
 
-        >>> from meilisearch_python_sdk.decorators import add_documents
+        >>> from meilisearch_python_sdk import Client
+        >>> from meilisearch_python_sdk.decorators import add_documents, ConnectionInfo
+        >>>
         >>>
-        >>> @add_documents(index_name="movies", url="http://localhost:7700", api_token="masterKey")
+        >>> # With `Client`
+        >>> client = Client(url="http://localhost:7700", api_key="masterKey")
+        >>> @add_documents(index_name="movies", connection_info=client)
+        >>> def my_function() -> list[dict[str, Any]]:
+        >>>     return [{"id": 1, "title": "Test 1"}, {"id": 2, "title": "Test 2"}]
+        >>>
+        >>> # With `ConnectionInfo`
+        >>> @add_documents(
+                index_name="movies",
+                connection_info=ConnectionInfo(url="http://localhost:7700", api_key="masterKey"),
+            )
         >>> def my_function() -> list[dict[str, Any]]:
         >>>     return [{"id": 1, "title": "Test 1"}, {"id": 2, "title": "Test 2"}]
     """
@@ -131,16 +160,25 @@ def decorator(func: Callable) -> Callable:
         @wraps(func)
         def wrapper(*args: Any, **kwargs: Any) -> Any:
             result = func(*args, **kwargs)
-            if client:
-                _add_documents(client, index_name, result, batch_size, primary_key, wait_for_task)
+            if isinstance(connection_info, Client):
+                _add_documents(
+                    connection_info,
+                    index_name,
+                    result,
+                    batch_size,
+                    primary_key,
+                    wait_for_task,
+                )
                 return result
 
-            if not url:
-                raise ValueError("Either an async_client or url is required")
-
-            decorator_client = Client(url, api_token)
+            decorator_client = Client(url=connection_info.url, api_key=connection_info.api_key)
             _add_documents(
-                decorator_client, index_name, result, batch_size, primary_key, wait_for_task
+                decorator_client,
+                index_name,
+                result,
+                batch_size,
+                primary_key,
+                wait_for_task,
             )
 
             return result

tests/test_decorators.py

@@ -2,7 +2,11 @@
 
 import pytest
 
-from meilisearch_python_sdk.decorators import add_documments, async_add_documments
+from meilisearch_python_sdk.decorators import (
+    ConnectionInfo,
+    add_documments,
+    async_add_documments,
+)
 
 
 @pytest.mark.parametrize("batch_size, primary_key", [(None, None), (10, "alternate")])
@@ -15,7 +19,7 @@ def test_add_documents_with_client(batch_size, primary_key, client):
 
     @add_documments(
         index_name=index_name,
-        client=client,
+        connection_info=client,
         batch_size=batch_size,
         primary_key=primary_key,
         wait_for_task=True,
@@ -35,7 +39,7 @@ def tester():
 
 
 @pytest.mark.parametrize("batch_size, primary_key", [(None, None), (10, "alternate")])
-def test_add_documents_with_url(batch_size, primary_key, client, base_url, master_key):
+def test_add_documents_with_connection_info(batch_size, primary_key, client, base_url, master_key):
     index_name = str(uuid4())
     documents = []
 
@@ -44,8 +48,7 @@ def test_add_documents_with_url(batch_size, primary_key, client, base_url, maste
 
     @add_documments(
         index_name=index_name,
-        url=base_url,
-        api_token=master_key,
+        connection_info=ConnectionInfo(url=base_url, api_key=master_key),
         batch_size=batch_size,
         primary_key=primary_key,
         wait_for_task=True,
@@ -64,18 +67,6 @@ def tester():
     assert result.results == documents
 
 
-def test_add_documents_no_client_or_url():
-    index_name = str(uuid4())
-    documents = [{"id": 1, "title": "Title 1"}, {"id": 2, "title": "Title 2"}]
-
-    @add_documments(index_name=index_name, wait_for_task=True)
-    def tester():
-        return documents
-
-    with pytest.raises(ValueError):
-        tester()
-
-
 @pytest.mark.parametrize("batch_size, primary_key", [(None, None), (10, "alternate")])
 async def test_async_add_documents_with_client(batch_size, primary_key, async_client):
     index_name = str(uuid4())
@@ -86,7 +77,7 @@ async def test_async_add_documents_with_client(batch_size, primary_key, async_cl
 
     @async_add_documments(
         index_name=index_name,
-        async_client=async_client,
+        connection_info=async_client,
         batch_size=batch_size,
         primary_key=primary_key,
         wait_for_task=True,
@@ -108,7 +99,7 @@ async def tester():
 
 
 @pytest.mark.parametrize("batch_size, primary_key", [(None, None), (10, "alternate")])
-async def test_async_add_documents_with_url(
+async def test_async_add_documents_with_connection_info(
     batch_size, primary_key, async_client, base_url, master_key
 ):
     index_name = str(uuid4())
@@ -119,8 +110,7 @@ async def test_async_add_documents_with_url(
 
     @async_add_documments(
         index_name=index_name,
-        url=base_url,
-        api_token=master_key,
+        connection_info=ConnectionInfo(url=base_url, api_key=master_key),
         batch_size=batch_size,
         primary_key=primary_key,
         wait_for_task=True,
@@ -139,15 +129,3 @@ async def tester():
 
     # order will be random since documents were added async so sort them first.
     assert sorted(result.results, key=lambda x: x["id"]) == documents
-
-
-async def test_async_add_documents_no_client():
-    index_name = str(uuid4())
-    documents = [{"id": 1, "title": "Title 1"}, {"id": 2, "title": "Title 2"}]
-
-    @async_add_documments(index_name=index_name, wait_for_task=True)
-    async def tester():
-        return documents
-
-    with pytest.raises(ValueError):
-        await tester()