Python client for Figshare
Project description
* Pigshare
Python client library and commandline tool for institutional Figshare.
The commandline options are created dynamically from the available api-method wrapper code, which is why some of them might feel a bit clumsy. Also, many of the commands only support values as json-formatted strings. I might change that in the future, but it'd require more complex cli-argparse creation code and I'm not sure whether it's worth it.
** Requirements
- python-dev package (for simplejson compilation I think)
- argparse
- setuptools
- restkit
- booby
- simplejson
- parinx
- pyclist
- argcomplete
** Installation
*** Release
(sudo) pip install https://github.com/UoA-eResearch/pigshare/archive/master.zip
*** Development version from Github
(sudo) pip install https://github.com/UoA-eResearch/pigshare/archive/master.zip
** Usage (commandline client)
*** Connection details
*pigshare* reads a config file $HOME/.pigshare.conf, in the format:
: [default]
: url = https://api.figsh.com/v2
: token = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
(note, this example uses the staging environment)
*pigshare* supports profiles, so you can have multiple profiles in your config file like for example:
: [default]
: url = https://api.figsh.com/v2
: token = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
: [markus]
: url = https://api.figshare.com/v2
: token = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
: [not_markus_but_somebody_else]
: url = https://api.figshare.com/v2
: token = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Now, when you call *pigshare* with the *-p* argument, you can switch between different backends/identities:
: pigshare -p markus list_articles
the command you chose will be using the selected connection parameters.
*** Features:
**** Supported
- creation of articles
- listing of public and private articles
- searching for public and private articles
- updating of articles
- creation of collections
- listing of public and private collections
- searching for public and private collections
- updating of collections
**** TODO
- adding of files to an articles (uploading)
- everything else
*** General usage
For public read access, this is not required.
Basic usage is displayed via:
: pigshare -h
Command specific usage can be displayed via:
: pigshare [command] -h
*** Filtering
(Sub-)commands that display one or more items can be called using an output filter (the **-o** argument before the sub-command). Depending on the sub-command called only certain fields of the items are available (e.g. *list_articles* has only a subset of fields compared to *read_article*).
I'd recommend trying out the command you want to run first, and checking which fields are available, then run the command again with the appropriate filter. A command to list all articles and only display the *doi* and *title* of each article would be:
: pigshare -o doi,title list_articles
*** Commonly used commands
**** Articles
***** List articles
To list all articles and display the *doi*, (internal) *id*, *title*, *url*, and *published_date* for each, issue:
: pigshare list_articles
To display a table with all articles, but only display *doi* and *title*, you can use:
: pigshare -o doi,title list_articles
***** Read an article
To display the properties of an article, use:
: pigshare read_article [article_id]
To display the doi and all tags of a number of articles, use (tags are not part of the 'short' article format that the *list_articles* command returns):
: pigshare -o doi,tags read_article [article_id] [article_id] [article_id]
***** Search for articles
To list all articles matching a search string, issue:
: pigshare search_articles --search_term [search_term]
To display all dois and titles of articles that match a search string:
: pigshare -o doi,title search_articles --search_term [search_term]
**** Collections
Very similar to articles.
*** Other random example calls:
: # create new article
: pigshare create_article --article '{"title": "Markus test", "custom_fields": {"key1": "value"}}'
: # create new collection
: pigshare create_collection --collection '{"title": "Collection markus test", "articles": [2009074,2009075,2009084], "custom_fields": {"test1": "value1"}}'
: # add articles to a collection
: pigshare add_article --collection_id 2761 --article_ids [2009103,2009106]
: # search articles that contain a search_term, display only ids, separated by ',' (useful to copy and paste into 'add_article' command)
: pigshare -o id -s ',' search_my_articles --search_term [search_term]
: # list all of your personal articles, and add all of them to a collection
: for id in `pigshare -o id list_my_articles`; do echo "$id"; pigshare add_article --collection_id 3222 --article_id "$id"; done
: # update/overwrite the title and articles connected to a collection
: pigshare update_collection --id 2761 --collection '{"title": "Collection markus test changed", "articles": [2009074,2009075]}'
: # update/overwrite the categories field in a collection
: pigshare update_article --id 2000077 --article '{"categories": [2]}'
: # update/overwrite the custom_fields of a collection
: pigshare update_article --id 2000077 --article '{"custom_fields": {"field1":"value1"}}'
** Usage (Library)
TODO
History
-------
0.1.0 (2015-01-11)
---------------------
* First release on PyPI.
Python client library and commandline tool for institutional Figshare.
The commandline options are created dynamically from the available api-method wrapper code, which is why some of them might feel a bit clumsy. Also, many of the commands only support values as json-formatted strings. I might change that in the future, but it'd require more complex cli-argparse creation code and I'm not sure whether it's worth it.
** Requirements
- python-dev package (for simplejson compilation I think)
- argparse
- setuptools
- restkit
- booby
- simplejson
- parinx
- pyclist
- argcomplete
** Installation
*** Release
(sudo) pip install https://github.com/UoA-eResearch/pigshare/archive/master.zip
*** Development version from Github
(sudo) pip install https://github.com/UoA-eResearch/pigshare/archive/master.zip
** Usage (commandline client)
*** Connection details
*pigshare* reads a config file $HOME/.pigshare.conf, in the format:
: [default]
: url = https://api.figsh.com/v2
: token = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
(note, this example uses the staging environment)
*pigshare* supports profiles, so you can have multiple profiles in your config file like for example:
: [default]
: url = https://api.figsh.com/v2
: token = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
: [markus]
: url = https://api.figshare.com/v2
: token = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
: [not_markus_but_somebody_else]
: url = https://api.figshare.com/v2
: token = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Now, when you call *pigshare* with the *-p* argument, you can switch between different backends/identities:
: pigshare -p markus list_articles
the command you chose will be using the selected connection parameters.
*** Features:
**** Supported
- creation of articles
- listing of public and private articles
- searching for public and private articles
- updating of articles
- creation of collections
- listing of public and private collections
- searching for public and private collections
- updating of collections
**** TODO
- adding of files to an articles (uploading)
- everything else
*** General usage
For public read access, this is not required.
Basic usage is displayed via:
: pigshare -h
Command specific usage can be displayed via:
: pigshare [command] -h
*** Filtering
(Sub-)commands that display one or more items can be called using an output filter (the **-o** argument before the sub-command). Depending on the sub-command called only certain fields of the items are available (e.g. *list_articles* has only a subset of fields compared to *read_article*).
I'd recommend trying out the command you want to run first, and checking which fields are available, then run the command again with the appropriate filter. A command to list all articles and only display the *doi* and *title* of each article would be:
: pigshare -o doi,title list_articles
*** Commonly used commands
**** Articles
***** List articles
To list all articles and display the *doi*, (internal) *id*, *title*, *url*, and *published_date* for each, issue:
: pigshare list_articles
To display a table with all articles, but only display *doi* and *title*, you can use:
: pigshare -o doi,title list_articles
***** Read an article
To display the properties of an article, use:
: pigshare read_article [article_id]
To display the doi and all tags of a number of articles, use (tags are not part of the 'short' article format that the *list_articles* command returns):
: pigshare -o doi,tags read_article [article_id] [article_id] [article_id]
***** Search for articles
To list all articles matching a search string, issue:
: pigshare search_articles --search_term [search_term]
To display all dois and titles of articles that match a search string:
: pigshare -o doi,title search_articles --search_term [search_term]
**** Collections
Very similar to articles.
*** Other random example calls:
: # create new article
: pigshare create_article --article '{"title": "Markus test", "custom_fields": {"key1": "value"}}'
: # create new collection
: pigshare create_collection --collection '{"title": "Collection markus test", "articles": [2009074,2009075,2009084], "custom_fields": {"test1": "value1"}}'
: # add articles to a collection
: pigshare add_article --collection_id 2761 --article_ids [2009103,2009106]
: # search articles that contain a search_term, display only ids, separated by ',' (useful to copy and paste into 'add_article' command)
: pigshare -o id -s ',' search_my_articles --search_term [search_term]
: # list all of your personal articles, and add all of them to a collection
: for id in `pigshare -o id list_my_articles`; do echo "$id"; pigshare add_article --collection_id 3222 --article_id "$id"; done
: # update/overwrite the title and articles connected to a collection
: pigshare update_collection --id 2761 --collection '{"title": "Collection markus test changed", "articles": [2009074,2009075]}'
: # update/overwrite the categories field in a collection
: pigshare update_article --id 2000077 --article '{"categories": [2]}'
: # update/overwrite the custom_fields of a collection
: pigshare update_article --id 2000077 --article '{"custom_fields": {"field1":"value1"}}'
** Usage (Library)
TODO
History
-------
0.1.0 (2015-01-11)
---------------------
* First release on PyPI.