In storage.Key.get_contents_to_filename, improve error checking and exception handling and add timestamp to file object

From TODO:

    # TODO: Add good error checking.
    # TODO: Add good exception handling.
    # TODO: Set timestamp? Make optional, default being to set it if possible?

Also, consider renaming get_contents_to_filename and get_contents_to_file. The get is a misleading verb, since a read into a file is what is happening.

See gcloud.storage.Key.get_contents_to_filename for relevant code and #146 for some context.

git blame output

b7f1b774 (JJ Geewax   2014-01-29 18:02:29 -0500 169)     # TODO: Add good error checking.
b7f1b774 (JJ Geewax   2014-01-29 18:02:29 -0500 170)     # TODO: Add good exception handling.
b7f1b774 (JJ Geewax   2014-01-29 18:02:29 -0500 171)     # TODO: Set timestamp? Make optional, default being to set it if possible?

@jgeewax

@jgeewax WRT raising / handling errors: the open() call will raise IOError on failure: ISTM that we can just let that error propagate, as with any error raised by self.get_contents_to_file().

WRT the timestamp: we open the file in 'wb' mode, which will cause its mtime to be updated by the OS. Are you suggesting that we set the timestamp to a different value (e.g., based on some metadata?) We aren't saving any such metadata when uploading.

@dhermes

@dhermes : The naming was based on boto's names.

@tseaver : Re open() call, you mean if the filename is invalid ? i agree it's fine to let that propagate up.. i wouldn't expect that error to get caught.

Re timestamp: I think my thought was that we could set the last modified time of the local file to the last modified time of the object in GCS. i wouldn't mind if we decided to scrap that all together though...

WRT naming: I would prefer names like save_contents_to_filename and upload_contents_from_filename, which make the directionality unambiguous.

#311 tracks the enhancement for synchronizing the file's mtime.

@tseaver

WRT naming: I like @tseaver proposal. If we do the change, I think we should make the naming uniform for all the get_contents_* and save_contents_* methods (a total of 6).