> ## Documentation Index
> Fetch the complete documentation index at: https://docs.r28.ai/charter/llms.txt
> Use this file to discover all available pages before exploring further.
# Google Drive
> List, create, copy and share files; comment; read revisions, shared drives and quota.
```python gdrive_example.py {7} theme={null}
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()`](/charter/charter/reference/configuration#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](/charter/charter/auth/providers/google) 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`](/charter/charter/reference/credentials#envtokenprovider) re-reads the variable on every call, so a token rotated beside the process is picked up without a restart; [`StaticTokenProvider`](/charter/charter/reference/credentials#statictokenprovider) takes one you already hold as a string. Neither renews anything, so the calls stop when the token expires.
```python gdrive_script.py {4} theme={null}
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`](/charter/charter/reference/oauth#oauth2client) turns a client registration and a stored refresh token into an access token, and [renews it](/charter/charter/auth/authorization-servers#what-the-cache-does-precisely) before it lapses.
```python gdrive_agent.py {8} theme={null}
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](/charter/charter/auth/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`](/charter/charter/reference/credentials#subjectprovider) builds one credential per user through a factory you write, and [`use_subject`](/charter/charter/reference/credentials#use_subject) names the user a call acts for. [Your users' accounts](/charter/charter/auth/oauth-flow) is the consent route inside your app; [serving many users](/charter/charter/auth/authorization-servers#serving-many-users) is the per-subject cache and its eviction.
```python gdrive_server.py {17,21} theme={null}
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`](/charter/charter/reference/factories#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.
```python Without the pack theme={null}
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,
)
```
```python With the pack theme={null}
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](#authenticating). A pack takes it through [`configure()`](/charter/charter/reference/configuration#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:
```python gdrive_pagination.py theme={null}
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`](/charter/charter/reference/tool), called with
[`ainvoke`](/charter/charter/reference/tool#tool-ainvoke) as in the snippet above. The name
links to its parameters, its response and what it costs.
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
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.
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.
`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.
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.
`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.
Searching a shared drive without `corpora=drive` is a 400. The schema
refuses the combination rather than sending it.
## Related
* [Google](/charter/charter/auth/providers/google) — consent screen, scopes, refresh
* [Google Docs](/charter/charter/packs/gdocs) — write into a document this pack created
* [Google Sheets](/charter/charter/packs/gsheets) — write into a spreadsheet this pack created