feat: add async support #118

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged

kishorenc merged 54 commits into typesense:master from tharropoulos:async

Feb 5, 2026

+11,627 −3,629

.github/workflows/test-and-lint.yml

-Original file line number
+Diff line change
@@ Expand Up / @@ -44,6 +44,9 @@ jobs: @@
         - name: Install the project
           run: uv sync --locked --all-extras --dev
+        - name: Check sync generation
+          run: uv run python utils/run-unasync.py --check
         - name: Lint with Ruff
           run: |
             uv run ruff check src/typesense
@@ Expand Down @@

README.md

-Original file line number
+Diff line change
@@ Expand Up @@
     See detailed [API documentation](https://typesense.org/api).
+    ## Async usage
+    Use `AsyncClient` when working in an async runtime:
+    ```python
+    import asyncio
+    import typesense
+    async def main() -> None:
+        client = typesense.AsyncClient({
+            "api_key": "abcd",
+            "nodes": [{"host": "localhost", "port": "8108", "protocol": "http"}],
+            "connection_timeout_seconds": 2,
+        })
+        print(await client.collections.retrieve())
+        await client.api_call.aclose()
+    if __name__ == "__main__":
+        asyncio.run(main())
+    ```
+    See `examples/async_collection_operations.py` for a fuller async walkthrough.
     ## Compatibility
     | Typesense Server | typesense-python |
     |------------------|------------------|
+    | \>= v30.0        | \>= v2.0.0       |
+    | \>= v28.0        | \>= v1.0.0       |
     | \>= v26.0        | \>= v0.20.0      |
     | \>= v0.25.0      | \>= v0.16.0      |
     | \>= v0.23.0      | \>= v0.14.0      |
@@ Expand All / @@ -32,7 +60,11 @@ See detailed [API documentation](https://typesense.org/api). @@
     ## Contributing
+    > [!NOTE]
+    > Development happens in async-only code; sync code is generated automatically via `utils/run-unasync.py`.
     Bug reports and pull requests are welcome on GitHub at [https://github.com/typesense/typesense-python].
+    If you change any part of the client's source code, run `uv run utils/run-unasync.py` before opening a PR to keep the generated sync files in sync.
     ## License
@@ Expand Down @@

examples/async_collection_operations.py

-Original file line number
+Diff line change
@@ -0,0 +1,196 @@
+    import asyncio
+    import json
+    import os
+    import sys
+    curr_dir = os.path.dirname(os.path.realpath(__file__))
+    repo_root = os.path.abspath(os.path.join(curr_dir, os.pardir))
+    sys.path.insert(1, os.path.join(repo_root, "src"))
+    import typesense
+    from typesense.exceptions import TypesenseClientError
+    async def main() -> None:
+        client = typesense.AsyncClient(
+            {
+                "api_key": "xyz",
+                "nodes": [
+                    {
+                        "host": "localhost",
+                        "port": "8108",
+                        "protocol": "http",
+                    }
+                ],
+                "connection_timeout_seconds": 2,
+            }
+        )
+        try:
+            # Drop pre-existing collection if any
+            try:
+                await client.collections["books"].delete()
+            except Exception:
+                pass
+            # Create a collection
+            create_response = await client.collections.create(
+                {
+                    "name": "books",
+                    "fields": [
+                        {"name": "title", "type": "string"},
+                        {"name": "authors", "type": "string[]", "facet": True},
+                        {"name": "publication_year", "type": "int32", "facet": True},
+                        {"name": "ratings_count", "type": "int32"},
+                        {"name": "average_rating", "type": "float"},
+                        {"name": "image_url", "type": "string"},
+                    ],
+                    "default_sorting_field": "ratings_count",
+                }
+            )
+            print(create_response)
+            # Retrieve the collection we just created
+            retrieve_response = await client.collections["books"].retrieve()
+            print(retrieve_response)
+            # Try retrieving all collections
+            retrieve_all_response = await client.collections.retrieve()
+            print(retrieve_all_response)
+            # Add a book
+            hunger_games_book = {
+                "id": "1",
+                "authors": ["Suzanne Collins"],
+                "average_rating": 4.34,
+                "publication_year": 2008,
+                "title": "The Hunger Games",
+                "image_url": "https://images.gr-assets.com/books/1447303603m/2767052.jpg",
+                "ratings_count": 4780653,
+            }
+            await client.collections["books"].documents.create(hunger_games_book)
+            # Upsert the same document
+            print(await client.collections["books"].documents.upsert(hunger_games_book))
+            # Or update it
+            hunger_games_book_updated = {"id": "1", "average_rating": 4.45}
+            print(
+                await client.collections["books"]
+                .documents["1"]
+                .update(hunger_games_book_updated)
+            )
+            # Try updating with bad data (with coercion enabled)
+            hunger_games_book_updated = {"id": "1", "average_rating": "4.55"}
+            print(
+                await client.collections["books"]
+                .documents["1"]
+                .update(hunger_games_book_updated, {"dirty_values": "coerce_or_reject"})
+            )
+            # Export the documents from a collection
+            export_output = await client.collections["books"].documents.export()
+            print(export_output)
+            # Fetch a document in a collection
+            print(await client.collections["books"].documents["1"].retrieve())
+            # Search for documents in a collection
+            print(
+                await client.collections["books"].documents.search(
+                    {
+                        "q": "hunger",
+                        "query_by": "title",
+                        "sort_by": "ratings_count:desc",
+                    }
+                )
+            )
+            # Make multiple search requests at the same time
+            print(
+                await client.multi_search.perform(
+                    {
+                        "searches": [
+                            {
+                                "q": "hunger",
+                                "query_by": "title",
+                            },
+                            {
+                                "q": "suzanne",
+                                "query_by": "authors",
+                            },
+                        ]
+                    },
+                    {"collection": "books", "sort_by": "ratings_count:desc"},
+                )
+            )
+            # Remove a document from a collection
+            print(await client.collections["books"].documents["1"].delete())
+            # Import documents into a collection
+            docs_to_import = []
+            for exported_doc_str in export_output.split("\n"):
+                docs_to_import.append(json.loads(exported_doc_str))
+            import_results = await client.collections["books"].documents.import_(
+                docs_to_import
+            )
+            print(import_results)
+            # Upserting documents
+            import_results = await client.collections["books"].documents.import_(
+                docs_to_import,
+                {
+                    "action": "upsert",
+                    "return_id": True,
+                },
+            )
+            print(import_results)
+            # Schema change: add optional field
+            schema_change = {
+                "fields": [{"name": "in_stock", "optional": True, "type": "bool"}]
+            }
+            print(await client.collections["books"].update(schema_change))
+            # Update value matching a filter
+            updated_doc = {"publication_year": 2009}
+            print(
+                await client.collections["books"].documents.update(
+                    updated_doc, {"filter_by": "publication_year: 2008"}
+                )
+            )
+            # Drop the field
+            schema_change = {"fields": [{"name": "in_stock", "drop": True}]}
+            print(await client.collections["books"].update(schema_change))
+            # Deleting documents matching a filter query
+            print(
+                await client.collections["books"].documents.delete(
+                    {"filter_by": "ratings_count: 4780653"}
+                )
+            )
+            # Try importing empty list
+            try:
+                import_results = await client.collections["books"].documents.import_(
+                    [], {"action": "upsert"}
+                )
+                print(import_results)
+            except TypesenseClientError:
+                print("Detected import of empty document list.")
+            # Drop the collection
+            drop_response = await client.collections["books"].delete()
+            print(drop_response)
+        finally:
+            await client.api_call.aclose()
+    if __name__ == "__main__":
+        asyncio.run(main())

pyproject.toml

-Original file line number
+Diff line change
@@ Expand Up / @@ -21,7 +21,10 @@ classifiers = [ @@
         "Programming Language :: Python :: 3.12",
         "Programming Language :: Python :: 3.13",
     ]
-    dependencies = ["requests", "typing-extensions"]
+    dependencies = [
+        "httpx>=0.28.1",
+        "typing-extensions",
+    ]
     dynamic = ["version"]
     [project.urls]
@@ Expand All / @@ -35,16 +38,18 @@ build-backend = "setuptools.build_meta" @@
     [dependency-groups]
     dev = [
-        "mypy",
+        "mypy>=1.19.0",
         "pytest",
+        "pytest-asyncio",
         "coverage",
         "pytest-mock",
-        "requests-mock",
         "python-dotenv",
-        "types-requests",
         "faker",
         "ruff>=0.11.11",
         "isort>=6.0.1",
+        "respx>=0.22.0",
+        "requests",
+        "unasync>=0.6.0",
     ]
     [tool.uv]
@@ Expand Down @@

pytest.ini

-Original file line number
+Diff line change
@@ -1,4 +1,5 @@
     [pytest]
     pythonpath = src
+    asyncio_mode = auto
     markers =
         open_ai

src/typesense/__init__.py

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -1,5 +1,6 @@
  
    from .client import Client  # NOQA

    from .sync.client import Client  # NOQA

    from .async_.client import AsyncClient  # NOQA

    __all__ = ["Client"]

    __version__ = "1.3.0"

    __version__ = "2.0.0"

    __all__ = ["Client", "AsyncClient"]

src/typesense/alias.py

This file was deleted.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add async support #118

Diff view

Diff view

There are no files selected for viewing

Uh oh!

Uh oh!