minus 1.1

Python library & command-line utility which interacts with the minus.com (http://minus.com) file sharing service

minus.py


Introduction
------------

minus.py is a Python library which interacts with the minus.com
(http://minus.com) file sharing service.

It provides three layered services:

a) A 'Pythonic' API to the Minus.com REST interface
b) An interactive Minus.com client - modeled on ftp(1)
c) A non-interactive command-line utility to upload/download files
to Minus.com

Pythonic API
------------

The minus library exposes the Minus.com REST interface through a
number of Python proxy objects:

MinusConnection - Low-level connection to REST API
MinusUser - User object
MinusFolder - Folder object
MinusFile - File object

MinusAPIError - API Exception

A simple example of interaction with the API is -

>>> minus = MinusConnection('api_key','api_secret')
>>> minus.authenticate('user','password')
>>> user = minus.activeuser()
>>> print [ f._name for f in user.folders() ]
>>> folder = minus.find('Stuff')
>>> print [ f._name for f in folder.files() ]

(See object docstrings for methods available)

Paging is handled transparently through the PagedList/PagedListIter
classes - these support lazy loading however in general this is
not used through the helper classes.

Interactive Client
------------------

If the module is run directly the __main__ method will call an
interactive CLI client based on the 'cmd' library. This behaves
in a similar way to the ftp(1) client. Basic help and command
line editing are provided through the 'cmd' library.

The available commands are:

cd <folder> Change remote folder
del <files>.. Delete remote files
get <remote> [<local>] Get remote file
lcd <path> Change local directory
lpwd Print local path
ls List remote folder
mget <files>.. Get multiple remote files
mkdir Create remote folder (private)
mkpublic Create remote folder (public)
mput <files>.. Put multiple local files
put <local> [<remote>] Put local file
pwd Print remote folder
rmdir Delete remote folder (deletes contents)
stat <files>.. Print details on remote files

The library supports local/remote globbing and local i/o rediraction - eg.

Remote glob: mget *.jpg (works with mget/del/ls/stat)
Local glob: mput *.txt (works with mput)
Pipe to stdout: get <file> -
Pipe to process: get <file> |less
Pipe from process: put date| date.txt

Note - Minus.com allows multiple folders/files with the same name (the id
attribute provides a unique id)

A simple example of an interactive session is:

# ./minus.py --username <user>
Password:
(Minus:user) [/] : ls
Folder Updated Files Creator Visibility
--------------------------------------------------------------------------------
Stuff 2012-01-08 12:25:44 15 user private
Stuff2 2012-01-08 13:28:04 0 user public
(Minus:paulc) [/] : cd Stuff
--> CWD "Stuff" OK
(Minus:user) [/Stuff] : ls
Name Uploaded Size Title
--------------------------------------------------------------------------------
SNV33271.jpg 2012-01-05 18:36:22 251673 -
SNV33183.jpg 2012-01-05 18:35:57 176134 -
(Minus:paulc) [/Stuff] : get SNV33271.jpg
--> GET "SNV33271.jpg" OK (251673 bytes)
(Minus:user) [/Stuff] : put t1.data
--> PUT "t1.data" OK (13672 bytes)

Command Line Utility
--------------------

If the module is run from the command line with the --get, --put, or
--list-folders options the utility runs non interactively and provides
a simple way of uploading/downloading content - eg.

Upload local files:

./minus.py --user user --put 'Folder Name' <files>

(Folder is created if it doesnt already exist)

Upload local files to public folder:

./minus.py --user user --public --put 'Folder Name' <files>

Download remote files:

./minus.py --user user --get 'Folder Name'

Download matching remote files:

./minus.py --user user --get 'Folder Name' \*.jpg \*.png

(Remember to quote remote glob so that it isn't expanded by the shell)

List Folders:

./minus.py --user user --list-folders

(You can specify the password on the command-line however note that this
will be visible in process args - if not specified will be prompted)

API Key
-------

You must have a valid Minus.com API_KEY/API_SECRET to use the library (see
http://minus.com/pages/api to request an API key). These are normally
passed into the MinusConnection constructor.

To use the CLI client the API_KEY/API_SECRET should be placed in a config
file (by default ~/.minus.conf - can be changed using the --config flag).
The file is in '.ini' format and contains a single [api] section with
api_key and api_secret keys:

[api]
api_key: ...
api_secret: ...

Debugging/Development
---------------------

You can turn on the --debug flag to see the HTTP requests/responses and also
use the --shell flag to drop into an interactive Python interpreter immediately
after authentication where you can experiment with the API - there will be
MinusConnection (minus) and MinusUser (user) variables available.

Dependencies
------------

The module comprises a single file and can be either installed normally using
pip/site-packages etc or just installed & called from a local directory. There
are no dependencies other than the Python interpreter (tested with 2.7 but
should be ok with earlier).

Repository/Issues
-----------------

The master repository is https://bitbucket.org/paulc/minus. Please use the
Issue tracker there to raise any issues.

License
-------

MIT

Author
------

Paul Chakravarti ([e-mail])