Azure/azure-sdk-for-python azure-ai-textanalytics_1.0.0b1

on GitHub

1.0.0b1 (2020-01-09)

Version (1.0.0b1) is the first preview of our efforts to create a user-friendly and Pythonic client library for Azure Text Analytics. For more information about this, and preview releases of other Azure SDK libraries, please visit
https://azure.github.io/azure-sdk/releases/latest/python.html.

Breaking changes: New API design

• New namespace/package name:

  • The namespace/package name for Azure Text Analytics client library has changed from azure.cognitiveservices.language.textanalytics to azure.ai.textanalytics

• New operations and naming:

  • detect_language is renamed to detect_languages
  • entities is renamed to recognize_entities
  • key_phrases is renamed to extract_key_phrases
  • sentiment is renamed to analyze_sentiment
  • New operation recognize_pii_entities finds personally identifiable information entities in text
  • New operation recognize_linked_entities provides links from a well-known knowledge base for each recognized entity
  • New module-level operations single_detect_language, single_recognize_entities, single_extract_key_phrases, single_analyze_sentiment, single_recognize_pii_entities, and single_recognize_linked_entities perform
    function on a single string instead of a batch of text documents and can be imported from the azure.ai.textanalytics namespace.
  • New client and module-level async APIs added to subnamespace azure.ai.textanalytics.aio.
  • MultiLanguageInput has been renamed to TextDocumentInput
  • LanguageInput has been renamed to DetectLanguageInput
  • DocumentLanguage has been renamed to DetectLanguageResult
  • DocumentEntities has been renamed to RecognizeEntitiesResult
  • DocumentLinkedEntities has been renamed to RecognizeLinkedEntitiesResult
  • DocumentKeyPhrases has been renamed to ExtractKeyPhrasesResult
  • DocumentSentiment has been renamed to AnalyzeSentimentResult
  • DocumentStatistics has been renamed to TextDocumentStatistics
  • RequestStatistics has been renamed to TextDocumentBatchStatistics
  • Entity has been renamed to NamedEntity
  • Match has been renamed to LinkedEntityMatch
  • The batching methods' documents parameter has been renamed inputs

• New input types:

  • detect_languages can take as input a list[DetectLanguageInput] or a list[str]. A list of dict-like objects in the same shape as DetectLanguageInput is still accepted as input.
  • recognize_entities, recognize_pii_entities, recognize_linked_entities, extract_key_phrases, analyze_sentiment can take as input a list[TextDocumentInput] or list[str].
    A list of dict-like objects in the same shape as TextDocumentInput is still accepted as input.

• New parameters/keyword arguments:

  • All operations now take a keyword argument model_version which allows the user to specify a string referencing the desired model version to be used for analysis. If no string specified, it will default to the latest, non-preview version.
  • detect_languages now takes a parameter country_hint which allows you to specify the country hint for the entire batch. Any per-item country hints will take precedence over a whole batch hint.
  • recognize_entities, recognize_pii_entities, recognize_linked_entities, extract_key_phrases, analyze_sentiment now take a parameter language which allows you to specify the language for the entire batch.
    Any per-item specified language will take precedence over a whole batch hint.
  • A default_country_hint or default_language keyword argument can be passed at client instantiation to set the default values for all operations.
  • A response_hook keyword argument can be passed with a callback to use the raw response from the service. Additionally, values returned for TextDocumentBatchStatistics and model_version used must be retrieved using a response hook.
  • show_stats and model_version parameters move to keyword only arguments.

• New return types

  • The return types for the batching methods (detect_languages, recognize_entities, recognize_pii_entities, recognize_linked_entities, extract_key_phrases, analyze_sentiment) now return a heterogeneous list of
    result objects and document errors in the order passed in with the request. To iterate over the list and filter for result or error, a boolean property on each object called is_error can be used to determine whether the returned response object at
    that index is a result or an error:
  • detect_languages now returns a List[Union[DetectLanguageResult, DocumentError]]
  • recognize_entities now returns a List[Union[RecognizeEntitiesResult, DocumentError]]
  • recognize_pii_entities now returns a List[Union[RecognizePiiEntitiesResult, DocumentError]]
  • recognize_linked_entities now returns a List[Union[RecognizeLinkedEntitiesResult, DocumentError]]
  • extract_key_phrases now returns a List[Union[ExtractKeyPhrasesResult, DocumentError]]
  • analyze_sentiment now returns a List[Union[AnalyzeSentimentResult, DocumentError]]
  • The module-level, single text operations will return a single result object or raise the error found on the document:
  • single_detect_languages returns a DetectLanguageResult
  • single_recognize_entities returns a RecognizeEntitiesResult
  • single_recognize_pii_entities returns a RecognizePiiEntitiesResult
  • single_recognize_linked_entities returns a RecognizeLinkedEntitiesResult
  • single_extract_key_phrases returns a ExtractKeyPhrasesResult
  • single_analyze_sentiment returns a AnalyzeSentimentResult

• New underlying REST pipeline implementation, based on the new azure-core library.

• Client and pipeline configuration is now available via keyword arguments at both the client level, and per-operation. See README for a full list of optional configuration arguments.

• Authentication using azure-identity credentials

  • see the
    Azure Identity documentation
    for more information

• New error hierarchy:

  • All service errors will now use the base type: azure.core.exceptions.HttpResponseError
  • There is one exception type derived from this base type for authentication errors:
    • ClientAuthenticationError: Authentication failed.