[textanalytics] arch feedback (Azure#25453)

* remove polling_method from protocol and make covariant

* update docstrings

* pylint

Author: kristapratico

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

@@ -17,9 +17,11 @@
 class TextAnalyticsApiVersion(str, Enum, metaclass=CaseInsensitiveEnumMeta):
     """Cognitive Service for Language or Text Analytics API versions supported by this package"""
 
-    #: this is the default version
+    #: This is the default version and corresponds to the Cognitive Service for Language API.
     V2022_05_01 = "2022-05-01"
+    #: This version corresponds to Text Analytics API.
     V3_1 = "v3.1"
+    #: This version corresponds to Text Analytics API.
     V3_0 = "v3.0"
 
 

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

@@ -9,7 +9,6 @@
 from urllib.parse import urlencode
 from typing import Any, Mapping, Optional, Callable, TypeVar, cast
 from typing_extensions import Protocol, runtime_checkable
-from azure.core.polling import PollingMethod
 from azure.core.exceptions import HttpResponseError
 from azure.core.polling import LROPoller
 from azure.core.polling.base_polling import (
@@ -25,7 +24,7 @@
 _SUCCEEDED = frozenset(["succeeded", "partiallycompleted", "partiallysucceeded"])
 
 
-PollingReturnType = TypeVar("PollingReturnType")
+PollingReturnType = TypeVar("PollingReturnType", covariant=True)
 
 
 @runtime_checkable
@@ -35,34 +34,74 @@ class TextAnalysisLROPoller(Protocol[PollingReturnType]):
 
     @property
     def details(self) -> Mapping[str, Any]:
-        ...
+        """Long-running operation metadata.
 
-    def polling_method(self) -> PollingMethod[PollingReturnType]:  # pylint: disable=no-self-use
-        ...
+        :return: A mapping of details about the long-running operation.
+        :rtype: Mapping[str, Any]
+        """
 
     def continuation_token(self) -> str:  # pylint: disable=no-self-use
-        ...
+        """Return a continuation token that allows to restart the poller later.
+
+        :returns: An opaque continuation token
+        :rtype: str
+        """
 
     def status(self) -> str:  # pylint: disable=no-self-use
-        ...
+        """Returns the current status string.
+
+        :returns: The current status string
+        :rtype: str
+        """
 
     def result(self, timeout: Optional[int] = None) -> PollingReturnType: # pylint: disable=no-self-use, unused-argument
-        ...
+        """Return the result of the long running operation, or
+        the result available after the specified timeout.
+
+        :returns: The deserialized resource of the long running operation,
+         if one is available.
+        :raises ~azure.core.exceptions.HttpResponseError: Server problem with the query.
+        """
 
     def wait(self, timeout: Optional[float] = None) -> None:  # pylint: disable=no-self-use, unused-argument
-        ...
+        """Wait on the long running operation for a specified length
+        of time. You can check if this call as ended with timeout with the
+        "done()" method.
+
+        :param float timeout: Period of time to wait for the long running
+         operation to complete (in seconds).
+        :raises ~azure.core.exceptions.HttpResponseError: Server problem with the query.
+        """
 
     def done(self) -> bool:  # pylint: disable=no-self-use
-        ...
+        """Check status of the long running operation.
+
+        :returns: 'True' if the process has completed, else 'False'.
+        :rtype: bool
+        """
 
     def add_done_callback(self, func: Callable) -> None:  # pylint: disable=no-self-use, unused-argument
-        ...
+        """Add callback function to be run once the long running operation
+        has completed - regardless of the status of the operation.
+
+        :param callable func: Callback function that takes at least one
+         argument, a completed LongRunningOperation.
+        """
 
     def remove_done_callback(self, func: Callable) -> None:  # pylint: disable=no-self-use, unused-argument
-        ...
+        """Remove a callback from the long running operation.
+
+        :param callable func: The function to be removed from the callbacks.
+        :raises ValueError: if the long running operation has already completed.
+        """
 
     def cancel(self) -> None:  # pylint: disable=no-self-use
-        ...
+        """Cancel the operation currently being polled.
+
+        :return: None
+        :rtype: None
+        :raises ~azure.core.exceptions.HttpResponseError: When the operation has already reached a terminal state.
+        """
 
 
 class TextAnalyticsOperationResourcePolling(OperationResourcePolling):