Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
2fd671d
Migrate Google Drive authentication to google-auth
shcheklein Nov 19, 2026
47c6eca
Require a fresh OAuth login for PyDrive2 2.x
shcheklein Nov 20, 2026
3a59fe7
Handle concurrent refresh, refresh-only credentials and OAuth scope c…
shcheklein Nov 20, 2026
1608965
Align authentication imports and storage types with the new CI checks
shcheklein Nov 20, 2026
374d1be
Wrap reStructuredText consistently and use native annotations
shcheklein Nov 20, 2026
050745f
Remove redundant credential module docstring
shcheklein Nov 20, 2026
10d072f
Keep user credential persistence in the auth module
shcheklein Nov 20, 2026
04ca8b6
Share credential persistence across file and dictionary logins
shcheklein Nov 20, 2026
5c22a60
Merge main into migrate-google-auth
shcheklein Nov 21, 2026
cea1540
Use a consistent return in credential refresh
shcheklein Nov 21, 2026
d4fae0c
Preserve credential permissions and coordinate OAuth cache refreshes
shcheklein Nov 21, 2026
289b12f
Merge remote-tracking branch 'origin/main' into migrate-google-auth
shcheklein Nov 21, 2026
8fd2074
Skip the Windows Python 3.15 frozen-app test pending #399
shcheklein Nov 21, 2026
baf7e6a
Fix credential cache reads and isolate optional OAuth configuration
shcheklein Nov 21, 2026
47d812a
Verify the compressed cache fixture with the Windows Overlay Filter
shcheklein Nov 21, 2026
57640a6
Let Python manage the credential reader descriptor
shcheklein Nov 21, 2026
ebe80fc
Rebuild authorized Drive transports when switching credentials
shcheklein Nov 21, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 7 additions & 4 deletions CONTRIBUTING.rst
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,14 @@ Contributing code
~~~~~~~~~~~~~~~~~

If you have improvements to PyDrive2, send us your pull requests! For those
just getting started, Github has a `howto <https://help.github.com/articles/using-pull-requests/>`_.
just getting started, Github has a `howto`_.

Install the development tools with ``python -m pip install -e '.[tests,fsspec,typing]'``.
Run ``ruff check .`` to lint Python files and ``ruff format .`` to format them.
Run ``python -m mypy`` to type-check the package for Python 3.11.
Install the development tools with
``python -m pip install -e '.[tests,fsspec,typing]'``. Run ``ruff check .`` to
lint Python files and ``ruff format .`` to format them. Run ``python -m mypy``
to type-check the package for Python 3.11.

.. _howto: https://help.github.com/articles/using-pull-requests/

Live Drive tests for external pull requests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down
45 changes: 27 additions & 18 deletions README.rst
Original file line number Diff line number Diff line change
@@ -1,42 +1,43 @@
|CI| |Conda| |PyPI|

.. |CI| image:: https://github.com/iterative/PyDrive2/workflows/Tests/badge.svg?branch=main
.. |CI| image::
https://github.com/iterative/PyDrive2/workflows/Tests/badge.svg?branch=main
:target: https://github.com/iterative/PyDrive2/actions
:alt: GHA Tests

.. |Conda| image:: https://img.shields.io/conda/v/conda-forge/PyDrive2.svg?label=conda&logo=conda-forge
.. |Conda| image::
https://img.shields.io/conda/v/conda-forge/PyDrive2.svg?label=conda&logo=conda-forge
:target: https://anaconda.org/conda-forge/PyDrive2
:alt: Conda-forge

.. |PyPI| image:: https://img.shields.io/pypi/v/PyDrive2.svg?label=pip&logo=PyPI&logoColor=white
.. |PyPI| image::
https://img.shields.io/pypi/v/PyDrive2.svg?label=pip&logo=PyPI&logoColor=white
:target: https://pypi.org/project/PyDrive2
:alt: PyPI

PyDrive2
--------

*PyDrive2* is a wrapper library of
`google-api-python-client <https://github.com/google/google-api-python-client>`_
that simplifies many common Google Drive API V2 tasks. It is an actively
maintained fork of `https://pypi.python.org/pypi/PyDrive <https://pypi.python.org/pypi/PyDrive>`_.
By the authors and maintainers of the `Git for Data <https://dvc.org>`_ - DVC
project.
*PyDrive2* is a wrapper library of `google-api-python-client`_ that simplifies
many common Google Drive API V2 tasks. It is an actively maintained fork of
https://pypi.python.org/pypi/PyDrive. By the authors and maintainers of the
`Git for Data <https://dvc.org>`_ - DVC project.

Project Info
------------

- Package: `https://pypi.python.org/pypi/PyDrive2 <https://pypi.python.org/pypi/PyDrive2>`_
- Documentation: `https://docs.iterative.ai/PyDrive2 <https://docs.iterative.ai/PyDrive2>`_
- Source: `https://github.com/iterative/PyDrive2 <https://github.com/iterative/PyDrive2>`_
- Changelog: `https://github.com/iterative/PyDrive2/releases <https://github.com/iterative/PyDrive2/releases>`_
- Package: https://pypi.python.org/pypi/PyDrive2
- Documentation: https://docs.iterative.ai/PyDrive2
- Source: https://github.com/iterative/PyDrive2
- Changelog: https://github.com/iterative/PyDrive2/releases
- `Running tests </pydrive2/test/README.rst>`_

Features of PyDrive2
--------------------

- Simplifies OAuth2.0 into just few lines with flexible settings.
- Wraps `Google Drive API V2 <https://developers.google.com/drive/v2/web/about-sdk>`_ into
classes of each resource to make your program more object-oriented.
- Wraps `Google Drive API V2`_ into classes of each resource to make your
program more object-oriented.
- Helps common operations else than API calls, such as content fetching
and pagination control.
- Provides `fsspec`_ filesystem implementation.
Expand Down Expand Up @@ -101,7 +102,8 @@ efficient way.
# Created file hello.png with mimeType image/png

file3 = drive.CreateFile({'id': file2['id']})
print('Downloading file %s from Google Drive' % file3['title']) # 'hello.png'
print('Downloading file %s from Google Drive' % file3['title'])
# 'hello.png'
file3.GetContentFile('world.png') # Save Drive file as a local file

# or download Google Docs files in an export format provided.
Expand All @@ -122,7 +124,9 @@ File listing pagination made easy

# Paginate file lists by specifying number of max results
for file_list in drive.ListFile({'maxResults': 10}):
print('Received {} files from Files.list()'.format(len(file_list))) # <= 10
print(
'Received {} files from Files.list()'.format(len(file_list))
) # <= 10
for file1 in file_list:
print('title: {}, id: {}'.format(file1['title'], file1['id']))

Expand All @@ -142,7 +146,8 @@ Install PyDrive2 with the required dependencies

from pydrive2.fs import GDriveFileSystem

# replace `root` with ID of a drive or directory and give service account access to it
# replace `root` with ID of a drive or directory and give service account
# access to it
fs = GDriveFileSystem("root", client_id=my_id, client_secret=my_secret)

for root, dnames, fnames in fs.walk("root"):
Expand All @@ -164,3 +169,7 @@ Thanks to all our contributors!
:target: https://github.com/iterative/PyDrive2/graphs/contributors

.. _`fsspec`: https://filesystem-spec.readthedocs.io/en/latest/

.. _google-api-python-client:
https://github.com/google/google-api-python-client
.. _Google Drive API V2: https://developers.google.com/drive/v2/web/about-sdk
17 changes: 10 additions & 7 deletions docs/filelist.rst
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
File listing made easy
=============================
======================

PyDrive2 handles pagination and returns
:class:`~pydrive2.files.GoogleDriveFile` instances.
Expand All @@ -22,12 +22,15 @@ v3 examples. PyDrive2 uses v2. When adapting a query, check the

from pydrive2.drive import GoogleDrive

drive = GoogleDrive(gauth) # Create GoogleDrive instance with authenticated GoogleAuth instance
# Create GoogleDrive instance with authenticated GoogleAuth instance
drive = GoogleDrive(gauth)

# Auto-iterate through all files in the root folder.
file_list = drive.ListFile({'q': "'root' in parents and trashed=false"}).GetList()
file_list = drive.ListFile(
{'q': "'root' in parents and trashed=false"}
).GetList()
for file1 in file_list:
print('title: %s, id: %s' % (file1['title'], file1['id']))
print('title: %s, id: %s' % (file1['title'], file1['id']))

You can update the metadata or content of each returned file.

Expand All @@ -42,9 +45,9 @@ contains up to ten files.

# Paginate file lists by specifying number of max results
for file_list in drive.ListFile({'q': 'trashed=true', 'maxResults': 10}):
print('Received %s files from Files.list()' % len(file_list)) # <= 10
for file1 in file_list:
print('title: %s, id: %s' % (file1['title'], file1['id']))
print('Received %s files from Files.list()' % len(file_list)) # <= 10
for file1 in file_list:
print('title: %s, id: %s' % (file1['title'], file1['id']))


.. _files.list query parameters:
Expand Down
42 changes: 25 additions & 17 deletions docs/filemanagement.rst
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
File management made easy
=========================

There are many methods to create and update file metadata and contents.
With *PyDrive*, you don't have to care about any of these different API methods.
There are many methods to create and update file metadata and contents. With
*PyDrive*, you don't have to care about any of these different API methods.
Edit the metadata or contents of a :class:`~pydrive2.files.GoogleDriveFile`
and call :meth:`~pydrive2.files.GoogleDriveFile.Upload` to save the changes.

Expand All @@ -26,11 +26,13 @@ In this example, ``gauth`` is an authenticated
# title: Hello.txt, id: {{FILE_ID}}

:meth:`~pydrive2.drive.GoogleDrive.CreateFile` creates a local file object
with the drive's credentials. Call :meth:`~pydrive2.files.GoogleDriveFile.Upload`
to create ``Hello.txt`` on Google Drive.
with the drive's credentials. Call
:meth:`~pydrive2.files.GoogleDriveFile.Upload` to create ``Hello.txt`` on
Google Drive.

Delete, Trash and un-Trash files
--------------------------------

You may want to delete, trash, or un-trash a file. To do this use ``Delete()``,
``Trash()`` or ``UnTrash()`` on a GoogleDriveFile object.

Expand Down Expand Up @@ -92,7 +94,8 @@ PyDrive gives you access to the metadata of an object through

file1 = drive.CreateFile({'id': '<some file ID here>'})

# Fetches all basic metadata fields, including file size, last modified etc.
# Fetches all basic metadata fields, including file size, last modified
# etc.
file1.FetchMetadata()

# Fetches all metadata available.
Expand All @@ -107,6 +110,7 @@ See the `Drive API v2 file resource`_ for the available fields.

Insert permissions
__________________

Insert, retrieving or deleting permissions is illustrated by making a file
readable to all who have a link to the file.

Expand Down Expand Up @@ -159,9 +163,10 @@ For the more advanced user: ``GetPermissions()`` is a shorthand for:

Remove a Permission
___________________

*PyDrive* allows you to remove a specific permission using the
``DeletePermission(permission_id)`` function. This function allows you to delete
one permission at a time by providing the permission's ID.
``DeletePermission(permission_id)`` function. This function allows you to
delete one permission at a time by providing the permission's ID.

.. code-block:: python

Expand Down Expand Up @@ -194,7 +199,7 @@ field in the query below is ``title``.
files = drive.ListFile(query).GetList()

List revisions
________________
______________

Revisions can be fetched using the ``GetRevisions()`` function of a
``GoogleDriveFile``, and can be used like so:
Expand All @@ -221,7 +226,10 @@ Sample code continues from `Download file metadata from file ID`_:

.. code-block:: python

file4 = drive.CreateFile({'title':'appdata.json', 'mimeType':'application/json'})
file4 = drive.CreateFile({
'title': 'appdata.json',
'mimeType': 'application/json',
})
file4.SetContentString('{"firstname": "John", "lastname": "Smith"}')
file4.Upload() # Upload file.
file4.SetContentString('{"firstname": "Claudio", "lastname": "Afshar"}')
Expand All @@ -247,10 +255,10 @@ like so:
content_string = file4.GetContentString(encoding='ISO-8859-1')

Upload data as bytes in memory buffer
--------------------------------------
-------------------------------------

Data can be kept as bytes in an in-memory buffer when we use the ``io`` module’s
Byte IO operations, we can upload files that reside in memory, for
Data can be kept as bytes in an in-memory buffer when we use the ``io``
module’s Byte IO operations, we can upload files that reside in memory, for
example we have a base64 image, we can decode the string and upload it to drive
without first saving it to disk and calling
:meth:`~pydrive2.files.GoogleDriveFile.SetContentFile`.
Expand Down Expand Up @@ -339,11 +347,11 @@ See the :download:`complete Python example <../examples/strip_bom_example.py>`.
Abusive files
-------------

Files identified as `abusive`_ (malware, etc.) are only downloadable by the owner.
If you see a
'This file has been identified as malware or spam and cannot be downloaded'
error, set 'acknowledge_abuse=True' parameter in `GetContentFile()`. By using
it you indicate that you acknowledge the risks of downloading potential malware.
Files identified as `abusive`_ (malware, etc.) are only downloadable by the
owner. If you see a 'This file has been identified as malware or spam and
cannot be downloaded' error, set 'acknowledge_abuse=True' parameter in
`GetContentFile()`. By using it you indicate that you acknowledge the risks of
downloading potential malware.

.. _Drive API v2 file resource:
https://developers.google.com/workspace/drive/api/reference/rest/v2/files#resource:-file
Expand Down
28 changes: 20 additions & 8 deletions docs/fsspec.rst
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,12 @@ someone else's cached credentials:
profile="myprofile",
)

PyDrive2 2.x uses a separate default cache. The first interactive connection
after upgrading from 1.x prompts you to sign in. If you supplied a user
credential file explicitly, choose a fresh path. For DVC jobs that use
``GDRIVE_CREDENTIALS_DATA`` for a user account, replace that secret with the
newly saved JSON. Service-account jobs can reuse their configured key.

Writing cached credentials to a file and using it if it already exists (which
avoids interactive auth):

Expand Down Expand Up @@ -76,7 +82,8 @@ Using json keyfile path:
from pydrive2.fs import GDriveFileSystem

fs = GDriveFileSystem(
# replace with ID of a drive or directory and give service account access to it
# replace with ID of a drive or directory and give service account
# access to it
"root",
use_service_account=True,
client_json_file_path="/path/to/keyfile.json",
Expand All @@ -89,7 +96,8 @@ Using json keyfile string:
from pydrive2.fs import GDriveFileSystem

fs = GDriveFileSystem(
# replace with ID of a drive or directory and give service account access to it
# replace with ID of a drive or directory and give service account
# access to it
"root",
use_service_account=True,
client_json=json_string,
Expand All @@ -101,20 +109,23 @@ If your service account uses `domain-wide delegation`_, set
Additional parameters
---------------------

:trash_only (bool): Move files to trash instead of deleting.
:acknowledge_abuse (bool): Acknowledge the risk when downloading a file
flagged as abusive. See :ref:`abusive-files`.
:trash_only (bool):
Move files to trash instead of deleting.
:acknowledge_abuse (bool):
Acknowledge the risk when downloading a file flagged as abusive.
See :ref:`abusive-files`.

Using filesystem
----------------

.. code-block:: python

# replace `root` with ID of a drive or directory and give service account access to it
# replace `root` with ID of a drive or directory and give service account
# access to it
for root, dnames, fnames in fs.walk("root"):
for dname in dnames:
print(f"dir: {root}/{dname}")

for fname in fnames:
print(f"file: {root}/{fname}")

Expand All @@ -125,4 +136,5 @@ about and manipulating files, refer to fsspec docs on
.. _`fsspec`: https://filesystem-spec.readthedocs.io/en/latest/
.. _domain-wide delegation:
https://developers.google.com/workspace/guides/create-credentials#set-up-domain-wide-delegation
.. _`how to use a filesystem`: https://filesystem-spec.readthedocs.io/en/latest/usage.html#use-a-file-system
.. _`how to use a filesystem`:
https://filesystem-spec.readthedocs.io/en/latest/usage.html#use-a-file-system
14 changes: 8 additions & 6 deletions docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,16 @@
Welcome to PyDrive2's documentation!
====================================

PyDrive2 is a wrapper library of `google-api-python-client`_ that simplifies many common Google Drive API tasks.
PyDrive2 is a wrapper library of `google-api-python-client`_ that simplifies
many common Google Drive API tasks.

Project Info
============

- Package: `https://pypi.python.org/pypi/PyDrive2 <https://pypi.python.org/pypi/PyDrive2>`_
- Documentation: `https://docs.iterative.ai/PyDrive2 <https://docs.iterative.ai/PyDrive2>`_
- Source: `https://github.com/iterative/PyDrive2 <https://github.com/iterative/PyDrive2>`_
- Changelog: `https://github.com/iterative/PyDrive2/releases <https://github.com/iterative/PyDrive2/releases>`_
- Package: https://pypi.python.org/pypi/PyDrive2
- Documentation: https://docs.iterative.ai/PyDrive2
- Source: https://github.com/iterative/PyDrive2
- Changelog: https://github.com/iterative/PyDrive2/releases

How to install
==============
Expand All @@ -32,7 +33,8 @@ To install the current development version from GitHub, use:
$ pip install git+https://github.com/iterative/PyDrive2.git#egg=PyDrive2


.. _`google-api-python-client`: https://github.com/google/google-api-python-client
.. _`google-api-python-client`:
https://github.com/google/google-api-python-client

Table of Contents
=================
Expand Down
Loading
Loading