Azure AI Text Analytics Client Library for Python

Warnings

• breaking The legacy package `azure-cognitiveservices-language-textanalytics` is deprecated and no longer maintained. Users should migrate to `azure-ai-textanalytics`. This migration involves changes in package name, import paths, and potentially API calls due to the underlying Azure Language service's shift to date-based API versioning from version 5.2.x onwards.
  Fix: Uninstall the old package (`pip uninstall azure-cognitiveservices-language-textanalytics`), install the new one (`pip install azure-ai-textanalytics`), and update import statements and client initialization as per the official documentation.
• gotcha The `TextAnalyticsClient` defaults to a specific stable API version of the Azure Language service (e.g., '2023-04-01' for library version 5.4.0). New features released in later service API versions (including preview versions) might not be available unless you explicitly specify the desired `api_version` during client instantiation.
  Fix: Pass the `api_version` keyword argument to the `TextAnalyticsClient` constructor (e.g., `TextAnalyticsClient(endpoint, credential, api_version="2024-07-01-preview")`) to access newer features or target a specific service API version.
• gotcha Azure Active Directory (AAD) authentication (using credentials from `azure-identity`) is not supported with regional endpoints (e.g., `https://westus2.api.cognitive.microsoft.com/`). To use AAD authentication, your Azure AI Language resource must have a custom subdomain configured.
  Fix: Configure a custom subdomain for your Azure AI Language resource in the Azure Portal and use that custom endpoint when initializing the `TextAnalyticsClient` with AAD credentials.
• gotcha For executing multiple different text analysis actions (e.g., sentiment analysis, entity recognition, key phrase extraction) in a single request on a batch of documents, the `begin_analyze_actions` method should be used. Direct client methods like `analyze_sentiment` are designed for performing a single type of analysis on a collection of documents.
  Fix: Utilize `client.begin_analyze_actions()` with a list of action models (e.g., `[RecognizeEntitiesAction(), AnalyzeSentimentAction()]`) for batch processing of diverse NLP tasks. This often leads to more efficient API usage.

Install

• pip install azure-ai-textanalytics Install stable version

Imports

• TextAnalyticsClient

  from azure.ai.textanalytics import TextAnalyticsClient

• AzureKeyCredential

  from azure.core.credentials import AzureKeyCredential

• LanguageDetectionAction

  from azure.ai.textanalytics import LanguageDetectionAction

• azure.cognitiveservices.language.textanalytics
  This is the old, deprecated package name. Migrate to azure-ai-textanalytics.

Quickstart

This quickstart demonstrates how to instantiate a `TextAnalyticsClient` using an API key and endpoint, and then perform sentiment analysis on a batch of documents. Ensure you replace placeholder credentials with your actual Azure Language service endpoint and API key, preferably via environment variables.

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.textanalytics import TextAnalyticsClient

# Set environment variables for endpoint and key
# AZURE_LANGUAGE_ENDPOINT='https://YOUR_RESOURCE_NAME.cognitiveservices.azure.com/'
# AZURE_LANGUAGE_KEY='YOUR_API_KEY'

endpoint = os.environ.get('AZURE_LANGUAGE_ENDPOINT', 'YOUR_LANGUAGE_ENDPOINT')
key = os.environ.get('AZURE_LANGUAGE_KEY', 'YOUR_LANGUAGE_KEY')

if endpoint == 'YOUR_LANGUAGE_ENDPOINT' or key == 'YOUR_LANGUAGE_KEY':
    print("Please set the 'AZURE_LANGUAGE_ENDPOINT' and 'AZURE_LANGUAGE_KEY' environment variables.")
else:
    try:
        text_analytics_client = TextAnalyticsClient(
            endpoint=endpoint, 
            credential=AzureKeyCredential(key)
        )

        documents = [
            "I had a wonderful trip to Seattle last week.",
            "The coffee was terrible and the staff was rude.",
            "The city was beautiful, but the weather was rainy."
        ]

        response = text_analytics_client.analyze_sentiment(documents=documents)

        for doc in response:
            if not doc.is_error:
                print(f"Document Text: {documents[doc.id]}")
                print(f"Overall Sentiment: {doc.sentiment}")
                print("Sentence sentiments:")
                for sentence in doc.sentences:
                    print(f"  Sentence: {sentence.text}")
                    print(f"  Sentiment: {sentence.sentiment}")
                    print(f"  Positive score: {round(sentence.confidence_scores.positive, 2)}")
                    print(f"  Neutral score: {round(sentence.confidence_scores.neutral, 2)}")
                    print(f"  Negative score: {round(sentence.confidence_scores.negative, 2)}\n")
            else:
                print(f"Document ID: {doc.id}, Error: {doc.error}")

    except Exception as e:
        print(f"An error occurred: {e}")