1# 2.0.0 Migration Guide
2
3The 2.0 release of `google-api-python-client` includes a substantial reliability
4improvement, compared with 1.x, as discovery documents are now cached in the library
5rather than fetched dynamically. It is highly recommended to upgrade from v1.x to v2.x.
6
7Only python 3.6 and newer is supported. If you are not able to upgrade python, then
8please continue to use version 1.x as we will continue supporting python 2.7+ in
9[v1](https://github.com/googleapis/google-api-python-client/tree/v1).
10
11Discovery documents will no longer be retrieved dynamically when
12you call  `discovery.build()`. The discovery documents will instead be retrieved
13from the client library directly. New versions of this library are released weekly.
14As a result of caching the discovery documents, the size of this package is at least
1550 MB larger compared to the previous version.
16
17
18For users of public APIs
19------------------------
20Existing code written for earlier versions of this library will not require
21updating.
22
23For users of private APIs
24-------------------------
25If the discovery document requires an authentication key to access it then the
26discovery document is private and it will not be shipped with the library.
27Only discovery documents listed in [this public directory](https://www.googleapis.com/discovery/v1/apis/)
28are included in the library. Users of private APIs should set the
29`static_discovery` argument of `discovery.build()` to `False` to continue to
30retrieve the service definition from the internet. As of version 2.1.0,
31for backwards compatibility with version 1.x, if `static_discovery` is not
32specified, the default value for `static_discovery` will be `True` when
33the `discoveryServiceUrl` argument of `discovery.build()` is provided.
34
35If you experience issues or have questions, please file an [issue](https://github.com/googleapis/google-api-python-client/issues).
36
37## Supported Python Versions
38
39> **WARNING**: Breaking change
40
41The 2.0.0 release requires Python 3.6+, as such you must upgrade to Python 3.6+
42to use version 2.0.0.
43
44## Method Calls
45
46**Note**: Existing code written for earlier versions of this library will not
47require updating. You should only update your code if you are using an API
48which does not have a public discovery document.
49
50> **WARNING**: Breaking change
51
52The 2.0 release no longer retrieves discovery documents dynamically on each
53call to `discovery.build()`. Instead, discovery documents are retrieved from
54the client library itself.
55
56Under the hood, the `discovery.build()` function retrieves a discovery artifact
57in order to construct the service object. The breaking change is that the
58`discovery.build()` function will no longer retrieve discovery artifacts
59dynamically. Instead it will use service definitions shipped in the library.
60
61
62**Before:**
63```py
64from googleapiclient.discovery import build
65
66# Retrieve discovery artifacts from the internet
67with build('drive', 'v3') as service:
68    # ...
69```
70
71**After:**
72```py
73from googleapiclient.discovery import build
74
75# Retrieve discovery artifacts from the client library
76with build('drive', 'v3') as service:
77    # ...
78
79# Retrieve discovery artifacts from the internet for a private API
80with build('drive', 'v3', static_discovery=False, developerKey=XXXXX) as service:
81    # ...
82```
83