Typesense Python

Typesense Python is the official API client for Typesense, an open-source, typo-tolerant search engine. It wraps the full Typesense REST API — collections, documents, search, aliases, synonyms, and analytics — behind both synchronous and asynchronous Python clients so you can add fast, relevant search to any application.

The library manages authentication, request routing across multiple Typesense nodes, retries, and response parsing, exposing clean objects for collections and documents. It ships type hints and a node manager for high-availability deployments.

What You Get

• A Client object for managing collections, documents, aliases, and synonyms
• Both synchronous and asynchronous client implementations
• Multi-node configuration with health-aware routing and automatic failover
• Full search support including filtering, faceting, and typo tolerance
• Typed API surface with a py.typed marker and analytics/rules endpoints

Common Use Cases

• Adding instant, typo-tolerant search to a Python web application
• Indexing product catalogs or content collections with schema-defined fields
• Building faceted and filtered search experiences over structured data
• Running a highly available search cluster with multi-node client failover

Under The Hood

Architecture — The src/typesense package is split into sync and async_ implementations sharing common request logic. A request_handler routes calls to the Typesense REST API, while node_manager tracks node health and selects a healthy node for each request, providing failover across a cluster. configuration.py holds connection settings, exceptions.py maps API errors to typed exceptions, and types/ carries request/response type definitions.

Tech Stack — Pure Python distributed under Apache-2.0, using requests for HTTP transport and shipping a py.typed marker for full type support. It uses a src/ layout, ruff for linting, and uv for dependency management, with parallel synchronous and asynchronous client trees.

Code Quality — The repository contains an extensive per-resource test suite (collections, documents, aliases, synonyms, analytics, and more) run under pytest, plus consistent typing and a dedicated exceptions module. The node manager and request handler are cleanly separated from the resource classes.

API Design — The public API mirrors Typesense concepts directly: client.collections.create(schema), collection.documents.create(doc), and collection.documents.search(params). Naming is consistent between the sync and async clients, and multi-node setup is a single configuration dict, keeping getting-started boilerplate small.