<div align="center">
<img src="de.png" style="position:relative;top: 75px;width:50px;" />
# PyCyAPI
unofficial Python/CLI client for the [CyVerse](https://www.cyverse.org/) [Science](https://cyverse.org/Science-APIs) (a.k.a. [Terrain](https://de.cyverse.org/terrain/docs/index.html)) APIs
[](https://github.com/Computational-Plant-Science/pycyapi/tags/latest)
[](https://pypi.python.org/pypi/pycyapi)
[](https://pypi.python.org/pypi/pycyapi)
[](https://pypi.python.org/pypi/pycyapi)
</div>
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
- [Status](#status)
- [Requirements](#requirements)
- [Installation](#installation)
- [Usage](#usage)
- [Authenticating](#authenticating)
- [Commands](#commands)
- [Version](#version)
- [Token](#token)
- [User](#user)
- [List](#list)
- [Stat](#stat)
- [Pull](#pull)
- [Push](#push)
- [Exists](#exists)
- [Create](#create)
- [Share](#share)
- [Unshare](#unshare)
- [Tag](#tag)
- [Tags](#tags)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## Status
API coverage is still sparse, focusing mainly on `data` and `fileio` endpoints. It will likely stay this way as this project exists predominantly for consumption by [`plantit`](https://github.com/Computational-Plant-Science/plantit) and [`plantit-action`](https://github.com/Computational-Plant-Science/plantit-action).
## Requirements
- Python 3.8+
## Installation
To install with pip:
```shell
pip install pycyapi
```
## Usage
Generally, the CLI is invoked with `pycyapi <command>`. All commands return JSON except `pycyapi token ...` (see below), which returns the token in plain text.
### Authenticating
The `pycyapi` CLI must obtain an access token to authenticate with CyVerse. The token may be provided to commands via the `--token` parameter, or set as an environment variable `CYVERSE_TOKEN`. An access token can be obtained from the Terrain API by sending a request with basic auth headers (valid CyVerse username and password):
```shell
GET https://de.cyverse.org/terrain/token/cas
```
A `token` command (see below) is provided as convenient alternative to manually obtaining a token.
### Commands
To show available commands help run `pycyapi --help`. The following commands are available:
- `version`: Show the current `pycyapi` version.
- `token`: Retrieve a CyVerse authentication token.
- `user`: Retrieve the user's profile information.
- `list`: List files in a collection.
- `stat`: Get information about a file or collection.
- `pull`: Download one or more files from a collection.
- `push`: Upload one or more files to a collection.
- `exists`: Check if a path exists in the data store.
- `create`: Create a collection in the data store.
- `share`: Share a file or collection with another user.
- `unshare`: Revoke another user's access to your file or collection.
- `tag`: Set metadata for a given file or collection.
- `tags`: Get metadata for a given file or collection.
To show usage information for a specific command, run `pycyapi <command> --help`.
#### Version
To show the current version of `pycyapi`, use the `version` command:
```shell
pycyapi version
```
#### Token
To request a CyVerse CAS authentication token, use the `token` command:
```shell script
pycyapi token --username <your CyVerse username> --password <your CyVerse password>
```
The token can be passed via `--token (-t)` argument to authenticate subsequent commands.
#### User
The `user` command can be used to retrieve public profile information for CyVerse users. For instance:
```shell
pycyapi user -t <token> wbonelli
```
#### List
To list the contents of a collection in the data store, use the `list` command. For instance:
```shell
pycyapi list -t <token> /iplant/home/shared/iplantcollaborative/testing_tools/
```
#### Stat
To view metadata for a particular collection or object in the data store, use the `stat` command. For instance:
```shell
pycyapi stat -t <token> /iplant/home/shared/iplantcollaborative/testing_tools/
```
#### Pull
To download a single file from the data store to the current working directory, simply provide its full path:
```shell
pycyapi pull -t <token> /iplant/home/shared/iplantcollaborative/testing_tools/cowsay/cowsay.txt
```
To download all files from the `/iplant/home/shared/iplantcollaborative/testing_tools/cowsay/` collection to the current working directory, just provide the collection path instead:
```shell
pycyapi pull -t <token> /iplant/home/shared/iplantcollaborative/testing_tools/cowsay/
```
Optional arguments are:
- `--local_path (-p)`: Local path to download files to
- `--include_pattern (-ip)`: File patterns to include (0+)
- `--force (-f)`: Whether to overwrite already-existing files
#### Push
To upload all files in the current working directory to the `/iplant/home/<my>/<directory/` in the CyVerse Data Store, use:
```shell
pycyapi push -t <token> /iplant/home/<username>/<collection>/
```
Optional arguments include:
- `--local_path (-p)`: Local path to download files to
- `--include_pattern (-ip)`: File patterns to include (0+)
- `--include_name (-in)`: File names to include (0+)
- `--exclude_pattern (-ep)`: File patterns to exclude (0+)
- `--exclude_name (-en)`: File names to exclude (0+)
To upload a single file to the data store, provide the `--local_path (-p)` argument. For instance:
```shell
pycyapi push -t <token> /iplant/home/<username>/<collection/ -p /my/local/file.txt
```
If only `include_...`s are provided, only the file patterns and names specified will be included. If only `exclude_...`s section are present, all files except the patterns and names specified will be included. If you provide both `include_...` and `exclude_...` sections, the `include_...` rules will first be applied to generate a subset of files, which will then be filtered by the `exclude_...` rules.
#### Exists
To determine whether a particular path exists in the data store, use the `exists` command. For instance, to check if a collection exists:
```shell
pycyapi exists -t <token> /iplant/home/<username>/<collection
```
The `--type` option can be provided with value `dir` or `file` to verify that the given path is of the specified type.
#### Create
To create a new collection, use the `create` command:
```shell
pycyapi create -t <token> /iplant/home/<username>/<new collection name>
```
#### Share
To share a file or collection with another user, use the `share` command:
```shell
pycyapi share -t <token> /iplant/home/<username>/<collection> --username <user to share with> --permission <'read' or 'write'>
```
Note that you must provide both the `--username` and `--permission` flags.
#### Unshare
To revoke another user's access to your file or collection, use the `unshare` command:
```shell
pycyapi unshare -t <token> /iplant/home/<username>/<collection> --username <username>
```
This applies to both `read` and `write` permissions for the specified user.
#### Tag
To set metadata for a given file object or collection in your data store, use the `tag` command:
```shell
pycyapi tag <data object ID> -t <token> -a k1=v1 -a k2=v2
```
This applies the two given attributes to the data object (attributes must be formatted `key=value`).
**Warning:** this command is an overwrite, not an append. We do not support appending tags as there is no Terrain endpoint to add/remove individual metadata attributes. Note also that by default, key/value pairs are passed on the `avus` attribute of the request body rather than `irods-avus`, e.g.:
```shell
POST https://de.cyverse.org/terrain/secured/filesystem/<ID>/metadata
{
"irods-avus": [],
"avus": [
{
"attr": "some key"
"value": "some value",
"unit": ""
}
]
}
```
To configure `irods-avus` attributes as well as or in place of standard attributes, use the `--irods_attribute (-ia)` option. Both standard and iRODS attributes can be used in the same invocation.
#### Tags
To retrieve the metadata describing a particular file object or collection, use the `tags` command:
```shell
pycyapi tags <data object ID> -t <token>
```
This will retrieve standard attributes by default. To retrieve iRODS attributes instead, use the `--irods (-i)` option.
Raw data
{
"_id": null,
"home_page": "https://github.com/Computational-Plant-Science/pycyapi",
"name": "pycyapi",
"maintainer": "Wes Bonelli",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "wbonelli@uga.edu",
"keywords": "hpc,slurm,singularity",
"author": "Computational Plant Science Lab",
"author_email": "wbonelli@uga.edu",
"download_url": "https://files.pythonhosted.org/packages/9f/d4/f798dc6308a9e167d21b9087ae384cd04045fafcf0f186f46baafa27db04/pycyapi-0.0.13.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n<img src=\"de.png\" style=\"position:relative;top: 75px;width:50px;\" />\n\n# PyCyAPI\n\nunofficial Python/CLI client for the [CyVerse](https://www.cyverse.org/) [Science](https://cyverse.org/Science-APIs) (a.k.a. [Terrain](https://de.cyverse.org/terrain/docs/index.html)) APIs\n\n\n[](https://github.com/Computational-Plant-Science/pycyapi/tags/latest)\n[](https://pypi.python.org/pypi/pycyapi)\n[](https://pypi.python.org/pypi/pycyapi)\n[](https://pypi.python.org/pypi/pycyapi)\n\n</div>\n\n<!-- START doctoc generated TOC please keep comment here to allow auto update -->\n<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->\n\n- [Status](#status)\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Usage](#usage)\n - [Authenticating](#authenticating)\n - [Commands](#commands)\n - [Version](#version)\n - [Token](#token)\n - [User](#user)\n - [List](#list)\n - [Stat](#stat)\n - [Pull](#pull)\n - [Push](#push)\n - [Exists](#exists)\n - [Create](#create)\n - [Share](#share)\n - [Unshare](#unshare)\n - [Tag](#tag)\n - [Tags](#tags)\n\n<!-- END doctoc generated TOC please keep comment here to allow auto update -->\n\n## Status\n\nAPI coverage is still sparse, focusing mainly on `data` and `fileio` endpoints. It will likely stay this way as this project exists predominantly for consumption by [`plantit`](https://github.com/Computational-Plant-Science/plantit) and [`plantit-action`](https://github.com/Computational-Plant-Science/plantit-action).\n\n## Requirements\n\n- Python 3.8+\n\n## Installation\n\nTo install with pip:\n\n```shell\npip install pycyapi\n```\n\n## Usage\n\n Generally, the CLI is invoked with `pycyapi <command>`. All commands return JSON except `pycyapi token ...` (see below), which returns the token in plain text.\n\n### Authenticating\n\nThe `pycyapi` CLI must obtain an access token to authenticate with CyVerse. The token may be provided to commands via the `--token` parameter, or set as an environment variable `CYVERSE_TOKEN`. An access token can be obtained from the Terrain API by sending a request with basic auth headers (valid CyVerse username and password):\n\n```shell\nGET https://de.cyverse.org/terrain/token/cas\n```\n\nA `token` command (see below) is provided as convenient alternative to manually obtaining a token.\n\n### Commands\n\nTo show available commands help run `pycyapi --help`. The following commands are available:\n\n- `version`: Show the current `pycyapi` version.\n- `token`: Retrieve a CyVerse authentication token.\n- `user`: Retrieve the user's profile information.\n- `list`: List files in a collection.\n- `stat`: Get information about a file or collection.\n- `pull`: Download one or more files from a collection.\n- `push`: Upload one or more files to a collection.\n- `exists`: Check if a path exists in the data store.\n- `create`: Create a collection in the data store.\n- `share`: Share a file or collection with another user.\n- `unshare`: Revoke another user's access to your file or collection.\n- `tag`: Set metadata for a given file or collection.\n- `tags`: Get metadata for a given file or collection.\n\nTo show usage information for a specific command, run `pycyapi <command> --help`.\n\n#### Version\n\nTo show the current version of `pycyapi`, use the `version` command:\n\n```shell\npycyapi version\n```\n\n#### Token\n\nTo request a CyVerse CAS authentication token, use the `token` command:\n\n```shell script\npycyapi token --username <your CyVerse username> --password <your CyVerse password>\n```\n\nThe token can be passed via `--token (-t)` argument to authenticate subsequent commands.\n\n#### User\n\nThe `user` command can be used to retrieve public profile information for CyVerse users. For instance:\n\n```shell\npycyapi user -t <token> wbonelli\n```\n\n#### List\n\nTo list the contents of a collection in the data store, use the `list` command. For instance:\n\n```shell\npycyapi list -t <token> /iplant/home/shared/iplantcollaborative/testing_tools/\n```\n\n#### Stat\n\nTo view metadata for a particular collection or object in the data store, use the `stat` command. For instance:\n\n```shell\npycyapi stat -t <token> /iplant/home/shared/iplantcollaborative/testing_tools/\n```\n\n#### Pull\n\nTo download a single file from the data store to the current working directory, simply provide its full path:\n\n```shell\npycyapi pull -t <token> /iplant/home/shared/iplantcollaborative/testing_tools/cowsay/cowsay.txt\n```\n\nTo download all files from the `/iplant/home/shared/iplantcollaborative/testing_tools/cowsay/` collection to the current working directory, just provide the collection path instead:\n\n```shell\npycyapi pull -t <token> /iplant/home/shared/iplantcollaborative/testing_tools/cowsay/\n```\n\nOptional arguments are:\n\n- `--local_path (-p)`: Local path to download files to\n- `--include_pattern (-ip)`: File patterns to include (0+)\n- `--force (-f)`: Whether to overwrite already-existing files\n\n#### Push\n\nTo upload all files in the current working directory to the `/iplant/home/<my>/<directory/` in the CyVerse Data Store, use:\n\n```shell\npycyapi push -t <token> /iplant/home/<username>/<collection>/\n```\n\nOptional arguments include:\n\n- `--local_path (-p)`: Local path to download files to\n- `--include_pattern (-ip)`: File patterns to include (0+)\n- `--include_name (-in)`: File names to include (0+)\n- `--exclude_pattern (-ep)`: File patterns to exclude (0+)\n- `--exclude_name (-en)`: File names to exclude (0+)\n\nTo upload a single file to the data store, provide the `--local_path (-p)` argument. For instance:\n\n```shell\npycyapi push -t <token> /iplant/home/<username>/<collection/ -p /my/local/file.txt\n```\n\nIf only `include_...`s are provided, only the file patterns and names specified will be included. If only `exclude_...`s section are present, all files except the patterns and names specified will be included. If you provide both `include_...` and `exclude_...` sections, the `include_...` rules will first be applied to generate a subset of files, which will then be filtered by the `exclude_...` rules.\n\n#### Exists\n\nTo determine whether a particular path exists in the data store, use the `exists` command. For instance, to check if a collection exists:\n\n```shell\npycyapi exists -t <token> /iplant/home/<username>/<collection\n```\n\nThe `--type` option can be provided with value `dir` or `file` to verify that the given path is of the specified type.\n\n#### Create\n\nTo create a new collection, use the `create` command:\n\n```shell\npycyapi create -t <token> /iplant/home/<username>/<new collection name>\n```\n\n#### Share\n\nTo share a file or collection with another user, use the `share` command:\n\n```shell\npycyapi share -t <token> /iplant/home/<username>/<collection> --username <user to share with> --permission <'read' or 'write'>\n```\n\nNote that you must provide both the `--username` and `--permission` flags.\n\n#### Unshare\n\nTo revoke another user's access to your file or collection, use the `unshare` command:\n\n```shell\npycyapi unshare -t <token> /iplant/home/<username>/<collection> --username <username>\n```\n\nThis applies to both `read` and `write` permissions for the specified user.\n\n#### Tag\n\nTo set metadata for a given file object or collection in your data store, use the `tag` command:\n\n```shell\npycyapi tag <data object ID> -t <token> -a k1=v1 -a k2=v2\n```\n\nThis applies the two given attributes to the data object (attributes must be formatted `key=value`).\n\n**Warning:** this command is an overwrite, not an append. We do not support appending tags as there is no Terrain endpoint to add/remove individual metadata attributes. Note also that by default, key/value pairs are passed on the `avus` attribute of the request body rather than `irods-avus`, e.g.:\n\n```shell\nPOST https://de.cyverse.org/terrain/secured/filesystem/<ID>/metadata\n{\n \"irods-avus\": [],\n \"avus\": [\n {\n \"attr\": \"some key\"\n \"value\": \"some value\",\n \"unit\": \"\"\n }\n ]\n}\n```\n\nTo configure `irods-avus` attributes as well as or in place of standard attributes, use the `--irods_attribute (-ia)` option. Both standard and iRODS attributes can be used in the same invocation.\n\n#### Tags\n\nTo retrieve the metadata describing a particular file object or collection, use the `tags` command:\n\n```shell\npycyapi tags <data object ID> -t <token>\n```\n\nThis will retrieve standard attributes by default. To retrieve iRODS attributes instead, use the `--irods (-i)` option.\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Python client for the CyVerse Science APIs",
"version": "0.0.13",
"split_keywords": [
"hpc",
"slurm",
"singularity"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "3c50af3a705595a47bed15fc0dcb20e4",
"sha256": "0fd120f83a83acade1c00da4e8ec9bbd705e6dce28bd9806fb726317ff85f909"
},
"downloads": -1,
"filename": "pycyapi-0.0.13-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3c50af3a705595a47bed15fc0dcb20e4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 25656,
"upload_time": "2022-12-22T04:44:51",
"upload_time_iso_8601": "2022-12-22T04:44:51.566643Z",
"url": "https://files.pythonhosted.org/packages/b5/f4/83a56aa09d01352458ad9e366bda8c0e8e298c89cd05caa938742755a153/pycyapi-0.0.13-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "8943ba3db66b3f7d49b2bf55d6fe415f",
"sha256": "575697ec61bf4ee8bf96e9236d255985b51b2ef87ab5fcad7d435c6c16f9b136"
},
"downloads": -1,
"filename": "pycyapi-0.0.13.tar.gz",
"has_sig": false,
"md5_digest": "8943ba3db66b3f7d49b2bf55d6fe415f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 22944,
"upload_time": "2022-12-22T04:44:53",
"upload_time_iso_8601": "2022-12-22T04:44:53.550625Z",
"url": "https://files.pythonhosted.org/packages/9f/d4/f798dc6308a9e167d21b9087ae384cd04045fafcf0f186f46baafa27db04/pycyapi-0.0.13.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-22 04:44:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "Computational-Plant-Science",
"github_project": "pycyapi",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pycyapi"
}
JSON
