docs sweep for the beta (#27316)

Author: kristapratico

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

@@ -15,7 +15,7 @@
   `NumberResolution`, `NumericRangeResolution`, `OrdinalResolution`, `SpeedResolution`, `TemperatureResolution`,
   `TemporalSpanResolution`, `VolumeResolution`, `WeightResolution`, `AgeUnit`, `AreaUnit`, `TemporalModifier`,
   `InformationUnit`, `LengthUnit`, `NumberKind`, `RangeKind`, `RelativeTo`, `SpeedUnit`, `TemperatureUnit`,
-  `VolumeUnit`, and `WeightUnit`.
+  `VolumeUnit`, `DateTimeSubKind`, and `WeightUnit`.
 - Added the Abstractive Summarization feature and related models: `AbstractSummaryAction`, `AbstractSummaryResult`, `AbstractiveSummary`,
   and `SummaryContext`. Access the feature through the `begin_analyze_actions` API.
 - Added automatic language detection to long-running operation APIs. Pass `auto` into the document `language` hint to use this feature.

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

@@ -98,6 +98,7 @@
     VolumeUnit,
     WeightUnit,
     ClassificationType,
+    DateTimeSubKind,
 )
 from ._lro import AnalyzeHealthcareEntitiesLROPoller, AnalyzeActionsLROPoller, TextAnalysisLROPoller
 
@@ -196,6 +197,7 @@
     "AbstractSummaryAction",
     "ClassificationType",
     "DynamicClassificationResult",
+    "DateTimeSubKind",
 ]
 
 __version__ = VERSION

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

@@ -58,6 +58,9 @@ def __init__(
                 "x-envoy-upstream-service-time",
                 "Strict-Transport-Security",
                 "x-content-type-options",
+                "warn-code",
+                "warn-agent",
+                "warn-text",
             }
         )
         http_logging_policy.allowed_query_params.update(

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

@@ -375,8 +375,8 @@ class RecognizeEntitiesResult(DictMixin):
         field will contain information about the document payload.
     :vartype statistics:
         Optional[~azure.ai.textanalytics.TextDocumentStatistics]
-    :ivar detected_language: If 'language' was set to 'auto' for the document in the request this
-        field will contain a 2 letter ISO 639-1 representation of the language detected for this document.
+    :ivar detected_language: If 'language' is set to 'auto' for the document in the request this
+        field will contain the DetectedLanguage for the document.
     :vartype detected_language: Optional[~azure.ai.textanalytics.DetectedLanguage]
     :ivar bool is_error: Boolean check for error item when iterating over list of
         results. Always False for an instance of a RecognizeEntitiesResult.
@@ -429,8 +429,8 @@ class RecognizePiiEntitiesResult(DictMixin):
         field will contain information about the document payload.
     :vartype statistics:
         Optional[~azure.ai.textanalytics.TextDocumentStatistics]
-    :ivar detected_language: If 'language' was set to 'auto' for the document in the request this
-        field will contain a 2 letter ISO 639-1 representation of the language detected for this document.
+    :ivar detected_language: If 'language' is set to 'auto' for the document in the request this
+        field will contain the DetectedLanguage for the document.
     :vartype detected_language: Optional[~azure.ai.textanalytics.DetectedLanguage]
     :ivar bool is_error: Boolean check for error item when iterating over list of
         results. Always False for an instance of a RecognizePiiEntitiesResult.
@@ -493,8 +493,8 @@ class AnalyzeHealthcareEntitiesResult(DictMixin):
         FHIR compatible object for consumption in other Healthcare tools. For additional
         information see https://www.hl7.org/fhir/overview.html.
     :vartype fhir_bundle: Optional[dict[str, any]]
-    :ivar detected_language: If 'language' was set to 'auto' for the document in the request this
-        field will contain a 2 letter ISO 639-1 representation of the language detected for this document.
+    :ivar detected_language: If 'language' is set to 'auto' for the document in the request this
+        field will contain the DetectedLanguage for the document.
     :vartype detected_language: Optional[~azure.ai.textanalytics.DetectedLanguage]
     :ivar bool is_error: Boolean check for error item when iterating over list of
         results. Always False for an instance of a AnalyzeHealthcareEntitiesResult.
@@ -1052,8 +1052,8 @@ class ExtractKeyPhrasesResult(DictMixin):
         field will contain information about the document payload.
     :vartype statistics:
         Optional[~azure.ai.textanalytics.TextDocumentStatistics]
-    :ivar detected_language: If 'language' was set to 'auto' for the document in the request this
-        field will contain a 2 letter ISO 639-1 representation of the language detected for this document.
+    :ivar detected_language: If 'language' is set to 'auto' for the document in the request this
+        field will contain the DetectedLanguage for the document.
     :vartype detected_language: Optional[~azure.ai.textanalytics.DetectedLanguage]
     :ivar bool is_error: Boolean check for error item when iterating over list of
         results. Always False for an instance of a ExtractKeyPhrasesResult.
@@ -1104,8 +1104,8 @@ class RecognizeLinkedEntitiesResult(DictMixin):
         field will contain information about the document payload.
     :vartype statistics:
         Optional[~azure.ai.textanalytics.TextDocumentStatistics]
-    :ivar detected_language: If 'language' was set to 'auto' for the document in the request this
-        field will contain a 2 letter ISO 639-1 representation of the language detected for this document.
+    :ivar detected_language: If 'language' is set to 'auto' for the document in the request this
+        field will contain the DetectedLanguage for the document.
     :vartype detected_language: Optional[~azure.ai.textanalytics.DetectedLanguage]
     :ivar bool is_error: Boolean check for error item when iterating over list of
         results. Always False for an instance of a RecognizeLinkedEntitiesResult.
@@ -1165,8 +1165,8 @@ class AnalyzeSentimentResult(DictMixin):
     :ivar sentences: Sentence level sentiment analysis.
     :vartype sentences:
         list[~azure.ai.textanalytics.SentenceSentiment]
-    :ivar detected_language: If 'language' was set to 'auto' for the document in the request this
-        field will contain a 2 letter ISO 639-1 representation of the language detected for this document.
+    :ivar detected_language: If 'language' is set to 'auto' for the document in the request this
+        field will contain the DetectedLanguage for the document.
     :vartype detected_language: Optional[~azure.ai.textanalytics.DetectedLanguage]
     :ivar bool is_error: Boolean check for error item when iterating over list of
         results. Always False for an instance of a AnalyzeSentimentResult.
@@ -1473,6 +1473,9 @@ class TextDocumentInput(DictMixin, MultiLanguageInput):
      operation APIs with API version 2022-10-01-preview or newer). If
      not set, uses "en" for English as default.
     :vartype language: Optional[str]
+
+    .. versionadded:: 2022-10-01-preview
+        The 'auto' option for language.
     """
 
     def __init__(self, **kwargs):
@@ -2306,8 +2309,8 @@ class RecognizeCustomEntitiesResult(DictMixin):
     :ivar statistics: If `show_stats=True` was specified in the request this
         field will contain information about the document payload.
     :vartype statistics: Optional[~azure.ai.textanalytics.TextDocumentStatistics]
-    :ivar detected_language: If 'language' was set to 'auto' for the document in the request this
-        field will contain a 2 letter ISO 639-1 representation of the language detected for this document.
+    :ivar detected_language: If 'language' is set to 'auto' for the document in the request this
+        field will contain the DetectedLanguage for the document.
     :vartype detected_language: Optional[~azure.ai.textanalytics.DetectedLanguage]
     :ivar bool is_error: Boolean check for error item when iterating over list of
         results. Always False for an instance of a RecognizeCustomEntitiesResult.
@@ -2433,8 +2436,8 @@ class ClassifyDocumentResult(DictMixin):
     :ivar statistics: If `show_stats=True` was specified in the request this
         field will contain information about the document payload.
     :vartype statistics: Optional[~azure.ai.textanalytics.TextDocumentStatistics]
-    :ivar detected_language: If 'language' was set to 'auto' for the document in the request this
-        field will contain a 2 letter ISO 639-1 representation of the language detected for this document.
+    :ivar detected_language: If 'language' is set to 'auto' for the document in the request this
+        field will contain the DetectedLanguage for the document.
     :vartype detected_language: Optional[~azure.ai.textanalytics.DetectedLanguage]
     :ivar bool is_error: Boolean check for error item when iterating over list of
         results. Always False for an instance of a ClassifyDocumentResult.
@@ -2630,10 +2633,11 @@ class AnalyzeHealthcareEntitiesAction(DictMixin):
     :ivar Optional[str] fhir_version: The FHIR Spec version that the result will use to format the fhir_bundle
         on the result object. For additional information see https://www.hl7.org/fhir/overview.html.
         The only acceptable values to pass in are None and "4.0.1". The default value is None.
-    :ivar Optional[str] document_type: Document type that can be provided as input for Fhir Documents. Expect to
+    :ivar document_type: Document type that can be provided as input for Fhir Documents. Expect to
         have fhir_version provided when used. Behavior of using None enum is the same as not using the
         document_type parameter. Known values are: "None", "ClinicalTrial", "DischargeSummary",
         "ProgressNote", "HistoryAndPhysical", "Consult", "Imaging", "Pathology", and "ProcedureNote".
+    :vartype document_type: Optional[str or ~azure.ai.textanalytics.HealthcareDocumentType]
 
     .. versionadded:: 2022-05-01
         The *AnalyzeHealthcareEntitiesAction* model.
@@ -2676,7 +2680,7 @@ def _to_generated(self, api_version, task_id):  # pylint: disable=unused-argumen
 class ExtractSummaryAction(DictMixin):
     """ExtractSummaryAction encapsulates the parameters for starting a long-running Extractive Text
     Summarization operation. For a conceptual discussion of extractive summarization, see the service documentation:
-    https://docs.microsoft.com/azure/cognitive-services/text-analytics/how-tos/extractive-summarization
+    https://learn.microsoft.com/azure/cognitive-services/language-service/summarization/overview
 
     :keyword Optional[str] model_version: The model version to use for the analysis.
     :keyword Optional[str] string_index_type: Specifies the method used to interpret string offsets.
@@ -2758,8 +2762,7 @@ class ExtractSummaryResult(DictMixin):
         field will contain information about the document payload.
     :vartype statistics: Optional[~azure.ai.textanalytics.TextDocumentStatistics]
     :ivar detected_language: If 'language' is set to 'auto' for the document in the request this
-        field will contain a 2 letter ISO 639-1 representation of the language detected for this
-        document.
+        field will contain the DetectedLanguage for the document.
     :vartype detected_language: Optional[~azure.ai.textanalytics.DetectedLanguage]
     :ivar bool is_error: Boolean check for error item when iterating over list of
         results. Always False for an instance of an ExtractSummaryResult.
@@ -2860,13 +2863,12 @@ def _from_generated(cls, sentence):
 class AbstractSummaryResult(DictMixin):
     """AbstractSummaryResult is a result object which contains
     the summary generated for a particular document.
-.
+
     :ivar id: Unique, non-empty document identifier. Required.
     :vartype id: str
     :ivar detected_language: If 'language' is set to 'auto' for the document in the request this
-        field will contain a 2 letter ISO 639-1 representation of the language detected for this
-        document.
-    :vartype detected_language: Optional[~azure.ai.textanalytics.DetectedLanguage}
+        field will contain the DetectedLanguage for the document.
+    :vartype detected_language: Optional[~azure.ai.textanalytics.DetectedLanguage]
     :ivar warnings: Warnings encountered while processing document. Results will still be returned
         if there are warnings, but they may not be fully accurate.
     :vartype warnings: list[~azure.ai.textanalytics.TextAnalyticsWarning]
@@ -3000,13 +3002,18 @@ def _from_generated(cls, summary):
 
 class AbstractSummaryAction(DictMixin):
     """AbstractSummaryAction encapsulates the parameters for starting a long-running
-    abstractive summarization operation.
+    abstractive summarization operation. For a conceptual discussion of extractive summarization,
+    see the service documentation:
+    https://learn.microsoft.com/azure/cognitive-services/language-service/summarization/overview
 
     Abstractive summarization generates a summary for the input documents. Abstractive summarization
     is different from extractive summarization in that extractive summarization is the strategy of
     concatenating extracted sentences from the input document into a summary, while abstractive
     summarization involves paraphrasing the document using novel sentences.
 
+    .. note:: The abstractive summarization feature is part of a gated preview. Request access here:
+        https://aka.ms/applyforgatedsummarizationfeatures
+
     :keyword Optional[int] sentence_count: It controls the approximate number of sentences in the output summaries.
     :keyword Optional[str] model_version: The model version to use for the analysis.
     :keyword Optional[str] string_index_type: Specifies the method used to interpret string offsets.
@@ -3021,6 +3028,7 @@ class AbstractSummaryAction(DictMixin):
         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.
+    :ivar Optional[int] sentence_count: It controls the approximate number of sentences in the output summaries.
     :ivar Optional[str] model_version: The model version to use for the analysis.
     :ivar Optional[str] string_index_type: Specifies the method used to interpret string offsets.
         `UnicodeCodePoint`, the Python encoding, is the default. To override the Python default,
@@ -3034,7 +3042,6 @@ class AbstractSummaryAction(DictMixin):
         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.
-    :ivar Optional[int] sentence_count: It controls the approximate number of sentences in the output summaries.
 
     .. versionadded:: 2022-10-01-preview
         The *AbstractSummaryAction* model.

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

@@ -1119,6 +1119,9 @@ def begin_analyze_actions(
         combine multiple text analysis actions into one call. Otherwise, we recommend you use
         the action specific endpoints, for example :func:`analyze_sentiment`.
 
+        .. note:: The abstractive summarization feature is part of a gated preview. Request access here:
+            https://aka.ms/applyforgatedsummarizationfeatures
+
         .. note:: See the service documentation for regional support of custom action features:
             https://aka.ms/azsdk/textanalytics/customfunctionalities
 
@@ -1714,6 +1717,9 @@ def dynamic_classification(
         Assigns either one or multiple categories per document. This type of classification
         doesn't require model training.
 
+        .. note:: The dynamic classification feature is part of a gated preview. Request access here:
+            https://aka.ms/applyforgatedlanguagefeature
+
         See https://aka.ms/azsdk/textanalytics/data-limits for service data limits.
 
         :param documents: The set of documents to process as part of this batch.

sdk/textanalytics/azure-ai-textanalytics/azure/ai/textanalytics/aio/_base_client_async.py

@@ -43,6 +43,9 @@ def __init__(
                 "x-envoy-upstream-service-time",
                 "Strict-Transport-Security",
                 "x-content-type-options",
+                "warn-code",
+                "warn-agent",
+                "warn-text",
             }
         )
         http_logging_policy.allowed_query_params.update(

sdk/textanalytics/azure-ai-textanalytics/azure/ai/textanalytics/aio/_text_analytics_client_async.py

@@ -1115,6 +1115,9 @@ async def begin_analyze_actions(
         combine multiple text analysis actions into one call. Otherwise, we recommend you use
         the action specific endpoints, for example :func:`analyze_sentiment`.
 
+        .. note:: The abstractive summarization feature is part of a gated preview. Request access here:
+            https://aka.ms/applyforgatedsummarizationfeatures
+
         .. note:: See the service documentation for regional support of custom action features:
             https://aka.ms/azsdk/textanalytics/customfunctionalities
 
@@ -1712,6 +1715,9 @@ async def dynamic_classification(
         Assigns either one or multiple categories per document. This type of classification
         doesn't require model training.
 
+        .. note:: The dynamic classification feature is part of a gated preview. Request access here:
+            https://aka.ms/applyforgatedlanguagefeature
+
         See https://aka.ms/azsdk/textanalytics/data-limits for service data limits.
 
         :param documents: The set of documents to process as part of this batch.

sdk/textanalytics/azure-ai-textanalytics/samples/async_samples/sample_abstract_summary_async.py

@@ -14,6 +14,9 @@
     Abstractive summarization generates a summary that may not use the same words as those in
     the document, but captures the main idea.
 
+    The abstractive summarization feature is part of a gated preview. Request access here:
+    https://aka.ms/applyforgatedsummarizationfeatures
+
 USAGE:
     python sample_abstract_summary_async.py
 

sdk/textanalytics/azure-ai-textanalytics/samples/async_samples/sample_dynamic_classification_async.py

@@ -11,6 +11,9 @@
     This sample demonstrates how to dynamically classify documents into one or multiple categories.
     No model training is required to use dynamic classification.
 
+    The dynamic classification feature is part of a gated preview. Request access here:
+    https://aka.ms/applyforgatedlanguagefeature
+
 USAGE:
     python sample_dynamic_classification_async.py
 

sdk/textanalytics/azure-ai-textanalytics/samples/sample_abstract_summary.py

@@ -14,6 +14,9 @@
     Abstractive summarization generates a summary that may not use the same words as those in
     the document, but captures the main idea.
 
+    The abstractive summarization feature is part of a gated preview. Request access here:
+    https://aka.ms/applyforgatedsummarizationfeatures
+
 USAGE:
     python sample_abstract_summary.py