Skip to content
Permalink
Browse files
docs: add recommendation to use v2.x and static discovery artifacts (#…
  • Loading branch information
parthea committed Jul 12, 2021
1 parent 88096a5 commit ca7328cb5340ea282a3d98782926a0b6881a33ed
Showing with 33 additions and 23 deletions.
  1. +16 −4 README.md
  2. +17 −19 UPGRADING.md
@@ -16,10 +16,22 @@ where possible, for new code development. For more information, please visit
[Client Libraries Explained](https://cloud.google.com/apis/docs/client-libraries-explained).

## Version 2.0 Release
The 2.0 release of `google-api-python-client` is a significant upgrade compared
to v1. Please see the [Migration Guide](https://github.com/googleapis/google-api-python-client/blob/master/UPGRADING.md) for more information.
As a result of caching the discovery documents, the size of this package is at
least 50 MB larger compared to the previous version.
The 2.0 release of `google-api-python-client` includes a substantial reliability
improvement, compared with 1.x, as discovery documents are now cached in the library
rather than fetched dynamically. It is highly recommended to upgrade from v1.x to v2.x.

Only python 3.6 and newer is supported. If you are not able to upgrade python, then
please continue to use version 1.x as we will continue supporting python 2.7+ in
[v1](https://github.com/googleapis/google-api-python-client/tree/v1).

Discovery documents will no longer be retrieved dynamically when
you call `discovery.build()`. The discovery documents will instead be retrieved
from the client library directly. New versions of this library are released weekly.
As a result of caching the discovery documents, the size of this package is at least
50 MB larger compared to the previous version.

Please see the [Migration Guide](https://github.com/googleapis/google-api-python-client/blob/master/UPGRADING.md)
for more information.

## Documentation

@@ -1,35 +1,34 @@
# 2.0.0 Migration Guide

The 2.0 release of `google-api-python-client` is a significant upgrade as only
python 3.6 and newer is supported. If you are not able to upgrade python, then
The 2.0 release of `google-api-python-client` includes a substantial reliability
improvement, compared with 1.x, as discovery documents are now cached in the library
rather than fetched dynamically. It is highly recommended to upgrade from v1.x to v2.x.

Only python 3.6 and newer is supported. If you are not able to upgrade python, then
please continue to use version 1.x as we will continue supporting python 2.7+ in
[v1](https://github.com/googleapis/google-api-python-client/tree/v1).

In addition, discovery documents will no longer be retrieved dynamically when
Discovery documents will no longer be retrieved dynamically when
you call `discovery.build()`. The discovery documents will instead be retrieved
from the client library directly. As a result of caching the discovery
documents, the size of this package is at least 50 MB larger compared to the
previous version.
from the client library directly. New versions of this library are released weekly.
As a result of caching the discovery documents, the size of this package is at least
50 MB larger compared to the previous version.


For users of public APIs
------------------------
Existing code written for earlier versions of this library will not require
updating. We believe this new default behaviour will provide a more predictable
experience for users. If always using the latest version of a service definition
is more important than reliability, users should set the `static_discovery`
argument of `discovery.build()` to `False` to retrieve the service definition
from the internet.
updating.

For users of private APIs
-------------------------
If the discovery document requires an authentication key to access it, the
If the discovery document requires an authentication key to access it then the
discovery document is private and it will not be shipped with the library.
Only discovery documents listed in [this public directory](https://www.googleapis.com/discovery/v1/apis/)
are included in the library. Users of private APIs should set the
`static_discovery` argument of `discovery.build()` to `False` to continue to
retrieve the service definition from the internet. As of version 2.1.0,
for backwards compatability with version 1.x, if `static_discovery` is not
for backwards compatibility with version 1.x, if `static_discovery` is not
specified, the default value for `static_discovery` will be `True` when
the `discoveryServiceUrl` argument of `discovery.build()` is provided.

@@ -45,13 +44,12 @@ to use version 2.0.0.
## Method Calls

**Note**: Existing code written for earlier versions of this library will not
require updating. You should only update your code if always using the latest
version of a service definition is more important than reliability or if you
are using an API which does not have a public discovery document.
require updating. You should only update your code if you are using an API
which does not have a public discovery document.

> **WARNING**: Breaking change
The 2.0.0 release no longer retrieves discovery documents dynamically on each
The 2.0 release no longer retrieves discovery documents dynamically on each
call to `discovery.build()`. Instead, discovery documents are retrieved from
the client library itself.

@@ -78,7 +76,7 @@ from googleapiclient.discovery import build
with build('drive', 'v3') as service:
# ...
# Retrieve discovery artifacts from the internet
with build('drive', 'v3', static_discovery=False) as service:
# Retrieve discovery artifacts from the internet for a private API
with build('drive', 'v3', static_discovery=False, developerKey=XXXXX) as service:
# ...
```

0 comments on commit ca7328c

Please sign in to comment.