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

meilisearch_python_sdk/models/index.py

@@ -0,0 +1,67 @@
+from datetime import datetime
+from typing import Dict, Optional
+
+import pydantic
+from camel_converter.pydantic_base import CamelBase
+
+from meilisearch_python_sdk._utils import is_pydantic_2, iso_to_date_time
+
+
+class IndexBase(CamelBase):
+    uid: str
+    primary_key: Optional[str]
+
+
+class IndexInfo(IndexBase):
+    created_at: datetime
+    updated_at: datetime
+
+    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) -> datetime:
+            converted = iso_to_date_time(v)
+
+            if not converted:  # pragma: no cover
+                raise ValueError("updated_at is required")
+
+            return converted
+
+    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) -> datetime:
+            converted = iso_to_date_time(v)
+
+            if not converted:
+                raise ValueError("updated_at is required")
+
+            return converted
+
+
+class IndexStats(CamelBase):
+    number_of_documents: int
+    is_indexing: bool
+    field_distribution: Dict[str, int]

meilisearch_python_sdk/models/search.py

@@ -0,0 +1,59 @@
+from typing import Any, Dict, List, Optional, Union
+
+from camel_converter.pydantic_base import CamelBase
+from pydantic import Field
+
+
+class FacetHits(CamelBase):
+    value: str
+    count: int
+
+
+class FacetSearchResults(CamelBase):
+    facet_hits: List[FacetHits]
+    facet_query: str
+    processing_time_ms: int
+
+
+class SearchParams(CamelBase):
+    index_uid: str
+    query: Optional[str] = Field(None, alias="q")
+    offset: int = 0
+    limit: int = 20
+    filter: Optional[Union[str, List[Union[str, List[str]]]]] = None
+    facets: Optional[List[str]] = None
+    attributes_to_retrieve: List[str] = ["*"]
+    attributes_to_crop: Optional[List[str]] = None
+    crop_length: int = 200
+    attributes_to_highlight: Optional[List[str]] = None
+    sort: Optional[List[str]] = None
+    show_matches_position: bool = False
+    highlight_pre_tag: str = "<em>"
+    highlight_post_tag: str = "</em>"
+    crop_marker: str = "..."
+    matching_strategy: str = "all"
+    hits_per_page: Optional[int] = None
+    page: Optional[int] = None
+    attributes_to_search_on: Optional[List[str]] = None
+    show_ranking_score: bool = False
+    show_ranking_score_details: bool = False
+    vector: Optional[List[float]] = None
+
+
+class SearchResults(CamelBase):
+    hits: List[Dict[str, Any]]
+    offset: Optional[int] = None
+    limit: Optional[int] = None
+    estimated_total_hits: Optional[int] = None
+    processing_time_ms: int
+    query: str
+    facet_distribution: Optional[Dict[str, Any]] = None
+    total_pages: Optional[int] = None
+    total_hits: Optional[int] = None
+    page: Optional[int] = None
+    hits_per_page: Optional[int] = None
+    vector: Optional[List[float]] = None
+
+
+class SearchResultsWithUID(SearchResults):
+    index_uid: str

meilisearch_python_sdk/models/settings.py

@@ -0,0 +1,72 @@
+from typing import Any, Dict, List, Optional
+
+import pydantic
+from camel_converter.pydantic_base import CamelBase
+
+from meilisearch_python_sdk._utils import is_pydantic_2
+
+
+class MinWordSizeForTypos(CamelBase):
+    one_typo: Optional[int] = None
+    two_typos: Optional[int] = None
+
+
+class TypoTolerance(CamelBase):
+    enabled: bool = True
+    disable_on_attributes: Optional[List[str]] = None
+    disable_on_words: Optional[List[str]] = None
+    min_word_size_for_typos: Optional[MinWordSizeForTypos] = None
+
+
+class Faceting(CamelBase):
+    max_values_per_facet: int
+    sort_facet_values_by: Optional[Dict[str, str]] = None
+
+    if is_pydantic_2():
+
+        @pydantic.field_validator("sort_facet_values_by")  # type: ignore[attr-defined]
+        @classmethod
+        def validate_facet_order(cls, v: Optional[Dict[str, str]]) -> Optional[Dict[str, str]]:
+            if not v:  # pragma: no cover
+                return None
+
+            for _, value in v.items():
+                if value not in ("alpha", "count"):
+                    raise ValueError('facet_order must be either "alpha" or "count"')
+
+            return v
+
+    else:  # pragma: no cover
+
+        @pydantic.validator("sort_facet_values_by")  # type: ignore[attr-defined]
+        @classmethod
+        def validate_facet_order(cls, v: Optional[Dict[str, str]]) -> Optional[Dict[str, str]]:
+            if not v:
+                return None
+
+            for _, value in v.items():
+                if value not in ("alpha", "count"):
+                    raise ValueError('facet_order must be either "alpha" or "count"')
+
+            return v
+
+
+class Pagination(CamelBase):
+    max_total_hits: int
+
+
+class MeilisearchSettings(CamelBase):
+    synonyms: Optional[Dict[str, Any]] = None
+    stop_words: Optional[List[str]] = None
+    ranking_rules: Optional[List[str]] = None
+    filterable_attributes: Optional[List[str]] = None
+    distinct_attribute: Optional[str] = None
+    searchable_attributes: Optional[List[str]] = None
+    displayed_attributes: Optional[List[str]] = None
+    sortable_attributes: Optional[List[str]] = None
+    typo_tolerance: Optional[TypoTolerance] = None
+    faceting: Optional[Faceting] = None
+    pagination: Optional[Pagination] = None
+    separator_tokens: Optional[List[str]] = None
+    non_separator_tokens: Optional[List[str]] = None
+    dictionary: Optional[List[str]] = None

meilisearch_python_sdk/models/task.py

@@ -0,0 +1,109 @@
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Union
+
+import pydantic
+from camel_converter.pydantic_base import CamelBase
+from pydantic import Field
+
+from meilisearch_python_sdk._utils import is_pydantic_2, iso_to_date_time
+
+
+class TaskId(CamelBase):
+    uid: int
+
+
+class TaskResult(TaskId):
+    index_uid: Optional[str] = None
+    status: str
+    task_type: Union[str, Dict[str, Any]] = Field(..., alias="type")
+    details: Optional[Dict[str, Any]] = None
+    error: Optional[Dict[str, Any]] = None
+    canceled_by: Optional[int] = None
+    duration: Optional[str] = None
+    enqueued_at: datetime
+    started_at: Optional[datetime] = None
+    finished_at: Optional[datetime] = None
+
+    if is_pydantic_2():
+
+        @pydantic.field_validator("enqueued_at", mode="before")  # type: ignore[attr-defined]
+        @classmethod
+        def validate_enqueued_at(cls, v: str) -> datetime:
+            converted = iso_to_date_time(v)
+
+            if not converted:  # pragma: no cover
+                raise ValueError("enqueued_at is required")
+
+            return converted
+
+        @pydantic.field_validator("started_at", mode="before")  # type: ignore[attr-defined]
+        @classmethod
+        def validate_started_at(cls, v: str) -> Union[datetime, None]:
+            return iso_to_date_time(v)
+
+        @pydantic.field_validator("finished_at", mode="before")  # type: ignore[attr-defined]
+        @classmethod
+        def validate_finished_at(cls, v: str) -> Union[datetime, None]:
+            return iso_to_date_time(v)
+
+    else:  # pragma: no cover
+
+        @pydantic.validator("enqueued_at", pre=True)
+        @classmethod
+        def validate_enqueued_at(cls, v: str) -> datetime:
+            converted = iso_to_date_time(v)
+
+            if not converted:
+                raise ValueError("enqueued_at is required")
+
+            return converted
+
+        @pydantic.validator("started_at", pre=True)
+        @classmethod
+        def validate_started_at(cls, v: str) -> Union[datetime, None]:
+            return iso_to_date_time(v)
+
+        @pydantic.validator("finished_at", pre=True)
+        @classmethod
+        def validate_finished_at(cls, v: str) -> Union[datetime, None]:
+            return iso_to_date_time(v)
+
+
+class TaskStatus(CamelBase):
+    results: List[TaskResult]
+    total: int
+    limit: int
+    from_: int = Field(..., alias="from")
+    next: Optional[int] = None
+
+
+class TaskInfo(CamelBase):
+    task_uid: int
+    index_uid: Optional[str] = None
+    status: str
+    task_type: Union[str, Dict[str, Any]] = Field(..., alias="type")
+    enqueued_at: datetime
+
+    if is_pydantic_2():
+
+        @pydantic.field_validator("enqueued_at", mode="before")  # type: ignore[attr-defined]
+        @classmethod
+        def validate_enqueued_at(cls, v: str) -> datetime:
+            converted = iso_to_date_time(v)
+
+            if not converted:  # pragma: no cover
+                raise ValueError("enqueued_at is required")
+
+            return converted
+
+    else:  # pragma: no cover
+
+        @pydantic.validator("enqueued_at", pre=True)
+        @classmethod
+        def validate_enqueued_at(cls, v: str) -> datetime:
+            converted = iso_to_date_time(v)
+
+            if not converted:
+                raise ValueError("enqueued_at is required")
+
+            return converted

meilisearch_python_sdk/models/version.py

@@ -0,0 +1,10 @@
+from datetime import datetime
+from typing import Union
+
+from camel_converter.pydantic_base import CamelBase
+
+
+class Version(CamelBase):
+    commit_sha: str
+    commit_date: Union[datetime, str]
+    pkg_version: str

meilisearch_python_sdk-2.0.0.dist-info/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.

meilisearch_python_sdk-2.0.0.dist-info/METADATA

@@ -0,0 +1,253 @@
+Metadata-Version: 2.1
+Name: meilisearch-python-sdk
+Version: 2.0.0
+Summary: A Python async client for the Meilisearch API
+Home-page: https://github.com/sanders41/meilisearch-python-sdk
+License: MIT
+Keywords: meilisearch,async,python,client,sdk
+Author: Paul Sanders
+Author-email: psanders1@gmail.com
+Requires-Python: >=3.8,<4.0
+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
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Dist: PyJWT (>=2.3.0)
+Requires-Dist: aiofiles (>=0.7)
+Requires-Dist: camel-converter (>=1.0.0)
+Requires-Dist: httpx (>=0.17)
+Requires-Dist: pydantic (>=1.8)
+Project-URL: Documentation, https://meilisearch-python-sdk.paulsanders.dev
+Project-URL: Repository, https://github.com/sanders41/meilisearch-python-sdk
+Description-Content-Type: text/markdown
+
+# Meilisearch Python SDK
+
+[![Tests Status](https://github.com/sanders41/meilisearch-python-sdk/workflows/Testing/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)
+
+:warning: This project was previously named `meilisearch-python-async`. Development on that project
+continues here under the new name.
+
+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/), chose the `AsyncClint`
+otherwise chose the `Client`. The functionality of the two clients is the same, the difference
+being the `AsyncClient` provides async methods and uses the `AsyncIndex`, which also provides async
+methods, while the `Client` provides blocking methods and uses the `Index`, which also provides
+blocking methods.
+
+## Installation
+
+Using a virtual environmnet 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://docs.meilisearch.com/reference/features/installation.html#download-and-launch).
+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
+```
+
+## Useage
+
+### 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
+
+client = Client('http://127.0.0.1:7700', 'masterKey')
+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://docs.meilisearch.com/reference/api/updates.html#get-an-update-status)
+of the updates. To do this you would save the result response from adding the documets to a
+variable, this will be a UpdateId object, and use it to check the status of the updates.
+
+#### AsyncClient
+
+```py
+update = await index.add_documents(documents)
+status = await client.index('books').get_update_status(update.update_id)
+```
+
+#### Client
+
+```py
+update = index.add_documents(documents)
+status = client.index('books').get_update_status(update.update_id)
+```
+
+### 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 blocking the event loop the
+gains here will not be seen and the performance between the clients will be very close to the same.
+
+### 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)
+
+### Muiltiple 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/).
+
+## 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-2.0.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+meilisearch_python_sdk/__init__.py,sha256=2MyxnAmiZgA3M_pP_WW7p__dasT6xhyrO2--STSrXQk,259
+meilisearch_python_sdk/_client.py,sha256=3piM_YUdrbBgphDmPNlhlxHC0MhTdaT7UL2M__Gbjpk,60671
+meilisearch_python_sdk/_http_requests.py,sha256=eRYosZQI3rfA8iTqMiBopnzWo3TlWEGQd659S-jsZ_U,4829
+meilisearch_python_sdk/_index.py,sha256=r9L7-z-WoepocDD3Yz860zV8G-Em8q9TxU2GnTwNQE4,207964
+meilisearch_python_sdk/_task.py,sha256=HiyrLsQn5O2PlnUsKPc0RLSPZnJMIsiwA3WSmFsU2Qk,11874
+meilisearch_python_sdk/_utils.py,sha256=SMoBWDlLtAEtpD8n94CCcHvtBA-HLWyolxPY-n4K_UE,1610
+meilisearch_python_sdk/_version.py,sha256=hyBh0bE6J-qEFrdhg0HzT5ZFxu3-X1LLCrhPVnUnu0w,18
+meilisearch_python_sdk/errors.py,sha256=0sAKYt47-zFpKsEU6W8Qnvf4uHBynKtlGPpPl-5laSA,2085
+meilisearch_python_sdk/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+meilisearch_python_sdk/models/client.py,sha256=tT97Y-HWrBNiCgj4w7aC_YXtdLpJr0nUE2P-URVZ9Dg,4714
+meilisearch_python_sdk/models/documents.py,sha256=NpAJwsFIUED0wtAsyQ8e_1b43clBdcYpr-TczHVEdnc,202
+meilisearch_python_sdk/models/health.py,sha256=hvruti7ylsk7bAh8RPOhTPcRrjx6MPgdkDFX9vZ5Qks,95
+meilisearch_python_sdk/models/index.py,sha256=gIb7GYlvkLqv4kyI4Xec2IkLFgvZx0w2kz7iEOCNXNU,1845
+meilisearch_python_sdk/models/search.py,sha256=E5jLxyDJXv16dQopA6_pIj0gRQxNkT3i_8RVyfP0lH4,1734
+meilisearch_python_sdk/models/settings.py,sha256=s2TfT3ZnoAc2vyaWbiJheXHMgvD_8AcuKRFkJ7iGzYA,2377
+meilisearch_python_sdk/models/task.py,sha256=fX8AnYEMzF4ZJsO3LQlaEpNJHL-iSCBqFV0y7M1Adew,3324
+meilisearch_python_sdk/models/version.py,sha256=YDu-aj5H-d6nSaWRTXzlwWghmZAoiknaw250UyEd48I,215
+meilisearch_python_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+meilisearch_python_sdk-2.0.0.dist-info/LICENSE,sha256=xVzevI1TrlKfM0plmJ7vfK1Muu0V9n-dGE8RnDrOFlM,1069
+meilisearch_python_sdk-2.0.0.dist-info/METADATA,sha256=xS4ljtwElNZOcQLZ6J7oe-8QK1D0x7xNzYAHxn2U-zc,8182
+meilisearch_python_sdk-2.0.0.dist-info/WHEEL,sha256=d2fvjOD7sXsVzChCqf0Ty0JbHKBaLYwDbGQDwQTnJ50,88
+meilisearch_python_sdk-2.0.0.dist-info/RECORD,,

meilisearch_python_sdk-2.0.0.dist-info/WHEEL

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