Google API Client Library for Python

Code samples and snippets are located in the samples/ directory. Each folder containing example code requires its own noxfile.py script. To test a specific sample folder:

1. Navigate to the sample directory (e.g., samples/snippets).
2. Run the appropriate nox session (e.g., py-3.8).

Note: Sample tests run against a real Google Cloud Project and require authentication configuration similar to System Tests.

# Run all tests in a folder
$ cd samples/snippets
$ nox -s py-3.8

# Run a single sample test
$ cd samples/snippets
$ nox -s py-3.8 -- -k <name of test>

It is recommended to install this library within a virtualenv to avoid dependency conflicts and permission issues. Follow the steps for your operating system below.

### Mac/Linux
```bash
pip3 install virtualenv
virtualenv <your-env>
source <your-env>/bin/activate
<your-env>/bin/pip install google-api-python-client

Windows

pip install virtualenv
virtualenv <your-env>
<your-env>\Scripts\activate
<your-env>\Scripts\pip.exe install google-api-python-client

The project uses nox to instrument and run tests. You can run unit tests, system tests, or coverage checks using specific session names.

Unit Tests

• Run all unit tests: nox -s unit
• Run a single unit test: nox -s unit-<python_version> -- -k <test_name> (e.g., nox -s unit-3.14 -- -k my_test_function)

System Tests Note: System tests are only configured to run under Python 3.8. They require local authentication (e.g., via gcloud) or a service account.

• Run all system tests: nox -s system
• Run a single system test: nox -s system-3.8 -- -k <test_name>

Coverage and Documentation

• Check test statement coverage: nox -s cover (100% coverage is required)
• Build HTML documentation: nox -s docs

After obtaining credentials from the OAuth flow, use the build function to create a service object, then execute API requests through that object.

from googleapiclient.discovery import build

# 1. Build the service object
drive_service = build('drive', 'v3', credentials=credentials)

# 2. Make requests
files = drive_service.files().list().execute()

Use OAuth 2.0 for calls accessing private user data. This requires the user to grant your application access via specific Scopes.

Key concepts:

• Scopes: Declare the set of operations permitted (e.g., read-only vs. read-write).
• Tokens: The authorization server provides access tokens (used to authorize calls) and refresh tokens (used to acquire new access tokens when they expire).
• Client ID and Client Secret: Unique identifiers for your application created in the Google Cloud API Access pane. Common types include Web application, Installed application, and Service Account client IDs.

Warning: Keep refresh tokens, access tokens, and client secrets private.

Once you have a credentials object, follow these steps to call an API:

1. Build the service object: Use googleapiclient.discovery.build() with the API name, version, and your credentials.
2. Execute requests: Use the methods provided by the service object and call .execute() on the request object.

import googleapiclient.discovery

# 1. Build the service
sqladmin = googleapiclient.discovery.build('sqladmin', 'v1beta3', credentials=credentials)

# 2. Make the request
response = sqladmin.instances().list(project='example-123').execute()

To use service accounts and the Google API Client Library for Python, install the following dependencies:

pip install google-auth google-auth-httplib2 google-api-python-client

The execute() method returns a Python object built from the JSON response sent by the API server. You can access data using standard dictionary/list indexing.

To handle errors, catch HttpError to access the status code and error details.