Add metadata to get, fget and get_partial methods

docs/API.md

@@ -567,6 +567,7 @@ __Parameters__
 |:---|:---|:---|
 |``bucket_name``   |_string_   |Name of the bucket.   |
 |``object_name``   |_string_   |Name of the object.   |
+|``metadata``      |_dict_   |Any additional metadata. (optional, defaults to None).   |
 
 __Return Value__
 
@@ -600,6 +601,7 @@ __Parameters__
 |``object_name``   |_string_  |Name of the object.   |
 |``offset``   |_int_ |``offset`` of the object from where the stream will start.   |
 |``length``   |_int_ |``length`` of the object that will be read in the stream (optional, if not specified we read the rest of the file from the offset).   |
+|``metadata``      |_dict_   |Any additional metadata. (optional, defaults to None).   |
 
 __Return Value__
 
@@ -631,7 +633,8 @@ __Parameters__
 |:---|:---|:---|
 |``bucket_name``   |_string_   |Name of the bucket.   |
 |``object_name``   |_string_    |Name of the object.   |
-|``file_path``   |_string_ | Path on the local filesystem to which the object data will be written. |
+|``metadata``   |_dict_ | Any additional metadata. (optional, defaults to None). |
+|``file_path``   |_dict_ | Path on the local filesystem to which the object data will be written. |
 
 __Return Value__
 

examples/put_and_get_encrypted_object.py

@@ -0,0 +1,41 @@
+import base64
+from io import BytesIO
+import hashlib
+
+from minio.api import Minio
+
+AWSAccessKeyId = ''
+AWSSecretKey = ''
+
+STORAGE_ENDPOINT = 's3.amazonaws.com'
+STORAGE_BUCKET = ''
+
+
+def main():
+    content = BytesIO(b'Hello again')
+
+    key = b'32byteslongsecretkeymustprovided'
+    encryption_key = base64.b64encode(key).decode()
+    encryption_key_md5 = base64.b64encode(hashlib.md5(key).digest()).decode()
+
+    minio = Minio(STORAGE_ENDPOINT, access_key=AWSAccessKeyId, secret_key=AWSSecretKey)
+
+    # Put object with special headers which encrypt object in S3 with provided key
+    minio.put_object(STORAGE_BUCKET, 'test_crypt.txt', content, content.getbuffer().nbytes,
+                     metadata={
+                         'x-amz-server-side-encryption-customer-algorithm': 'AES256',
+                         'x-amz-server-side-encryption-customer-key': encryption_key,
+                         'x-amz-server-side-encryption-customer-key-MD5': encryption_key_md5
+                     })
+
+    # Get decrypted object with same headers
+    obj = minio.get_object(STORAGE_BUCKET, 'test_crypt1.txt', metadata={
+        'x-amz-server-side-encryption-customer-algorithm': 'AES256',
+        'x-amz-server-side-encryption-customer-key': encryption_key,
+        'x-amz-server-side-encryption-customer-key-MD5': encryption_key_md5
+    })
+
+    print(obj.read())
+
+if __name__ == '__main__':
+    main()

minio/api.py

@@ -688,7 +688,7 @@ def fput_object(self, bucket_name, object_name, file_path,
         # Return etag here.
         return mpart_result.etag
 
-    def fget_object(self, bucket_name, object_name, file_path):
+    def fget_object(self, bucket_name, object_name, file_path, metadata=None):
         """
         Retrieves an object from a bucket and writes at file_path.
 
@@ -698,6 +698,7 @@ def fget_object(self, bucket_name, object_name, file_path):
         :param bucket_name: Bucket to read object from.
         :param object_name: Name of the object to read.
         :param file_path: Local file path to save the object.
+        :param metadata: Any additional metadata to be added to GET request's headers.
         """
         is_valid_bucket_name(bucket_name)
         is_non_empty_string(object_name)
@@ -723,7 +724,7 @@ def fget_object(self, bucket_name, object_name, file_path):
             # Get partial object.
             response = self._get_partial_object(bucket_name, object_name,
                                                 offset=file_statinfo.st_size,
-                                                length=0)
+                                                length=0, metadata=metadata)
 
             # Save content_size to verify if we wrote more data.
             content_size = int(response.headers['content-length'])
@@ -756,7 +757,7 @@ def fget_object(self, bucket_name, object_name, file_path):
         # Return the stat
         return stat
 
-    def get_object(self, bucket_name, object_name):
+    def get_object(self, bucket_name, object_name, metadata=None):
         """
         Retrieves an object from a bucket.
 
@@ -771,16 +772,18 @@ def get_object(self, bucket_name, object_name):
 
         :param bucket_name: Bucket to read object from
         :param object_name: Name of object to read
+        :param metadata: Any additional metadata to be added to GET request's headers.
         :return: :class:`urllib3.response.HTTPResponse` object.
 
         """
         is_valid_bucket_name(bucket_name)
         is_non_empty_string(object_name)
 
         return self._get_partial_object(bucket_name,
-                                        object_name)
+                                        object_name,
+                                        metadata=metadata)
 
-    def get_partial_object(self, bucket_name, object_name, offset=0, length=0):
+    def get_partial_object(self, bucket_name, object_name, offset=0, length=0, metadata=None):
         """
         Retrieves an object from a bucket.
 
@@ -801,6 +804,7 @@ def get_partial_object(self, bucket_name, object_name, offset=0, length=0):
            Must be >= 0.
         :param length: Optional number of bytes to retrieve.
            Must be an integer.
+        :param metadata: Any additional metadata to be added to GET request's headers.
         :return: :class:`urllib3.response.HTTPResponse` object.
 
         """
@@ -809,7 +813,8 @@ def get_partial_object(self, bucket_name, object_name, offset=0, length=0):
 
         return self._get_partial_object(bucket_name,
                                         object_name,
-                                        offset, length)
+                                        offset, length,
+                                        metadata=metadata)
 
     def copy_object(self, bucket_name, object_name, object_source,
                     conditions=None):
@@ -1445,7 +1450,7 @@ def presigned_post_policy(self, post_policy):
 
     # All private functions below.
     def _get_partial_object(self, bucket_name, object_name,
-                            offset=0, length=0):
+                            offset=0, length=0, metadata=None):
         """Retrieves an object from a bucket.
 
         Optionally takes an offset and length of data to retrieve.
@@ -1466,13 +1471,18 @@ def _get_partial_object(self, bucket_name, object_name,
            Must be >= 0.
         :param length: Optional number of bytes to retrieve.
            Must be > 0.
+        :param metadata: Any additional metadata to be uploaded along
+            with request.
         :return: :class:`urllib3.response.HTTPResponse` object.
 
         """
         is_valid_bucket_name(bucket_name)
         is_non_empty_string(object_name)
 
         headers = {}
+        if metadata:
+            headers = metadata
+
         if offset != 0 or length != 0:
             request_range = '{}-{}'.format(
                 offset, "" if length == 0 else offset + length - 1

tests/functional/tests.py

@@ -138,14 +138,16 @@ def main():
     client.stat_object(bucket_name, object_name+'-copy')
 
     # Get a full object
-    object_data = client.get_object(bucket_name, object_name)
+    object_data = client.get_object(bucket_name, object_name,
+                                    metadata={'x-amz-meta-testing': 'value'})
     with open('newfile', 'wb') as file_data:
         for data in object_data:
             file_data.write(data)
     file_data.close()
 
     # Get a full object locally.
-    client.fget_object(bucket_name, object_name, 'newfile-f')
+    client.fget_object(bucket_name, object_name, 'newfile-f',
+                       metadata={'x-amz-meta-testing': 'value'})
 
     client.fput_object(bucket_name, object_name+'-f', 'testfile',
                        metadata={'x-amz-meta-testing': 'value'})