fs.googledrivefs


Namefs.googledrivefs JSON
Version 2.4.2 PyPI version JSON
download
home_pagehttps://github.com/rkhwaja/fs.googledrivefs
SummaryPyfilesystem2 implementation for Google Drive
upload_time2023-11-23 04:14:35
maintainer
docs_urlNone
authorRehan Khwaja
requires_python>=3.7
licenseMIT
keywords filesystem pyfilesystem2 google
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # fs.googledrivefs

[![codecov](https://codecov.io/gh/rkhwaja/fs.googledrivefs/branch/master/graph/badge.svg)](https://codecov.io/gh/rkhwaja/fs.googledrivefs) [![PyPI version](https://badge.fury.io/py/fs.googledrivefs.svg)](https://badge.fury.io/py/fs.googledrivefs)

Implementation of [pyfilesystem2](https://docs.pyfilesystem.org/) file system for Google Drive

# Installation

```bash
  pip install fs.googledrivefs
```

# Usage

```python
  from google.oauth2.credentials import Credentials
  from fs.googledrivefs import GoogleDriveFS

  credentials = Credentials(oauth2_access_token,
    refresh_token=oauth2_refresh_token,
    token_uri="https://www.googleapis.com/oauth2/v4/token",
    client_id=oauth2_client_id,
    client_secret=oauth2_client_secret)

  fs = GoogleDriveFS(credentials=credentials)

  # fs is now a standard pyfilesystem2 file system, alternatively you can use the opener...

  from fs.opener import open_fs

  fs2 = open_fs("googledrive:///?access_token=<oauth2 access token>&refresh_token=<oauth2 refresh token>&client_id=<oauth2 client id>&client_secret=<oauth2 client secret>")

  # fs2 is now a standard pyfilesystem2 file system
```

## Default Google Authentication

If your application is accessing the Google Drive API as a 
[GCP Service Account](https://cloud.google.com/iam/docs/service-accounts), `fs.googledrivefs` will
default to authenticating using the Service Account credentials specified by the 
[`GOOGLE_APPLICATION_CREDENTIALS` environment variable](https://cloud.google.com/docs/authentication/getting-started). 
This can greatly simplify the URLs used by the opener:

```python
  from fs.opener import open_fs

  fs2 = open_fs("googledrive:///required/path")
```

You can also use the same method of authentication when using `GoogleDriveFS` directly:

```python
  import google.auth
  from fs.googledrivefs import GoogleDriveFS

  credentials, _ = google.auth.default()
  fs = GoogleDriveFS(credentials=credentials)
```

## Using `fs.googledrivefs` with an organisation's Google Account

While access to the Google Drive API is straightforward to enable for a personal Google Account,
a user of an organisation's Google Account will typically only be able to enable an API in the
context of a
[GCP Project](https://cloud.google.com/resource-manager/docs/creating-managing-projects).
The user can then configure a 
[Service Account](https://cloud.google.com/iam/docs/understanding-service-accounts)
to access all or a sub-set of the user's files using `fs.googledrivefs` with the following steps:

- create a GCP Project
- enable the Google Drive API for that Project
- create a Service Account for that Project
- share any Drive directory (or file) with that Service Account (using the accounts email)

## Notes on forming `fs` urls for GCP Service Accounts

Say that your is drive is structured as follows:

```
/alldata
  /data1
  /data2
   :
```

Also say that you have given your application's service account access to everything in `data1`.
If your application opens url `/alldata/data1` using `fs.opener.open_fs()`, then `fs.googledrivefs`
must first get the info for `alldata` to which it has no access and so the operation fails. 

To address this we can tell `fs.googledrivefs` to treat `data1` as the root directory by supplying
the file id of `data1` as the request parameter `root_id`. The fs url you would now use is
`googledrive:///?root_id=12345678901234567890`: 

```python
  from fs.opener import open_fs

  fs2 = open_fs("googledrive:///?root_id=12345678901234567890")
```

You can also use the `rootId` when using `GoogleDriveFS` directly:

```python
  import google.auth
  from fs.googledrivefs import GoogleDriveFS

  credentials, _ = google.auth.default()
  fs = GoogleDriveFS(credentials=credentials, rootId="12345678901234567890")
```

Note that any file or directory's id is readily accessible from it's web url.

# Development

To run the tests, set the following environment variables:

- GOOGLEDRIVEFS_TEST_CLIENT_ID - your client id (see Google Developer Console)
- GOOGLEDRIVEFS_TEST_CLIENT_SECRET - your client secret (see Google Developer Console)
- GOOGLEDRIVEFS_TEST_CREDENTIALS_PATH - path to a json file which will contain the credentials

Then generate the credentials json file by running

```bash
  python tests/generate-credentials.py
```

Then run the tests by executing

```bash
  pytest
```

in the root directory
(note that if `GOOGLEDRIVEFS_TEST_CREDENTIALS_PATH` isn't set 
then the test suite will try to use the default Google credentials).
The tests may take an hour or two to complete.
They create and destroy many, many files and directories
mostly under the /test-googledrivefs directory in the user's Google Drive
and a few in the root directory

Note that, if your tests are run using a service account,
you can set the root id using `GOOGLEDRIVEFS_TEST_ROOT_ID`.

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/rkhwaja/fs.googledrivefs",
    "name": "fs.googledrivefs",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.7",
    "maintainer_email": "",
    "keywords": "filesystem,Pyfilesystem2,google",
    "author": "Rehan Khwaja",
    "author_email": "rehan@khwaja.name",
    "download_url": "https://files.pythonhosted.org/packages/93/74/ae4399bf6f86f8f89409f49b4b9905bb047d1a10620ce7eb0e1c13d4461e/fs_googledrivefs-2.4.2.tar.gz",
    "platform": null,
    "description": "# fs.googledrivefs\n\n[![codecov](https://codecov.io/gh/rkhwaja/fs.googledrivefs/branch/master/graph/badge.svg)](https://codecov.io/gh/rkhwaja/fs.googledrivefs) [![PyPI version](https://badge.fury.io/py/fs.googledrivefs.svg)](https://badge.fury.io/py/fs.googledrivefs)\n\nImplementation of [pyfilesystem2](https://docs.pyfilesystem.org/) file system for Google Drive\n\n# Installation\n\n```bash\n  pip install fs.googledrivefs\n```\n\n# Usage\n\n```python\n  from google.oauth2.credentials import Credentials\n  from fs.googledrivefs import GoogleDriveFS\n\n  credentials = Credentials(oauth2_access_token,\n    refresh_token=oauth2_refresh_token,\n    token_uri=\"https://www.googleapis.com/oauth2/v4/token\",\n    client_id=oauth2_client_id,\n    client_secret=oauth2_client_secret)\n\n  fs = GoogleDriveFS(credentials=credentials)\n\n  # fs is now a standard pyfilesystem2 file system, alternatively you can use the opener...\n\n  from fs.opener import open_fs\n\n  fs2 = open_fs(\"googledrive:///?access_token=<oauth2 access token>&refresh_token=<oauth2 refresh token>&client_id=<oauth2 client id>&client_secret=<oauth2 client secret>\")\n\n  # fs2 is now a standard pyfilesystem2 file system\n```\n\n## Default Google Authentication\n\nIf your application is accessing the Google Drive API as a \n[GCP Service Account](https://cloud.google.com/iam/docs/service-accounts), `fs.googledrivefs` will\ndefault to authenticating using the Service Account credentials specified by the \n[`GOOGLE_APPLICATION_CREDENTIALS` environment variable](https://cloud.google.com/docs/authentication/getting-started). \nThis can greatly simplify the URLs used by the opener:\n\n```python\n  from fs.opener import open_fs\n\n  fs2 = open_fs(\"googledrive:///required/path\")\n```\n\nYou can also use the same method of authentication when using `GoogleDriveFS` directly:\n\n```python\n  import google.auth\n  from fs.googledrivefs import GoogleDriveFS\n\n  credentials, _ = google.auth.default()\n  fs = GoogleDriveFS(credentials=credentials)\n```\n\n## Using `fs.googledrivefs` with an organisation's Google Account\n\nWhile access to the Google Drive API is straightforward to enable for a personal Google Account,\na user of an organisation's Google Account will typically only be able to enable an API in the\ncontext of a\n[GCP Project](https://cloud.google.com/resource-manager/docs/creating-managing-projects).\nThe user can then configure a \n[Service Account](https://cloud.google.com/iam/docs/understanding-service-accounts)\nto access all or a sub-set of the user's files using `fs.googledrivefs` with the following steps:\n\n- create a GCP Project\n- enable the Google Drive API for that Project\n- create a Service Account for that Project\n- share any Drive directory (or file) with that Service Account (using the accounts email)\n\n## Notes on forming `fs` urls for GCP Service Accounts\n\nSay that your is drive is structured as follows:\n\n```\n/alldata\n  /data1\n  /data2\n   :\n```\n\nAlso say that you have given your application's service account access to everything in `data1`.\nIf your application opens url `/alldata/data1` using `fs.opener.open_fs()`, then `fs.googledrivefs`\nmust first get the info for `alldata` to which it has no access and so the operation fails. \n\nTo address this we can tell `fs.googledrivefs` to treat `data1` as the root directory by supplying\nthe file id of `data1` as the request parameter `root_id`. The fs url you would now use is\n`googledrive:///?root_id=12345678901234567890`: \n\n```python\n  from fs.opener import open_fs\n\n  fs2 = open_fs(\"googledrive:///?root_id=12345678901234567890\")\n```\n\nYou can also use the `rootId` when using `GoogleDriveFS` directly:\n\n```python\n  import google.auth\n  from fs.googledrivefs import GoogleDriveFS\n\n  credentials, _ = google.auth.default()\n  fs = GoogleDriveFS(credentials=credentials, rootId=\"12345678901234567890\")\n```\n\nNote that any file or directory's id is readily accessible from it's web url.\n\n# Development\n\nTo run the tests, set the following environment variables:\n\n- GOOGLEDRIVEFS_TEST_CLIENT_ID - your client id (see Google Developer Console)\n- GOOGLEDRIVEFS_TEST_CLIENT_SECRET - your client secret (see Google Developer Console)\n- GOOGLEDRIVEFS_TEST_CREDENTIALS_PATH - path to a json file which will contain the credentials\n\nThen generate the credentials json file by running\n\n```bash\n  python tests/generate-credentials.py\n```\n\nThen run the tests by executing\n\n```bash\n  pytest\n```\n\nin the root directory\n(note that if `GOOGLEDRIVEFS_TEST_CREDENTIALS_PATH` isn't set \nthen the test suite will try to use the default Google credentials).\nThe tests may take an hour or two to complete.\nThey create and destroy many, many files and directories\nmostly under the /test-googledrivefs directory in the user's Google Drive\nand a few in the root directory\n\nNote that, if your tests are run using a service account,\nyou can set the root id using `GOOGLEDRIVEFS_TEST_ROOT_ID`.\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Pyfilesystem2 implementation for Google Drive",
    "version": "2.4.2",
    "project_urls": {
        "Homepage": "https://github.com/rkhwaja/fs.googledrivefs"
    },
    "split_keywords": [
        "filesystem",
        "pyfilesystem2",
        "google"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "3cdd472df466b133e73125efa342893d540cf9337e2acd4227a0cf04034997ca",
                "md5": "10ecd11aee9a653bd6063e44aeef8035",
                "sha256": "e3aee34d068f75cfd7a0412f1395ab2bbcb34d166ae0ecd2c8d1d39a2504ccf8"
            },
            "downloads": -1,
            "filename": "fs_googledrivefs-2.4.2-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "10ecd11aee9a653bd6063e44aeef8035",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.7",
            "size": 11785,
            "upload_time": "2023-11-23T04:14:33",
            "upload_time_iso_8601": "2023-11-23T04:14:33.018257Z",
            "url": "https://files.pythonhosted.org/packages/3c/dd/472df466b133e73125efa342893d540cf9337e2acd4227a0cf04034997ca/fs_googledrivefs-2.4.2-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "9374ae4399bf6f86f8f89409f49b4b9905bb047d1a10620ce7eb0e1c13d4461e",
                "md5": "66481133c629ef3a77bc013ccd0a8a96",
                "sha256": "78536d18b8b727ce34d30ffeb3a82c9b24eeb4e5e70a637669944c507dd5755a"
            },
            "downloads": -1,
            "filename": "fs_googledrivefs-2.4.2.tar.gz",
            "has_sig": false,
            "md5_digest": "66481133c629ef3a77bc013ccd0a8a96",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.7",
            "size": 12447,
            "upload_time": "2023-11-23T04:14:35",
            "upload_time_iso_8601": "2023-11-23T04:14:35.444146Z",
            "url": "https://files.pythonhosted.org/packages/93/74/ae4399bf6f86f8f89409f49b4b9905bb047d1a10620ce7eb0e1c13d4461e/fs_googledrivefs-2.4.2.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-11-23 04:14:35",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "rkhwaja",
    "github_project": "fs.googledrivefs",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "fs.googledrivefs"
}
        
Elapsed time: 0.14447s