From ca7328cb5340ea282a3d98782926a0b6881a33ed Mon Sep 17 00:00:00 2001 From: Anthonios Partheniou Date: Mon, 12 Jul 2021 15:50:11 -0400 Subject: [PATCH] docs: add recommendation to use v2.x and static discovery artifacts (#1434) --- README.md | 20 ++++++++++++++++---- UPGRADING.md | 36 +++++++++++++++++------------------- 2 files changed, 33 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index e5c8d36f0d7..334e1ecf31e 100644 --- a/README.md +++ b/README.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 diff --git a/UPGRADING.md b/UPGRADING.md index 9ac0088393c..d1c60a9faff 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -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: # ... ```