pybox

INTRODUCTION

pybox is a Python API/client that manipulates files on box.com (a.k.a box.net). It can display user's account information, file structure, and file information, manage(move/rename/delete/upload/download) files and directories, and most importantly, it can recursively compare and synchronize directories between client and server.

USAGE

Please take the following steps:

1. Obtain an API key from here.

2. Copy boxrc.example to user's home directory, rename it to .boxrc in a POSIX system (e.g. Unix, Linux, Mac OS X) or _boxrc in a non-POSIX system(e.g. Windows).

3. Edit .boxrc/_boxrc: replace api_key's value(YOUR_API_KEY) with the API key you've got in step 1.

4. Copy box-logging.conf.example to box-logging.conf.

5. Edit(optionally) box-logging.conf, e.g. change 'BOX.LOG' to different name or path. If you'd like to put this log configuration file to a different directory, don't forget to add an environment variable named LOG_CONF_DIR.

6. Open a command terminal, change directory to the pybox directory, then run:

   python pybox/boxclient.py -U YOUR_LOGIN_EMAIL -p -a

   Replace the above email with your actual login email on box.net, and type your password when prompted. If login/password combination is correct, you will get your auth token from the output(something like "auth_token: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

7. Edit .boxrc/_boxrc again. Replace(or add) account section(YOUR_ACCOUNT_LOGIN) with your login(actually, it can be any string, not necessarily the same as your box login email), replace auth_token value(YOUR_AUTH_TOKEN) with the one you've got in step 6.

8. If you have multiple box accounts, just repeat step 6 and 7.

If everything goes smoothly, you are now free to manipulate your files on the box account(s) without typing password any more. Generally the command is:

python pybox/boxclient.py -U YOUR_LOGIN [options] [args]

Please be noticed that this time YOUR_LOGIN is the string you set in step 7.

All supported options are listed as follows:

• -U, --username specify username/email

• -p, --password prompt password (only needed when auth_token is not found)

• -a, --auth-token print auth token

• -I, --account-info get box account information

• -t, --target specify target type(f for file<default>, d for directory)

• -l, --list list directory

• -w, --what-id get a path(server-side)'s id

• -i, --info get file information

• -M, --mkdir make a directory

• -R, --remove remove a file or directory

• -m, --move move a file or directory

• -r, --rename rename a file or directory

• -1, --onelevel list one level files

• -z, --zip list file tree in zip format

• -N, --nofiles only list directory

• -s, --simple show simple information

• -c, --chdir change directory

• -d, --download download file

• -u, --upload upload file

• -P, --plain-name use plain name(server-side) instead of id

• -C, --compare compare local and remote directories

• -S, --sync sync local and remote directories

• -n, --dry-run show what would have been transferred when sync

• -f, --from-file read arguments from file(arguments separated by line break)

EXAMPLES

Assume all the following operations are performed on Bob's account.

• show account information:

    python pybox/boxclient.py -Ubob -I
  

• list all files(caution: this could be VERY VERY slow):

    python pybox/boxclient.py -Ubob -l 0 (0 is the root id)
  

• list all first-level files with fewer details:

    python pybox/boxclient.py -Ubob -ls1 0
  

• create a directory dir1 under root:

    python pybox/boxclient.py -Ubob -M dir1
  

• create a directory dir2 under dir1:

    python pybox/boxclient.py -Ubob -P -c dir1 -M dir2
  

• get directory dir1/dir2(starting from root)'s id:

    python pybox/boxclient.py -Ubob -w dir1/dir2
  

• upload file file1, file2 and directory dir3 to root directory:

    python pybox/boxclient.py -Ubob -u file1 file2 dir3
  

• upload file3 to a directory whose id is 1005691453

    python pybox/boxclient.py -Ubob -c1005691453 -u file3
  

• upload file4 to a directory whose path is 'path1/path2'(starting from root)

    python pybox/boxclient.py -Ubob -P -c path1/path2 -u file4
  

• remove a file whose id is 1005181453

    python pybox/boxclient.py -Ubob -R 1005181453
  

• remove a directory whose path is path1/path2(starting from root)

    python pybox/boxclient.py -Ubob -PR -td path1/path2
  

• rename file file1 to file1.new, file file2 to file2.new

    python pybox/boxclient.py -Ubob -Pr file1 file1.new file2 file2.new
  

• rename directory dir1 to dir2

    python pybox/boxclient.py -Ubob -Pr -td dir1 dir2
  

• move a file with id 1025611460 to a directory with id 225236230

    python pybox/boxclient.py -Ubob -m 1025611460 225236230
  

• move directory dir1 to directory dir2, directory dir3/dir4 to directory dir5/dir6/dir7

    python pybox/boxclient.py -Ubob -td -Pm dir1 dir2 dir3/dir4 dir5/dir6/dir7
  

• download a directory dir1/dir2

    python pybox/boxclient.py -Ubob -td -Pd dir1/dir2
  

• compare a local directory /Users/bob/dir1 with a remote directory dir2/dir3

    python pybox/boxclient.py -Ubob -td -PC /Users/bob/dir1 dir2/dir3
  

• sync a local directory /Users/bob/dir1(source) with a remote directory dir2/dir3(destination)

    python pybox/boxclient.py -Ubob -PS /Users/bob/dir1 dir2/dir3
  

REFERENCE

Box API documentation

LICENSE

Copyright 2011-2012 Hui Zheng

Released under the MIT License.