aiogoogle

5.17.0 · active · verified Sat Apr 11

aiogoogle is an asynchronous Google API client for Python, leveraging `aiohttp` for non-blocking I/O. It simplifies interaction with various Google services using service accounts, user credentials, and API keys. The current version is 5.17.0, and it maintains an active release cadence with frequent bug fixes and feature enhancements.

Warnings

breaking In `v5.16.0`, `aiogoogle` changed its internal `aiohttp` dependency from inheritance to composition. If your code subclassed `Aiogoogle` or other core components and relied on directly inherited `aiohttp` methods or attributes, this change will break your implementation.
Fix: Refactor your code to use `aiogoogle`'s public API or `aiohttp` directly via `Aiogoogle.session` if specific `aiohttp` functionality is needed, rather than relying on inherited methods. Review the `v5.16.0` release notes for details on the change.
gotcha Calling `.discover()` with an incorrect API name or version (e.g., 'drive', 'v4' if 'v3' is the latest) can result in a 404 HTTP error. While `v5.13.0` added suggestions, it's a common initial stumbling block.
Fix: Always verify the correct API name and version from Google's API discovery documentation. Use `aiogoogle.discover('api_name', 'latest')` to automatically get the latest stable version if available, or check specific version strings in Google's API explorer.
gotcha Authentication setup is frequently a source of errors. Mismatching scopes for credentials, incorrect service account key paths, or improperly configured OAuth 2.0 user flows can lead to authentication failures or 'Permission Denied' errors.
Fix: Carefully review the required scopes for the Google API you are using and ensure your `ServiceAccountCreds` or `UserCreds` are configured with these scopes. For service accounts, double-check the JSON key file path. For user creds, ensure the OAuth 2.0 flow completes successfully and tokens are refreshed.
deprecated Previous versions of `aiogoogle` might have issued `aiohttp` deprecation warnings directly related to `aiohttp`'s own internal changes. While `aiogoogle` has addressed many of these in `v5.13.1` and `v5.13.2`, older library versions might still surface these.
Fix: Upgrade `aiogoogle` to the latest version (`v5.13.2` or newer) to benefit from the fixes that removed these warnings and ensure compatibility with newer `aiohttp` versions.

Install

pip install aiogoogle Install aiogoogle

Imports

Aiogoogle
```
from aiogoogle import Aiogoogle
```
UserCreds
```
from aiogoogle.auth.oauth2 import UserCreds
```
While `create_user_creds` exists, `UserCreds` from `oauth2` is the direct credential object for advanced use or direct instantiation.
ServiceAccountCreds
```
from aiogoogle.auth.service_account import ServiceAccountCreds
```
Similar to `UserCreds`, `ServiceAccountCreds` from `service_account` is the direct credential object, often used with a JSON key file path.

GoogleAPIError

from aiogoogle.exceptions import GoogleAPIError

Quickstart

This quickstart demonstrates how to initialize `Aiogoogle` using `ServiceAccountCreds` and discover a Google API (Cloud Resource Manager v3). It highlights the `async with` context manager for proper session management. Replace `path/to/your/service_account_key.json` with your actual service account key path and ensure `GOOGLE_APPLICATION_CREDENTIALS_PATH` environment variable is set for authentication. The project listing is commented out as it requires proper permissions and a valid project.

import asyncio
import os
from aiogoogle import Aiogoogle
from aiogoogle.auth.service_account import ServiceAccountCreds

# For simplicity, using a dummy service account key path
# In a real application, ensure this path is secure and correct.
SERVICE_ACCOUNT_KEY_PATH = os.environ.get('GOOGLE_APPLICATION_CREDENTIALS_PATH', 'path/to/your/service_account_key.json')

async def get_google_services():
    if not os.path.exists(SERVICE_ACCOUNT_KEY_PATH): # Dummy check for quickstart
        print(f"Warning: Service account key not found at {SERVICE_ACCOUNT_KEY_PATH}. "
              "Using dummy credentials which will likely fail authentication.")
        # Create dummy creds to allow Aiogoogle instantiation
        creds = ServiceAccountCreds(scopes=['https://www.googleapis.com/auth/cloud-platform'])
    else:
        creds = ServiceAccountCreds.from_file(SERVICE_ACCOUNT_KEY_PATH,
                                              scopes=['https://www.googleapis.com/auth/cloud-platform'])

    async with Aiogoogle(service_account_creds=creds) as aiogoogle:
        # Discover a Google API, e.g., Cloud Resource Manager API
        try:
            cloudresourcemanager_v3 = await aiogoogle.discover('cloudresourcemanager', 'v3')
            print("Successfully discovered Cloud Resource Manager API v3!")

            # Example: List projects (requires appropriate permissions)
            # This call will likely fail without proper authentication and permissions.
            # try:
            #     projects_req = cloudresourcemanager_v3.projects.list(query='state:ACTIVE')
            #     projects_res = await aiogoogle.as_service_account(projects_req)
            #     print("Projects found:", projects_res)
            # except GoogleAPIError as e:
            #     print(f"Error listing projects: {e.reason}")

        except Exception as e:
            print(f"Failed to discover API or an error occurred: {e}")

if __name__ == '__main__':
    asyncio.run(get_google_services())

view raw JSON →