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.
Install & Compatibility
Where this runs
tested against v5.17.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.925 runs
installs and imports cleanly · install 0.0s · import 1.062s · 50.1MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 6.3s · import 0.956s · 52MB
50MB installed
● package 50MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Aiogoogle
✓ from aiogoogle import Aiogoogle
UserCreds
✓ from aiogoogle.auth.oauth2 import UserCreds
✗ from aiogoogle.auth.utils import create_user_creds
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
✗ from aiogoogle.auth.utils import create_service_account_creds
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
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())
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'aiogoogle'
This error occurs when the 'aiogoogle' package is not installed in your Python environment.
fixInstall the 'aiogoogle' package using pip: 'pip install aiogoogle'.
ImportError: cannot import name 'Aiogoogle' from 'aiogoogle'
This error occurs when attempting to import 'Aiogoogle' directly from the 'aiogoogle' package, which is incorrect.
fixUse the correct import statement: 'from aiogoogle import Aiogoogle'.
AttributeError: module 'aiogoogle' has no attribute 'discover'
This error occurs when trying to call a non-existent 'discover' attribute on the 'aiogoogle' module.
fixEnsure you are using the 'Aiogoogle' class correctly: 'async with Aiogoogle(...) as aiogoogle: service = await aiogoogle.discover("calendar", "v3")'. TypeError: 'NoneType' object is not callable
This error occurs when attempting to call a method on a 'None' object, possibly due to incorrect initialization of 'Aiogoogle'.
fixVerify that 'Aiogoogle' is properly initialized with the required credentials before making API calls.
RuntimeError: Event loop is closed
This error occurs when attempting to run asynchronous code after the event loop has been closed.
fixEnsure that the event loop is running when executing asynchronous functions, and avoid closing it prematurely.
Audit
Dependencies
aiohttprequiredCore HTTP client for asynchronous requests.