Release v2.0.4: Unified sync/async API + conn.conn cleanup + ZooKeeper docs

- Unified sync/async: SchemaAPI, KNN, MoreLikeThis, Suggest, Extract
  accept both Solr and AsyncSolr. DualTransport + _chain() helper.
- AsyncSchemaAPI etc. kept as backward-compatible aliases.
- Renamed Solr.conn/AsyncSolr.conn to _client (encapsulation).
- Expanded SolrCloud/SolrZooKeeper docs: full method descriptions,
  parameters, return types, examples, failover behavior.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: search5

README.md

@@ -102,6 +102,14 @@ poetry run pytest tests/
 
 ## Changelog
 
+### 2.0.4
+
+- **Unified sync/async API**: `SchemaAPI(conn)` works with both `Solr` and `AsyncSolr`
+- Single class, dual mode — no need for separate `AsyncSchemaAPI` etc.
+- `DualTransport` auto-detects sync vs async connection
+- `_chain()` helper for composing sync values and async coroutines
+- `AsyncSchemaAPI`, `AsyncKNN`, `AsyncMoreLikeThis`, `AsyncSuggest`, `AsyncExtract` kept as backward-compatible aliases
+
 ### 2.0.3
 
 - **Async companion classes**: `AsyncSchemaAPI`, `AsyncKNN`, `AsyncMoreLikeThis`, `AsyncSuggest`, `AsyncExtract`

docs/changelog.rst

@@ -1,6 +1,40 @@
 Changelog
 =========
 
+2.0.4 (2026-03-27)
+-------------------
+
+**New features:**
+
+- **Unified sync/async API**: all companion classes (``SchemaAPI``, ``KNN``,
+  ``MoreLikeThis``, ``Suggest``, ``Extract``) now accept both ``Solr`` (sync)
+  and ``AsyncSolr`` (async) connections.
+- With a sync connection, methods return values directly. With an async
+  connection, methods return coroutines (to be ``await``-ed).
+- **``DualTransport``** in ``solr/transport.py``: auto-detects sync vs async
+  and delegates to ``SolrTransport`` or ``AsyncTransport`` accordingly.
+- **``_chain()``** helper composes a transform onto either a sync value or
+  an async coroutine, eliminating code duplication in companion classes.
+- ``AsyncSchemaAPI``, ``AsyncKNN``, ``AsyncMoreLikeThis``, ``AsyncSuggest``,
+  and ``AsyncExtract`` are kept as backward-compatible aliases.
+
+**Example:**
+
+.. code-block:: python
+
+    from solr import Solr, AsyncSolr, SchemaAPI
+
+    # Sync — returns list directly
+    conn = Solr('http://localhost:8983/solr/mycore')
+    schema = SchemaAPI(conn)
+    fields = schema.fields()
+
+    # Async — returns coroutine
+    async with AsyncSolr('http://localhost:8983/solr/mycore') as conn:
+        schema = SchemaAPI(conn)
+        fields = await schema.fields()
+
+
 2.0.3 (2026-03-27)
 -------------------
 

docs/quickstart.rst

@@ -521,15 +521,23 @@ Priority: ``auth`` callable > ``auth_token`` > ``http_user/http_pass``.
 SolrCloud
 ---------
 
-**With ZooKeeper** (real-time node discovery, requires ``kazoo``)::
+Install ZooKeeper support::
+
+    pip install solrpy[cloud]
+
+**With ZooKeeper** (real-time node discovery via ``kazoo``)::
 
     from solr import SolrZooKeeper, SolrCloud
 
-    zk = SolrZooKeeper('zk1:2181,zk2:2181')
-    cloud = SolrCloud(zk, collection='mycore')
+    zk = SolrZooKeeper('zk1:2181,zk2:2181,zk3:2181')
+    cloud = SolrCloud(zk, collection='products')
 
-    response = cloud.select('*:*')
-    cloud.add({'id': '1', 'title': 'test'}, commit=True)
+    # Reads go to any active replica (automatic failover)
+    response = cloud.select('category:books', rows=20)
+
+    # Writes are routed to shard leaders
+    cloud.add({'id': '1', 'title': 'Solr in Action'}, commit=True)
+    cloud.delete(id='1', commit=True)
 
     cloud.close()
     zk.close()
@@ -540,14 +548,58 @@ SolrCloud
 
     cloud = SolrCloud.from_urls(
         ['http://solr1:8983/solr', 'http://solr2:8983/solr'],
-        collection='mycore')
+        collection='products')
 
     response = cloud.select('*:*')
     cloud.close()
 
-Install ZooKeeper support::
+Pass connection options (timeout, auth, SSL) via ``**solr_kwargs``::
 
-    pip install solrpy[cloud]
+    cloud = SolrCloud(zk, collection='secure',
+                      timeout=10,
+                      auth_token='my-jwt-token')
+
+Failover retries default to 3 with exponential backoff::
+
+    # Customize retry behavior
+    cloud = SolrCloud(zk, collection='products',
+                      retry_count=5, retry_delay=1.0)
+
+
+Using SolrZooKeeper directly
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can also use ``SolrZooKeeper`` independently for cluster inspection::
+
+    from solr import SolrZooKeeper
+
+    zk = SolrZooKeeper('zk1:2181,zk2:2181')
+
+    # List active nodes
+    print(zk.live_nodes())
+    # ['solr1:8983_solr', 'solr2:8983_solr', 'solr3:8983_solr']
+
+    # Get all replica URLs for a collection
+    replicas = zk.replica_urls('products')
+    # ['http://solr1:8983/solr', 'http://solr2:8983/solr']
+
+    # Get shard leader URLs (one per shard)
+    leaders = zk.leader_urls('products')
+    # ['http://solr1:8983/solr']
+
+    # Check collection aliases
+    aliases = zk.aliases()
+    # {'prod': 'products_v2', 'staging': 'products_v1'}
+
+    # Aliases are resolved automatically in replica_urls/leader_urls
+    zk.replica_urls('prod')  # same as zk.replica_urls('products_v2')
+
+    # Inspect collection state (shards, replicas, router)
+    state = zk.collection_state('products')
+    for shard, data in state['shards'].items():
+        print(shard, len(data['replicas']), 'replicas')
+
+    zk.close()
 
 
 Pydantic response models
@@ -576,6 +628,41 @@ Convert search results to typed Pydantic models (``pip install solrpy[pydantic]`
     products = resp.as_models(Product)
 
 
+Async usage
+-----------
+
+Use ``AsyncSolr`` for async/await support (e.g. in FastAPI, aiohttp)::
+
+    from solr import AsyncSolr
+
+    async with AsyncSolr('http://localhost:8983/solr/mycore') as conn:
+        response = await conn.select('*:*')
+        for doc in response.results:
+            print(doc['id'])
+
+Unified sync/async companions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Since 2.0.4, all companion classes work with both ``Solr`` and ``AsyncSolr``.
+No need for separate ``AsyncSchemaAPI``, ``AsyncKNN``, etc.::
+
+    from solr import Solr, AsyncSolr, SchemaAPI, KNN
+
+    # Sync
+    conn = Solr('http://localhost:8983/solr/mycore')
+    schema = SchemaAPI(conn)
+    fields = schema.fields()
+
+    # Async — same class, returns coroutines
+    async with AsyncSolr('http://localhost:8983/solr/mycore') as conn:
+        schema = SchemaAPI(conn)
+        fields = await schema.fields()
+
+The ``AsyncSchemaAPI``, ``AsyncKNN``, ``AsyncMoreLikeThis``,
+``AsyncSuggest``, and ``AsyncExtract`` names are kept as backward-compatible
+aliases.
+
+
 Closing the connection
 ----------------------