Drive¶
Drive ¶
Drive(auth: GoogleAuth)
High-level Google Drive client.
Works with My Drive and shared drives.
Example
auth = GoogleAuth() auth.authenticate()
drive = Drive(auth)
List files¶
for file in drive.list_files(): print(f"{file.name} ({file.mime_type})")
Upload¶
drive.upload("document.pdf")
Download (Google Docs are exported)¶
file = drive.get("file_id") file.download("local_copy.pdf")
Initialize Drive client.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
auth
|
GoogleAuth
|
GoogleAuth instance with valid credentials |
required |
iter_files ¶
iter_files(query: str | None = None, parent_id: str | None = None, mime_type: str | None = None, max_results: int | None = 100, order_by: str = 'modifiedTime desc', trashed: bool | None = False) -> Iterator[File]
Lazily yield files, following result pages.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
query
|
str | None
|
Drive API query string (raw; quote values with drive_query_literal) |
None
|
parent_id
|
str | None
|
Filter by parent folder ID |
None
|
mime_type
|
str | None
|
Filter by MIME type |
None
|
max_results
|
int | None
|
Maximum files to yield (None = all) |
100
|
order_by
|
str
|
Sort order |
'modifiedTime desc'
|
trashed
|
bool | None
|
False excludes trashed files, True lists only trashed files, None includes both |
False
|
list_files ¶
list_files(query: str | None = None, parent_id: str | None = None, mime_type: str | None = None, max_results: int | None = 100, order_by: str = 'modifiedTime desc', trashed: bool | None = False) -> list[File]
List files in Drive.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
query
|
str | None
|
Drive API query string (raw; quote values with drive_query_literal) |
None
|
parent_id
|
str | None
|
Filter by parent folder ID |
None
|
mime_type
|
str | None
|
Filter by MIME type |
None
|
max_results
|
int | None
|
Maximum files to return (None = all) |
100
|
order_by
|
str
|
Sort order |
'modifiedTime desc'
|
trashed
|
bool | None
|
False excludes trashed files, True lists only trashed files, None includes both |
False
|
Returns:
| Type | Description |
|---|---|
list[File]
|
List of File objects |
search ¶
search(name: str, exact: bool = False) -> list[File]
Search files by name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
File name to search |
required |
exact
|
bool
|
Exact match vs contains |
False
|
Returns:
| Type | Description |
|---|---|
list[File]
|
Matching files |
get_content ¶
get_content(file_id: str) -> bytes
Download file content as bytes.
Google Docs/Sheets/Slides have no binary content; use export().
export ¶
export(file_id: str, format: str) -> bytes
Export a Google Doc, Sheet, Slides or Drawing.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file_id
|
str
|
File ID |
required |
format
|
str
|
Short name ("pdf", "docx", "xlsx", "csv", ...; see EXPORT_FORMATS) or a MIME type |
required |
Returns:
| Type | Description |
|---|---|
bytes
|
Exported content. Drive caps exports at 10 MB. |
download ¶
download(file_id: str, path: str, export_format: str | None = None) -> str
Download file to local path.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file_id
|
str
|
File ID |
required |
path
|
str
|
Local path to save |
required |
export_format
|
str | None
|
Export Google files to this format instead of downloading (required for Docs/Sheets/Slides) |
None
|
Returns:
| Type | Description |
|---|---|
str
|
Path where file was saved |
update ¶
update(file_id: str, name: str | None = None, description: str | None = None, starred: bool | None = None) -> File
Update file metadata. Only the arguments you pass are changed.
Returns:
| Type | Description |
|---|---|
File
|
The updated File |
copy ¶
copy(file_id: str, name: str | None = None, parent_id: str | None = None) -> File
Copy a file. Folders can't be copied.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file_id
|
str
|
File to copy |
required |
name
|
str | None
|
Name of the copy (default: Drive's "Copy of ...") |
None
|
parent_id
|
str | None
|
Folder for the copy (default: same as the original) |
None
|
Returns:
| Type | Description |
|---|---|
File
|
The new file |
move ¶
move(file_id: str, parent_id: str) -> File
Move a file into another folder (removing it from its current ones).
Returns:
| Type | Description |
|---|---|
File
|
The moved file |
upload ¶
upload(path: str, name: str | None = None, parent_id: str | None = None, mime_type: str | None = None, on_progress: ProgressCallback | None = None) -> File
Upload a file (resumable, in chunks; each chunk is retried on failure).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str
|
Local file path |
required |
name
|
str | None
|
Name in Drive (default: local filename) |
None
|
parent_id
|
str | None
|
Parent folder ID |
None
|
mime_type
|
str | None
|
MIME type (auto-detected if not provided) |
None
|
on_progress
|
ProgressCallback | None
|
Called with the fraction uploaded (0.0-1.0) |
None
|
Returns:
| Type | Description |
|---|---|
File
|
Created File |
upload_content ¶
upload_content(content: bytes | BinaryIO, name: str, parent_id: str | None = None, mime_type: str = 'application/octet-stream', on_progress: ProgressCallback | None = None) -> File
Upload content directly.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
content
|
bytes | BinaryIO
|
File content as bytes or file-like object |
required |
name
|
str
|
Name in Drive |
required |
parent_id
|
str | None
|
Parent folder ID |
None
|
mime_type
|
str
|
MIME type |
'application/octet-stream'
|
on_progress
|
ProgressCallback | None
|
Called with the fraction uploaded (0.0-1.0) |
None
|
Returns:
| Type | Description |
|---|---|
File
|
Created File |
create_folder ¶
create_folder(name: str, parent_id: str | None = None) -> Folder
Create a folder.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Folder name |
required |
parent_id
|
str | None
|
Parent folder ID |
None
|
Returns:
| Type | Description |
|---|---|
Folder
|
Created Folder |
trash ¶
trash(file_id: str) -> bool
Move file to trash.
Returns:
| Type | Description |
|---|---|
bool
|
True if trashed, False if the file doesn't exist. Other failures |
bool
|
(auth, permissions, rate limit) raise. |
restore ¶
restore(file_id: str) -> bool
Restore a file from the trash.
Returns:
| Type | Description |
|---|---|
bool
|
True if restored, False if the file doesn't exist. Other failures raise. |
delete ¶
delete(file_id: str) -> bool
Permanently delete file. Prefer trash() unless you mean it.
Returns:
| Type | Description |
|---|---|
bool
|
True if deleted, False if the file doesn't exist. Other failures raise. |
list_permissions ¶
list_permissions(file_id: str) -> list[Permission]
List who has access to a file.
add_permission ¶
add_permission(file_id: str, role: str = 'reader', type: str = 'user', email: str | None = None, domain: str | None = None, notify: bool = True) -> Permission
Grant access to a file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file_id
|
str
|
File ID |
required |
role
|
str
|
reader, commenter, writer, ... |
'reader'
|
type
|
str
|
user, group, domain or anyone |
'user'
|
email
|
str | None
|
Required for user and group |
None
|
domain
|
str | None
|
Required for domain |
None
|
notify
|
bool
|
Email the user or group (ignored for domain/anyone) |
True
|
Returns:
| Type | Description |
|---|---|
Permission
|
The created Permission |
share ¶
share(file_id: str, email: str, role: str = 'reader', notify: bool = True) -> bool
Share a file with someone.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file_id
|
str
|
File ID |
required |
email
|
str
|
Email to share with |
required |
role
|
str
|
Permission role (reader, writer, commenter) |
'reader'
|
notify
|
bool
|
Send notification email |
True
|
Returns:
| Type | Description |
|---|---|
bool
|
True if shared, False if the file doesn't exist. Other failures |
bool
|
(invalid role or email, permissions) raise. |
remove_permission ¶
remove_permission(file_id: str, permission_id: str) -> bool
Revoke a permission.
Returns:
| Type | Description |
|---|---|
bool
|
True if removed, False if the file or permission doesn't exist. |
File
dataclass
¶
File(id: str, name: str, mime_type: str, size: int = 0, created_time: datetime | None = None, modified_time: datetime | None = None, parents: list[str] = list(), web_view_link: str | None = None, web_content_link: str | None = None, description: str | None = None, starred: bool = False, trashed: bool = False, md5_checksum: str | None = None, _drive: Optional[Drive] = None)
Google Drive file.
Represents a file in Google Drive with methods for download, update, and management.
download ¶
download(path: str | None = None, export_format: str | None = None) -> str
Download file to local path.
Google Docs, Sheets and Slides can't be downloaded as-is; they are
exported (by default to docx/xlsx/pptx, or export_format).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | None
|
Local path (default: current dir with original name, plus the export extension for Google files) |
None
|
export_format
|
str | None
|
Export format for Google files ("pdf", "docx", ...) |
None
|
Returns:
| Type | Description |
|---|---|
str
|
Path where file was saved |
get_content ¶
get_content() -> bytes
Get file content as bytes.
Returns:
| Type | Description |
|---|---|
bytes
|
File content |
Permission
dataclass
¶
Permission(id: str, type: str, role: str, email_address: str | None = None, domain: str | None = None, display_name: str | None = None)
Who can access a file and how.
type is "user", "group", "domain" or "anyone"; role is "reader", "commenter", "writer", "fileOrganizer", "organizer" or "owner".