docs: Add an example of how to specify canned ACL when uploading an object in the S3 driver.
Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/c677de30 Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/c677de30 Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/c677de30 Branch: refs/heads/trunk Commit: c677de3093118dbd33b3077afb3cc34009386d91 Parents: 7f1ad37 Author: Tomaz Muraus <[email protected]> Authored: Fri Jan 17 05:03:50 2014 +0100 Committer: Tomaz Muraus <[email protected]> Committed: Fri Jan 17 05:05:07 2014 +0100 ---------------------------------------------------------------------- docs/examples/storage/s3/upload_object_acls.py | 19 ++++++++++++++++ docs/storage/drivers/s3.rst | 24 +++++++++++++++++++++ 2 files changed, 43 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/libcloud/blob/c677de30/docs/examples/storage/s3/upload_object_acls.py ---------------------------------------------------------------------- diff --git a/docs/examples/storage/s3/upload_object_acls.py b/docs/examples/storage/s3/upload_object_acls.py new file mode 100644 index 0000000..9f07462 --- /dev/null +++ b/docs/examples/storage/s3/upload_object_acls.py @@ -0,0 +1,19 @@ +from libcloud.storage.types import Provider +from libcloud.storage.providers import get_driver + +FILE_PATH = '/home/user/myfile.tar.gz' + +cls = get_driver(Provider.S3) +driver = cls('api key', 'api secret key') + +container = driver.get_container(container_name='my-backups-12345') + +# This method blocks until all the parts have been uploaded. +extra = {'content_type': 'application/octet-stream', + 'acl': 'public-read'} + +with open(FILE_PATH, 'rb') as iterator: + obj = driver.upload_object_via_stream(iterator=iterator, + container=container, + object_name='backup.tar.gz', + extra=extra) http://git-wip-us.apache.org/repos/asf/libcloud/blob/c677de30/docs/storage/drivers/s3.rst ---------------------------------------------------------------------- diff --git a/docs/storage/drivers/s3.rst b/docs/storage/drivers/s3.rst index f3213ff..20776e5 100644 --- a/docs/storage/drivers/s3.rst +++ b/docs/storage/drivers/s3.rst @@ -39,4 +39,28 @@ you can even upload / create empty objects. .. literalinclude:: /examples/storage/s3/multipart_large_file_upload.py :language: python +2. Specifying canned ACL when uploading an object +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you want to specify custom ACL when uploading an object, you can do so by +passing ``extra`` argument with the ``acl`` attribute to the upload methods. + +Valid values for this attribute are: + +* ``private`` (default) +* ``public-read`` +* ``public-read-write`` +* ``authenticated-read`` +* ``bucket-owner-read`` +* ``bucket-owner-full-control`` + +For example: + +.. literalinclude:: /examples/storage/s3/upload_object_acls.py + :language: python + +For more information about the canned ACLs, please refer to the `Canned ACL` +section of the Amazon S3 documentation. + .. _`Amazon Simple Storage Service (Amazon S3)`: http://aws.amazon.com/s3/ +.. _`Canned ACL`: http://docs.aws.amazon.com/AmazonS3/latest/dev/ACLOverview.html#CannedACL
