Search: Skill Versions (#20431)

* Initial commit.

* Add docstrings for skill_version

* Ensure SearchIndexerSkillset can convert between custom and generated models.

* Update tests.

* Fix async skillsets and tests.

* Add client-side validation and tests for model properties.

* Re-record tests.

* Fix pylint errors.

* Rerecord tests. Fix linter errors.

* Fix ordering on old Python version.

* Add changelog entry.

* Fix linter issues. Make enums NOT case insensitive due to pylint failure.

* Remove client-side validation. Update models.

* Update test and re-record skillset tests.

* Change :param annotations to :ivar for custom models.

* Rename SearchField normalizer to normalizer_name.

* Restore :param annotation for now.

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

@@ -8,15 +8,31 @@
   - `azure.search.documents.models.Captions`
   - `azure.search.documents.models.CaptionResult`
   - `azure.search.documents.indexes.models.CustomEntityLookupSkillLanguage`
+  - `azure.search.documents.indexes.models.EntityRecognitionSkillVersion`
   - `azure.search.documents.indexes.models.LexicalNormalizerName`
   - `azure.search.documents.indexes.models.PIIDetectionSkill`
   - `azure.search.documents.indexes.models.PIIDetectionSkillMaskingMode`
   - `azure.search.documents.indexes.models.SearchIndexerCache`
   - `azure.search.documents.indexes.models.SearchIndexerDataIdentity`
   - `azure.search.documents.indexes.models.SearchIndexerDataNoneIdentity`
   - `azure.search.documents.indexes.models.SearchIndexerDataUserAssignedIdentity`
+  - `azure.search.documents.indexes.models.SentimentSkillVersion`
 - Added `normalizer_name` property to `AnalyzeTextOptions` model.
 
+### Breaking Changes
+
+- Removed:
+  - `azure.search.documents.indexes.models.SentimentSkillV3`
+  - `azure.search.documents.indexes.models.EntityRecognitionSkillV3`
+- Renamed:
+  - `SearchField.normalizer` renamed to `SearchField.normalizer_name`.
+
+### Other Changes
+- `SentimentSkill` and `EntityRecognitionSkill` can now be created by specifying
+  the `skill_version` keyword argument with a `SentimentSkillVersion` or
+  `EntityRecognitionSkillVersion`, respectively. The default behavior if `skill_version`
+  is not specified is to create a version 1 skill.
+
 ## 11.3.0b2 (2021-08-10)
 
 ### Features Added

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

@@ -10,7 +10,7 @@
 from azure.core.tracing.decorator import distributed_trace
 
 from ._generated import SearchClient as _SearchServiceClient
-from ._generated.models import SearchIndexerSkillset
+from .models import SearchIndexerSkillset
 from ._utils import (
     get_access_conditions,
     normalize_endpoint,
@@ -469,7 +469,7 @@ def get_skillsets(self, **kwargs):
         """
         kwargs["headers"] = self._merge_client_headers(kwargs.get("headers"))
         result = self._client.skillsets.list(**kwargs)
-        return result.skillsets
+        return [SearchIndexerSkillset._from_generated(skillset) for skillset in result.skillsets] # pylint:disable=protected-access
 
     @distributed_trace
     def get_skillset_names(self, **kwargs):
@@ -507,7 +507,8 @@ def get_skillset(self, name, **kwargs):
 
         """
         kwargs["headers"] = self._merge_client_headers(kwargs.get("headers"))
-        return self._client.skillsets.get(name, **kwargs)
+        result = self._client.skillsets.get(name, **kwargs)
+        return SearchIndexerSkillset._from_generated(result) # pylint:disable=protected-access
 
     @distributed_trace
     def delete_skillset(self, skillset, **kwargs):
@@ -563,8 +564,9 @@ def create_skillset(self, skillset, **kwargs):
 
         """
         kwargs["headers"] = self._merge_client_headers(kwargs.get("headers"))
-
-        return self._client.skillsets.create(skillset, **kwargs)
+        skillset = skillset._to_generated() if hasattr(skillset, '_to_generated') else skillset # pylint:disable=protected-access
+        result = self._client.skillsets.create(skillset, **kwargs)
+        return SearchIndexerSkillset._from_generated(result) # pylint:disable=protected-access
 
     @distributed_trace
     def create_or_update_skillset(self, skillset, **kwargs):
@@ -585,10 +587,12 @@ def create_or_update_skillset(self, skillset, **kwargs):
             skillset, kwargs.pop("match_condition", MatchConditions.Unconditionally)
         )
         kwargs.update(access_condition)
+        skillset = skillset._to_generated() if hasattr(skillset, '_to_generated') else skillset # pylint:disable=protected-access
 
-        return self._client.skillsets.create_or_update(
+        result = self._client.skillsets.create_or_update(
             skillset_name=skillset.name,
             skillset=skillset,
             error_map=error_map,
             **kwargs
         )
+        return SearchIndexerSkillset._from_generated(result) # pylint:disable=protected-access

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

@@ -10,7 +10,7 @@
 from azure.core.tracing.decorator_async import distributed_trace_async
 
 from .._generated.aio import SearchClient as _SearchServiceClient
-from .._generated.models import SearchIndexerSkillset
+from ..models import SearchIndexerSkillset
 from .._utils import (
     get_access_conditions,
     normalize_endpoint,
@@ -462,7 +462,7 @@ async def get_skillsets(self, **kwargs):
         """
         kwargs["headers"] = self._merge_client_headers(kwargs.get("headers"))
         result = await self._client.skillsets.list(**kwargs)
-        return result.skillsets
+        return [SearchIndexerSkillset._from_generated(skillset) for skillset in result.skillsets] # pylint:disable=protected-access
 
     @distributed_trace_async
     async def get_skillset_names(self, **kwargs):
@@ -500,7 +500,8 @@ async def get_skillset(self, name, **kwargs):
 
         """
         kwargs["headers"] = self._merge_client_headers(kwargs.get("headers"))
-        return await self._client.skillsets.get(name, **kwargs)
+        result = await self._client.skillsets.get(name, **kwargs)
+        return SearchIndexerSkillset._from_generated(result) # pylint:disable=protected-access
 
     @distributed_trace_async
     async def delete_skillset(self, skillset, **kwargs):
@@ -556,8 +557,9 @@ async def create_skillset(self, skillset, **kwargs):
 
         """
         kwargs["headers"] = self._merge_client_headers(kwargs.get("headers"))
-
-        return await self._client.skillsets.create(skillset, **kwargs)
+        skillset = skillset._to_generated() if hasattr(skillset, '_to_generated') else skillset # pylint:disable=protected-access
+        result = await self._client.skillsets.create(skillset, **kwargs)
+        return SearchIndexerSkillset._from_generated(result) # pylint:disable=protected-access
 
     @distributed_trace_async
     async def create_or_update_skillset(self, skillset, **kwargs):
@@ -578,10 +580,12 @@ async def create_or_update_skillset(self, skillset, **kwargs):
             skillset, kwargs.pop("match_condition", MatchConditions.Unconditionally)
         )
         kwargs.update(access_condition)
+        skillset = skillset._to_generated() if hasattr(skillset, '_to_generated') else skillset # pylint:disable=protected-access
 
-        return await self._client.skillsets.create_or_update(
+        result = await self._client.skillsets.create_or_update(
             skillset_name=skillset.name,
             skillset=skillset,
             error_map=error_map,
             **kwargs
         )
+        return SearchIndexerSkillset._from_generated(result) # pylint:disable=protected-access

sdk/search/azure-search-documents/azure/search/documents/indexes/models/__init__.py

@@ -58,9 +58,7 @@
     ElisionTokenFilter,
     EntityCategory,
     EntityLinkingSkill,
-    EntityRecognitionSkill,
     EntityRecognitionSkillLanguage,
-    EntityRecognitionSkillV3,
     FieldMapping,
     FieldMappingFunction,
     FreshnessScoringFunction,
@@ -124,15 +122,12 @@
     SearchIndexerKnowledgeStoreProjection,
     SearchIndexerKnowledgeStoreTableProjectionSelector,
     SearchIndexerLimits,
-    SearchIndexerSkillset,
     SearchIndexerStatus,
     ScoringFunction,
     ScoringFunctionAggregation,
     ScoringFunctionInterpolation,
     ScoringProfile,
-    SentimentSkill,
     SentimentSkillLanguage,
-    SentimentSkillV3,
     ShaperSkill,
     ShingleTokenFilter,
     Similarity as SimilarityAlgorithm,
@@ -169,10 +164,15 @@
 from ._models import (
     AnalyzeTextOptions,
     CustomAnalyzer,
+    EntityRecognitionSkill,
+    EntityRecognitionSkillVersion,
     PatternAnalyzer,
     PatternTokenizer,
     SearchIndexerDataSourceConnection,
+    SearchIndexerSkillset,
     SearchResourceEncryptionKey,
+    SentimentSkill,
+    SentimentSkillVersion,
     SynonymMap,
 )
 
@@ -207,7 +207,7 @@
     "EntityLinkingSkill",
     "EntityRecognitionSkill",
     "EntityRecognitionSkillLanguage",
-    "EntityRecognitionSkillV3",
+    "EntityRecognitionSkillVersion",
     "FieldMapping",
     "FieldMappingFunction",
     "FreshnessScoringFunction",
@@ -286,7 +286,7 @@
     "SearchableField",
     "SentimentSkill",
     "SentimentSkillLanguage",
-    "SentimentSkillV3",
+    "SentimentSkillVersion",
     "ShaperSkill",
     "ShingleTokenFilter",
     "SimpleField",

sdk/search/azure-search-documents/azure/search/documents/indexes/models/_index.py

@@ -152,11 +152,11 @@ class SearchField(msrest.serialization.Model):
      "standard.lucene", "standardasciifolding.lucene", "keyword", "pattern", "simple", "stop",
      "whitespace".
     :type index_analyzer_name: str or ~azure.search.documents.indexes.models.LexicalAnalyzerName
-    :param normalizer: The name of the normalizer to use for the field. This option can be used
+    :param normalizer_name: The name of the normalizer to use for the field. This option can be used
      only with fields with filterable, sortable, or facetable enabled. Once the normalizer is
      chosen, it cannot be changed for the field. Must be null for complex fields. Possible values
      include: "asciifolding", "elision", "lowercase", "standard", "uppercase".
-    :type normalizer: str or ~azure.search.documents.indexes.models.LexicalNormalizerName
+    :type normalizer_name: str or ~azure.search.documents.indexes.models.LexicalNormalizerName
     :param synonym_map_names: A list of the names of synonym maps to associate with this field. This
      option can be used only with searchable fields. Currently only one synonym map per field is
      supported. Assigning a synonym map to a field ensures that query terms targeting that field are
@@ -185,7 +185,7 @@ class SearchField(msrest.serialization.Model):
         "analyzer_name": {"key": "analyzerName", "type": "str"},
         "search_analyzer_name": {"key": "searchAnalyzerName", "type": "str"},
         "index_analyzer_name": {"key": "indexAnalyzerName", "type": "str"},
-        "normalizer": {"key": "normalizer", "type": "str"},
+        "normalizer_name": {"key": "normalizerName", "type": "str"},
         "synonym_map_names": {"key": "synonymMapNames", "type": "[str]"},
         "fields": {"key": "fields", "type": "[SearchField]"},
     }
@@ -203,7 +203,7 @@ def __init__(self, **kwargs):
         self.analyzer_name = kwargs.get("analyzer_name", None)
         self.search_analyzer_name = kwargs.get("search_analyzer_name", None)
         self.index_analyzer_name = kwargs.get("index_analyzer_name", None)
-        self.normalizer = kwargs.get("normalizer", None)
+        self.normalizer_name = kwargs.get("normalizer_name", None)
         self.synonym_map_names = kwargs.get("synonym_map_names", None)
         self.fields = kwargs.get("fields", None)
 
@@ -222,7 +222,7 @@ def _to_generated(self):
             analyzer=self.analyzer_name,
             search_analyzer=self.search_analyzer_name,
             index_analyzer=self.index_analyzer_name,
-            normalizer=self.normalizer,
+            normalizer=self.normalizer_name,
             synonym_maps=self.synonym_map_names,
             fields=fields,
         )
@@ -243,7 +243,7 @@ def _from_generated(cls, search_field):
             else None
         )
         try:
-            normalizer = search_field.normalizer
+            normalizer = search_field.normalizer_name
         except AttributeError:
             normalizer = None
         return cls(