diff --git a/README.md b/README.md index d531ca1f79..c86eee5499 100644 --- a/README.md +++ b/README.md @@ -10,14 +10,15 @@ This library is considered complete and is in maintenance mode. This means that we will address critical bugs and security issues but will not add any new features. -This library is officially supported by Google. However, the maintainers of +This library is officially supported by Google. However, the maintainers of this repository recommend using [Cloud Client Libraries for Python](https://github.com/googleapis/google-cloud-python), 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` includes a substantial reliability -improvement, compared with 1.x, as discovery documents are now cached in the library + +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.7 and newer is supported. If you are not able to upgrade python, then @@ -27,12 +28,22 @@ please continue to use version 1.x as we will continue supporting python 2.7+ in 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. +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/main/UPGRADING.md) for more information. +### Note on Private APIs + +If you are using a private API (not listed in the [public directory](https://www.googleapis.com/discovery/v1/apis/)), +you must set `static_discovery=False` to fetch the service definition dynamically: + +```python +from googleapiclient.discovery import build +service = build('my_api', 'v1', static_discovery=False, developerKey='YOUR_API_KEY') +``` + ## Documentation See the [docs folder](https://github.com/googleapis/google-api-python-client/blob/main/docs/README.md) for more detailed instructions and additional documentation. @@ -44,15 +55,16 @@ The maintainers of this repository recommend using where possible, for new code development due to the following reasons: With [Cloud Client Libraries for Python](https://github.com/googleapis/google-cloud-python): + - There is a separate client library for each API, so you can choose -which client libraries to download. Whereas, `google-api-python-client` is a -single client library for all APIs. As a result, the total package size for -`google-api-python-client` exceeds 50MB. + which client libraries to download. Whereas, `google-api-python-client` is a + single client library for all APIs. As a result, the total package size for + `google-api-python-client` exceeds 50MB. - There are stricter controls for breaking changes to the underlying APIs -as each client library is focused on a specific API. + as each client library is focused on a specific API. - There are more features in these Cloud Client Libraries as each library is -focused on a specific API, and in some cases, the libraries are owned by team -who specialized in that API. + focused on a specific API, and in some cases, the libraries are owned by team + who specialized in that API. - Developers will benefit from intellisense. For more information, please visit @@ -106,12 +118,14 @@ Python < 3.7 ## Third Party Libraries and Dependencies The following libraries will be installed when you install the client library: -* [httplib2](https://github.com/httplib2/httplib2) -* [uritemplate](https://github.com/sigmavirus24/uritemplate) + +- [httplib2](https://github.com/httplib2/httplib2) +- [uritemplate](https://github.com/sigmavirus24/uritemplate) For development you will also need the following libraries: -* [WebTest](https://pypi.org/project/WebTest/) -* [pyopenssl](https://pypi.python.org/pypi/pyOpenSSL) + +- [WebTest](https://pypi.org/project/WebTest/) +- [pyopenssl](https://pypi.python.org/pypi/pyOpenSSL) ## Contributing diff --git a/UPGRADING.md b/UPGRADING.md index facde263fb..752e81fb59 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -1,7 +1,7 @@ # 2.0.0 Migration Guide -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 +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.7 and newer is supported. If you are not able to upgrade python, then @@ -9,19 +9,18 @@ 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 +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. +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 -For users of public APIs ------------------------- Existing code written for earlier versions of this library will not require -updating. +updating. + +## For users of private APIs -For users of private APIs -------------------------- 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/) @@ -44,7 +43,7 @@ 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 you are using an API +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 @@ -58,8 +57,8 @@ in order to construct the service object. The breaking change is that the `discovery.build()` function will no longer retrieve discovery artifacts dynamically. Instead it will use service definitions shipped in the library. - **Before:** + ```py from googleapiclient.discovery import build @@ -69,6 +68,7 @@ with build('drive', 'v3') as service: ``` **After:** + ```py from googleapiclient.discovery import build @@ -77,6 +77,6 @@ with build('drive', 'v3') as service: # ... # Retrieve discovery artifacts from the internet for a private API -with build('drive', 'v3', static_discovery=False, developerKey=XXXXX) as service: +with build('my_api', 'v1', static_discovery=False, developerKey='YOUR_API_KEY') as service: # ... ```