[Yufeng He (he-yufeng)]

Motivation & Context

AzureDocumentDBStore and AzureDocumentDBCollection reject caller-supplied PyMongo clients, databases, and collections whenever redundant connection settings are present. They also require an explicit database name for an account-level injected client instead of using the existing environment selector. This prevents configuration layers from injecting a fully configured object while still forwarding unrelated construction settings.

Fixes #9954, which is labelled ready-for-implementation and defines the injection, selector, and ownership acceptance cases. No competing open PR exists for this issue.

Description & Review Guide

• What are the major changes? Injected objects now bypass connection strings, client options, selected .env files, and ambient connection settings. Account clients resolve a missing database selector from AZURE_DOCUMENTDB_DATABASE_NAME. Collections created from an injected client or database resolve a missing collection selector from an explicit argument, the registered model definition, then AZURE_DOCUMENTDB_COLLECTION_NAME. Resource settings are loaded separately, so connection parsing and validation cannot leak back into these paths.
• Injected database and collection names still support exact matching validation, multiple injected objects are still rejected, and caller-owned clients remain open after wrapper cleanup. No-injection initialization and connector-owned cleanup are unchanged.
• The package guide and constructor documentation now describe precedence, selector fallback, and ownership. New regression coverage spans all five store/collection injection targets, explicit and environment selectors, missing selectors, invalid ambient settings, name mismatches, and registered-model fallback without an explicit definition. The original settings matrix produced 14 failures on the base and passes after the change. Missing-selector errors now name the actual database_name or collection_name constructor argument. On final head edc158364f, the complete connector suite is 129 passed, 1 skipped; mypy and zuban report no issues in the four test source files, Pyright reports zero source errors, and Ruff passes.
• What is the impact of these changes? Alpha construction stops raising for redundant settings and consistently treats injected objects as caller-owned. Provider operation and schema options are untouched.
• What do you want reviewers to focus on? Please check the separation between client-construction settings and resource selectors, especially the registered-definition-before-environment collection-name precedence and the preservation of multiple-injection and name-mismatch errors.

Related Issue

Fixes #9954

AI Assistance

• No material AI assistance was used.
• This is an AI-assisted contribution. I reviewed, understood, and verified all submitted content and accept responsibility for it.

AI assistance details: implementation, tests, documentation, and this PR description. The author reviewed the final diff, ran the base-to-fixed regression controls and connector suite, and checked Ruff, Pyright, and repository hooks locally.

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change or repository-automation exception.
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix); a workflow keeps the label and title prefix in sync automatically.

[Copilot]

🟡 Changes recommended

Missing-selector errors reference a nonexistent constructor argument, and precedence tests leave registered-model collection names untested against conflicting environment settings.

2 open issues

• Report the correct constructor argument for missing selectors · New
• Test environment precedence for registered model definitions · New

What changed in this PR

This PR addresses #9954 by making the Python DocumentDB connector prefer caller-injected PyMongo objects over connection settings while preserving caller ownership.

Changes:

• Separates resource-selector resolution from client-construction settings.
• Adds environment fallback for unresolved selectors, with model-defined collection names taking precedence.
• Documents injection behavior and adds regression tests for precedence, validation, and cleanup.

File	Description
python/​packages/​azure-documentdb/​tests/​azure_documentdb/​test_settings.py	Adds injection, selector, name-mismatch, and ownership regression coverage.
python/​packages/​azure-documentdb/​README.md	Explains injected-object precedence and selector fallback.
python/​packages/​azure-documentdb/​agent_framework_azure_documentdb/​_vector_store.py	Updates injection handling, isolates selector settings, and documents constructor behavior.

_{Review effort: Balanced}

[Yufeng He (he-yufeng)]

Split the selector-only settings into database and collection schemas. Missing-selector errors now identify the actual database_name or collection_name constructor argument as well as the corresponding environment variable. The regression asserts both parts of the message for account-client, collection-client, and database injection paths.

[Yufeng He (he-yufeng)]

Added a registered-model regression with no definition argument and a conflicting AZURE_DOCUMENTDB_COLLECTION_NAME, parameterized over both injected account-client and injected-database paths. The collection name comes from the registration in both cases. The full connector suite now has 129 passed, 1 skipped.