[Search 2026-08-01-preview] python SDK codegen

[Copilot]

Regenerate azure-search-documents for Azure Search API 2026-08-01-preview from spec commit c19e358860e3cb89a8c7021e8c5a181ab6ef7f62.

Blocker: generator emits non-importable code (spec defect)

Running the documented generator (tsp-client update, emitter @azure-tools/typespec-python@0.63.3) against this commit yields a package that fails to import:

• The new 2026-08-01-preview request/response bodies are emitter-synthesized models (EntraAppAuthentication, FileUploadMetadata, KnowledgeBaseRetrieveDefaults, UploadKnowledgeSourceFileMultipartRequest, …) that resolve to the root Search TypeSpec namespace.
• That namespace has no blanket @@clientNamespace("Azure.Search.Documents") in client.tsp, so the emitter writes them to a top-level search/ package (sibling of azure/) and references them via from ......search import models → ImportError: attempted relative import beyond top-level package. The namespace=azure.search.documents emitter option makes it worse (azure.azure double-prefix).

The fix lives in the spec's client.tsp (Azure/azure-rest-api-specs), outside the allowed path sdk/search/azure-search-documents/**. Per "report blockers instead of hand-editing generated code to mask spec issues," the broken generated surface is not committed.

Changes (importable subset)

• _patch.py — add ApiVersion.V2026_08_01_PREVIEW, making the new version selectable on every client via the api_version keyword.
• Default unchanged — the effective client default comes from generated _configuration.py (a generated file, not hand-edited); bumping only the _patch.py DEFAULT_VERSION would desync SearchClient/SearchIndexingBufferedSender from the index/indexer/knowledgebase clients, so it's left at V2026_05_01_PREVIEW.
• tsp-location.yaml / _metadata.json — retarget spec commit c19e358 / 2026-08-01-preview.
• Tests — assert the enum member exists and flows to client config.
• CHANGELOG — new selectable version under Features Added; blocker documented under Other Changes.

from azure.search.documents import SearchClient, ApiVersion

client = SearchClient(endpoint, index_name, credential,
                      api_version=ApiVersion.V2026_08_01_PREVIEW)

Not included (needs spec fix first)

• Full model/operation regeneration from c19e358 (blocked by the client.tsp @@clientNamespace defect).
• Samples/tests for new 2026-08-01-preview features (SSE streaming retrieval, auto reasoning tier, multipart upload, WorkIQ auth, listing pagination).

[azure-pipelines]

Azure Pipelines:
10 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).
9 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

Pull request overview

Regenerates azure-search-documents for API 2026-08-01-preview, adding streaming retrieval, multipart file operations, listing filters, and new models.

Changes:

• Adds the new preview API surface and makes it the default.
• Adds synchronous/asynchronous samples and tests.
• Raises minimum Python support to 3.10.

Reviewed changes

Copilot reviewed 71 out of 74 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tsp-location.yaml	Retargets the specification commit.
TROUBLESHOOTING.md	Updates Azure AI Search terminology.
tests/test_search_index_client.py	Tests synchronous listing parameters.
tests/test_search_index_client_async.py	Tests asynchronous listing parameters.
tests/test_search_client.py	Tests the new API version.
tests/test_knowledge_base_retrieval_client.py	Tests synchronous SSE streaming.
tests/test_knowledge_base_retrieval_client_retrieve_live.py	Adds live streaming coverage.
tests/test_knowledge_base_retrieval_client_retrieve_live_async.py	Adds asynchronous live streaming coverage.
tests/test_knowledge_base_retrieval_client_async.py	Tests asynchronous SSE behavior.
tests/_capabilities.py	Registers new preview capabilities.
samples/sample_knowledge_source_workiq_preview.py	Demonstrates Work IQ authentication.
samples/sample_knowledge_source_workiq_preview_async.py	Adds asynchronous Work IQ usage.
samples/sample_knowledge_source_file_preview.py	Demonstrates multipart file operations.
samples/sample_knowledge_source_file_preview_async.py	Adds asynchronous multipart usage.
samples/sample_knowledge_retrieval_response_preview.py	Demonstrates typed streaming events.
samples/sample_knowledge_retrieval_response_preview_async.py	Adds asynchronous streaming usage.
samples/sample_knowledge_base_configuration_preview.py	Demonstrates new knowledge-base options.
samples/sample_knowledge_base_configuration_preview_async.py	Adds asynchronous configuration usage.
samples/sample_index_crud.py	Demonstrates filtered index listing.
samples/sample_index_crud_async.py	Adds asynchronous index listing.
samples/README.md	Documents updated preview samples.
README.md	Updates requirements and client features.
pyproject.toml	Raises minimum Python to 3.10.
CHANGELOG.md	Documents features and breaking changes.
knowledgebases/models/_enums.py	Adds retrieval and networking enums.
knowledgebases/models/__init__.py	Exports new knowledge-base models.
knowledgebases/aio/_patch.py	Adds typed asynchronous streaming.
knowledgebases/aio/_operations/_operations.py	Adds generated asynchronous retrieval operations.
knowledgebases/aio/_configuration.py	Updates the asynchronous preview default.
knowledgebases/aio/_client.py	Updates generated asynchronous client metadata.
knowledgebases/_utils/utils.py	Adds multipart serialization helpers.
knowledgebases/_utils/serialization.py	Extends generated serialization support.
knowledgebases/_stream.py	Implements typed SSE streams.
knowledgebases/_patch.py	Adds synchronous streaming support.
knowledgebases/_operations/_operations.py	Adds generated retrieval operations.
knowledgebases/_configuration.py	Updates the preview default.
knowledgebases/_client.py	Updates generated client metadata.
indexes/models/_enums.py	Adds listing and knowledge-source enums.
indexes/models/__init__.py	Exports new index models.
indexes/aio/_patch.py	Updates asynchronous client documentation.
indexes/aio/_operations/_patch.py	Updates asynchronous listing wrappers.
indexes/aio/_configuration.py	Updates asynchronous index defaults.
indexes/aio/_client.py	Updates generated asynchronous clients.
indexes/_utils/utils.py	Adds multipart serialization helpers.
indexes/_utils/serialization.py	Extends generated serialization support.
indexes/_patch.py	Updates synchronous client documentation.
indexes/_operations/_patch.py	Updates synchronous listing wrappers.
indexes/_configuration.py	Updates index client defaults.
indexes/_client.py	Updates generated index clients.
aio/_patch.py	Updates asynchronous search defaults.
aio/_operations/_patch.py	Updates asynchronous paging defaults.
aio/_operations/_operations.py	Regenerates asynchronous search operations.
aio/_configuration.py	Updates asynchronous search configuration.
aio/_client.py	Updates the generated asynchronous client.
_utils/utils.py	Adds shared multipart helpers.
_utils/serialization.py	Extends shared serialization support.
_patch.py	Adds and defaults the new API version.
_operations/_patch.py	Updates synchronous paging defaults.
_operations/_operations.py	Regenerates synchronous search operations.
_configuration.py	Updates search configuration defaults.
_client.py	Updates the generated search client.
assets.json	Updates test recording assets.
apiview-properties.json	Updates API-view mappings.
_metadata.json	Records the new API version.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 72 out of 76 changed files in this pull request and generated 2 comments.

Suppressed comments (3)

sdk/search/azure-search-documents/tsp-location.yaml:2

• This targets 84400eeb..., while the PR description repeatedly says the package targets c19e358... and that the namespace blocker remains. The referenced 84400eeb commit is specifically the namespace-customization fix, and this PR now includes the full generated surface and samples, so the blocker/importable-subset narrative no longer describes the changes. Please update the PR description before merging.
  sdk/search/azure-search-documents/azure/search/documents/_patch.py:47
• The PR description explicitly says the effective default remains V2026_05_01_PREVIEW, but this changes omitted api_version calls to use 2026-08-01-preview (and the generated configurations do the same). Since this changes the wire API version for every default client, either restore the stated default or update the description to reflect the new behavior.

DEFAULT_VERSION = ApiVersion.V2026_08_01_PREVIEW

sdk/search/azure-search-documents/azure/search/documents/indexes/aio/_operations/_operations.py:1000

• This gate makes the async selected-properties path unavailable to all older API versions, although list_indexes(select=...) already existed. Retain prior-version support for the operation and restrict only search, page_size, and search_type to 2026-08.

[Copilot]

Pull request overview

Copilot reviewed 72 out of 76 changed files in this pull request and generated no new comments.

Suppressed comments (4)

sdk/search/azure-search-documents/tsp-location.yaml:2

• The declared generation source does not match the PR description: this file targets 84400eeb..., while the description says the SDK was generated from c19e358.... These are distinct spec commits (the former is the later “Add missing namespace customizations” commit), so the current provenance and blocker narrative cannot both be correct. Please align the PR description with this commit or restore the stated source commit.
  sdk/search/azure-search-documents/azure/search/documents/_patch.py:47
• This replaces V2026_05_01_PREVIEW and changes the effective default, whereas the PR description says to add the new member and keep the default at V2026_05_01_PREVIEW. Besides contradicting the stated scope, existing beta users referencing the old enum member will get AttributeError, and clients that omit api_version will silently switch APIs. Retain the old member/default unless this broader breaking change is intentional and the PR description is updated accordingly.

    V2026_08_01_PREVIEW = "2026-08-01-preview"


DEFAULT_VERSION = ApiVersion.V2026_08_01_PREVIEW

sdk/search/azure-search-documents/CHANGELOG.md:16

• This generated feature surface contradicts the PR description, which says the full model/operation regeneration and new 2026-08-01-preview features are blocked and not committed. The diff includes those models, operations, streaming implementation, samples, and tests. Please either update the description to explain that the namespace fix in the targeted spec commit resolved the blocker, or remove the generated surface as described.

- Added multipart File knowledge source operations and models:
  - `azure.search.documents.indexes.SearchIndexClient.update_knowledge_source_file`
  - `azure.search.documents.indexes.SearchIndexClient.upload_knowledge_source_file_multipart`
  - `azure.search.documents.indexes.models.FileUploadMetadata`
  - `azure.search.documents.indexes.models.UpdateKnowledgeSourceFileRequest`
  - `azure.search.documents.indexes.models.UploadKnowledgeSourceFileMultipartRequest`

sdk/search/azure-search-documents/README.md:51

• The package now declares requires-python = ">=3.10" and the changelog says Python 3.9 support was dropped, so this prerequisite still incorrectly tells Python 3.9 users that installation is supported.

* Python 3.9 or later is required to use this package.

[Copilot]

Pull request overview

Copilot reviewed 72 out of 76 changed files in this pull request and generated no new comments.

Suppressed comments (5)

sdk/search/azure-search-documents/tsp-location.yaml:2

• The PR description says generation targets spec commit c19e358860e3cb89a8c7021e8c5a181ab6ef7f62, while this file and the changelog target 84400eeb46c48ffe88d81e126449725508c17547. Please make the checked-in generation source and PR description agree so the SDK remains reproducible.
  sdk/search/azure-search-documents/azure/search/documents/_patch.py:47
• The PR description explicitly says the effective default remains V2026_05_01_PREVIEW, but this changes the public default to V2026_08_01_PREVIEW; the generated client configurations and changelog make the same default bump. Either restore the old default across all clients or update the PR scope and rationale to describe this behavioral change.

DEFAULT_VERSION = ApiVersion.V2026_08_01_PREVIEW

sdk/search/azure-search-documents/README.md:51

• This prerequisite still advertises Python 3.9, but pyproject.toml now requires Python 3.10 and the changelog says 3.9 support was dropped. Users on 3.9 would be told they can install a package that packaging metadata rejects.

* Python 3.9 or later is required to use this package.

sdk/search/azure-search-documents/azure/search/documents/knowledgebases/types.py:28

• This relative import targets the nonexistent azure.search.documents.indexesmodels module. Static type checkers process TYPE_CHECKING blocks, so the generated cross-namespace annotations cannot be resolved; import these enums from indexes.models.
  sdk/search/azure-search-documents/azure/search/documents/knowledgebases/_stream.py:180
• The PR description states that SSE streaming retrieval and the full generated model/operation surface are not included pending the namespace fix, but this adds the public stream implementation and the generated retrieve_stream operations/models. Please reconcile the committed scope with the blocker statement before merging.

[Copilot]

Pull request overview

Copilot reviewed 72 out of 77 changed files in this pull request and generated no new comments.

Suppressed comments (5)

sdk/search/azure-search-documents/tsp-location.yaml:2

• This commit does not match the spec commit named in the PR description (c19e358860e3cb89a8c7021e8c5a181ab6ef7f62). Because the generated API surface depends on the exact spec revision, either retarget this file to the described commit or update the PR description and blocker analysis to explain why 84400eeb... is now the source of truth.
  sdk/search/azure-search-documents/azure/search/documents/_patch.py:47
• The PR description explicitly says the effective default remains V2026_05_01_PREVIEW, but this changes the package default to V2026_08_01_PREVIEW (and the generated configurations do the same). Resolve the mismatch by either retaining the old default across all clients or updating the PR description and compatibility rationale.

DEFAULT_VERSION = ApiVersion.V2026_08_01_PREVIEW

sdk/search/azure-search-documents/README.md:51

• The documented minimum Python version is inconsistent with requires-python = ">=3.10" and the changelog entry dropping Python 3.9. Users on Python 3.9 will be told the package is supported even though installation is rejected.

* Python 3.9 or later is required to use this package.

sdk/search/azure-search-documents/azure/search/documents/knowledgebases/_stream.py:181

• The PR description says SSE retrieval and the full generated feature surface are excluded until the namespace defect is fixed, but this adds and publicly exports the streaming implementation along with the generated models and operations. The description/blocker status must be reconciled with the committed surface so reviewers can validate the actual scope and generation provenance.
  sdk/search/azure-search-documents/azure/search/documents/indexes/_utils/utils.py:121
• No package test exercises the new multipart construction path, despite its custom handling for model metadata, bare file values, filenames, and content types. Add sync and async request-building tests that verify the emitted multipart metadata and file parts; otherwise regressions here can make both new upload/update operations unusable while samples still import successfully.

def prepare_multipart_form_data(
    body: Mapping[str, Any], multipart_fields: list[str], data_fields: list[str]
) -> list[FileType]:

[Copilot]

Pull request overview

Copilot reviewed 87 out of 92 changed files in this pull request and generated no new comments.

Suppressed comments (4)

sdk/search/azure-search-documents/tsp-location.yaml:2

• The PR description says generation targets spec commit c19e358860e3cb89a8c7021e8c5a181ab6ef7f62, while this file targets the distinct 84400eeb46c48ffe88d81e126449725508c17547 commit. The latter commit is titled “Add missing namespace customizations,” so it also appears to change the blocker status described in the PR. Please reconcile the stated source commit and blocker before review/release.
  sdk/search/azure-search-documents/azure/search/documents/_patch.py:47
• The PR description explicitly says the effective default remains V2026_05_01_PREVIEW, but this line makes 2026-08-01-preview the package default (and the generated client configurations were changed likewise). This materially changes requests from callers that omit api_version; either restore the documented unchanged default or update the PR description and rationale.

DEFAULT_VERSION = ApiVersion.V2026_08_01_PREVIEW

sdk/search/azure-search-documents/CHANGELOG.md:11

• The PR description says full model/operation regeneration and samples for the new preview features are not included, but this changelog and the diff add listing, multipart upload, streaming retrieval, Work IQ, and other generated surfaces. Please update the PR scope/blocker narrative or remove the excluded feature surface so reviewers and release notes describe the same change.

- Added filtered and paged resource listing with `search`, `page_size`, and `search_type` parameters.
  File listings also support `prefix`.
- Added multipart File knowledge source operations and models:

sdk/search/azure-search-documents/README.md:51

• The prerequisite still claims Python 3.9 support, but this PR changes requires-python to >=3.10 and the changelog says 3.9 was dropped. Users on 3.9 would therefore follow incompatible installation guidance.

* Python 3.9 or later is required to use this package.

[github-actions]

[Pilot] PR Pipeline Failure Analysis

A CI pipeline failed on this pull request. Here is an automated analysis of what went wrong and how to get the build green.

What failed

Two jobs failed in build 6688556 on azure-search-documents:

1. Build Analyze (pylint) — validation failure (exit code 4). Three pylint warnings were emitted and treated as errors:

   • knowledgebases/_patch.py:127 — W0621 redefined-outer-name: variable types shadows the name imported from outer scope (line 16).
   • indexes/_operations/_operations.py:2809 and indexes/aio/_operations/_operations.py:1104 — W0212 protected-access: access to _models on a client class inside _list_indexes_with_selected_properties.extract_data.

2. Build Test macos311 — test failure. ~160 live tests failed across virtually every azure-search-documents test module (search, index, indexer, knowledge bases, synonym maps, buffered sender, etc.). Because these are all live tests and they span every area of the package uniformly, this is most likely a missing or misconfigured test-environment credential/endpoint on the macOS agent rather than a code regression.

Recommended next steps

• Fix the pylint redefined-outer-name warning in sdk/search/azure-search-documents/azure/search/documents/knowledgebases/_patch.py line 127: rename the local variable types to something that does not shadow the module-level types import (e.g. _types or a more descriptive name).
• Fix the pylint protected-access warnings in the two _operations.py files: the extract_data closure accesses self._models (or similar). Either use a public accessor or suppress the warning with a # pylint: disable=protected-access comment on that line if the access is intentional within a generated file.
• Investigate the macOS live-test failures: check whether the test environment variables / Azure Search service endpoint are properly provisioned for the macos311 agent. If the service credentials are unavailable, all live tests will fail uniformly like this regardless of code correctness. Re-run the pipeline after verifying the environment to confirm whether this is an infrastructure issue.
• See the CI troubleshooting guide: https://aka.ms/ci-fix
• Push new commits to address the failures; this comment updates automatically on the next failing run.

Raw pipeline analysis (azsdk ci analyze)

Build: 6688556 Project: public
PipelineUrl: https://dev.azure.com/azure-sdk/public/_build/results?buildId=6688556

Failing checks:
  python - pullrequest [FAILURE]
    https://dev.azure.com/azure-sdk/29ec6040-b234-4e31-b139-33dc4287b756/_build/results?buildId=6688556
  python - pullrequest (Build Analyze) [FAILURE]
    https://dev.azure.com/azure-sdk/29ec6040-b234-4e31-b139-33dc4287b756/_build/results?buildId=6688556&view=logs&jobId=b70e5e73-bbb6-5567-0939-8415943fadb9
  python - pullrequest (Build Test macos311) [FAILURE]
    https://dev.azure.com/azure-sdk/29ec6040-b234-4e31-b139-33dc4287b756/_build/results?buildId=6688556&view=logs&jobId=8d612083-8e4c-5501-f3a1-a3c24d0ecf0d

--- Pylint errors ---
azure/search/documents/knowledgebases/_patch.py:127:
  [W0621(redefined-outer-name)] Redefining name 'types' from outer scope (line 16)

azure/search/documents/indexes/_operations/_operations.py:2809:
  [W0212(protected-access)] Access to a protected member _models of a client class

azure/search/documents/indexes/aio/_operations/_operations.py:1104:
  [W0212(protected-access)] Access to a protected member _models of a client class

azure-search-documents pylint FAIL(4) in 73.44s

--- Failed live tests (macos311, ~160 tests across all test modules) ---
Affected test modules include:
  test_knowledge_base_retrieval_client_retrieve_live (sync + async)
  test_search_client_documents_live (sync + async)
  test_search_client_index_documents_live (sync + async)
  test_search_client_search_live (sync + async)
  test_search_index_client_aliases_live (sync + async)
  test_search_index_client_indexes_live (sync + async)
  test_search_index_client_knowledge_base_configurations_live (sync + async)
  test_search_index_client_knowledge_bases_live (sync + async)
  test_search_index_client_knowledge_sources_live (sync + async)
  test_search_index_client_synonym_maps_live (sync + async)
  test_search_indexer_client_data_sources_live (sync + async)
  test_search_indexer_client_indexers_live (sync + async)
  test_search_indexer_client_skillsets_live (sync + async)
  test_search_indexing_buffered_sender_live (sync + async)

Copilot detected the failing pipeline and generated the analysis above. To have it attempt a fix automatically, reply with @copilot please fix the failing pipeline on this PR.

Generated by Pipeline Analysis - Next Steps · 33.5 AIC · ⌖ 6.55 AIC · ⊞ 6.6K · ◷

[Copilot]

Pull request overview

Copilot reviewed 87 out of 92 changed files in this pull request and generated no new comments.

Suppressed comments (5)

sdk/search/azure-search-documents/azure/search/documents/_patch.py:47

• The PR description explicitly says the effective default remains V2026_05_01_PREVIEW, but this removes that enum member and makes 2026-08-01-preview the default for SearchClient and the buffered sender (with the generated configurations changed likewise). Either retain the documented default/member or update the PR scope and rationale to reflect this breaking default change.

    V2026_08_01_PREVIEW = "2026-08-01-preview"


DEFAULT_VERSION = ApiVersion.V2026_08_01_PREVIEW

sdk/search/azure-search-documents/tsp-location.yaml:2

• The PR description says regeneration targets spec commit c19e358860e3cb89a8c7021e8c5a181ab6ef7f62 and that the generated surface is intentionally not committed, but this pins a different commit (84400eeb...) and the PR includes the full generated models, operations, streaming API, and samples. Align the pinned commit and committed scope with the description so generation provenance is reproducible.
  sdk/search/azure-search-documents/azure/search/documents/_utils/utils.py:129
• Required multipart data parts are dropped when their value is falsey. For example, a valid request body with metadata={} omits the metadata part entirely, even though both multipart request types require that part. Check for None instead so empty JSON objects and other falsey values are still serialized.

    for data_field in data_fields:
        data_entry = body.get(data_field)
        if data_entry:
            files.append((data_field, str(serialize_multipart_data_entry(data_entry))))

sdk/search/azure-search-documents/azure/search/documents/knowledgebases/_patch.py:139

• These runtime __annotations__ mutations do not repair the static typing surface shipped in this py.typed package. The regenerated knowledgebases/types.py:28 still imports from nonexistent ..indexesmodels, and indexes/types.py:27 similarly imports nonexistent ..knowledgebasesmodels; the package's ignore_missing_imports setting only masks this locally, while consumers cannot resolve those types. Fix the generated/spec namespaces (or the generated TYPE_CHECKING imports) rather than relying only on runtime annotation patching.
  sdk/search/azure-search-documents/README.md:51
• The package now declares requires-python = ">=3.10" and lists only Python 3.10–3.14 in pyproject.toml, so this prerequisite incorrectly tells Python 3.9 users they can install the package.

* Python 3.9 or later is required to use this package.