Google Drive

25 toolsOAuth bearer

gdrive_example.py

from charter.auth import EnvTokenProvider
from charter.packs import gdrive

credentials = EnvTokenProvider("GOOGLE_ACCESS_TOKEN")
gdrive.configure(credentials)

files = await gdrive.files_list.ainvoke(q="trashed = false")

List files, create a folder or a Google Doc, copy, trash or permanently delete, share, comment, and read revisions, shared drives and quota. Search uses Drive’s q grammar. files.delete is permanent — to trash, files.update with trashed=true. This pack sends metadata, not bytes. Media upload is not expressed; files.create makes a folder, a Workspace document, or an empty blob. files.export is the other direction.

Authenticating

This pack takes a Google OAuth bearer token, and configure() is optional when $GOOGLE_ACCESS_TOKEN is set. Which credential provider you hand it depends on whose account the calls run as.

Refer to Google’s provider page for the “GOOGLE” constant the snippets below name, the scopes these 25 tools ask for, and this server’s refresh behaviour.

A token you hold

For a script, or a notebook. EnvTokenProvider re-reads the variable on every call, so a token rotated beside the process is picked up without a restart; StaticTokenProvider takes one you already hold as a string. Neither renews anything, so the calls stop when the token expires.

gdrive_script.py

from charter.auth import EnvTokenProvider
from charter.packs import gdrive

credentials = EnvTokenProvider("GOOGLE_ACCESS_TOKEN")
gdrive.configure(credentials)

One account, refreshed

For an agent or a server acting as you. OAuth2Client turns a client registration and a stored refresh token into an access token, and renews it before it lapses.

gdrive_agent.py

from charter.auth import OAuth2Client
from charter.packs import gdrive

credentials = OAuth2Client(
    GOOGLE,
    client_id=os.environ["GOOGLE_CLIENT_ID"],
    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
)
gdrive.configure(credentials)

No refresh token yet? Your own account is the one-time consent flow that hands you one.

Many end users

For a product whose users each connect their own account. SubjectProvider builds one credential per user through a factory you write, and use_subject names the user a call acts for. Your users’ accounts is the consent route inside your app; serving many users is the per-subject cache and its eviction.

gdrive_server.py

from functools import partial

from charter.auth import OAuth2Client, SubjectProvider, use_subject
from charter.packs import gdrive

# Yours to write: a user id in, that user's credential out.
async def for_user(user_id: str) -> OAuth2Client:
    grant = await db.grants.get(user_id, "google")
    return OAuth2Client(
        GOOGLE,
        client_id=os.environ["GOOGLE_CLIENT_ID"],
        client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
        refresh_token=grant.refresh_token,
        on_refresh=partial(save_to_db, user_id),
    )

credentials = SubjectProvider(for_user)
gdrive.configure(credentials)

# Per request: whose grant the tools use.
with use_subject(request.user_id):
    ...  # your agent runs here

The scope covers every file the account can open. Drive also offers drive.file, which only reaches files this app created; this pack lists and deletes across the drive, so it asks for full drive.

The client

oauth_tool_factory is the whole client: a thin wrapper over httpx that attaches your token and these endpoint constants to each request. google-api-python-client and google-auth do not enter your dependency tree.

from charter import oauth_tool_factory

gdrive_api_client = oauth_tool_factory(
    base_url="https://www.googleapis.com/",
    provider="google",
    credential_provider=credentials,
    scopes=["https://www.googleapis.com/auth/drive"],
    body_format="json",
    query_format="repeat",
    body_case="camel",
    query_case="camel",
    path_case="snake",
    # this API reports failure with an HTTP status code
    envelope=None,
)

from charter.packs import gdrive

gdrive.configure(credentials)

# The base URL, the casing, the envelope and the pagination are
# already declared. 25 tools, ready to hand to a model:
tools = gdrive.TOOLS

credentials is whichever of the three you built in Authenticating. A pack takes it through configure(); a client you build takes the same object as credential_provider, and has no configure() of its own.

Paging through a list

A cursor belongs to the tool that returns it, so it is declared on that tool’s builder call:

gdrive_pagination.py

files_list = gdrive_api_client(
    name="files_list",
    args_schema=FilesListRequest,
    method="GET",
    url_template="drive/v3/files",
    pagination=Pagination(
        cursor_field="nextPageToken",
        cursor_param="pageToken",
    ),
)

Pagination is declared on files_list, permissions_list, comments_list, revisions_list and drives_list. The other 20 take no cursor.

Tools

Each is a Tool, called with ainvoke as in the snippet above. The name links to its parameters, its response and what it costs.

Filesfiles_listGETList the user’s files.files_getGETGet a file’s metadata by ID.files_exportGETExport a Google Workspace document to the requested MIME type and return the exported content.files_createPOSTCreate a file’s metadata: a folder (mimeType application/vnd.google-apps.folder), a Google Doc / Sheet / Slide, or an empty blob.files_updatePATCHChange part of a file’s metadata.files_copyPOSTCreate a copy of a file and apply any requested updates with patch semantics.files_deleteDELETEPermanently delete a file owned by the user without moving it to the trash.files_empty_trashDELETEPermanently delete all of the user’s trashed files.Permissionspermissions_createPOSTCreate a permission for a file or shared drive.permissions_listGETList a file’s or shared drive’s permissions.permissions_getGETGet a permission by ID.permissions_updatePATCHUpdate a permission with patch semantics.permissions_deleteDELETEDelete a permission.Commentscomments_listGETList a file’s comments.comments_createPOSTCreate a comment on a file.comments_updatePATCHUpdate a comment with patch semantics.comments_deleteDELETEDelete a comment.Repliesreplies_createPOSTCreate a reply to a comment.replies_updatePATCHUpdate a reply with patch semantics.replies_deleteDELETEDelete a reply.Revisionsrevisions_listGETList a file’s revisions.revisions_getGETGet a revision’s metadata by ID.Shared drivesdrives_listGETList the user’s shared drives.drives_getGETGet a shared drive’s metadata by ID.Accountabout_getGETGet information about the user, the user’s Drive, and system capabilities.

Every tool declares quota_cost 1. Drive meters queries per 60 seconds per user rather than charging different amounts per call, so a uniform 1 is the honest number; the link in the wire table is where the real limits live.

Gotchas

files.list returns trashed files unless you filter them out

The default list is every file the user can see, including trash. Add trashed = false to q for the view a person sees in Drive. An unfiltered first call looks like a successful search that included files the caller thought were gone.

files.delete is permanent

It does not move the file to the trash. To trash, files.update with trashed set to true. Emptying trash is files_empty_trash, which is also permanent.

Moving a file is addParents and removeParents, not parents

parents on the file body is honoured on create and copy, and ignored on update. Update requests must use the addParents and removeParents query parameters. A file can only have one parent.

comments and about require fields

Drive’s comments and about resources do not return fields unless you name them. comments_list and about_get take a required fields query parameter — for example comments(id,content,author,createdTime,resolved) or user,storageQuota. Omitting it is a 400, not an empty list.

This pack does not upload bytes

files.create posts JSON metadata. Uploading a PDF or an image uses Drive’s /upload URI, which this pack does not declare. Create a Google Doc or Sheet here and write into it with the Docs or Sheets pack.

If driveId is set, corpora must be drive

Searching a shared drive without corpora=drive is a 400. The schema refuses the combination rather than sending it.

Google — consent screen, scopes, refresh
Google Docs — write into a document this pack created
Google Sheets — write into a spreadsheet this pack created

OAuth packs

API-key packs

Authenticating

A token you hold

One account, refreshed

Many end users

The client

Paging through a list

Tools

Gotchas

​Authenticating

​A token you hold

​One account, refreshed

​Many end users

​The client

​Paging through a list

​Tools

​Gotchas

​Related

Authenticating

A token you hold

One account, refreshed

Many end users

The client

Paging through a list

Tools

Gotchas

Related