Migrating to Python Client Library v0.25.1

The Client Library for Python v0.25.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 Vision API client libraries in order to use the v0.25.1 Python client library.

Running previous versions of the client library

You are not required to upgrade your Python client library to v0.25.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:

google-cloud-vision==0.25

Removed Modules

The following modules were removed in the Python Client Library v0.25.1 package.

  • google.cloud.vision.annotations

  • google.cloud.vision.batch

  • google.cloud.vision.client

  • google.cloud.vision.color

  • google.cloud.vision.crop_hint

  • google.cloud.vision.entity

  • google.cloud.vision.face

  • google.cloud.vision.feature

  • google.cloud.vision.geometry

  • google.cloud.vision.image

  • google.cloud.vision.likelihood

  • google.cloud.vision.safe_search

  • google.cloud.vision.text

  • google.cloud.vision.web

Required Code Changes

Imports

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

The types module contains the new classes that are required for creating requests, such as types.Image.

from google.cloud import vision

Additionally, the new google.cloud.vision.enums module contains the enumerations useful for parsing and understanding API responses, such as enums.Likelihood.UNLIKELY and enums.FaceAnnotation.Landmark.Type.LEFT_EYE.

Create a client

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

Previous versions of the client libraries:

old_client = vision.Client()

Python Client Library v0.25.1:

client = vision.ImageAnnotatorClient()

Constructing objects that represent image content

To identify image content from a local file, from a Google Cloud Storage URI, or from a web URI, use the new Image class.

Constructing objects that represent image content from a local file

The following example shows the new way to represent image content from a local file.

Previous versions of the client libraries:

with io.open(file_name, 'rb') as image_file:
    content = image_file.read()

image = old_client.image(content=content)

Python Client Library v0.25.1:

with open(path, "rb") as image_file:
    content = image_file.read()

image = vision.Image(content=content)

Constructing objects that represent image content from a URI

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

Previous versions of the client libraries:

image = old_client.image(source_uri=uri)

Python Client Library v0.25.1:

image = vision.Image()
image.source.image_uri = uri

Making requests and processing responses

With the Python Client Library v.0.25.1 the API methods such as face_detection belong to the ImageAnnotatorClient object as opposed to the Image objects.

The returned values are different for several methods as explained below.

Particularly, bounding box vertices are now stored in bounding_poly.vertices as opposed to bounds.vertices. The coordinates of each vertex are stored in vertex.x and vertex.y as opposed to vertex.x_coordinate and vertex.y_coordinate.

The bounding box change affects face_detection, logo_detection, text_detection, document_text_detection, and crop_hints.

Making a face detection request and processing the response

Emotion likelihoods are now returned as enumerations stored in face.surprise_likelihood as opposed to face.emotions.surprise. The names of likelihood labels can be recovered by importing google.cloud.vision.enums.Likelihood.

Previous versions of the client libraries::

with io.open(file_name, 'rb') as image_file:
    content = image_file.read()

image = old_client.image(content=content)

faces = image.detect_faces()

for face in faces:
    print('anger: {}'.format(face.emotions.anger))
    print('joy: {}'.format(face.emotions.joy))
    print('surprise: {}'.format(face.emotions.surprise))

    vertices = (['({},{})'.format(bound.x_coordinate, bound.y_coordinate)
                for bound in face.bounds.vertices])

    print('face bounds: {}'.format(','.join(vertices)))

Python Client Library v0.25.1:

with open(path, "rb") as image_file:
    content = image_file.read()

image = vision.Image(content=content)

response = client.face_detection(image=image)
faces = response.face_annotations

# Names of likelihood from google.cloud.vision.enums
likelihood_name = (
    "UNKNOWN",
    "VERY_UNLIKELY",
    "UNLIKELY",
    "POSSIBLE",
    "LIKELY",
    "VERY_LIKELY",
)
print("Faces:")

for face in faces:
    print(f"anger: {likelihood_name[face.anger_likelihood]}")
    print(f"joy: {likelihood_name[face.joy_likelihood]}")
    print(f"surprise: {likelihood_name[face.surprise_likelihood]}")

    vertices = [
        f"({vertex.x},{vertex.y})" for vertex in face.bounding_poly.vertices
    ]

    print("face bounds: {}".format(",".join(vertices)))

if response.error.message:
    raise Exception(
        "{}\nFor more info on error messages, check: "
        "https://cloud.google.com/apis/design/errors".format(response.error.message)
    )

Making a label detection request and processing the response

Previous versions of the client libraries::

with io.open(file_name, 'rb') as image_file:
    content = image_file.read()

image = old_client.image(content=content)

labels = image.detect_labels()

for label in labels:
    print(label.description)

Python Client Library v0.25.1:

with open(path, "rb") as image_file:
    content = image_file.read()

image = vision.Image(content=content)

response = client.label_detection(image=image)
labels = response.label_annotations
print("Labels:")

for label in labels:
    print(label.description)

if response.error.message:
    raise Exception(
        "{}\nFor more info on error messages, check: "
        "https://cloud.google.com/apis/design/errors".format(response.error.message)
    )

Making a landmark detection request and processing the response

Previous versions of the client libraries::

Landmark locations' latitude and longitude are now stored in location.lat_lng.latitude and location.lat_lng.longitude, as opposed to location.latitude and location.longitude.

with io.open(file_name, 'rb') as image_file:
    content = image_file.read()

image = old_client.image(content=content)

landmarks = image.detect_landmarks