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

meilisearch_python_sdk/models/version.py

@@ -0,0 +1,9 @@
+from datetime import datetime
+
+from camel_converter.pydantic_base import CamelBase
+
+
+class Version(CamelBase):
+    commit_sha: str
+    commit_date: datetime | str
+    pkg_version: str

meilisearch_python_sdk/models/webhook.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from camel_converter.pydantic_base import CamelBase
+
+
+class Webhook(CamelBase):
+    uuid: str
+    url: str
+    headers: dict[str, str] | None = None
+    is_editable: bool
+
+
+class Webhooks(CamelBase):
+    results: list[Webhook]
+
+
+class WebhookCreate(CamelBase):
+    url: str
+    headers: dict[str, str] | None = None
+
+
+class WebhookUpdate(CamelBase):
+    url: str | None = None
+    headers: dict[str, str] | None = None

meilisearch_python_sdk/plugins.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from enum import Enum
+from typing import TYPE_CHECKING, Any, NamedTuple, Protocol
+
+if TYPE_CHECKING:  # pragma: no cover
+    from meilisearch_python_sdk.models.search import FacetSearchResults, SearchResults
+    from meilisearch_python_sdk.models.task import TaskInfo
+    from meilisearch_python_sdk.types import JsonDict, JsonMapping
+
+
+class AsyncEvent(Enum):
+    PRE = "pre"
+    CONCURRENT = "concurrent"
+    POST = "post"
+
+
+class Event(Enum):
+    PRE = "pre"
+    POST = "post"
+
+
+class AsyncPlugin(Protocol):
+    CONCURRENT_EVENT: bool
+    POST_EVENT: bool
+    PRE_EVENT: bool
+
+    async def run_plugin(
+        self, event: AsyncEvent, **kwargs: Any
+    ) -> (
+        None | list[JsonDict] | TaskInfo | list[TaskInfo] | SearchResults | FacetSearchResults
+    ):  # pragma: no cover
+        ...
+
+
+class AsyncDocumentPlugin(Protocol):
+    CONCURRENT_EVENT: bool
+    POST_EVENT: bool
+    PRE_EVENT: bool
+
+    async def run_document_plugin(
+        self,
+        event: AsyncEvent,
+        *,
+        documents: Sequence[JsonMapping],
+        primary_key: str | None,
+        **kwargs: Any,
+    ) -> Sequence[JsonMapping] | None:  # pragma: no cover
+        ...
+
+
+class AsyncPostSearchPlugin(Protocol):
+    CONCURRENT_EVENT: bool
+    POST_EVENT: bool
+    PRE_EVENT: bool
+
+    async def run_post_search_plugin(
+        self,
+        event: AsyncEvent,
+        *,
+        search_results: SearchResults,
+        **kwargs: Any,
+    ) -> SearchResults | None:  # pragma: no cover
+        ...
+
+
+class Plugin(Protocol):
+    POST_EVENT: bool
+    PRE_EVENT: bool
+
+    def run_plugin(
+        self, event: Event, **kwargs: Any
+    ) -> (
+        None | list[JsonDict] | TaskInfo | list[TaskInfo] | SearchResults | FacetSearchResults
+    ):  # pragma: no cover
+        ...
+
+
+class DocumentPlugin(Protocol):
+    POST_EVENT: bool
+    PRE_EVENT: bool
+
+    def run_document_plugin(
+        self,
+        event: Event,
+        *,
+        documents: Sequence[JsonMapping],
+        primary_key: str | None,
+        **kwargs: Any,
+    ) -> Sequence[JsonMapping] | None:  # pragma: no cover
+        ...
+
+
+class PostSearchPlugin(Protocol):
+    POST_EVENT: bool
+    PRE_EVENT: bool
+
+    def run_post_search_plugin(
+        self, event: Event, *, search_results: SearchResults, **kwargs: Any
+    ) -> SearchResults | None:  # pragma: no cover
+        ...
+
+
+class AsyncIndexPlugins(NamedTuple):
+    add_documents_plugins: Sequence[AsyncPlugin | AsyncDocumentPlugin] | None = None
+    delete_all_documents_plugins: Sequence[AsyncPlugin] | None = None
+    delete_document_plugins: Sequence[AsyncPlugin] | None = None
+    delete_documents_plugins: Sequence[AsyncPlugin] | None = None
+    delete_documents_by_filter_plugins: Sequence[AsyncPlugin] | None = None
+    facet_search_plugins: Sequence[AsyncPlugin] | None = None
+    search_plugins: Sequence[AsyncPlugin | AsyncPostSearchPlugin] | None = None
+    update_documents_plugins: Sequence[AsyncPlugin | AsyncDocumentPlugin] | None = None
+
+
+class IndexPlugins(NamedTuple):
+    add_documents_plugins: Sequence[Plugin | DocumentPlugin] | None = None
+    delete_all_documents_plugins: Sequence[Plugin] | None = None
+    delete_document_plugins: Sequence[Plugin] | None = None
+    delete_documents_plugins: Sequence[Plugin] | None = None
+    delete_documents_by_filter_plugins: Sequence[Plugin] | None = None
+    facet_search_plugins: Sequence[Plugin] | None = None
+    search_plugins: Sequence[Plugin | PostSearchPlugin] | None = None
+    update_documents_plugins: Sequence[Plugin | DocumentPlugin] | None = None

meilisearch_python_sdk/types.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from collections.abc import MutableMapping
+from typing import Any, TypeAlias
+
+Filter: TypeAlias = str | list[str | list[str]]
+JsonDict: TypeAlias = dict[str, Any]
+JsonMapping: TypeAlias = MutableMapping[str, Any]

meilisearch_python_sdk-5.5.0.dist-info/METADATA

@@ -0,0 +1,279 @@
+Metadata-Version: 2.4
+Name: meilisearch-python-sdk
+Version: 5.5.0
+Summary: A Python client providing both async and sync support for the Meilisearch API
+Project-URL: repository, https://github.com/sanders41/meilisearch-python-sdk
+Project-URL: homepage, https://github.com/sanders41/meilisearch-python-sdk
+Project-URL: documentation, https://meilisearch-python-sdk.paulsanders.dev
+Author-email: Paul Sanders <paul@paulsanders.dev>
+License: MIT License
+        
+        Copyright (c) 2021 Paul Sanders
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: async,client,meilisearch,python,sdk
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: aiofiles>=0.7
+Requires-Dist: camel-converter[pydantic]>=1.0.0
+Requires-Dist: httpx[http2]>=0.17
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyjwt>=2.3.0
+Provides-Extra: all
+Requires-Dist: orjson; extra == 'all'
+Requires-Dist: ujson; extra == 'all'
+Provides-Extra: orjson
+Requires-Dist: orjson>=3.10.6; extra == 'orjson'
+Provides-Extra: ujson
+Requires-Dist: ujson>=5.10.0; extra == 'ujson'
+Description-Content-Type: text/markdown
+
+# Meilisearch Python SDK
+
+[![Tests Status](https://github.com/sanders41/meilisearch-python-sdk/actions/workflows/testing.yml/badge.svg?branch=main&event=push)](https://github.com/sanders41/meilisearch-python-sdk/actions?query=workflow%3ATesting+branch%3Amain+event%3Apush)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/sanders41/meilisearch-python-sdk/main.svg)](https://results.pre-commit.ci/latest/github/sanders41/meilisearch-python-sdk/main)
+[![Coverage](https://codecov.io/github/sanders41/meilisearch-python-sdk/coverage.svg?branch=main)](https://codecov.io/gh/sanders41/meilisearch-python-sdk)
+[![PyPI version](https://badge.fury.io/py/meilisearch-python-sdk.svg)](https://badge.fury.io/py/meilisearch-python-sdk)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/meilisearch-python-sdk?color=5cc141)](https://github.com/sanders41/meilisearch-python-sdk)
+
+Meilisearch Python SDK provides both an async and sync client for the
+[Meilisearch](https://github.com/meilisearch/meilisearch) API.
+
+Which client to use depends on your use case. If the code base you are working with uses asyncio,
+for example if you are using [FastAPI](https://fastapi.tiangolo.com/), choose the `AsyncClient`,
+otherwise choose the sync `Client`. The functionality of the two clients is the same, the difference
+being that the `AsyncClient` provides async methods and uses the `AsyncIndex` with its own
+additional async methods. On the other hand, `Client` provides blocking methods and uses the `Index`
+with its own blocking methods.
+
+## Installation
+
+Using a virtual environment is recommended for installing this package. Once the virtual
+environment is created and activated, install the package with:
+
+```sh
+pip install meilisearch-python-sdk
+```
+
+## Run Meilisearch
+
+There are several ways to
+[run Meilisearch](https://www.meilisearch.com/docs/learn/getting_started/installation).
+Pick the one that works best for your use case and then start the server.
+
+As as example to use Docker:
+
+```sh
+docker pull getmeili/meilisearch:latest
+docker run -it --rm -p 7700:7700 getmeili/meilisearch:latest ./meilisearch --master-key=masterKey
+```
+
+## Usage
+
+### Add Documents
+
+#### AsyncClient
+
+- Note: `client.index("books") creates an instance of an AsyncIndex object but does not make a
+  network call to send the data yet so it does not need to be awaited.
+
+```py
+from meilisearch_python_sdk import AsyncClient
+
+async with AsyncClient('http://127.0.0.1:7700', 'masterKey') as client:
+    index = client.index("books")
+
+    documents = [
+        {"id": 1, "title": "Ready Player One"},
+        {"id": 42, "title": "The Hitchhiker's Guide to the Galaxy"},
+    ]
+
+    await index.add_documents(documents)
+```
+
+#### Client
+
+```py
+from meilisearch_python_sdk import Client
+
+with Client('http://127.0.0.1:7700', 'masterKey') as client:
+    index = client.index("books")
+
+    documents = [
+        {"id": 1, "title": "Ready Player One"},
+        {"id": 42, "title": "The Hitchhiker's Guide to the Galaxy"},
+    ]
+
+    index.add_documents(documents)
+```
+
+The server will return an update id that can be used to
+[get the status](https://www.meilisearch.com/docs/reference/api/tasks#status)
+of the updates. To do this you would save the result response from adding the documents to a
+variable, this will be an `UpdateId` object, and use it to check the status of the updates.
+
+#### AsyncClient
+
+```py
+task = await index.add_documents([{"id": 1, "title": "test"}])
+status = await client.get_task(task.task_uid)
+```
+
+#### Client
+
+```py
+task = index.add_documents([{"id": 1, "title": "test"}])
+status = client.get_task(task.task_uid)
+```
+
+### Basic Searching
+
+#### AsyncClient
+
+```py
+search_result = await index.search("ready player")
+```
+
+#### Client
+
+```py
+search_result = index.search("ready player")
+```
+
+### Base Search Results: SearchResults object with values
+
+```py
+SearchResults(
+    hits = [
+        {
+            "id": 1,
+            "title": "Ready Player One",
+        },
+    ],
+    offset = 0,
+    limit = 20,
+    nb_hits = 1,
+    exhaustive_nb_hits = bool,
+    facets_distributionn = None,
+    processing_time_ms = 1,
+    query = "ready player",
+)
+```
+
+### Custom Search
+
+Information about the parameters can be found in the
+[search parameters](https://docs.meilisearch.com/reference/features/search_parameters.html) section
+of the documentation.
+
+#### AsyncClient
+
+```py
+await index.search(
+    "guide",
+    attributes_to_highlight=["title"],
+    filters="book_id > 10"
+)
+```
+
+#### Client
+
+```py
+index.search(
+    "guide",
+    attributes_to_highlight=["title"],
+    filters="book_id > 10"
+)
+```
+
+### Custom Search Results: SearchResults object with values
+
+```py
+SearchResults(
+    hits = [
+        {
+            "id": 42,
+            "title": "The Hitchhiker's Guide to the Galaxy",
+            "_formatted": {
+                "id": 42,
+                "title": "The Hitchhiker's Guide to the <em>Galaxy</em>"
+            }
+        },
+    ],
+    offset = 0,
+    limit = 20,
+    nb_hits = 1,
+    exhaustive_nb_hits = bool,
+    facets_distributionn = None,
+    processing_time_ms = 5,
+    query = "galaxy",
+)
+```
+
+## Benchmark
+
+The following benchmarks compare this library to the official
+[Meilisearch Python](https://github.com/meilisearch/meilisearch-python) library. Note that all
+of the performance gains seen with the `AsyncClient` are achieved by taking advantage of asyncio.
+This means that if your code is not taking advantage of asyncio or it does not block the event loop,
+the gains here will not be seen and the performance between the clients will be very similar.
+
+### Add Documents in Batches
+
+This test compares how long it takes to send 1 million documents in batches of 1 thousand to the
+Meilisearch server for indexing (lower is better). The time does not take into account how long
+Meilisearch takes to index the documents since that is outside of the library functionality.
+
+![Add Documents in Batches](https://raw.githubusercontent.com/sanders41/meilisearch-python-sdk/main/assets/add_in_batches.png)
+
+### Multiple Searches
+
+This test compares how long it takes to complete 1000 searches (lower is better)
+
+![Multiple Searches](https://raw.githubusercontent.com/sanders41/meilisearch-python-sdk/main/assets/searches.png)
+
+### Independent testing
+
+[Prashanth Rao](https://github.com/prrao87) did some independent testing and found this async client
+to be ~30% faster than the sync client for data ingestion. You can find a good write-up of the
+results how he tested them in his [blog post](https://thedataquarry.com/posts/meilisearch-async/).
+
+## Testing
+
+[pytest-meilisearch](https://github.com/sanders41/pytest-meilisearch) is a pytest plugin that can
+help with testing your code. It provides a lot of the boiler plate code you will need.
+
+## Documentation
+
+See our [docs](https://meilisearch-python-sdk.paulsanders.dev) for the full documentation.
+
+## Contributing
+
+Contributions to this project are welcome. If you are interested in contributing please see our
+[contributing guide](CONTRIBUTING.md)

meilisearch_python_sdk-5.5.0.dist-info/RECORD

@@ -0,0 +1,32 @@
+meilisearch_python_sdk/__init__.py,sha256=SB0Jlm6FwT13J9xasZKseZzTWBk0hkfe1CWyWmIIZnE,258
+meilisearch_python_sdk/_batch.py,sha256=Hbt-M8Lt8ZDZqcKToUMzUd5zvT-gku709er4pRlvXWk,5065
+meilisearch_python_sdk/_client.py,sha256=_hEcFLbt8F2IadFaGMU9jAlAuelw1eMiAULDrbBKd8I,95566
+meilisearch_python_sdk/_http_requests.py,sha256=9NMTKrJDFpdWZKPLNGlRQ54EtqhPXlhov3EoeR3VrwU,6773
+meilisearch_python_sdk/_task.py,sha256=vZuBozL0qQDJBwEGgq6mrmYjJPBNi_NzCMk_uql0tsA,12485
+meilisearch_python_sdk/_utils.py,sha256=NoCDxJPhjABeuSxFTNCih585UDWdXEUBD_FvdgtScQw,1539
+meilisearch_python_sdk/_version.py,sha256=ds5syOHDBbzfjd9EvTjYcNNffSC3N5Io68elHur19F0,18
+meilisearch_python_sdk/decorators.py,sha256=6v630usrbHS8KFxgEI1U_STo3QWDnwGzOnbq7NPGp_0,8703
+meilisearch_python_sdk/errors.py,sha256=RNNHXtXLBiCVZaLM2MeKKs9RbRuE-SLRttiPeVAEXgA,2133
+meilisearch_python_sdk/json_handler.py,sha256=c1rGKzYlE0dGfLygQjPqVUNfQkN1JvafBGmIx31JW8g,2044
+meilisearch_python_sdk/plugins.py,sha256=YySzTuVr4IrogTgrP8q-gZPsew8TwedopjWnTj5eV48,3607
+meilisearch_python_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+meilisearch_python_sdk/types.py,sha256=-A3WB73EKUCBOOaeqVS_S9_1-QgtjAjl-3v_2XRfpF0,249
+meilisearch_python_sdk/index/__init__.py,sha256=sULiCF_Gqa66SDLuyvlHQ1NW-6ch5sWU6UNZ572sdEA,152
+meilisearch_python_sdk/index/_common.py,sha256=3OtndcUg7z36aFJSTqaBnK4f56DUQ3ip2DM11cZybMo,9337
+meilisearch_python_sdk/index/async_index.py,sha256=y_EI-Hxzd43qVtOY-yVElOc6mC-qRhLVd90zP3eqWsI,205349
+meilisearch_python_sdk/index/index.py,sha256=QIQmKvPLUDcbiFyHfZjL2ZhQl4lPKBhu3rHIltELWfU,153861
+meilisearch_python_sdk/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+meilisearch_python_sdk/models/batch.py,sha256=PYnJxCB_rvOaGM4Z-EFgxHqTaFct_s8djlCXkaa1V8k,1613
+meilisearch_python_sdk/models/client.py,sha256=nefi6ViSaSd_mtopRAhM9tzzepwChFJUkGTXPAr4RY8,2756
+meilisearch_python_sdk/models/documents.py,sha256=eT3FHrPND-g2IzNRyOHQApTTJ1WbFcGlqgxZ6aKrRgI,247
+meilisearch_python_sdk/models/health.py,sha256=hvruti7ylsk7bAh8RPOhTPcRrjx6MPgdkDFX9vZ5Qks,95
+meilisearch_python_sdk/models/index.py,sha256=WLQOi3_HChko134FkRU1H3_cJjhHJCFclcx4oDBlqHU,1228
+meilisearch_python_sdk/models/search.py,sha256=U3ph1GW9Xkbw33pIlGDa7rlTGsdvqahjRJjPxUou8n8,3581
+meilisearch_python_sdk/models/settings.py,sha256=eh0xnro4D_sj8ck2nifa3tBdf2_7RcZlAY_zQhfsY0s,5730
+meilisearch_python_sdk/models/task.py,sha256=bMFN_oloEcpIlEp_suPGRlZ1io35JP_9y7_1zqaOJJg,2252
+meilisearch_python_sdk/models/version.py,sha256=ISU-ZHgpXLBFDuMpWWfKdVo9Dq1HcD7s6HFnCiGTF8Y,184
+meilisearch_python_sdk/models/webhook.py,sha256=zSkEJJdEflinW3_seJTLQ_ZWs4w-pjTD3SS1ZawC32k,455
+meilisearch_python_sdk-5.5.0.dist-info/METADATA,sha256=0cEHjvwINSidAhpB3-Q10DvB6S_xVusXtFbgMJ5kQCg,9729
+meilisearch_python_sdk-5.5.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+meilisearch_python_sdk-5.5.0.dist-info/licenses/LICENSE,sha256=xVzevI1TrlKfM0plmJ7vfK1Muu0V9n-dGE8RnDrOFlM,1069
+meilisearch_python_sdk-5.5.0.dist-info/RECORD,,

meilisearch_python_sdk-5.5.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

meilisearch_python_sdk-5.5.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Paul Sanders
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.