Migrating to Python Client Library v0.26.1

The Client Library for Python v0.26.1 includes some significant changes to how previous client libraries were designed. These changes can be summarized as follows:

  • Consolidation of modules into fewer types

  • Replacing untyped parameters with strongly-typed classes and enumerations

This topic provides details on the changes that you will need to make to your Python code for the Cloud Natural Language API client libraries in order to use the v0.26.1 Python client library.

Running previous versions of the client library

You are not required to upgrade your Python client library to v0.26.1. If you want to continue using a previous version of the Python client library and do not want to migrate your code, then you should specify the version of the Python client library used by your app. To specify a specific library version, edit the requirements.txt file as shown following:

google-cloud-language==0.25

Deprecated Modules

The following modules are deprecated in the Python Client Library v0.26.1 package.

  • google.cloud.language.api_responses

  • google.cloud.language.client

  • google.cloud.language.document

  • google.cloud.language.entity

  • google.cloud.language.sentence

  • google.cloud.language.sentiment

  • google.cloud.language.syntax

Required Code Changes

Imports

Include the new google.cloud.language.types module in order to access the new types in the Python Client Library v0.26.1.

The types module contains the new classes that are required for creating requests, such as types.Document. The enums module contains the enumerations for specifying document type. You can continue to use strings such as 'PLAIN_TEXT' and 'HTML' to specify your document type, however we recommend that you use the enumerations in the enums module.

from google.cloud import language
from google.cloud.language import enums
from google.cloud.language import types

Additionally, the new google.cloud.language.enums module contains the enumerations useful for parsing and understanding API responses, such as enums.Entity.Type.PERSON and enums.PartOfSpeech.Tag.ADJ.

Create a client

The Client class has been replaced with the LanguageServiceClient class. Replace references to the Client class with LanguageServiceClient.

Previous versions of the client libraries:

old_client = language.Client()

Python Client Library v0.26.1:

client = language.LanguageServiceClient()

Constructing objects that represent text content

To identify text content from a text string or from a Google Cloud Storage URI use the new Document class.

Constructing objects that represent text content from text string

The following example shows the new way to represent text content from a text string.

Previous versions of the client libraries:

document = old_client.document_from_text(content=text)

Python Client Library v0.26.1:

document = types.Document(
    content=text,
    type=enums.Document.Type.PLAIN_TEXT)

You can also analyze HTML by setting document.type = enums.Document.Type.HTML.

Constructing objects that represent text content from Google Cloud Storage URI

The following example shows the new way to represent text content from a Google Cloud Storage URI or a web URI. gcs_uri is the URI to a text file on Google Cloud Storage.

Previous versions of the client libraries:

document = old_client.document_from_gcs_uri(gcs_uri=gcs_uri)

Python Client Library v0.26.1:

document = types.Document(
    gcs_content_uri=gcs_uri,
    type=enums.Document.Type.PLAIN_TEXT)

You can also analyze HTML by setting document.type = enums.Document.Type.HTML.

Making requests and processing responses

With the Python Client Library v0.26.1 the API methods such as analyze_sentiment belong to the LanguageServiceClient object as opposed to the Document objects.

The returned values are slightly different for analyze_entities and analyze_syntax as explained below.

Making an analyze sentiment request and processing the response

Previous versions of the client libraries:

document = language_client.document_from_text(text)

sentiment = document.analyze_sentiment().sentiment

print('Score: {}'.format(sentiment.score))
print('Magnitude: {}'.format(sentiment.magnitude))

Python Client Library v0.26.1:

document = types.Document(
    content=text,
    type=enums.Document.Type.PLAIN_TEXT)

# Detects sentiment in the document. You can also analyze HTML with:
#   document.type == enums.Document.Type.HTML
sentiment = client.analyze_sentiment(document).document_sentiment

print('Score: {}'.format(sentiment.score))
print('Magnitude: {}'.format(sentiment.magnitude))

Making an analyze entities request and processing the response

Entities' types are now stored as entity.type as opposed to entity.entity_type.

Previous versions of the client libraries:

document = language_client.document_from_text(text)

entities = document.analyze_entities().entities

for entity in entities:
    print('=' * 20)
    print(u'{:<16}: {}'.format('name', entity.name))
    print(u'{:<16}: {}'.format('type', entity.entity_type))
    print(u'{:<16}: {}'.format('metadata', entity.metadata))
    print(u'{:<16}: {}'.format('salience', entity.salience))
    print(u'{:<16}: {}'.format('wikipedia_url',
          entity.metadata.get('wikipedia_url', '-')))

Python Client Library v0.26.1:

document = types.Document(
    content=text,
    type=enums.Document.Type.PLAIN_TEXT)

# Detects entities in the document. You can also analyze HTML with:
#   document.type == enums.Document.Type.HTML
entities = client.analyze_entities(document).entities

# entity types from enums.Entity.Type
entity_type = ('UNKNOWN', 'PERSON', 'LOCATION', 'ORGANIZATION',
               'EVENT', 'WORK_OF_ART', 'CONSUMER_GOOD', 'OTHER')

for entity in entities:
    print('=' * 20)
    print(u'{:<16}: {}'.format('name', entity.name))
    print(u'{:<16}: {}'.format('type', entity_type[entity.type]))
    print(u'{:<16}: {}'.format('metadata', entity.metadata))
    print(u'{:<16}: {}'.format('salience', entity.salience))
    print(u'{:<16}: {}'.format('wikipedia_url',
          entity.metadata.get('wikipedia_url', '-')))

Making an analyze syntax request and processing the response

Tokens' part of speech tags, token.part_of_speech.tag, are now returned as enumerations, whose names can be recovered by importing google.cloud.language.enums.PartOfSpeech.Tag.

Tokens' text contents are now stored as token.text.content as opposed to token.text_content.

Previous versions of the client libraries:

document = language_client.document_from_text(text)

tokens = document.analyze_syntax().tokens

for token in tokens:
    print(u'{}: {}'.format(token.part_of_speech.tag, token.text_content))

Python Client Library v0.26.1:

document = types.Document(
    content=text,
    type=enums.Document.Type.PLAIN_TEXT)

# Detects syntax in the document. You can also analyze HTML with:
#   document.type == enums.Document.Type.HTML
tokens = client.analyze_syntax(document).tokens

# part-of-speech tags from enums.PartOfSpeech.Tag
pos_tag = ('UNKNOWN', 'ADJ', 'ADP', 'ADV', 'CONJ', 'DET', 'NOUN', 'NUM',
           'PRON', 'PRT', 'PUNCT', 'VERB', 'X', 'AFFIX')

for token in tokens:
    print(u'{}: {}'.format(pos_tag[token.part_of_speech.tag],
                           token.text.content))

Send feedback about...

Cloud Natural Language API Documentation