fix: add method to close httplib2 connections (#1038)
Fixes #618 🦕
httplib2 leaves sockets open by default. This can lead to situations where programs run out of available sockets. httplib2 added a method last year to clean up connections. https://github.com/httplib2/httplib2/blob/9bf300cdc372938f4237150d5b9b615879eb51a1/python3/httplib2/__init__.py#L1498-L1506
This PR adds two ways to close http connections. The interface is intentionally similar to the proposed design for GAPIC clients. googleapis/gapic-generator-python#575
diff --git a/docs/start.md b/docs/start.md
index 2db95fa..ceac5dd 100644
--- a/docs/start.md
+++ b/docs/start.md
@@ -45,12 +45,24 @@
### Build the service object
-Whether you are using simple or authorized API access, you use the [build()](http://googleapis.github.io/google-api-python-client/docs/epy/googleapiclient.discovery-module.html#build) function to create a service object. It takes an API name and API version as arguments. You can see the list of all API versions on the [Supported APIs](dyn/index.md) page. The service object is constructed with methods specific to the given API. To create it, do the following:
+Whether you are using simple or authorized API access, you use the [build()](http://googleapis.github.io/google-api-python-client/docs/epy/googleapiclient.discovery-module.html#build) function to create a service object. It takes an API name and API version as arguments. You can see the list of all API versions on the [Supported APIs](dyn/index.md) page. The service object is constructed with methods specific to the given API.
+
+`httplib2`, the underlying transport library, makes all connections persistent by default. Use the service object with a context manager or call `close` to avoid leaving sockets open.
```python
from googleapiclient.discovery import build
-service = build('api_name', 'api_version', ...)
+
+service = build('drive', 'v3')
+# ...
+service.close()
+```
+
+```python
+from googleapiclient.discovery import build
+
+with build('drive', 'v3') as service:
+ # ...
```
### Collections