From 4de7e95ceec0c96e88d9cb3b66fe6f83eda24269 Mon Sep 17 00:00:00 2001 From: Zeding Zhang Date: Mon, 2 Nov 2026 18:50:18 +0000 Subject: [PATCH 1/2] Python: Prefer injected Qdrant clients over connection settings An injected AsyncQdrantClient now takes precedence over URL, API key, and .env options. Those settings are not read, and the caller keeps ownership even when managed_client is true. Fixes #9957 Co-authored-by: ZedingZhang --- python/packages/qdrant/README.md | 6 +- .../agent_framework_qdrant/_vector_store.py | 104 +++++++++++------- .../packages/qdrant/tests/qdrant/conftest.py | 27 +++-- .../qdrant/tests/qdrant/test_collection.py | 77 ++++++++----- .../qdrant/tests/qdrant/test_settings.py | 78 ++++++++++++- 5 files changed, 206 insertions(+), 86 deletions(-) diff --git a/python/packages/qdrant/README.md b/python/packages/qdrant/README.md index 87bf7f14c8d..ce4df4ce044 100644 --- a/python/packages/qdrant/README.md +++ b/python/packages/qdrant/README.md @@ -23,9 +23,9 @@ then an optional `env_file_path`, then environment variables. API keys accept `str` or AF `SecretString` and are unwrapped only when creating the SDK client. You can instead pass a configured `AsyncQdrantClient` as `async_client` for -advanced SDK options. Supplied clients bypass settings loading and remain -caller-owned unless `managed_client=True`; connector-created clients are closed -on async context exit. +advanced SDK options. An injected client takes precedence over URL, API-key, +and `.env` settings and always remains caller-owned. Connector-created clients +are closed on async context exit. ## Usage diff --git a/python/packages/qdrant/agent_framework_qdrant/_vector_store.py b/python/packages/qdrant/agent_framework_qdrant/_vector_store.py index 35bb5e62743..2c72924489d 100644 --- a/python/packages/qdrant/agent_framework_qdrant/_vector_store.py +++ b/python/packages/qdrant/agent_framework_qdrant/_vector_store.py @@ -74,6 +74,34 @@ def _create_client( ) +def _resolve_client( + async_client: AsyncQdrantClient | None, + *, + url: str | None, + api_key: str | SecretString | None, + managed_client: bool | None, + env_file_path: str | None, + env_file_encoding: str | None, +) -> tuple[AsyncQdrantClient, bool]: + """Return the client and whether this connector closes it. + + An injected client is returned unchanged. URL, API key, and ``.env`` options + are not read, and the caller keeps ownership even when ``managed_client`` is set. + Connector-created clients are owned unless ``managed_client`` is false. + """ + if async_client is not None: + return async_client, False + return ( + _create_client( + url=url, + api_key=api_key, + env_file_path=env_file_path, + env_file_encoding=env_file_encoding, + ), + True if managed_client is None else managed_client, + ) + + _DISTANCES = { "DEFAULT": models.Distance.COSINE, "cosine_similarity": models.Distance.COSINE, @@ -327,7 +355,7 @@ class QdrantCollection(BaseVectorCollection[KeyT, ModelT], BaseVectorSearch[KeyT All dense fields are named vectors. The default metric is cosine similarity (larger is better), not cosine distance. Scores and thresholds retain native - Qdrant units. Supplied clients remain caller-owned unless explicitly managed. + Qdrant units. Supplied clients remain caller-owned. Portable filters require a server: Qdrant's local emulator has different null/missing and numeric matching behavior across supported SDK versions. @@ -359,34 +387,33 @@ def __init__( definition: Explicit dictionary schema. collection_name: Collection name, overriding the model name. embedding_generator: Default local embedding client. - async_client: Existing async client, borrowed by default. Use this for local mode or advanced configuration. - url: Server URL override; otherwise loaded from QdrantSettings, then the SDK defaults to localhost. - api_key: API key override as a string or SecretString; otherwise loaded from QdrantSettings. - managed_client: Whether to close the client. Defaults to True only for connector-created clients. + async_client: Existing async client for local mode or advanced configuration. When supplied, URL, + API-key, and .env options are ignored and the client remains caller-owned. + url: Server URL override used when creating a client; otherwise loaded from QdrantSettings, then the SDK + defaults to localhost. + api_key: API key override as a string or SecretString, used when creating a client; otherwise loaded from + QdrantSettings. + managed_client: Whether to close a connector-created client. Defaults to True. Ignored for an injected + client, which always remains caller-owned. env_file_path: Optional .env file to load before process environment variables. env_file_encoding: Encoding for the .env file; defaults to UTF-8. """ - if async_client is not None and any( - value is not None for value in (url, api_key, env_file_path, env_file_encoding) - ): - raise ValueError("Pass async_client or connection settings, not both.") + resolved_client, owns_client = _resolve_client( + async_client, + url=url, + api_key=api_key, + managed_client=managed_client, + env_file_path=env_file_path, + env_file_encoding=env_file_encoding, + ) super().__init__( record_type, definition=definition, collection_name=collection_name, embedding_generator=embedding_generator, - managed_client=async_client is None if managed_client is None else managed_client, - ) - self.async_client = ( - async_client - if async_client is not None - else _create_client( - url=url, - api_key=api_key, - env_file_path=env_file_path, - env_file_encoding=env_file_encoding, - ) + managed_client=owns_client, ) + self.async_client = resolved_client self._closed = False @property @@ -817,32 +844,31 @@ def __init__( """Initialize a store. Args: - async_client: Existing async client; borrowed unless managed_client=True. - url: Server URL override; otherwise loaded from QdrantSettings, then the SDK defaults to localhost. - api_key: API key override as a string or SecretString; otherwise loaded from QdrantSettings. + async_client: Existing async client. When supplied, URL, API-key, and .env options are ignored and the + client remains caller-owned. + url: Server URL override used when creating a client; otherwise loaded from QdrantSettings, then the SDK + defaults to localhost. + api_key: API key override as a string or SecretString, used when creating a client; otherwise loaded from + QdrantSettings. embedding_generator: Default embedding client inherited by collections. - managed_client: Whether to close the client. Defaults to True for connector-created clients. + managed_client: Whether to close a connector-created client. Defaults to True. Ignored for an injected + client, which always remains caller-owned. env_file_path: Optional .env file to load before process environment variables. env_file_encoding: Encoding for the .env file; defaults to UTF-8. """ - if async_client is not None and any( - value is not None for value in (url, api_key, env_file_path, env_file_encoding) - ): - raise ValueError("Pass async_client or connection settings, not both.") + resolved_client, owns_client = _resolve_client( + async_client, + url=url, + api_key=api_key, + managed_client=managed_client, + env_file_path=env_file_path, + env_file_encoding=env_file_encoding, + ) super().__init__( embedding_generator=embedding_generator, - managed_client=async_client is None if managed_client is None else managed_client, - ) - self.async_client = ( - async_client - if async_client is not None - else _create_client( - url=url, - api_key=api_key, - env_file_path=env_file_path, - env_file_encoding=env_file_encoding, - ) + managed_client=owns_client, ) + self.async_client = resolved_client self._closed = False def get_collection( diff --git a/python/packages/qdrant/tests/qdrant/conftest.py b/python/packages/qdrant/tests/qdrant/conftest.py index 47bff63a300..81d5c723f45 100644 --- a/python/packages/qdrant/tests/qdrant/conftest.py +++ b/python/packages/qdrant/tests/qdrant/conftest.py @@ -97,15 +97,18 @@ def make(record_type=dict, *, definition=definition, embedding_generator=None): async def server_collection(definition): if not os.getenv("QDRANT_TEST_URL"): pytest.skip("Set QDRANT_TEST_URL to a disposable Qdrant server.") - async with QdrantCollection( - dict, - definition=definition, - collection_name=f"af_qdrant_test_{uuid4().hex}", - async_client=AsyncQdrantClient(url=os.environ["QDRANT_TEST_URL"], check_compatibility=False), - managed_client=True, - ) as collection: - await collection.ensure_collection_exists() - try: - yield collection - finally: - await collection.ensure_collection_deleted() + client = AsyncQdrantClient(url=os.environ["QDRANT_TEST_URL"], check_compatibility=False) + try: + async with QdrantCollection( + dict, + definition=definition, + collection_name=f"af_qdrant_test_{uuid4().hex}", + async_client=client, + ) as collection: + await collection.ensure_collection_exists() + try: + yield collection + finally: + await collection.ensure_collection_deleted() + finally: + await client.close() diff --git a/python/packages/qdrant/tests/qdrant/test_collection.py b/python/packages/qdrant/tests/qdrant/test_collection.py index 33b6d159aa0..ff6c0ff6c4d 100644 --- a/python/packages/qdrant/tests/qdrant/test_collection.py +++ b/python/packages/qdrant/tests/qdrant/test_collection.py @@ -313,10 +313,22 @@ async def test_client_ownership(definition): ): pass client.close.assert_not_awaited() - async with QdrantStore(async_client=client, managed_client=True) as owner: - pass + async with QdrantStore(async_client=client, url="https://ignored.example", managed_client=True) as owner: + assert owner.async_client is client + assert not owner.managed_client await owner.aclose() - client.close.assert_awaited_once() + async with QdrantCollection( + dict, + definition=definition, + collection_name="test", + async_client=client, + api_key="ignored-key", + managed_client=True, + ) as injected: + assert injected.async_client is client + assert not injected.managed_client + await injected.aclose() + client.close.assert_not_awaited() client.reset_mock() with patch("agent_framework_qdrant._vector_store.AsyncQdrantClient", return_value=client): async with QdrantCollection( @@ -364,24 +376,32 @@ async def test_api_key_unwrapped_at_sdk_boundary( @pytest.mark.parametrize("route", ["collection", "store"]) -@pytest.mark.parametrize("api_key", [SecretString("test-api-key"), SecretString("")]) -def test_api_key_rejected_with_supplied_client(definition, route: str, api_key: SecretString): +@pytest.mark.parametrize("api_key", [SecretString("test-api-key"), SecretString(""), "plain-key", ""]) +async def test_api_key_ignored_with_supplied_client(definition, route: str, api_key: SecretString | str): client = AsyncMock(spec=AsyncQdrantClient) with ( patch("agent_framework_qdrant._vector_store.AsyncQdrantClient") as factory, - pytest.raises(ValueError, match="connection settings"), + patch("agent_framework_qdrant._vector_store.load_settings") as loader, ): + connector: QdrantCollection | QdrantStore if route == "collection": - QdrantCollection( + connector = QdrantCollection( dict, definition=definition, collection_name="test", async_client=client, api_key=api_key, + managed_client=True, ) + assert connector.definition is definition else: - QdrantStore(async_client=client, api_key=api_key) + connector = QdrantStore(async_client=client, api_key=api_key, managed_client=True) + assert connector.async_client is client + assert not connector.managed_client + await connector.aclose() factory.assert_not_called() + loader.assert_not_called() + client.close.assert_not_awaited() async def test_failed_and_partial_batches(definition, record): @@ -402,18 +422,21 @@ async def test_failed_and_partial_batches(definition, record): async def test_local_filters_rejected_even_on_empty_collection(definition): - async with QdrantCollection( - dict, - definition=definition, - collection_name="test", - async_client=AsyncQdrantClient(":memory:"), - managed_client=True, - ) as collection: - await collection.ensure_collection_exists() - with pytest.raises(NotImplementedError, match="server"): - await collection.get(filter=Filter("text", "eq", "hi")) - with pytest.raises(NotImplementedError, match="server"): - await collection.search(vector=[1, 0, 0], filter=Filter("integer", "eq", 1)) + client = AsyncQdrantClient(":memory:") + try: + async with QdrantCollection( + dict, + definition=definition, + collection_name="test", + async_client=client, + ) as collection: + await collection.ensure_collection_exists() + with pytest.raises(NotImplementedError, match="server"): + await collection.get(filter=Filter("text", "eq", "hi")) + with pytest.raises(NotImplementedError, match="server"): + await collection.search(vector=[1, 0, 0], filter=Filter("integer", "eq", 1)) + finally: + await client.close() @pytest.mark.parametrize("init_options", [{}, {"location": ":memory:"}, {"path": "local-storage"}]) @@ -486,12 +509,14 @@ async def test_unsupported_options_and_schema(definition): await collection.get(order_by={"integer": True}) with pytest.raises(ValueError, match="finite"): await collection.search(vector=[1, 0, 0], score_threshold=math.nan) - with pytest.raises(ValueError, match="connection settings"): - QdrantStore(async_client=client, url="http://localhost") - with pytest.raises(ValueError, match="connection settings"): - QdrantCollection( - dict, definition=definition, collection_name="test", async_client=client, url="http://localhost" - ) + store = QdrantStore(async_client=client, url="http://localhost", managed_client=True) + assert store.async_client is client + assert not store.managed_client + injected = QdrantCollection( + dict, definition=definition, collection_name="test", async_client=client, url="http://localhost" + ) + assert injected.async_client is client + assert injected.collection_name == "test" @pytest.mark.parametrize( diff --git a/python/packages/qdrant/tests/qdrant/test_settings.py b/python/packages/qdrant/tests/qdrant/test_settings.py index 908cb4bf718..4eebe4994cc 100644 --- a/python/packages/qdrant/tests/qdrant/test_settings.py +++ b/python/packages/qdrant/tests/qdrant/test_settings.py @@ -137,12 +137,78 @@ async def test_injected_client_bypasses_environment_settings(connector_factory, client.close.assert_not_awaited() -@pytest.mark.parametrize("settings", [{"env_file_path": "unused.env"}, {"env_file_encoding": "utf-16"}]) -def test_injected_client_rejects_explicit_env_options(connector_factory, settings): +@pytest.mark.parametrize( + "settings", + [ + {"url": "https://ignored.example"}, + {"url": ""}, + {"url": {}}, + {"api_key": "ignored-key"}, + {"api_key": SecretString("ignored-key")}, + {"api_key": ""}, + {"api_key": 123}, + {"env_file_path": "missing.env"}, + {"env_file_encoding": "invalid-encoding"}, + {"managed_client": True}, + { + "url": "https://ignored.example", + "api_key": SecretString("ignored-key"), + "env_file_path": "missing.env", + "env_file_encoding": "invalid-encoding", + "managed_client": True, + }, + ], +) +async def test_injected_client_ignores_connection_settings(connector_factory, monkeypatch, settings): + monkeypatch.setenv("QDRANT_URL", "not-a-url") + monkeypatch.setenv("QDRANT_API_KEY", "ambient-key") client = AsyncMock(spec=AsyncQdrantClient) + client.init_options = {} with ( - patch("agent_framework_qdrant._vector_store.load_settings") as loader, - pytest.raises(ValueError, match="connection settings"), + patch( + "agent_framework_qdrant._vector_store.load_settings", + side_effect=AssertionError("Unexpected settings read"), + ), + patch("agent_framework_qdrant._vector_store.AsyncQdrantClient") as factory, ): - connector_factory(async_client=client, **settings) - loader.assert_not_called() + async with connector_factory(async_client=client, **settings) as connector: + assert connector.async_client is client + assert connector.managed_client is False + if isinstance(connector, QdrantCollection): + assert connector.collection_name == "test" + assert connector.definition.key_field.name == "id" + with pytest.raises(ValueError, match="Unsupported"): + await connector.get(operation_options={"with_payload": False}) + await connector.aclose() + factory.assert_not_called() + client.close.assert_not_awaited() + + +async def test_store_collection_reuses_injected_client(definition, monkeypatch): + monkeypatch.setenv("QDRANT_URL", "not-a-url") + monkeypatch.setenv("QDRANT_API_KEY", "ambient-key") + client = AsyncMock(spec=AsyncQdrantClient) + with ( + patch( + "agent_framework_qdrant._vector_store.load_settings", + side_effect=AssertionError("Unexpected settings read"), + ), + patch("agent_framework_qdrant._vector_store.AsyncQdrantClient") as factory, + ): + async with QdrantStore( + async_client=client, + url="https://ignored.example", + api_key=SecretString("ignored-key"), + env_file_path="missing.env", + env_file_encoding="invalid-encoding", + managed_client=True, + ) as store: + collection = store.get_collection(dict, definition=definition, collection_name="documents") + assert collection.async_client is client + assert collection.managed_client is False + assert collection.collection_name == "documents" + assert collection.definition is definition + await collection.aclose() + await store.aclose() + factory.assert_not_called() + client.close.assert_not_awaited() From 6110918744345863569e5c0c2311359281f12e8b Mon Sep 17 00:00:00 2001 From: Zeding Zhang Date: Mon, 2 Nov 2026 18:59:15 +0000 Subject: [PATCH 2/2] Python: Validate Qdrant collections before creating a client QdrantCollection now runs base initialization before resolving a client, so invalid collection arguments raise without calling the SDK factory. Co-authored-by: ZedingZhang --- .../qdrant/agent_framework_qdrant/_vector_store.py | 14 +++++++------- .../qdrant/tests/qdrant/test_collection.py | 9 +++++++++ 2 files changed, 16 insertions(+), 7 deletions(-) diff --git a/python/packages/qdrant/agent_framework_qdrant/_vector_store.py b/python/packages/qdrant/agent_framework_qdrant/_vector_store.py index 2c72924489d..e1ac6936ccf 100644 --- a/python/packages/qdrant/agent_framework_qdrant/_vector_store.py +++ b/python/packages/qdrant/agent_framework_qdrant/_vector_store.py @@ -398,6 +398,12 @@ def __init__( env_file_path: Optional .env file to load before process environment variables. env_file_encoding: Encoding for the .env file; defaults to UTF-8. """ + super().__init__( + record_type, + definition=definition, + collection_name=collection_name, + embedding_generator=embedding_generator, + ) resolved_client, owns_client = _resolve_client( async_client, url=url, @@ -406,14 +412,8 @@ def __init__( env_file_path=env_file_path, env_file_encoding=env_file_encoding, ) - super().__init__( - record_type, - definition=definition, - collection_name=collection_name, - embedding_generator=embedding_generator, - managed_client=owns_client, - ) self.async_client = resolved_client + self.managed_client = owns_client self._closed = False @property diff --git a/python/packages/qdrant/tests/qdrant/test_collection.py b/python/packages/qdrant/tests/qdrant/test_collection.py index ff6c0ff6c4d..60405887ebf 100644 --- a/python/packages/qdrant/tests/qdrant/test_collection.py +++ b/python/packages/qdrant/tests/qdrant/test_collection.py @@ -519,6 +519,15 @@ async def test_unsupported_options_and_schema(definition): assert injected.collection_name == "test" +def test_invalid_collection_arguments_do_not_create_client(): + with ( + patch("agent_framework_qdrant._vector_store.AsyncQdrantClient") as factory, + pytest.raises(ValueError, match="VectorStoreCollectionDefinition"), + ): + QdrantCollection(dict, collection_name="test", url="https://qdrant.example") + factory.assert_not_called() + + @pytest.mark.parametrize( "kwargs", [