Registry / gcp / aiogoogle

aiogoogle

JSON →
library5.17.0pypypi✓ verified 52d ago

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.

gcphttp-networkingauth-security
pip install aiogoogle
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
musl
py 3.103.925 runs
installs and imports cleanly · install 0.0s · import 1.062s · 50.1MB
glibc
py 3.103.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())
Debug
Known issues
breakingIn `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.
affects: >=5.16.0
gotchaCalling `.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.
affects: all
gotchaAuthentication 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.
affects: all
deprecatedPrevious 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.
affects: <5.13.1
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'aiogoogle'
This error occurs when the 'aiogoogle' package is not installed in your Python environment.
fix
Install 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.
fix
Use 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.
fix
Ensure 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'.
fix
Verify 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.
fix
Ensure that the event loop is running when executing asynchronous functions, and avoid closing it prematurely.
Upgrade
Version history
5.17.0latest on PyPI
Audit
Dependencies
aiohttprequiredCore HTTP client for asynchronous requests.
Agent activity
91 hits · last 30 days
node
18
claudebot
4
seranking-bot
4
ahrefsbot
3
petalbot
2
amazonbot
1
Resources