[textanalytics] APIView feedback

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

@@ -18,6 +18,10 @@ Note: this version will be the last to officially support Python 3.5, future ver
 - Removed: `AnalyzeActionsType`
 - Removed: `AnalyzeActionsResult`
 - Removed: `AnalyzeActionsError`
+- Removed: `HealthcareEntityRelationRoleType`
+- Changed: renamed `HealthcareEntityRelationType` to `HealthcareEntityRelation`
+- Changed: renamed `PiiEntityCategoryType` to `PiiEntityCategory`
+- Changed: renamed `PiiEntityDomainType` to `PiiEntityDomain`
 
 ## 5.1.0b7 (2021-05-18)
 

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

@@ -31,7 +31,7 @@
     AssessmentSentiment,
     RecognizePiiEntitiesResult,
     PiiEntity,
-    PiiEntityDomainType,
+    PiiEntityDomain,
     AnalyzeHealthcareEntitiesResult,
     HealthcareEntity,
     HealthcareEntityDataSource,
@@ -40,13 +40,12 @@
     RecognizePiiEntitiesAction,
     ExtractKeyPhrasesAction,
     _AnalyzeActionsType,
-    HealthcareEntityRelationRoleType,
     HealthcareRelation,
     HealthcareRelationRole,
     HealthcareEntityAssertion,
     AnalyzeSentimentAction,
-    PiiEntityCategoryType,
-    HealthcareEntityRelationType,
+    PiiEntityCategory,
+    HealthcareEntityRelation,
     EntityConditionality,
     EntityCertainty,
     EntityAssociation,
@@ -81,7 +80,7 @@
     'AssessmentSentiment',
     'RecognizePiiEntitiesResult',
     'PiiEntity',
-    'PiiEntityDomainType',
+    'PiiEntityDomain',
     'AnalyzeHealthcareEntitiesResult',
     'HealthcareEntity',
     'HealthcareEntityDataSource',
@@ -90,9 +89,8 @@
     'RecognizePiiEntitiesAction',
     'ExtractKeyPhrasesAction',
     '_AnalyzeActionsType',
-    "PiiEntityCategoryType",
-    "HealthcareEntityRelationType",
-    "HealthcareEntityRelationRoleType",
+    "PiiEntityCategory",
+    "HealthcareEntityRelation",
     "HealthcareRelation",
     "HealthcareRelationRole",
     "HealthcareEntityAssertion",

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

@@ -97,7 +97,7 @@ class EntityConditionality(str, Enum):
     CONDITIONAL = "conditional"
 
 
-class HealthcareEntityRelationType(str, Enum):
+class HealthcareEntityRelation(str, Enum):
     """Type of relation. Examples include: ``DosageOfMedication`` or 'FrequencyOfMedication', etc.
     """
 
@@ -124,7 +124,7 @@ class HealthcareEntityRelationType(str, Enum):
     VALUE_OF_EXAMINATION = "ValueOfExamination"
 
 
-class PiiEntityCategoryType(str, Enum):
+class PiiEntityCategory(str, Enum):
 
     ABA_ROUTING_NUMBER = "ABARoutingNumber"
     AR_NATIONAL_IDENTITY_NUMBER = "ARNationalIdentityNumber"
@@ -333,30 +333,10 @@ class HealthcareEntityCategory(str, Enum):
     TREATMENT_NAME = "TreatmentName"
 
 
-class PiiEntityDomainType(str, Enum):
+class PiiEntityDomain(str, Enum):
     """The different domains of PII entities that users can filter by"""
     PROTECTED_HEALTH_INFORMATION = "phi"  # See https://aka.ms/tanerpii for more information.
 
-class HealthcareEntityRelationRoleType(str, Enum):
-    """Type of roles entities can have in `entity_relations`. There may be roles not covered in this enum"""
-    ABBREVIATED_TERM = "AbbreviatedTerm"
-    FULL_TERM = "FullTerm"
-    DIRECTION = "Direction"
-    BODY_STRUCTURE = "BodyStructure"
-    CONDITION = "Condition"
-    EXAMINATION = "Examination"
-    TREATMENT = "Treatment"
-    DOSAGE = "Dosage"
-    MEDICATION = "Medication"
-    FORM = "Form"
-    FREQUENCY = "Frequency"
-    QUALIFIER = "Qualifier"
-    RELATION = "Relation"
-    ROUTE = "Route"
-    TIME = "Time"
-    EVENT = "Event"
-    UNIT = "Unit"
-    VALUE = "Value"
 
 class DetectedLanguage(DictMixin):
     """DetectedLanguage contains the predicted language found in text,
@@ -538,7 +518,7 @@ class HealthcareRelation(DictMixin):
 
     :ivar relation_type: The type of relation, i.e. the relationship between "100mg" and
         "ibuprofen" in the document "The subject took 100 mg of ibuprofen" is "DosageOfMedication".
-    :vartype relation_type: str or ~azure.ai.textanalytics.HealthcareEntityRelationType
+    :vartype relation_type: str or ~azure.ai.textanalytics.HealthcareEntityRelation
     :ivar roles: The roles present in this relation. I.e., in the document
         "The subject took 100 mg of ibuprofen", the present roles are "Dosage" and "Medication".
     :vartype roles: list[~azure.ai.textanalytics.HealthcareRelationRole]
@@ -575,7 +555,7 @@ class HealthcareRelationRole(DictMixin):
     :ivar name: The role of the entity in the relationship. I.e., in the relation
         "The subject took 100 mg of ibuprofen", the dosage entity "100 mg" has role
         "Dosage".
-    :vartype name: str or ~azure.ai.textanalytics.HealthcareEntityRelationRoleType
+    :vartype name: str
     :ivar entity: The entity that is present in the relationship. For example, in
         "The subject took 100 mg of ibuprofen", this property holds the dosage entity
         of "100 mg".
@@ -1769,8 +1749,8 @@ class RecognizePiiEntitiesAction(DictMixin):
     :keyword categories_filter: Instead of filtering over all PII entity categories, you can pass in a list of
         the specific PII entity categories you want to filter out. For example, if you only want to filter out
         U.S. social security numbers in a document, you can pass in
-        `[PiiEntityCategoryType.US_SOCIAL_SECURITY_NUMBER]` for this kwarg.
-    :paramtype categories_filter: list[~azure.ai.textanalytics.PiiEntityCategoryType]
+        `[PiiEntityCategory.US_SOCIAL_SECURITY_NUMBER]` for this kwarg.
+    :paramtype categories_filter: list[~azure.ai.textanalytics.PiiEntityCategory]
     :keyword str string_index_type: Specifies the method used to interpret string offsets.
         `UnicodeCodePoint`, the Python encoding, is the default. To override the Python default,
         you can also pass in `Utf16CodePoint` or TextElement_v8`. For additional information
@@ -1789,8 +1769,8 @@ class RecognizePiiEntitiesAction(DictMixin):
     :ivar categories_filter: Instead of filtering over all PII entity categories, you can pass in a list of
         the specific PII entity categories you want to filter out. For example, if you only want to filter out
         U.S. social security numbers in a document, you can pass in
-        `[PiiEntityCategoryType.US_SOCIAL_SECURITY_NUMBER]` for this kwarg.
-    :vartype categories_filter: list[~azure.ai.textanalytics.PiiEntityCategoryType]
+        `[PiiEntityCategory.US_SOCIAL_SECURITY_NUMBER]` for this kwarg.
+    :vartype categories_filter: list[~azure.ai.textanalytics.PiiEntityCategory]
     :ivar str string_index_type: Specifies the method used to interpret string offsets.
         `UnicodeCodePoint`, the Python encoding, is the default. To override the Python default,
         you can also pass in `Utf16CodePoint` or TextElement_v8`. For additional information

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

@@ -324,12 +324,12 @@ def recognize_pii_entities(  # type: ignore
         :keyword domain_filter: Filters the response entities to ones only included in the specified domain.
             I.e., if set to 'phi', will only return entities in the Protected Healthcare Information domain.
             See https://aka.ms/tanerpii for more information.
-        :paramtype domain_filter: str or ~azure.ai.textanalytics.PiiEntityDomainType
+        :paramtype domain_filter: str or ~azure.ai.textanalytics.PiiEntityDomain
         :keyword categories_filter: Instead of filtering over all PII entity categories, you can pass in a list of
             the specific PII entity categories you want to filter out. For example, if you only want to filter out
             U.S. social security numbers in a document, you can pass in
-            `[PiiEntityCategoryType.US_SOCIAL_SECURITY_NUMBER]` for this kwarg.
-        :paramtype categories_filter: list[~azure.ai.textanalytics.PiiEntityCategoryType]
+            `[PiiEntityCategory.US_SOCIAL_SECURITY_NUMBER]` for this kwarg.
+        :paramtype categories_filter: list[~azure.ai.textanalytics.PiiEntityCategory]
         :keyword str string_index_type: Specifies the method used to interpret string offsets.
             `UnicodeCodePoint`, the Python encoding, is the default. To override the Python default,
             you can also pass in `Utf16CodePoint` or `TextElement_v8`. For additional information
@@ -506,7 +506,7 @@ def begin_analyze_healthcare_entities(  # type: ignore
         self,
         documents,  # type: Union[List[str], List[TextDocumentInput], List[Dict[str, str]]]
         **kwargs  # type: Any
-    ):  # type: (...) -> AnalyzeHealthcareEntitiesLROPoller[ItemPaged[AnalyzeHealthcareEntitiesResult]]
+    ):  # type: (...) -> AnalyzeHealthcareEntitiesLROPoller[ItemPaged[Union[AnalyzeHealthcareEntitiesResult, DocumentError]]]  # pylint: disable=line-too-long
         """Analyze healthcare entities and identify relationships between these entities in a batch of documents.
 
         Entities are associated with references that can be found in existing knowledge bases,
@@ -547,10 +547,12 @@ def begin_analyze_healthcare_entities(  # type: ignore
             additional details, and Microsoft Responsible AI principles at
             https://www.microsoft.com/ai/responsible-ai.
         :return: An instance of an AnalyzeHealthcareEntitiesLROPoller. Call `result()` on the this
-            object to return a pageable of :class:`~azure.ai.textanalytics.AnalyzeHealthcareEntitiesResult`.
+            object to return a heterogeneous pageable of
+            :class:`~azure.ai.textanalytics.AnalyzeHealthcareEntitiesResult` and
+            :class:`~azure.ai.textanalytics.DocumentError`.
         :rtype:
             ~azure.ai.textanalytics.AnalyzeHealthcareEntitiesLROPoller[~azure.core.paging.ItemPaged[
-            ~azure.ai.textanalytics.AnalyzeHealthcareEntitiesResult]]
+            Union[~azure.ai.textanalytics.AnalyzeHealthcareEntitiesResult, ~azure.ai.textanalytics.DocumentError]]]
         :raises ~azure.core.exceptions.HttpResponseError or TypeError or ValueError or NotImplementedError:
 
         .. admonition:: Example:
@@ -818,7 +820,7 @@ def begin_analyze_actions(  # type: ignore
         documents,  # type: Union[List[str], List[TextDocumentInput], List[Dict[str, str]]]
         actions,  # type: List[Union[RecognizeEntitiesAction, RecognizeLinkedEntitiesAction, RecognizePiiEntitiesAction, ExtractKeyPhrasesAction, AnalyzeSentimentAction]] # pylint: disable=line-too-long
         **kwargs  # type: Any
-    ):  # type: (...) -> AnalyzeActionsLROPoller[ItemPaged[List[Union[RecognizeEntitiesResult, RecognizeLinkedEntitiesResult, RecognizePiiEntitiesResult, ExtractKeyPhrasesResult, AnalyzeSentimentResult]]]]  # pylint: disable=line-too-long
+    ):  # type: (...) -> AnalyzeActionsLROPoller[ItemPaged[List[Union[RecognizeEntitiesResult, RecognizeLinkedEntitiesResult, RecognizePiiEntitiesResult, ExtractKeyPhrasesResult, AnalyzeSentimentResult, DocumentError]]]]  # pylint: disable=line-too-long
         """Start a long-running operation to perform a variety of text analysis actions over a batch of documents.
 
         We recommend you use this function if you're looking to analyze larger documents, and / or
@@ -864,7 +866,7 @@ def begin_analyze_actions(  # type: ignore
             ~azure.ai.textanalytics.AnalyzeActionsLROPoller[~azure.core.paging.ItemPaged[
             list[
             RecognizeEntitiesResult or RecognizeLinkedEntitiesResult or RecognizePiiEntitiesResult or
-            ExtractKeyPhrasesResult or AnalyzeSentimentResult
+            ExtractKeyPhrasesResult or AnalyzeSentimentResult or DocumentError
             ]]]
         :raises ~azure.core.exceptions.HttpResponseError or TypeError or ValueError or NotImplementedError:
 

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

@@ -320,12 +320,12 @@ async def recognize_pii_entities(  # type: ignore
         :keyword domain_filter: Filters the response entities to ones only included in the specified domain.
             I.e., if set to 'phi', will only return entities in the Protected Healthcare Information domain.
             See https://aka.ms/tanerpii for more information.
-        :paramtype domain_filter: str or ~azure.ai.textanalytics.PiiEntityDomainType
+        :paramtype domain_filter: str or ~azure.ai.textanalytics.PiiEntityDomain
         :keyword categories_filter: Instead of filtering over all PII entity categories, you can pass in a list of
             the specific PII entity categories you want to filter out. For example, if you only want to filter out
             U.S. social security numbers in a document, you can pass in
-            `[PiiEntityCategoryType.US_SOCIAL_SECURITY_NUMBER]` for this kwarg.
-        :paramtype categories_filter: list[~azure.ai.textanalytics.PiiEntityCategoryType]
+            `[PiiEntityCategory.US_SOCIAL_SECURITY_NUMBER]` for this kwarg.
+        :paramtype categories_filter: list[~azure.ai.textanalytics.PiiEntityCategory]
         :keyword str string_index_type: Specifies the method used to interpret string offsets.
             Can be one of 'UnicodeCodePoint' (default), 'Utf16CodePoint', or 'TextElement_v8'.
             For additional information see https://aka.ms/text-analytics-offsets
@@ -682,7 +682,7 @@ async def begin_analyze_healthcare_entities(  # type: ignore
         self,
         documents: Union[List[str], List[TextDocumentInput], List[Dict[str, str]]],
         **kwargs: Any,
-    ) -> AsyncAnalyzeHealthcareEntitiesLROPoller[AsyncItemPaged[AnalyzeHealthcareEntitiesResult]]:
+    ) -> AsyncAnalyzeHealthcareEntitiesLROPoller[AsyncItemPaged[Union[AnalyzeHealthcareEntitiesResult, DocumentError]]]:
         """Analyze healthcare entities and identify relationships between these entities in a batch of documents.
 
         Entities are associated with references that can be found in existing knowledge bases,
@@ -722,10 +722,12 @@ async def begin_analyze_healthcare_entities(  # type: ignore
             additional details, and Microsoft Responsible AI principles at
             https://www.microsoft.com/ai/responsible-ai.
         :return: An instance of an AsyncAnalyzeHealthcareEntitiesLROPoller. Call `result()` on the poller
-            object to return a pageable of :class:`~azure.ai.textanalytics.AnalyzeHealthcareResultItem`.
+            object to return a heterogeneous pageable of
+            :class:`~azure.ai.textanalytics.AnalyzeHealthcareEntitiesResult` and
+            :class:`~azure.ai.textanalytics.DocumentError`.
         :rtype:
             ~azure.ai.textanalytics.aio.AsyncAnalyzeHealthcareEntitiesLROPoller[~azure.core.paging.AsyncItemPaged[
-            ~azure.ai.textanalytics.AnalyzeHealthcareEntitiesResult]]
+            Union[~azure.ai.textanalytics.AnalyzeHealthcareEntitiesResult, ~azure.ai.textanalytics.DocumentError]]]
         :raises ~azure.core.exceptions.HttpResponseError or TypeError or ValueError or NotImplementedError:
 
         .. admonition:: Example:
@@ -802,7 +804,7 @@ async def begin_analyze_actions(  # type: ignore
         documents: Union[List[str], List[TextDocumentInput], List[Dict[str, str]]],
         actions: List[Union[RecognizeEntitiesAction, RecognizeLinkedEntitiesAction, RecognizePiiEntitiesAction, ExtractKeyPhrasesAction, AnalyzeSentimentAction]], # pylint: disable=line-too-long
         **kwargs: Any
-    ) -> AsyncAnalyzeActionsLROPoller[AsyncItemPaged[List[Union[RecognizeEntitiesResult, RecognizeLinkedEntitiesResult, RecognizePiiEntitiesResult, ExtractKeyPhrasesResult, AnalyzeSentimentResult]]]]:  # pylint: disable=line-too-long
+    ) -> AsyncAnalyzeActionsLROPoller[AsyncItemPaged[List[Union[RecognizeEntitiesResult, RecognizeLinkedEntitiesResult, RecognizePiiEntitiesResult, ExtractKeyPhrasesResult, AnalyzeSentimentResult, DocumentError]]]]:  # pylint: disable=line-too-long
         """Start a long-running operation to perform a variety of text analysis actions over a batch of documents.
 
         We recommend you use this function if you're looking to analyze larger documents, and / or
@@ -848,7 +850,7 @@ async def begin_analyze_actions(  # type: ignore
             ~azure.core.polling.AsyncLROPoller[~azure.core.async_paging.AsyncItemPaged[
             list[
             RecognizeEntitiesResult or RecognizeLinkedEntitiesResult or RecognizePiiEntitiesResult or
-            ExtractKeyPhrasesResult or AnalyzeSentimentResult
+            ExtractKeyPhrasesResult or AnalyzeSentimentResult or DocumentError
             ]]]
         :raises ~azure.core.exceptions.HttpResponseError or TypeError or ValueError or NotImplementedError:
 

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

@@ -41,7 +41,7 @@ async def sample_analyze_healthcare_entities_async():
     # [START analyze_healthcare_entities_async]
     import os
     from azure.core.credentials import AzureKeyCredential
-    from azure.ai.textanalytics import HealthcareEntityRelationType, HealthcareEntityRelationRoleType
+    from azure.ai.textanalytics import HealthcareEntityRelation
     from azure.ai.textanalytics.aio import TextAnalyticsClient
 
     endpoint = os.environ["AZURE_TEXT_ANALYTICS_ENDPOINT"]
@@ -96,7 +96,7 @@ async def sample_analyze_healthcare_entities_async():
     dosage_of_medication_relations = [
         entity_relation
         for doc in docs
-        for entity_relation in doc.entity_relations if entity_relation.relation_type == HealthcareEntityRelationType.DOSAGE_OF_MEDICATION
+        for entity_relation in doc.entity_relations if entity_relation.relation_type == HealthcareEntityRelation.DOSAGE_OF_MEDICATION
     ]
     # [END analyze_healthcare_entities_async]
 
@@ -113,8 +113,8 @@ async def sample_analyze_healthcare_entities_async():
     for relation in dosage_of_medication_relations:
         # The DosageOfMedication relation should only contain the dosage and medication roles
 
-        dosage_role = next(filter(lambda x: x.name == HealthcareEntityRelationRoleType.DOSAGE, relation.roles))
-        medication_role = next(filter(lambda x: x.name == HealthcareEntityRelationRoleType.MEDICATION, relation.roles))
+        dosage_role = next(filter(lambda x: x.name == "Dosage", relation.roles))
+        medication_role = next(filter(lambda x: x.name == "Medication", relation.roles))
 
         try:
             dosage_value = int(re.findall(r"\d+", dosage_role.entity.text)[0]) # we find the numbers in the dosage

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

@@ -38,7 +38,7 @@ def sample_analyze_healthcare_entities():
     # [START analyze_healthcare_entities]
     import os
     from azure.core.credentials import AzureKeyCredential
-    from azure.ai.textanalytics import TextAnalyticsClient, HealthcareEntityRelationType, HealthcareEntityRelationRoleType
+    from azure.ai.textanalytics import TextAnalyticsClient, HealthcareEntityRelation
 
     endpoint = os.environ["AZURE_TEXT_ANALYTICS_ENDPOINT"]
     key = os.environ["AZURE_TEXT_ANALYTICS_KEY"]
@@ -92,7 +92,7 @@ def sample_analyze_healthcare_entities():
     dosage_of_medication_relations = [
         entity_relation
         for doc in docs
-        for entity_relation in doc.entity_relations if entity_relation.relation_type == HealthcareEntityRelationType.DOSAGE_OF_MEDICATION
+        for entity_relation in doc.entity_relations if entity_relation.relation_type == HealthcareEntityRelation.DOSAGE_OF_MEDICATION
     ]
     # [END analyze_healthcare_entities]
 
@@ -109,8 +109,8 @@ def sample_analyze_healthcare_entities():
     for relation in dosage_of_medication_relations:
         # The DosageOfMedication relation should only contain the dosage and medication roles
 
-        dosage_role = next(iter(filter(lambda x: x.name == HealthcareEntityRelationRoleType.DOSAGE, relation.roles)))
-        medication_role = next(iter(filter(lambda x: x.name == HealthcareEntityRelationRoleType.MEDICATION, relation.roles)))
+        dosage_role = next(iter(filter(lambda x: x.name == "Dosage", relation.roles)))
+        medication_role = next(iter(filter(lambda x: x.name == "Medication", relation.roles)))
 
         try:
             dosage_value = int(re.findall(r"\d+", dosage_role.entity.text)[0]) # we find the numbers in the dosage