Cloud Files Python Binding Cookbook
This article shows how you can use the python-cloudfiles python binding to interact with your Cloud Files account. It is designed as a companion to the Cloud Files Curl cookbook article. It shows how to use the Python binding to do all the same things that the curl article shows how to do with curl.
The Basics
Python is a scripting language. You can use it to write programs that automate or simplify tasks you would otherwise have to carry out using a GUI or by typing in a series of commands. The Python binding for the Cloud Files API makes it easier for you to use the API with Python. It does this by providing a series of Python objects that you can use to manipulate the contents of your Cloud Files account.
Getting Started
For instructions on installing the python-cloudfiles binding, please take a look at our Python installation guide. This article assumes you have a certain amount of knowledge regarding the use of Python however it has been broken down such that most people should be able to follow along. Although this guide is not designed to teach you how to use Python, it is worth covering some basics to make this article a bit more accessible.
To create a python script, first open a text file and enter the code you want to run, then save the file e.g. " my_script.py" To run the script at the command line, type "python my_script.py" then hit Enter.
Using the Binding
Load Binding:
Now that you know how to create a script or start the interactive Python prompt we can begin. The first thing you need to do in your script or the interpreter is to load the code provided by the binding. This is done with the import statement.import cloudfiles
Create Connection:
Now that we have made the code available to use in our scripts we can make use of it. Lets start by making a connection object. This object holds all the information required to make an authenticated request to the Cloud Files API. Note: By default the connection object will authenticate against the US API. If you have a UK Cloud Files account an extra parameter is required.
#For US accounts
conn = cloudfiles.Connection('myusername', 'myapikey')
#For UK accounts
conn = cloudfiles.Connection('myusername', 'myapikey', authurl=cloudfiles.consts.uk_authurl)
Using this connection object, we can now start to interact with our Cloud Files account. Note: if you are using the binding on a Cloud Server located in the same data centre as your Cloud Files account, you can specify the parameter servicenet=True when you create the connection, so that the traffic uses the data centre's internal network. Traffic over ServiceNet does not incur bandwidth charges.
Listing Containers:
The first thing we're going to try is to list the containers on your account. One thing to bear in mind with the binding is that it can represent the data in multiple ways. One way is to produce a list of strings, each one the name of a different container. Another representation is as a list of container objects that can then be used to manipulate individual containers. conts is a list of three strings, each one the name of a container.
conts = conn.list_containers()print conts['backup', 'cloudservers','images', 'static']
conts is a container item result set which holds container objects, these container objects can be used to hold information about the respective container and are used to manipulate the container.
conts = conn.get_all_containers()print contsContainerResults: 4 containers
It is also possible to list the containers with more details including information such as the container size and the number of objects within the container.
conts = conn.list_containers_info()print conts[{u'count': 1, u'bytes': 54770176, u'name': u'backup'}, {u'count': 0, u'bytes': 0, u'name': u'cloudservers'}, {u'count': 3, u'bytes': 174686, u'name': u'images'}, {u'count': 0, u'bytes': 0, u'name': u'static'}]
Creating a Container:
Creating a container is nice and simple, once you have a name for the container you just need to pass it as an argument to the create_container method. The object returned is a container object representing the new container you have just created.
cont = conn.create_container('newcontainer')print contnewcontainer
Deleting a Container:
A container may be deleted by issuing a DELETE request, but keep in mind that only empty containers may be deleted. If a container currently has objects within it, then those objects must first be deleted.
conn.delete_container('newcontainer')Traceback (most recent call last):File "", line 1, inFile "/usr/local/lib/python2.7/site-packages/python-cloudfiles/cloudfiles/connection.py", line 275, in delete_containerraise ContainerNotEmpty(container_name)cloudfiles.errors.ContainerNotEmpty: Cannot delete non-empty Container newcontainer
When a container is successfully deleted nothing is returned.conn.delete_container('newcontainer')
Listing Objects:
Once you have a container object it is possible to list the objects within that container. By default only the first 10,000 objects are returned. The following lists the objects of a container called images:
cont = conn.get_container('images')print cont.list_objects()['banner.jpg', 'cloud.png', 'rackspace.jpg']
It is also possible get a more detailed object listing to view additional information about the objects such as size and content-type:
print cont.list_objects_info()[{u'bytes': 26326, u'last_modified': u'2012-02-01T12:47:22.911070', u'hash': u'9ed61f72b1f3777ff01b7ce128a67244', u'name': u'banner.jpg', u'content_type': u'image/jpeg'}, {u'bytes': 106206, u'last_modified': u'2012-02-01T12:47:24.130690', u'hash': u'8b31a0109b2998a0e42efa29859bde24', u'name': u'cloud.png', u'content_type': u'image/png'}, {u'bytes': 42154, u'last_modified': u'2012-02-01T12:47:25.235390', u'hash': u'cbf00714f4dcc0724ddbe4028f76814e', u'name': u'rackspace.jpg', u'content_type': u'image/jpeg'}]
It is possible to list more than 10,000 objects or to filter by specific objects by passing some additional parameter options. Please refer to the List Objects API documentation for more detailed information on the available parameters and how they work and take a look at the binding code to see how to use them.
Downloading an Object:
To download an object we have to get it and then save it. The following gets the object cloud.png and saves it in the current directory on your computer with the filename cloud.png.
obj = cont.get_object('cloud.png')obj.save_to_filename('cloud.png')
Uploading an Object:
To upload a new object to a container, you need to create the object and the load the file. The below example will upload a file called style.css to a container called static with a content-type of text/css.
Note: Setting the correct content-type is important depending on where the object will be used. The binding will attempt to guess the content-type of any object if it is not explicitly set.
cont = conn.get_container('static')obj = cont.create_object('style.css')#if the content_type is not specified the binding will attempt to guess the correct typeobj.content_type = 'text/css'obj.load_from_filename('style.css')
It is also possible to upload an object to make it appear as if the object is part of a directory structure. This is accomplished by naming the object with the full path including the directory components. This is useful when publishing containers to the CDN as the resulting CDN URL will appear as if it was part of a directory structure and is generally more organised. For example, repeating the above, but instead naming the style.css object so that it becomes css/style.css:
obj = container.create_object('css/style.css')#if the content_type is not specified the binding will attempt to guess the correct typeobj.content_type = 'text/css'obj.load_from_filename('style.css')
Deleting an Object:
Deleting an object requires you to run the container's delete object method and specify the object to be deleted.
cont.delete_object('style.css')
Performing a Server Side Copy:
By doing a server side copy it is possible to copy an existing object to a new storage location without having to go through the expense of performing the data upload from the client side. By combining server side copies with object deletion it is possible to do object moves and rename operations by first copying the object to the new location or name and then performing a delete on the original. Copying is not restricted to a single container.
The following example will copy the rackspace.jpg file to a new name of rackspace.jpeg in the images container:
obj = cont.get_object('rackspace.jpg')obj.copy_to('images', 'rackspace.jpeg')
Updating Object Headers:
It is possible to update certain HTTP headers corresponding to an object with the sync_metadata method. The most useful usage of this functionality is to correct an incorrectly set Content-Type header. Other headers that may also be set include the CORS and Content-Disposition headers.
The following is an example of how to update the Content-Type of an image to image/jpeg:
obj = cont.get_object('rackspace.jpg')obj.headers['Content-Type'] = 'image/jpeg'obj.sync_metadata()
CDN Operations:
The binding also includes the ability to modify parameters relating to the CDN.
Listing CDN Enabled Containers:
The container object you create has the relavent method for listing the public containers:
conn.list_public_containers()['files', 'static']
CDN Enabling a Container:
Before a container can have CDN operations performed on it, the container needs to be CDN enabled.
The following will enable and publish the images container:
cont = conn.get_container('images')cont.make_public()
Viewing a Container's CDN Details:
A container object has a number of attributes set which relate to the CDN. Viewable information includes whether the container is CDN enabled, if CDN logging is turned on and the currently set TTL as well as the various CDN domain names that can be used to reference content within the container.
The following show you how to print out the CDN details of the images container and the reponses:
print cont.is_public()True
print cont.public_uri()'http://c4965949.r49.cf2.rackcdn.com'
print cont.public_ssl_uri()'https://c4965949.ssl.cf2.rackcdn.com'
print cont.public_streaming_uri()'http://c4965949.r49.stream.cf2.rackcdn.com'
print cont.cdn_ttl259200
print cont.cdn_log_retentionFalse
Updating a Container's CDN Attributes:
The following shows how to update some of the attributes associated with a CDN container:
#To remove a container from the CDNcont.make_private()#To make a container publicly accessiblecont.make_public()#To change the TTL on a container or make it public with a speicific TTLcont.make_public(ttl=172800)#To enable CDN log retentioncont.log_retention(log_retention=True)
Purging an Object:
It is possible to force content removal from the CDN by issuing a CDN purge request. The purge request can only be done on a per object basis. The purge request will schedule a job with the CDN to have the indicated content removed from all member nodes of the CDN and can take some time to complete. It is possible to pass through a comma-separated list of e-mails so that a notification will be sent when the purge is completed.
At the time of writing only 25 purges may be done per account per day. If a container level purge needs to be performed, please contact support via a ticket naming the container to be purged and we can do this on your behalf. If a notification e-mail is required, please also let us know the desired e-mail(s) to use.
The following will perform a CDN purge of the rackspace.png file from the images container with a notification e-mail set to user@example.com:
cont = conn.get_container('images')obj = cont.get_object('rackspace.png')obj.purge_from_cdn(email='user@example.com')
Summary:
This article is meant to serve as a quick reference to the more common Cloud Files API requests and how to make them with the Python binding for Cloud Files. For more information on other features that the Cloud Files API offers please refer to the our Cloud Files API documentation. For more information on the Python binding take a look at the code on GitHub.
© 2011-2013 Rackspace US, Inc.
Except where otherwise noted, content on this site is licensed under a Creative Commons Attribution-NonCommercial-NoDerivs 3.0 Unported License
See license specifics and DISCLAIMER
0 Comments
Add new comment