refactor(index): remove connect, set_client, connection_args, redis_kwargs

[vishal-bala]

Motivation

SearchIndex.connect() and set_client() and their AsyncSearchIndex counterparts have warned since v0.4.0, and the project has shipped 23 further minor versions without removing them. #660 reported that set_client() closes a client the caller still owns; two pull requests tried to repair the ownership logic inside it and both were closed, because patching a method nobody should be on is the wrong fix.

None of these methods had working ownership semantics to preserve. set_client() attached a finalizer based on whatever ownership the index already had, so it closed a caller's client on an index built from redis_url and never took ownership on one built with a client. It also silently abandoned the client it replaced. The method over-claimed or under-claimed depending on how the index was constructed, so this removes a broken capability rather than a working one.

This is the second of three stacked pull requests. The first added owns_client, which is what a caller migrating off set_client() needs.

Changes

The four methods, and the coercion that went with them

AsyncSearchIndex.connect() emitted three DeprecationWarnings per call: its own decorator, a redundant inline warnings.warn(), and set_client()'s decorator via delegation. All three go together.

AsyncSearchIndex._validate_client() goes too, since set_client() was its only caller. It carried the sync-to-async client coercion, so handing an async index a sync client is now rejected rather than silently converted. Both constructors gained a guard for the wrong client flavour, which also restores the TypeError that set_client() used to raise for the sync index — previously the only place that rejection existed.

# before
index = SearchIndex(schema)
index.set_client(my_client)

# after
index = SearchIndex(schema, redis_client=my_client)
# ...or, to have the index close it for you
index = SearchIndex(schema, redis_client=my_client, owns_client=True)

The guard uses isinstance rather than issubclass(type(...)), deliberately: Mock(spec=AsyncRedis) sets __class__, so isinstance catches a mis-flavoured spec'd mock while an unspecced mock still passes, which much of the test suite relies on. It is also deliberately one-sided — it rejects the wrong flavour but does not assert the object is a Redis client at all, because a positive check would reject those mocks.

connection_args and redis_kwargs

Both are removed, and both had a second entry point the issue discussion never mentioned: they appeared in the nested_connection_keys tuples passed to _split_from_existing_kwargs, so from_existing(name, connection_args={...}) was accepted with no warning at all. Removing only the decorated path would have left the deprecated spelling alive.

**kwargs would otherwise swallow both names in silence, which is worse than the warning it replaces, so a table of old spellings raises a TypeError naming the current one. The message contains parameter names only, never argument values: connection keywords carry passwords, and a message shaped as "unexpected keys: {...}" would put a live credential into an exception string and from there into logs.

With those gone every caller of _split_from_existing_kwargs passed the same tuple, so nested_connection_keys is inlined.

Minor

• Four cast calls in the semantic cache were replaced by a TypedDict on BaseCache.redis_kwargs, removing eight casts in that file. They were all working around one missing annotation on a heterogeneous dict literal, and cast() asserted a type the checker could not verify.
• Both class docstrings gained a client-injection example. set_client()'s docstring was the only place in the rendered API reference that explained using a client you configured yourself, and docs/api/searchindex.rst renders both classes with a bare autoclass, so deleting the method took the explanation with it.
• disconnect() was documented as "Disconnect from the Redis database" on two classes and not at all on the async one, and its log line claimed the index did not own a client it had in fact created.

Notes

Removing @deprecated_argument from the two constructors surfaced four pre-existing type errors in the semantic cache. The decorator returns a bare Callable and wraps the function in an untyped wrapper, which erases the signature, so mypy had never checked a single call site of SearchIndex(...) or AsyncSearchIndex(...) anywhere in the codebase. There are roughly 45 remaining applications of that decorator, each a hole in make check-types; retyping it with ParamSpec is tracked separately, and would surface all of them at once.

RedisConnectionFactory.sync_to_async_redis() survives even though _validate_client() goes, because BaseCache._get_async_redis_client is a second, non-deprecated caller. Its coverage survives too, through the LLM cache integration tests that build a cache on a sync client and then await an async method.

from_existing now checks client flavour before the broader validate_sync_redis, which otherwise fired first with a message that says what is wrong but not what to do. The two checks cannot be merged: validate_sync_redis is an allow-list that rejects any non-client including a bare mock, while the constructor guard is a deny-list that must let mocks through.

disconnect_sync() on an async index is a no-op when a loop is already running, because it cannot await the close from inside one. That is intended — it exists for __del__ and shutdown hooks — but it was undocumented and one of the ownership tests had been asserting await disconnect() under a name promising disconnect_sync(), so the method it was named for was never exercised. Both are fixed.

Release Notes

SearchIndex.connect(), SearchIndex.set_client() and their AsyncSearchIndex counterparts are removed. Pass redis_client or redis_url to the constructor instead, and add owns_client=True if the index should close a client you supplied.

The connection_args and redis_kwargs constructor keywords are removed in favour of connection_kwargs; the value is unchanged. Both now raise TypeError naming the replacement rather than being silently ignored.

AsyncSearchIndex no longer converts a sync Redis client for you. Pass an async client, or convert a non-cluster client yourself with RedisConnectionFactory.sync_to_async_redis(). Passing the wrong flavour of client to either index class now raises TypeError at construction rather than failing at first use, and handing an async client to AsyncSearchIndex's counterpart raises TypeError where it previously raised ValueError.