Merge pull request #687 from sanders41/sync_client

Add a sync client

Author: sanders41

.github/workflows/pypi_publish.yaml

@@ -9,20 +9,16 @@ jobs:
     steps:
     - uses: actions/checkout@v4
     - name: Install Poetry
-      run: |
-        pip install pipx
-        pipx install poetry
+      run: pipx install poetry
+    - name: Add pypi token to Poetry
+      run: poetry config pypi-token.pypi ${{ secrets.PYPI_API_KEY }}
     - name: Set up Python
       uses: actions/setup-python@v4
       with:
         python-version: 3.11
         cache: "poetry"
     - name: Install Dependencies
-      run: |
-        poetry install
-    - name: Add pypi token to Poetry
-      run: |
-        poetry config pypi-token.pypi ${{ secrets.PYPI_API_KEY }}
+      run: poetry install
     - name: Publish package
       run: poetry publish --build
     - name: Deploy Docs

CONTRIBUTING.md

@@ -4,7 +4,7 @@
 
 All contributions, bug reports, bug fixes, documentation improvements, enhancements, and ideas are welcome.
 
-The best place to start is to check the [issues](https://github.com/sanders41/meilisearch-python-async/issues)
+The best place to start is to check the [issues](https://github.com/sanders41/meilisearch-python-sdk/issues)
 for something that interests you.
 
 ## Bug Reports
@@ -15,7 +15,7 @@ Please include:
 [GitHub markdown](https://docs.github.com/en/free-pro-team@latest/github/writing-on-github). For example:
 
   ```py
-  from meilisearch_python_async import Client
+  from meilisearch_python_sdk import Client
 
   async with Client(BASE_URL, MASTER_KEY) as client:
       client.index("movies")
@@ -34,12 +34,12 @@ this project.
 Once the project is forked clone it to your local machine:
 
 ```sh
-git clone https://github.com/your-user-name/meilisearch-python-async.git
-cd meilisearch-python-async
-git remote add upstream https://github.com/sanders41/meilisearch-python-async.git
+git clone https://github.com/your-user-name/meilisearch-python-sdk.git
+cd meilisearch-python-sdk
+git remote add upstream https://github.com/sanders41/meilisearch-python-sdk.git
 ```
 
-This creates the directory meilisearch-python-async and connects your repository to the upstream (main project) repository.
+This creates the directory meilisearch-python-sdk and connects your repository to the upstream (main project) repository.
 
 ### Working with the code
 
@@ -74,21 +74,21 @@ git pull upstream main --ff-only
 
 ### Code Standards and tests (ruff, black, mypy, pytest, and pre-commit)
 
-meilisearch-python-async uses [ruff](https://github.com/charliermarsh/ruff),
+meilisearch-python-sdk uses [ruff](https://github.com/charliermarsh/ruff),
 [Black](https://github.com/psf/black), and [mypy](https://mypy.readthedocs.io/en/stable/) to ensure
 consistent code formatting.
 
 You can run linting on your code at any time with:
 
 ```sh
 # Run black
-poetry run black meilisearch_python_async tests
+poetry run black meilisearch_python_sdk tests
 
 # Run ruff
 poetry run ruff check .
 
 # Run mypy
-poetry run mypy meilisearch_python_async
+poetry run mypy meilisearch_python_sdk
 ```
 
 It is also suggested that you setup [pre-commit](https://pre-commit.com/) in order to run linting
@@ -140,7 +140,7 @@ This project uses [pytest](https://docs.pytest.org/en/stable/) for testing. Plea
 additions/changes you make to the code have tests to go along with them. Code coverage should not
 drop blow it's current level with any pull requests you make, if it does the pull request will not
 be accepted. You can view the current coverage level in the codecov badge on the
-[main github page](https://github.com/sanders41/meilisearch-python-async). You can run tests and see the
+[main github page](https://github.com/sanders41/meilisearch-python-sdk). You can run tests and see the
 code coverage.
 
 There are multiple way Meilisearch can be setup for testing. The examples below use docker, however
@@ -186,7 +186,7 @@ To see a full list of `just` commands run `just --list`
 
 Documentation is automatically generated based on the doc strings from the functions/methods. If
 functions/methods are added/removed make sure to update the
-[api documentation page](https://github.com/sanders41/meilisearch-python-async/docs/api.md) accordingly.
+[api documentation page](https://github.com/sanders41/meilisearch-python-sdk/docs/api.md) accordingly.
 
 You can view any changes to the docs locally by running:
 
@@ -238,11 +238,11 @@ git remote -v
 
 ## Making a Pull Request
 
-After pushing your code to origin it is now on GitHub but not yet part of the meilisearch-python-async project. When you’re ready to ask for a code review, file a pull request. Before you do, once again make sure that you have followed all the guidelines outlined in this document regarding code style, tests, and documentation.
+After pushing your code to origin it is now on GitHub but not yet part of the meilisearch-python-sdk project. When you’re ready to ask for a code review, file a pull request. Before you do, once again make sure that you have followed all the guidelines outlined in this document regarding code style, tests, and documentation.
 
 ### Make the pull request
 
-If everything looks good, you are ready to make a pull request. This is how you let the maintainers of the meilisearch-python-async project know you have code ready to be reviewed. To submit the pull request:
+If everything looks good, you are ready to make a pull request. This is how you let the maintainers of the meilisearch-python-sdk project know you have code ready to be reviewed. To submit the pull request:
 
 1. Navigate to your repository on GitHub
 2. Click on the Pull Request button for your feature branch

README.md

@@ -1,14 +1,222 @@
-# Meilisearch Python Async
+# Meilisearch Python SDK
 
-:warning:
-This project has been renamed to [meilisearch-python-sdk](https://github.com/sanders41/meilisearch-python-sdk)
-:warning:
+[![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)
 
-Under the new name both an async and a sync client are provided. You should install the new package
-instead of this one.
+: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)