docs: Add docs folder with guides from developers.google.com

Author: grant

README.md

@@ -8,30 +8,38 @@ This is the Python client library for Google's discovery based APIs. To get star
 
 These client libraries are officially supported by Google.  However, the libraries are considered complete and are in maintenance mode. This means that we will address critical bugs and security issues but will not add any new features.
 
+## Documentation
+
+See the [docs folder](docs/README.md) for more detailed instructions and additional documentation.
+
 ## Google Cloud Platform
 
 For Google Cloud Platform APIs such as Datastore, Cloud Storage or Pub/Sub, we recommend using [Cloud Client Libraries for Python](https://github.com/GoogleCloudPlatform/google-cloud-python) which is under active development.
 
-# Installation
+## Installation
+
 To install, simply use `pip` or `easy_install`:
 
 ```bash
-$ pip install --upgrade google-api-python-client
+pip install --upgrade google-api-python-client
 ```
+
 or
+
 ```bash
-$ easy_install --upgrade google-api-python-client
+easy_install --upgrade google-api-python-client
 ```
 
-See the [Developers Guide](https://developers.google.com/api-client-library/python/start/get_started) for more detailed instructions and additional documentation.
+## Supported Python Versions
 
-# Supported Python Versions
 Python 3.4, 3.5, 3.6 and 3.7 are fully supported and tested. This library may work on later versions of 3, but we do not currently run tests against those versions
 
-# Deprecated Python Versions
+## Deprecated Python Versions
+
 Python == 2.7
 
-# Third Party Libraries and Dependencies
+## 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)
@@ -41,5 +49,6 @@ For development you will also need the following libraries:
 * [pycrypto](https://pypi.python.org/pypi/pycrypto)
 * [pyopenssl](https://pypi.python.org/pypi/pyOpenSSL)
 
-# Contributing
+## Contributing
+
 Please see the [contributing page](http://google.github.io/google-api-python-client/contributing.html) for more information. In particular, we love pull requests - but please make sure to sign the contributor license agreement.

docs/README.md

@@ -0,0 +1,35 @@
+# Google API Client LIbrary for Python Docs
+
+ The Google API Client Library for Python is designed for Python
+client-application developers. It offers simple, flexible
+access to many Google APIs.
+
+## Features
+
+- Call Google APIs simply
+- Use the library with Google App Engine
+- Handle Auath with fewer lines of code
+- Use standard tooling for installation
+
+## Documentation
+
+Learn how to use the Google API Python Client with these guides:
+
+- [Getting Started](start.md)
+- [Auth](auth.md)
+  - [API Keys](api-keys.md)
+  - [OAuth 2.0](oauth.md)
+  - [OAuth 2.0 for Web Server Applications](oauth-web.md)
+  - [OAuth 2.0 for Installed Applications](oauth-installed.md)
+  - [OAuth 2.0 for Server to Server Applications](oauth-server.md)
+  - [Client Secrets](client-secrets.md)
+- How to...
+  - [Use Logging](logging.md)
+  - [Upload Media](media.md)
+  - [Use Mocks](mocks.md)
+  - [Use Pagination](pagination.md)
+  - [Improve Performance](performance.md)
+  - [Understand Thread Safety](thread_safety.md)
+  - [Use Google App Engine](google_app_engine.md)
+  - [Use Django](django.md)
+  

docs/api-keys.md

@@ -0,0 +1,15 @@
+# API Keys
+
+When calling APIs that do not access private user data, you can use simple API keys. These keys are used to authenticate your application for accounting purposes. The Google Developers Console documentation also describes [API keys](https://developers.google.com/console/help/using-keys).
+
+> Note: If you do need to access private user data, you must use OAuth 2.0. See [Using OAuth 2.0 for Web Server Applications](oauth-server.md) and [Using OAuth 2.0 for Server to Server Applications](oauth-web.md) for more information.
+
+## Using API Keys
+
+To use API keys, pass them to the `build()` function when creating service objects. For example:
+
+```py
+books_service = build('books', 'v1', developerKey='api_key')
+```
+
+All calls made using that service object will include your API key.

docs/auth.md

@@ -0,0 +1,41 @@
+# Authentication Overview
+
+This document is an overview of how authentication, authorization, and accounting are accomplished. For all API calls, your application needs to be authenticated. When an API accesses a user's private data, your application must also be authorized by the user to access the data. For example, accessing a public Google+ post would not require user authorization, but accessing a user's private calendar would. Also, for quota and billing purposes, all API calls involve accounting. This document summarizes the protocols used by Google APIs and provides links to more information.
+
+## Access types
+
+It is important to understand the basics of how API authentication and authorization are handled. All API calls must use either simple or authorized access (defined below). Many API methods require authorized access, but some can use either. Some API methods that can use either behave differently, depending on whether you use simple or authorized access. See the API's method documentation to determine the appropriate access type.
+
+### 1. Simple API access (API keys)
+
+These API calls do not access any private user data. Your application must authenticate itself as an application belonging to your Google API Console project. This is needed to measure project usage for accounting purposes.
+
+**API key:** To authenticate your application, use an [API key](api-keys.md) for your API Console project. Every simple access call your application makes must include this key.
+
+> **Warning:** Keep your API key private. If someone obtains your key, they could use it to consume your quota or incur charges against your API Console project.
+
+### 2. Authorized API access (OAuth 2.0)
+
+These API calls access private user data. Before you can call them, the user that has access to the private data must grant your application access. Therefore, your application must be authenticated, the user must grant access for your application, and the user must be authenticated in order to grant that access. All of this is accomplished with OAuth 2.0 and libraries written for it.
+
+**Scope:** Each API defines one or more scopes that declare a set of operations permitted. For example, an API might have read-only and read-write scopes. When your application requests access to user data, the request must include one or more scopes. The user needs to approve the scope of access your application is requesting.
+
+**Refresh and access tokens:** When a user grants your application access, the OAuth 2.0 authorization server provides your application with refresh and access tokens. These tokens are only valid for the scope requested. Your application uses access tokens to authorize API calls. Access tokens expire, but refresh tokens do not. Your application can use a refresh token to acquire a new access token.
+
+> **Warning:** Keep refresh and access tokens private. If someone obtains your tokens, they could use them to access private user data.
+
+**Client ID and client secret:** These strings uniquely identify your application and are used to acquire tokens. They are created for your project on the [API Console](https://console.developers.google.com/). There are three types of client IDs, so be sure to get the correct type for your application:
+
+- [Web application](https://developers.google.com/accounts/docs/OAuth2WebServer) client IDs
+- [Installed application](https://developers.google.com/accounts/docs/OAuth2InstalledApp) client IDs
+- [Service Account](https://developers.google.com/accounts/docs/OAuth2ServiceAccount) client IDs
+
+> **Warning:** Keep your client secret private. If someone obtains your client secret, they could use it to consume your quota, incur charges against your Console project, and request access to user data.
+
+## Using API keys
+
+More information and examples for API keys are provided on the [API Keys](api-keys.md) page.
+
+## Using OAuth 2.0
+
+More information and examples for OAuth 2.0 are provided on the [OAuth 2.0](oauth.md) page.

docs/client-secrets.md

@@ -0,0 +1,80 @@
+# Client Secrets
+
+The Google APIs Client Library for Python uses the `client_secrets.json` file format for storing the `client_id`, `client_secret`, and other OAuth 2.0 parameters.
+
+The `client_secrets.json` file format is a [JSON](http://www.json.org/) formatted file containing the client ID, client secret, and other OAuth 2.0 parameters. Here is an example client_secrets.json file for a web application:
+
+```json
+{
+  "web": {
+    "client_id": "asdfjasdljfasdkjf",
+    "client_secret": "1912308409123890",
+    "redirect_uris": ["https://www.example.com/oauth2callback"],
+    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+    "token_uri": "https://accounts.google.com/o/oauth2/token"
+  }
+}
+```
+
+Here is an example client_secrets.json file for an installed application:
+
+```json
+{
+  "installed": {
+    "client_id": "837647042410-75ifg...usercontent.com",
+    "client_secret":"asdlkfjaskd",
+    "redirect_uris": ["http://localhost", "urn:ietf:wg:oauth:2.0:oob"],
+    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+    "token_uri": "https://accounts.google.com/o/oauth2/token"
+  }
+}
+```
+
+The format defines one of two client ID types:
+
+- `web`: Web application.
+- `installed`: Installed application.
+
+The `web` and `installed` sub-objects have the following mandatory members:
+
+- `client_id` (string): The client ID.
+- `client_secret` (string): The client secret.
+- `redirect_uris` (list of strings): A list of valid redirection endpoint URIs. This list should match the list entered for the client ID on the [API Access pane](https://code.google.com/apis/console#:access) of the Google APIs Console.
+- `auth_uri` (string): The authorization server endpoint URI.
+- `token_uri` (string): The token server endpoint URI.
+
+All of the above members are mandatory. The following optional parameters may appear:
+
+- `client_email` (string) The service account email associated with the client.
+- `auth_provider_x509_cert_url` (string) The URL of the public x509 certificate, used to verify the signature on JWTs, such as ID tokens, signed by the authentication provider.
+- `client_x509_cert_url` (string) The URL of the public x509 certificate, used to verify JWTs signed by the client.
+
+The following examples show how use a `client_secrets.json` file to create a `Flow` object in either an installed application or a web application:
+
+### Installed App
+
+```py
+from google_auth_oauthlib.flow import InstalledAppFlow
+...
+flow = InstalledAppFlow.from_client_secrets_file(
+    'path_to_directory/client_secret.json',
+    scopes=['https://www.googleapis.com/auth/calendar'])
+```
+
+### Web Server App
+
+```py
+import google.oauth2.credentials
+import google_auth_oauthlib.flow
+
+flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
+    'path_to_directory/client_secret.json',
+    scopes=['https://www.googleapis.com/auth/calendar'])
+
+flow.redirect_uri = 'https://www.example.com/oauth2callback'
+```
+
+## Motivation
+
+Traditionally providers of OAuth endpoints have relied upon cut-and-paste as the way users of their service move the client id and secret from a registration page into working code. That can be error prone, along with it being an incomplete picture of all the information that is needed to get OAuth 2.0 working, which requires knowing all the endpoints and configuring a Redirect Endpoint. If service providers start providing a downloadable client_secrets.json file for client information and client libraries start consuming client_secrets.json then a large amount of friction in implementing OAuth 2.0 can be reduced.
+

docs/django.md

@@ -0,0 +1,47 @@
+# Using Django
+
+The Google APIs Client Library for Python has special support for the [Django](https://www.djangoproject.com/) web framework. In particular, there are classes that simplify the OAuth 2.0 protocol steps. This document describes the Django-specific classes available for working with [Flow](https://developers.google.com/api-client-library/python/guide/aaa_oauth#flows), [Credentials](https://developers.google.com/api-client-library/python/guide/aaa_oauth#credentials), and [Storage](https://developers.google.com/api-client-library/python/guide/aaa_oauth#storage) objects.
+
+## Flows
+
+Use the [oauth2client.contrib.django\_orm.FlowField](https://oauth2client.readthedocs.io/en/latest/source/oauth2client.contrib.django_orm.html#oauth2client.contrib.django_orm.FlowField) class as a Django model field so that `Flow` objects can easily be stored. When your application is simultaneously going through OAuth 2.0 steps for many users, it's normally best to store per-user `Flow` objects before the first redirection. This way, your redirection handlers can retrieve the `Flow` object already created for the user. In the following code, a model is defined that allows `Flow` objects to be stored and keyed by `User`:
+
+```py
+from django.contrib.auth.models import User
+from django.db import models
+from oauth2client.contrib.django_orm import FlowField
+...
+class FlowModel(models.Model):
+  id = models.ForeignKey(User, primary_key=True)
+  flow = FlowField()
+```
+
+## Credentials
+
+Use the [oauth2client.contrib.django\_orm.CredentialsField](https://oauth2client.readthedocs.io/en/latest/source/oauth2client.contrib.django_orm.html#oauth2client.contrib.django_orm.CredentialsField) class as a Django model field so that `Credentials` objects can easily be stored. Similar to `Flow` objects, it's normally best to store per-user `Credentials` objects. In the following code, a model is defined that allows `Credentials` objects to be stored and keyed by `User`:
+
+```py
+from django.contrib.auth.models import User
+from django.db import models
+from oauth2client.contrib.django_orm import CredentialsField
+...
+class CredentialsModel(models.Model):
+  id = models.ForeignKey(User, primary_key=True)
+  credential = CredentialsField()
+```
+
+## Storage
+
+Use the [oauth2client.contrib.django\_orm.Storage](https://oauth2client.readthedocs.io/en/latest/source/oauth2client.contrib.django_orm.html#oauth2client.contrib.django_orm.Storage) class to store and retrieve `Credentials` objects using a model defined with a `CredentialsField` object. You pass the model, field name for the model key, value for the model key, and field name to the `CredentialsField` constructor. The following shows how to create, read, and write `Credentials` objects using the example `CredentialsModel` class above:
+
+```py
+from django.contrib.auth.models import User
+from oauth2client.contrib.django_orm import Storage
+from your_project.your_app.models import CredentialsModel
+...
+user = # A User object usually obtained from request.
+storage = Storage(CredentialsModel, 'id', user, 'credential')
+credential = storage.get()
+...
+storage.put(credential)
+```