# boxfs
Implementation of the [`fsspec`](https://filesystem-spec.readthedocs.io/en/latest/index.html)
protocol for [Box](https://www.box.com/overview) content management, enabling you to
interface with files stored on Box using a file-system-like navigation.
## Installation
You can install `boxfs` from [PyPI](https://pypi.org/project/boxfs/). Use the following
command:
```bash
pip install boxfs
```
To use install the optional `upath` dependency, use the following command
```bash
pip install boxfs[upath]
```
## Example
```python
import fsspec
from boxsdk import JWTAuth
oauth = JWTAuth.from_settings_file("PATH/TO/JWT_CONFIGURATION.json")
root_id = "<ID-of-file-system-root>"
### For simple file access, you can use `fsspec.open`
with fsspec.open("box://Documents/test_file.txt", "wb", oauth=oauth, root_id=root_id) as f:
f.write("This file was produced using boxfs")
### For more control, you can use `fsspec.filesystem`
fs = fsspec.filesystem('box', oauth=oauth, root_id=root_id)
# List directory contents
fs.ls("Documents")
# Make new directory
fs.mkdir("Documents/Test Folder")
# Remove a directory
fs.rmdir("Documents/Test Folder")
# Open and write file
with fs.open("Documents/test_file.txt", "wb") as f:
f.write("This file was updated using boxfs")
# Print file contents
fs.cat("Documents/test_file.txt")
# Delete file
fs.rm("Documents/test_file.txt")
# If you installed with the `upath` extra, you can also use the universal-pathlib UPath
# class.
from upath import UPath
path = UPath("Documents", fs=fs) / "test_file.txt"
path.read_text()
```
## Storage Options
The following storage options are accepted by `fsspec` when creating a `BoxFileSystem`
object:
- oauth: Box app OAuth2 configuration dictionary, e.g. loaded from
`JWTAuth.from_settings_file`, by default None
- client: An already instantiated boxsdk `Client` object
- client_type: Type of `Client` class to use when connecting to box
If `client` is provided, it is used for handling API calls. Otherwise, the file
system to instantiate a new client connection, of type `client_type`, using the
provided `oauth` configuration.
- root_id: Box ID (as `str`) of folder where file system root is placed, by default
None
- root_path: Path (as `str`) to Box root folder, must be relative to user's root
(e.g. "All Files"). The client must have access to the application user's root
folder (i.e., it cannot be downscoped to a subfolder)
If only `root_id` is provided, the `root_path` is determined from API calls. If
only `root_path` is provided, the `root_id` is determined from API calls. If
neither is provided, the application user's root folder is used.
- path_map: Mapping of paths to object ID strings, used to populate initial lookup
cache for quick directory navigation
- scopes: List of permissions to which the API token should be restricted. If None
(default), no restrictions are applied. If scopes are provided, the client
connection is (1) downscoped to use only the provided scopes, and
(2) restricted to the directory/subdirectories of the root folder.
## Creating a Box App
Before you can use `boxfs`, you will need a Box application through which you can route
your API calls. To do so, you can follow the steps for
["Setup with JWT"](https://developer.box.com/guides/authentication/jwt/jwt-setup/)
in the Box Developer documentation. The JWT configuration `.json` file that
you generate will have to be stored locally and loaded using
`JWTAuth.from_settings_file`. You also have to add your application's
Service Account as a collaborator on the root folder of your choosing, or
you will only have access to the Box application's files.
Raw data
{
"_id": null,
"home_page": "https://github.com/IBM/boxfs",
"name": "boxfs",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "file-storage,fsspec,file-system,box",
"author": "Thomas Hunter",
"author_email": "boxfs.tehunter@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/be/de/1c5e0faec600538f6a1d41c7ce7834cacddb2237923e30ddb225254b74b9/boxfs-0.2.1.tar.gz",
"platform": null,
"description": "# boxfs\n\nImplementation of the [`fsspec`](https://filesystem-spec.readthedocs.io/en/latest/index.html)\nprotocol for [Box](https://www.box.com/overview) content management, enabling you to\ninterface with files stored on Box using a file-system-like navigation.\n\n## Installation\n\nYou can install `boxfs` from [PyPI](https://pypi.org/project/boxfs/). Use the following\ncommand:\n\n```bash\npip install boxfs\n```\n\nTo use install the optional `upath` dependency, use the following command\n\n```bash\npip install boxfs[upath]\n```\n\n## Example\n\n```python\nimport fsspec\nfrom boxsdk import JWTAuth\n\noauth = JWTAuth.from_settings_file(\"PATH/TO/JWT_CONFIGURATION.json\")\nroot_id = \"<ID-of-file-system-root>\"\n\n### For simple file access, you can use `fsspec.open`\nwith fsspec.open(\"box://Documents/test_file.txt\", \"wb\", oauth=oauth, root_id=root_id) as f:\n f.write(\"This file was produced using boxfs\")\n\n### For more control, you can use `fsspec.filesystem`\nfs = fsspec.filesystem('box', oauth=oauth, root_id=root_id)\n# List directory contents\nfs.ls(\"Documents\")\n# Make new directory\nfs.mkdir(\"Documents/Test Folder\")\n# Remove a directory\nfs.rmdir(\"Documents/Test Folder\")\n\n# Open and write file\nwith fs.open(\"Documents/test_file.txt\", \"wb\") as f:\n f.write(\"This file was updated using boxfs\")\n\n# Print file contents\nfs.cat(\"Documents/test_file.txt\")\n# Delete file\nfs.rm(\"Documents/test_file.txt\")\n\n# If you installed with the `upath` extra, you can also use the universal-pathlib UPath\n# class.\nfrom upath import UPath\npath = UPath(\"Documents\", fs=fs) / \"test_file.txt\"\npath.read_text()\n```\n\n## Storage Options\n\nThe following storage options are accepted by `fsspec` when creating a `BoxFileSystem`\nobject:\n\n- oauth: Box app OAuth2 configuration dictionary, e.g. loaded from\n `JWTAuth.from_settings_file`, by default None\n- client: An already instantiated boxsdk `Client` object\n- client_type: Type of `Client` class to use when connecting to box\n\nIf `client` is provided, it is used for handling API calls. Otherwise, the file\nsystem to instantiate a new client connection, of type `client_type`, using the\nprovided `oauth` configuration.\n\n- root_id: Box ID (as `str`) of folder where file system root is placed, by default\n None\n- root_path: Path (as `str`) to Box root folder, must be relative to user's root\n (e.g. \"All Files\"). The client must have access to the application user's root\n folder (i.e., it cannot be downscoped to a subfolder)\n\nIf only `root_id` is provided, the `root_path` is determined from API calls. If\nonly `root_path` is provided, the `root_id` is determined from API calls. If\nneither is provided, the application user's root folder is used.\n\n- path_map: Mapping of paths to object ID strings, used to populate initial lookup\n cache for quick directory navigation\n- scopes: List of permissions to which the API token should be restricted. If None\n (default), no restrictions are applied. If scopes are provided, the client\n connection is (1) downscoped to use only the provided scopes, and\n (2) restricted to the directory/subdirectories of the root folder.\n\n## Creating a Box App\n\nBefore you can use `boxfs`, you will need a Box application through which you can route\nyour API calls. To do so, you can follow the steps for\n[\"Setup with JWT\"](https://developer.box.com/guides/authentication/jwt/jwt-setup/)\nin the Box Developer documentation. The JWT configuration `.json` file that\nyou generate will have to be stored locally and loaded using\n`JWTAuth.from_settings_file`. You also have to add your application's\nService Account as a collaborator on the root folder of your choosing, or\nyou will only have access to the Box application's files.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Implementation of fsspec for Box file storage",
"version": "0.2.1",
"project_urls": {
"Homepage": "https://github.com/IBM/boxfs",
"Repository": "https://github.com/IBM/boxfs"
},
"split_keywords": [
"file-storage",
"fsspec",
"file-system",
"box"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "86bb243d10169c8397051bad6bdd10beb2407fa490bfe01216f5fad09e066191",
"md5": "f43e448cd02899f45c71d434529e78ea",
"sha256": "ae796c30309bd5a02654fff9eddf1ed320356225568fad0e109e1942beaef72a"
},
"downloads": -1,
"filename": "boxfs-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f43e448cd02899f45c71d434529e78ea",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 9358,
"upload_time": "2023-08-23T19:24:34",
"upload_time_iso_8601": "2023-08-23T19:24:34.066940Z",
"url": "https://files.pythonhosted.org/packages/86/bb/243d10169c8397051bad6bdd10beb2407fa490bfe01216f5fad09e066191/boxfs-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bede1c5e0faec600538f6a1d41c7ce7834cacddb2237923e30ddb225254b74b9",
"md5": "4aab4e7d4bf3b067f9517be0b108d3cc",
"sha256": "c1889e12f53be3216b44f088237ac0f367a7a759a53b01b0c0edf2b3d694e50f"
},
"downloads": -1,
"filename": "boxfs-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "4aab4e7d4bf3b067f9517be0b108d3cc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 9523,
"upload_time": "2023-08-23T19:24:35",
"upload_time_iso_8601": "2023-08-23T19:24:35.233872Z",
"url": "https://files.pythonhosted.org/packages/be/de/1c5e0faec600538f6a1d41c7ce7834cacddb2237923e30ddb225254b74b9/boxfs-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-23 19:24:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "IBM",
"github_project": "boxfs",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "boxfs"
}
JSON
