[textanalytics] add single label classify bespoke method (Azure#25005)

* initial work

* docs,samples,linting

* expose TA poller

* add bespoke begin_single_label_classify

* oops

* missed rename of internal type

Author: kristapratico

sdk/textanalytics/azure-ai-textanalytics/CHANGELOG.md

@@ -5,6 +5,7 @@
 ### Features Added
 
 - Added `begin_recognize_custom_entities` client method to recognize custom named entities in documents.
+- Added `begin_single_label_classify` client method to perform custom single label classification on documents.
 
 ### Breaking Changes
 

sdk/textanalytics/azure-ai-textanalytics/README.md

@@ -235,7 +235,7 @@ The following section provides several code snippets covering some of the most c
 - [Healthcare Entities Analysis](#healthcare-entities-analysis "Healthcare Entities Analysis")
 - [Multiple Analysis](#multiple-analysis "Multiple analysis")
 - [Custom Entity Recognition][recognize_custom_entities_sample]
-- [Custom Single Category Classification][single_category_classify_sample]
+- [Custom Single Label Classification][single_label_classify_sample]
 - [Custom Multi Category Classification][multi_category_classify_sample]
 
 ### Analyze sentiment
@@ -514,7 +514,7 @@ Note: The Healthcare Entities Analysis service is only available in the Standard
 - Key Phrase Extraction
 - Sentiment Analysis
 - Custom Entity Recognition (see sample [here][recognize_custom_entities_sample])
-- Custom Single Category Classification (see sample [here][single_category_classify_sample])
+- Custom Single Label Classification (see sample [here][single_label_classify_sample])
 - Custom Multi Category Classification (see sample [here][multi_category_classify_sample])
 - Healthcare Entities Analysis
 
@@ -646,7 +646,7 @@ Common scenarios
 - Healthcare Entities Analysis: [sample_analyze_healthcare_entities.py][analyze_healthcare_entities_sample] ([async version][analyze_healthcare_entities_sample_async])
 - Multiple Analysis: [sample_analyze_actions.py][analyze_sample] ([async version][analyze_sample_async])
 - Custom Entity Recognition: [sample_recognize_custom_entities.py][recognize_custom_entities_sample] ([async_version][recognize_custom_entities_sample_async])
-- Custom Single Classification: [sample_single_category_classify.py][single_category_classify_sample] ([async_version][single_category_classify_sample_async])
+- Custom Single Label Classification: [sample_single_label_classify.py][single_label_classify_sample] ([async_version][single_label_classify_sample_async])
 - Custom Multi Classification: [sample_multi_category_classify.py][multi_category_classify_sample] ([async_version][multi_category_classify_sample_async])
 
 Advanced scenarios
@@ -745,8 +745,8 @@ This project has adopted the [Microsoft Open Source Code of Conduct][code_of_con
 [opinion_mining_sample_async]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/textanalytics/azure-ai-textanalytics/samples/async_samples/sample_analyze_sentiment_with_opinion_mining_async.py
 [recognize_custom_entities_sample]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/textanalytics/azure-ai-textanalytics/samples/sample_recognize_custom_entities.py
 [recognize_custom_entities_sample_async]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/textanalytics/azure-ai-textanalytics/samples/async_samples/sample_recognize_custom_entities_async.py
-[single_category_classify_sample]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/textanalytics/azure-ai-textanalytics/samples/sample_single_category_classify.py
-[single_category_classify_sample_async]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/textanalytics/azure-ai-textanalytics/samples/async_samples/sample_single_category_classify_async.py
+[single_label_classify_sample]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/textanalytics/azure-ai-textanalytics/samples/sample_single_label_classify.py
+[single_label_classify_sample_async]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/textanalytics/azure-ai-textanalytics/samples/async_samples/sample_single_label_classify_async.py
 [multi_category_classify_sample]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/textanalytics/azure-ai-textanalytics/samples/sample_multi_category_classify.py
 [multi_category_classify_sample_async]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/textanalytics/azure-ai-textanalytics/samples/async_samples/sample_multi_category_classify_async.py
 [cla]: https://cla.microsoft.com

sdk/textanalytics/azure-ai-textanalytics/azure/ai/textanalytics/__init__.py

@@ -51,7 +51,7 @@
     HealthcareEntityCategory,
     RecognizeCustomEntitiesAction,
     RecognizeCustomEntitiesResult,
-    SingleCategoryClassifyAction,
+    SingleLabelClassifyAction,
     MultiCategoryClassifyAction,
     ClassifyDocumentResult,
     ClassificationCategory,
@@ -109,7 +109,7 @@
     "HealthcareEntityCategory",
     "RecognizeCustomEntitiesAction",
     "RecognizeCustomEntitiesResult",
-    "SingleCategoryClassifyAction",
+    "SingleLabelClassifyAction",
     "MultiCategoryClassifyAction",
     "ClassifyDocumentResult",
     "ClassificationCategory",

sdk/textanalytics/azure-ai-textanalytics/azure/ai/textanalytics/_models.py

@@ -1750,7 +1750,7 @@ class _AnalyzeActionsType(str, Enum, metaclass=CaseInsensitiveEnumMeta):
     )
     ANALYZE_SENTIMENT = "analyze_sentiment"  #: Sentiment Analysis action.
     RECOGNIZE_CUSTOM_ENTITIES = "recognize_custom_entities"
-    SINGLE_CATEGORY_CLASSIFY = "single_category_classify"
+    SINGLE_LABEL_CLASSIFY = "single_label_classify"
     MULTI_CATEGORY_CLASSIFY = "multi_category_classify"
     ANALYZE_HEALTHCARE_ENTITIES = "analyze_healthcare_entities"
 
@@ -2375,8 +2375,8 @@ def _from_generated(cls, result):
         )
 
 
-class SingleCategoryClassifyAction(DictMixin):
-    """SingleCategoryClassifyAction encapsulates the parameters for starting a long-running custom single category
+class SingleLabelClassifyAction(DictMixin):
+    """SingleLabelClassifyAction encapsulates the parameters for starting a long-running custom single label
     classification operation. For information on regional support of custom features and how to train a model to
     classify your documents, see https://aka.ms/azsdk/textanalytics/customfunctionalities
 
@@ -2413,7 +2413,7 @@ def __init__(
         self.disable_service_logs = kwargs.get('disable_service_logs', None)
 
     def __repr__(self):
-        return "SingleCategoryClassifyAction(project_name={}, deployment_name={}, " \
+        return "SingleLabelClassifyAction(project_name={}, deployment_name={}, " \
                "disable_service_logs={})".format(
             self.project_name,
             self.deployment_name,

sdk/textanalytics/azure-ai-textanalytics/azure/ai/textanalytics/_request_handlers.py

@@ -92,7 +92,7 @@ def _determine_action_type(action):  # pylint: disable=too-many-return-statement
     if action.__class__.__name__ == "CustomEntitiesLROTask":
         return _AnalyzeActionsType.RECOGNIZE_CUSTOM_ENTITIES
     if action.__class__.__name__ == "CustomSingleLabelClassificationLROTask":
-        return _AnalyzeActionsType.SINGLE_CATEGORY_CLASSIFY
+        return _AnalyzeActionsType.SINGLE_LABEL_CLASSIFY
     if action.__class__.__name__ == "CustomMultiLabelClassificationLROTask":
         return _AnalyzeActionsType.MULTI_CATEGORY_CLASSIFY
     if action.__class__.__name__ == "HealthcareLROTask":

sdk/textanalytics/azure-ai-textanalytics/azure/ai/textanalytics/_response_handlers.py

@@ -306,7 +306,7 @@ def _get_deserialization_callback_from_task_type(task_type):  # pylint: disable=
         return sentiment_result
     if task_type == _AnalyzeActionsType.RECOGNIZE_CUSTOM_ENTITIES:
         return custom_entities_result
-    if task_type == _AnalyzeActionsType.SINGLE_CATEGORY_CLASSIFY:
+    if task_type == _AnalyzeActionsType.SINGLE_LABEL_CLASSIFY:
         return classify_document_result
     if task_type == _AnalyzeActionsType.MULTI_CATEGORY_CLASSIFY:
         return classify_document_result

sdk/textanalytics/azure-ai-textanalytics/azure/ai/textanalytics/_text_analytics_client.py

@@ -60,7 +60,7 @@
     AnalyzeHealthcareEntitiesResult,
     RecognizeCustomEntitiesAction,
     RecognizeCustomEntitiesResult,
-    SingleCategoryClassifyAction,
+    SingleLabelClassifyAction,
     MultiCategoryClassifyAction,
     ClassifyDocumentResult,
     AnalyzeHealthcareEntitiesAction,
@@ -1057,7 +1057,7 @@ def begin_analyze_actions(
                 ExtractKeyPhrasesAction,
                 AnalyzeSentimentAction,
                 RecognizeCustomEntitiesAction,
-                SingleCategoryClassifyAction,
+                SingleLabelClassifyAction,
                 MultiCategoryClassifyAction,
                 AnalyzeHealthcareEntitiesAction,
             ]
@@ -1102,7 +1102,7 @@ def begin_analyze_actions(
         :type actions:
             list[RecognizeEntitiesAction or RecognizePiiEntitiesAction or ExtractKeyPhrasesAction or
             RecognizeLinkedEntitiesAction or AnalyzeSentimentAction or
-            RecognizeCustomEntitiesAction or SingleCategoryClassifyAction or
+            RecognizeCustomEntitiesAction or SingleLabelClassifyAction or
             MultiCategoryClassifyAction or AnalyzeHealthcareEntitiesAction]
         :keyword str display_name: An optional display name to set for the requested analysis.
         :keyword str language: The 2 letter ISO 639-1 representation of language for the
@@ -1138,7 +1138,7 @@ def begin_analyze_actions(
         .. versionadded:: v3.1
             The *begin_analyze_actions* client method.
         .. versionadded:: 2022-04-01-preview
-            The *RecognizeCustomEntitiesAction*, *SingleCategoryClassifyAction*,
+            The *RecognizeCustomEntitiesAction*, *SingleLabelClassifyAction*,
             *MultiCategoryClassifyAction*, and *AnalyzeHealthcareEntitiesAction* input options and the
             corresponding *RecognizeCustomEntitiesResult*, *ClassifyDocumentResult*,
             and *AnalyzeHealthcareEntitiesResult* result objects
@@ -1404,3 +1404,115 @@ def begin_recognize_custom_entities(
 
         except HttpResponseError as error:
             return process_http_response_error(error)
+
+    @distributed_trace
+    @validate_multiapi_args(
+        version_method_added="2022-05-01"
+    )
+    def begin_single_label_classify(
+        self,
+        documents: Union[List[str], List[TextDocumentInput], List[Dict[str, str]]],
+        project_name,
+        deployment_name,
+        **kwargs: Any,
+    ) -> TextAnalyticsLROPoller[ItemPaged[Union[ClassifyDocumentResult, DocumentError]]]:
+        """Start a long-running custom single label classification operation.
+
+        For information on regional support of custom features and how to train a model to
+        classify your documents, see https://aka.ms/azsdk/textanalytics/customfunctionalities
+
+        :param documents: The set of documents to process as part of this batch.
+            If you wish to specify the ID and language on a per-item basis you must
+            use as input a list[:class:`~azure.ai.textanalytics.TextDocumentInput`] or a list of
+            dict representations of :class:`~azure.ai.textanalytics.TextDocumentInput`, like
+            `{"id": "1", "language": "en", "text": "hello world"}`.
+        :type documents:
+            list[str] or list[~azure.ai.textanalytics.TextDocumentInput] or list[dict[str, str]]
+        :param str project_name: Required. This field indicates the project name for the model.
+        :param str deployment_name: This field indicates the deployment name for the model.
+        :keyword str language: The 2 letter ISO 639-1 representation of language for the
+            entire batch. For example, use "en" for English; "es" for Spanish etc.
+            If not set, uses "en" for English as default. Per-document language will
+            take precedence over whole batch language. See https://aka.ms/talangs for
+            supported languages in Language API.
+        :keyword bool show_stats: If set to true, response will contain document level statistics.
+        :keyword bool disable_service_logs: If set to true, you opt-out of having your text input
+            logged on the service side for troubleshooting. By default, the Language service logs your
+            input text for 48 hours, solely to allow for troubleshooting issues in providing you with
+            the service's natural language processing functions. Setting this parameter to true,
+            disables input logging and may limit our ability to remediate issues that occur. Please see
+            Cognitive Services Compliance and Privacy notes at https://aka.ms/cs-compliance for
+            additional details, and Microsoft Responsible AI principles at
+            https://www.microsoft.com/ai/responsible-ai.
+        :keyword int polling_interval: Waiting time between two polls for LRO operations
+            if no Retry-After header is present. Defaults to 5 seconds.
+        :keyword str continuation_token:
+            Call `continuation_token()` on the poller object to save the long-running operation (LRO)
+            state into an opaque token. Pass the value as the `continuation_token` keyword argument
+            to restart the LRO from a saved state.
+        :keyword str display_name: An optional display name to set for the requested analysis.
+        :return: An instance of an TextAnalyticsLROPoller. Call `result()` on the this
+            object to return a heterogeneous pageable of
+            :class:`~azure.ai.textanalytics.ClassifyDocumentResult` and
+            :class:`~azure.ai.textanalytics.DocumentError`.
+        :rtype:
+            ~azure.ai.textanalytics.TextAnalyticsLROPoller[~azure.core.paging.ItemPaged[
+            ~azure.ai.textanalytics.ClassifyDocumentResult or ~azure.ai.textanalytics.DocumentError]]
+        :raises ~azure.core.exceptions.HttpResponseError:
+
+        .. versionadded:: 2022-05-01
+            The *begin_single_label_classify* client method.
+
+        .. admonition:: Example:
+
+            .. literalinclude:: ../samples/sample_single_label_classify.py
+                :start-after: [START single_label_classify]
+                :end-before: [END single_label_classify]
+                :language: python
+                :dedent: 4
+                :caption: Perform single label classification on a batch of documents.
+        """
+
+        continuation_token = kwargs.pop("continuation_token", None)
+        disable_service_logs = kwargs.pop("disable_service_logs", None)
+        polling_interval = kwargs.pop("polling_interval", 5)
+
+        if continuation_token:
+            return cast(
+                TextAnalyticsLROPoller[ItemPaged[Union[ClassifyDocumentResult, DocumentError]]],
+                _get_result_from_continuation_token(
+                    self._client._client,  # pylint: disable=protected-access
+                    continuation_token,
+                    TextAnalyticsLROPoller,
+                    AnalyzeActionsLROPollingMethod(
+                        timeout=polling_interval,
+                        **kwargs
+                    ),
+                    self._analyze_result_callback,
+                    bespoke=True
+                )
+            )
+
+        try:
+            return cast(
+                TextAnalyticsLROPoller[
+                    ItemPaged[Union[ClassifyDocumentResult, DocumentError]]
+                ],
+                self.begin_analyze_actions(
+                    documents,
+                    actions=[
+                        SingleLabelClassifyAction(
+                            project_name=project_name,
+                            deployment_name=deployment_name,
+                            disable_service_logs=disable_service_logs
+                        )
+                    ],
+                    polling_interval=polling_interval,
+                    poller_cls=TextAnalyticsLROPoller,
+                    bespoke=True,
+                    **kwargs
+                )
+            )
+
+        except HttpResponseError as error:
+            return process_http_response_error(error)

sdk/textanalytics/azure-ai-textanalytics/azure/ai/textanalytics/_validate.py

@@ -30,7 +30,7 @@ def check_for_unsupported_actions_types(*args, **kwargs):
         "2022-05-01":
         [
             "RecognizeCustomEntitiesAction",
-            "SingleCategoryClassifyAction",
+            "SingleLabelClassifyAction",
             "MultiCategoryClassifyAction",
             "AnalyzeHealthcareEntitiesAction"
         ]