Address Copilot review and refine 12.1.0b1 CHANGELOG

- Apply Copilot PR review fixes across _patch.py files: add explicit return type
  annotations, correct docstrings, and reference api_version via the ApiVersion
  enum.
- Drop a now-redundant pylint useless-suppression in test_search_indexer_models.

- Refine the 12.1.0b1 CHANGELOG section:
  - Promote KeywordTokenizerV2 and PathHierarchyTokenizerV2 (private -> public).
  - Add "added or changed" group for SearchFieldDataType (string sub-module ->
    enum class) and SynonymMap.format (class constant -> writable field).
  - Restructure the serialize()/deserialize() note to the sanctioned
    "Below methods do not exist on models in this release" lead-in.
  - Document CommonModelParameters.model -> ChatCompletionCommonModelParameters
    .model_name and SharePointSensitivityLabelInfo.tooltip ->
    PurviewSensitivityLabelInfo.tool_tip under properties renamed.
  - Annotate EntityRecognitionSkill -> V3 (drops include_typeless_entities and
    skill_version) and SentimentSkill -> V3 (drops skill_version).
  - Fix the Purview group lead-in to "properties and enum members".

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: hizixin

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

@@ -352,13 +352,14 @@ def get_answers(self) -> Optional[List[_models.QueryAnswerResult]]:
         """
         return cast(Optional[List[_models.QueryAnswerResult]], self._first_iterator_instance().get_answers())
 
-    def get_debug_info(self) -> _models.DebugInfo:
+    def get_debug_info(self) -> Optional[_models.DebugInfo]:
         """Return the debug information for the query.
 
-        :return: the debug information for the query
-        :rtype: ~azure.search.documents.models.DebugInfo
+        :return: the debug information for the query, or None when ``debug``
+            was not requested on the search call.
+        :rtype: ~azure.search.documents.models.DebugInfo or None
         """
-        return cast(_models.DebugInfo, self._first_iterator_instance().get_debug_info())
+        return cast(Optional[_models.DebugInfo], self._first_iterator_instance().get_debug_info())
 
 
 class _SearchClientOperationsMixin(_SearchClientOperationsMixinGenerated):

sdk/search/azure-search-documents/azure/search/documents/_operations/_patch.py

@@ -59,9 +59,10 @@ class SearchClient(_SearchClient):
     :param index_name: The name of the index. Required.
     :type index_name: str
     :keyword api_version: The API version to use for this operation. Known values are
-     "2026-05-01-preview" and None. Default value is "2026-05-01-preview". Note that overriding this
-     default value may result in unsupported behavior.
-    :paramtype api_version: str
+     listed on the :class:`~azure.search.documents.ApiVersion` enum. Default value is
+     ``ApiVersion.V2026_05_01_PREVIEW``. Note that overriding this default value may
+     result in unsupported behavior.
+    :paramtype api_version: str or ~azure.search.documents.ApiVersion
     :keyword str audience: Sets the Audience to use for authentication with Microsoft Entra ID. The
      audience is not considered when using a shared key. If audience is not provided, the public cloud
      audience will be assumed.

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

@@ -169,13 +169,14 @@ async def get_answers(self) -> Optional[List[_models.QueryAnswerResult]]:
         """
         return cast(Optional[List[_models.QueryAnswerResult]], await self._first_iterator_instance().get_answers())
 
-    async def get_debug_info(self) -> _models.DebugInfo:
+    async def get_debug_info(self) -> Optional[_models.DebugInfo]:
         """Return the debug information for the query.
 
-        :return: the debug information for the query
-        :rtype: ~azure.search.documents.models.DebugInfo
+        :return: the debug information for the query, or None when ``debug``
+            was not requested on the search call.
+        :rtype: ~azure.search.documents.models.DebugInfo or None
         """
-        return cast(_models.DebugInfo, await self._first_iterator_instance().get_debug_info())
+        return cast(Optional[_models.DebugInfo], await self._first_iterator_instance().get_debug_info())
 
 
 class _SearchClientOperationsMixin(_SearchClientOperationsMixinGenerated):

sdk/search/azure-search-documents/azure/search/documents/aio/_operations/_patch.py

@@ -36,9 +36,10 @@ class SearchClient(_SearchClient):
     :param index_name: The name of the index. Required.
     :type index_name: str
     :keyword api_version: The API version to use for this operation. Known values are
-     "2026-05-01-preview" and None. Default value is "2026-05-01-preview". Note that overriding this
-     default value may result in unsupported behavior.
-    :paramtype api_version: str
+     listed on the :class:`~azure.search.documents.ApiVersion` enum. Default value is
+     ``ApiVersion.V2026_05_01_PREVIEW``. Note that overriding this default value may
+     result in unsupported behavior.
+    :paramtype api_version: str or ~azure.search.documents.ApiVersion
     :keyword str audience: Sets the Audience to use for authentication with Microsoft Entra ID. The
      audience is not considered when using a shared key. If audience is not provided, the public cloud
      audience will be assumed.

sdk/search/azure-search-documents/azure/search/documents/aio/_patch.py

@@ -869,8 +869,7 @@ def reset_skills(
 
         :param name: The name of the skillset. Required.
         :type name: str
-        :param skill_names: The names of the skills to reset. If not specified, all skills in the
-            skillset will be reset. Required.
+        :param skill_names: The names of the skills to reset. Required.
         :type skill_names: ~azure.search.documents.indexes.models.SkillNames or JSON or IO[bytes]
         :return: None
         :rtype: None

sdk/search/azure-search-documents/azure/search/documents/indexes/_operations/_patch.py

@@ -25,9 +25,10 @@ class SearchIndexClient(_SearchIndexClient):
     :type credential: ~azure.core.credentials.AzureKeyCredential or
      ~azure.core.credentials.TokenCredential
     :keyword api_version: The API version to use for this operation. Known values are
-     "2026-05-01-preview" and None. Default value is "2026-05-01-preview". Note that overriding this
-     default value may result in unsupported behavior.
-    :paramtype api_version: str
+     listed on the :class:`~azure.search.documents.ApiVersion` enum. Default value is
+     ``ApiVersion.V2026_05_01_PREVIEW``. Note that overriding this default value may
+     result in unsupported behavior.
+    :paramtype api_version: str or ~azure.search.documents.ApiVersion
     :keyword str audience: Sets the Audience to use for authentication with Microsoft Entra ID. The
      audience is not considered when using a shared key. If audience is not provided, the public cloud
      audience will be assumed.
@@ -50,9 +51,10 @@ class SearchIndexerClient(_SearchIndexerClient):
     :type credential: ~azure.core.credentials.AzureKeyCredential or
      ~azure.core.credentials.TokenCredential
     :keyword api_version: The API version to use for this operation. Known values are
-     "2026-05-01-preview" and None. Default value is "2026-05-01-preview". Note that overriding this
-     default value may result in unsupported behavior.
-    :paramtype api_version: str
+     listed on the :class:`~azure.search.documents.ApiVersion` enum. Default value is
+     ``ApiVersion.V2026_05_01_PREVIEW``. Note that overriding this default value may
+     result in unsupported behavior.
+    :paramtype api_version: str or ~azure.search.documents.ApiVersion
     :keyword str audience: Sets the Audience to use for authentication with Microsoft Entra ID. The
      audience is not considered when using a shared key. If audience is not provided, the public cloud
      audience will be assumed.

sdk/search/azure-search-documents/azure/search/documents/indexes/_patch.py

@@ -848,8 +848,7 @@ async def reset_skills(
 
         :param name: The name of the skillset. Required.
         :type name: str
-        :param skill_names: The names of the skills to reset. If not specified, all skills in the
-            skillset will be reset. Required.
+        :param skill_names: The names of the skills to reset. Required.
         :type skill_names: ~azure.search.documents.indexes.models.SkillNames or JSON or IO[bytes]
         :return: None
         :rtype: None

sdk/search/azure-search-documents/azure/search/documents/indexes/aio/_operations/_patch.py

@@ -26,9 +26,10 @@ class SearchIndexClient(_SearchIndexClient):
     :type credential: ~azure.core.credentials.AzureKeyCredential or
      ~azure.core.credentials_async.AsyncTokenCredential
     :keyword api_version: The API version to use for this operation. Known values are
-     "2026-05-01-preview" and None. Default value is "2026-05-01-preview". Note that overriding this
-     default value may result in unsupported behavior.
-    :paramtype api_version: str
+     listed on the :class:`~azure.search.documents.ApiVersion` enum. Default value is
+     ``ApiVersion.V2026_05_01_PREVIEW``. Note that overriding this default value may
+     result in unsupported behavior.
+    :paramtype api_version: str or ~azure.search.documents.ApiVersion
     :keyword str audience: Sets the Audience to use for authentication with Microsoft Entra ID. The
      audience is not considered when using a shared key. If audience is not provided, the public cloud
      audience will be assumed.
@@ -53,9 +54,10 @@ class SearchIndexerClient(_SearchIndexerClient):
     :type credential: ~azure.core.credentials.AzureKeyCredential or
      ~azure.core.credentials_async.AsyncTokenCredential
     :keyword api_version: The API version to use for this operation. Known values are
-     "2026-05-01-preview" and None. Default value is "2026-05-01-preview". Note that overriding this
-     default value may result in unsupported behavior.
-    :paramtype api_version: str
+     listed on the :class:`~azure.search.documents.ApiVersion` enum. Default value is
+     ``ApiVersion.V2026_05_01_PREVIEW``. Note that overriding this default value may
+     result in unsupported behavior.
+    :paramtype api_version: str or ~azure.search.documents.ApiVersion
     :keyword str audience: Sets the Audience to use for authentication with Microsoft Entra ID. The
      audience is not considered when using a shared key. If audience is not provided, the public cloud
      audience will be assumed.

sdk/search/azure-search-documents/azure/search/documents/indexes/aio/_patch.py

@@ -26,9 +26,10 @@ class KnowledgeBaseRetrievalClient(_KnowledgeBaseRetrievalClient):
     :param knowledge_base_name: The name of the knowledge base. Required.
     :type knowledge_base_name: str
     :keyword api_version: The API version to use for this operation. Known values are
-     "2026-05-01-preview" and None. Default value is "2026-05-01-preview". Note that overriding this
-     default value may result in unsupported behavior.
-    :paramtype api_version: str
+     listed on the :class:`~azure.search.documents.ApiVersion` enum. Default value is
+     ``ApiVersion.V2026_05_01_PREVIEW``. Note that overriding this default value may
+     result in unsupported behavior.
+    :paramtype api_version: str or ~azure.search.documents.ApiVersion
     :keyword str audience: Sets the Audience to use for authentication with Microsoft Entra ID. The
      audience is not considered when using a shared key. If audience is not provided, the public cloud
      audience will be assumed.