Rename upload/download methods to clarify directionality.

- 'set_contents*' -> 'upload'.

- 'get_contents* -> 'download'.

Original boto-like names retained as aliases per @jgeewax.

Fixes #148.

Author: tseaver

gcloud/storage/key.py

@@ -162,8 +162,8 @@ def delete(self):
         """
         return self.bucket.delete_key(self)
 
-    def get_contents_to_file(self, file_obj):
-        """Gets the contents of this key to a file-like object.
+    def download_to_file(self, file_obj):
+        """Download the contents of this key into a file-like object.
 
         :type file_obj: file
         :param file_obj: A file handle to which to write the key's data.
@@ -173,31 +173,40 @@ def get_contents_to_file(self, file_obj):
         for chunk in KeyDataIterator(self):
             file_obj.write(chunk)
 
-    def get_contents_to_filename(self, filename):
-        """Get the contents of this key to a file by name.
+    # NOTE: Alias for boto-like API.
+    get_contents_to_file = download_to_file
+
+    def download_to_filename(self, filename):
+        """Download the contents of this key into a named file.
 
         :type filename: string
         :param filename: A filename to be passed to ``open``.
 
         :raises: :class:`gcloud.storage.exceptions.NotFoundError`
         """
         with open(filename, 'wb') as file_obj:
-            self.get_contents_to_file(file_obj)
+            self.download_to_file(file_obj)
+
+    # NOTE: Alias for boto-like API.
+    get_contents_to_filename = download_to_filename
 
-    def get_contents_as_string(self):
-        """Gets the data stored on this Key as a string.
+    def download_as_string(self):
+        """Download the contents of this key as a string.
 
         :rtype: string
         :returns: The data stored in this key.
         :raises: :class:`gcloud.storage.exceptions.NotFoundError`
         """
         string_buffer = StringIO()
-        self.get_contents_to_file(string_buffer)
+        self.download_to_file(string_buffer)
         return string_buffer.getvalue()
 
-    def set_contents_from_file(self, file_obj, rewind=False, size=None,
-                               content_type=None):
-        """Set the contents of this key to the contents of a file handle.
+    # NOTE: Alias for boto-like API.
+    get_contents_as_string = download_as_string
+
+    def upload_from_file(self, file_obj, rewind=False, size=None,
+                         content_type=None):
+        """Upload the contents of this key from a file-like object.
 
         :type file_obj: file
         :param file_obj: A file handle open for reading.
@@ -255,30 +264,25 @@ def set_contents_from_file(self, file_obj, rewind=False, size=None,
 
             bytes_uploaded += chunk_size
 
-    def set_contents_from_filename(self, filename):
-        """Open a path and set this key's contents to the content of that file.
+    # NOTE: Alias for boto-like API.
+    set_contents_from_file = upload_from_file
+
+    def upload_from_filename(self, filename):
+        """Upload this key's contents from the content of f named file.
 
         :type filename: string
         :param filename: The path to the file.
         """
         content_type, _ = mimetypes.guess_type(filename)
 
         with open(filename, 'rb') as file_obj:
-            self.set_contents_from_file(file_obj, content_type=content_type)
+            self.upload_from_file(file_obj, content_type=content_type)
 
-    def set_contents_from_string(self, data, content_type='text/plain'):
-        """Sets the contents of this key to the provided string.
+    # NOTE: Alias for boto-like API.
+    set_contents_from_filename = upload_from_filename
 
-        You can use this method to quickly set the value of a key::
-
-          >>> from gcloud import storage
-          >>> connection = storage.get_connection(project, email, key_path)
-          >>> bucket = connection.get_bucket(bucket_name)
-          >>> key = bucket.new_key('my_text_file.txt')
-          >>> key.set_contents_from_string('This is the contents of my file!')
-
-        Under the hood this is using a string buffer and calling
-        :func:`gcloud.storage.key.Key.set_contents_from_file`.
+    def upload_from_string(self, data, content_type='text/plain'):
+        """Upload contents of this key from the provided string.
 
         :type data: string
         :param data: The data to store in this key.
@@ -293,6 +297,9 @@ def set_contents_from_string(self, data, content_type='text/plain'):
                                     content_type=content_type)
         return self
 
+    # NOTE: Alias for boto-like API.
+    set_contents_from_string = upload_from_string
+
     def has_metadata(self, field=None):
         """Check if metadata is available locally.
 

gcloud/storage/test_key.py

@@ -142,7 +142,7 @@ def test_delete(self):
         key.delete()
         self.assertFalse(key.exists())
 
-    def test_get_contents_to_file(self):
+    def test_download_to_file(self):
         from StringIO import StringIO
         from gcloud._testing import _Monkey
         from gcloud.storage import key as MUT
@@ -153,10 +153,10 @@ def test_get_contents_to_file(self):
         key = self._makeOne(bucket, KEY)
         fh = StringIO()
         with _Monkey(MUT, KeyDataIterator=lambda self: iter(_CHUNKS)):
-            key.get_contents_to_file(fh)
+            key.download_to_file(fh)
         self.assertEqual(fh.getvalue(), ''.join(_CHUNKS))
 
-    def test_get_contents_to_filename(self):
+    def test_download_to_filename(self):
         from tempfile import NamedTemporaryFile
         from gcloud._testing import _Monkey
         from gcloud.storage import key as MUT
@@ -167,13 +167,13 @@ def test_get_contents_to_filename(self):
         key = self._makeOne(bucket, KEY)
         with _Monkey(MUT, KeyDataIterator=lambda self: iter(_CHUNKS)):
             with NamedTemporaryFile() as f:
-                key.get_contents_to_filename(f.name)
+                key.download_to_filename(f.name)
                 f.flush()
                 with open(f.name) as g:
                     wrote = g.read()
         self.assertEqual(wrote, ''.join(_CHUNKS))
 
-    def test_get_contents_as_string(self):
+    def test_download_as_string(self):
         from gcloud._testing import _Monkey
         from gcloud.storage import key as MUT
         _CHUNKS = ['abc', 'def']
@@ -182,10 +182,10 @@ def test_get_contents_as_string(self):
         bucket = _Bucket(connection)
         key = self._makeOne(bucket, KEY)
         with _Monkey(MUT, KeyDataIterator=lambda self: iter(_CHUNKS)):
-            fetched = key.get_contents_as_string()
+            fetched = key.download_as_string()
         self.assertEqual(fetched, ''.join(_CHUNKS))
 
-    def test_set_contents_from_file(self):
+    def test_upload_from_file(self):
         from tempfile import NamedTemporaryFile
         from urlparse import parse_qsl
         from urlparse import urlsplit
@@ -206,7 +206,7 @@ def test_set_contents_from_file(self):
         with NamedTemporaryFile() as fh:
             fh.write(DATA)
             fh.flush()
-            key.set_contents_from_file(fh, rewind=True)
+            key.upload_from_file(fh, rewind=True)
         rq = connection._requested
         self.assertEqual(len(rq), 3)
         self.assertEqual(rq[0]['method'], 'POST')
@@ -231,7 +231,7 @@ def test_set_contents_from_file(self):
         self.assertEqual(rq[2]['data'], DATA[5:])
         self.assertEqual(rq[2]['headers'], {'Content-Range': 'bytes 5-5/6'})
 
-    def test_set_contents_from_filename(self):
+    def test_upload_from_filename(self):
         from tempfile import NamedTemporaryFile
         from urlparse import parse_qsl
         from urlparse import urlsplit
@@ -252,7 +252,7 @@ def test_set_contents_from_filename(self):
         with NamedTemporaryFile(suffix='.jpeg') as fh:
             fh.write(DATA)
             fh.flush()
-            key.set_contents_from_filename(fh.name)
+            key.upload_from_filename(fh.name)
         rq = connection._requested
         self.assertEqual(len(rq), 3)
         self.assertEqual(rq[0]['method'], 'POST')
@@ -277,7 +277,7 @@ def test_set_contents_from_filename(self):
         self.assertEqual(rq[2]['data'], DATA[5:])
         self.assertEqual(rq[2]['headers'], {'Content-Range': 'bytes 5-5/6'})
 
-    def test_set_contents_from_string(self):
+    def test_upload_from_string(self):
         from urlparse import parse_qsl
         from urlparse import urlsplit
         KEY = 'key'
@@ -294,7 +294,7 @@ def test_set_contents_from_string(self):
         bucket = _Bucket(connection)
         key = self._makeOne(bucket, KEY)
         key.CHUNK_SIZE = 5
-        key.set_contents_from_string(DATA)
+        key.upload_from_string(DATA)
         rq = connection._requested
         self.assertEqual(len(rq), 3)
         self.assertEqual(rq[0]['method'], 'POST')