1 """
2 Cloud Files python client API.
3
4 Working with result sets:
5
6 >>> import cloudfiles
7 >>> # conn = cloudfiles.get_connection(username='jsmith', api_key='1234567890')
8 >>> conn = cloudfiles.get_connection('jsmith', '1234567890')
9 >>> containers = conn.get_all_containers()
10 >>> type(containers)
11 <class 'cloudfiles.container.ContainerResults'>
12 >>> len(containers)
13 2
14 >>> for container in containers:
15 >>> print container.name
16 fruit
17 vegitables
18 >>> print container[0].name
19 fruit
20 >>> fruit_container = container[0]
21 >>> objects = fruit_container.get_objects()
22 >>> for storage_object in objects:
23 >>> print storage_object.name
24 apple
25 orange
26 bannana
27 >>>
28
29 Setting the argument servicenet=True to get_conection will use the
30 Rackspace ServiceNet network to access Cloud Files (and not the public
31 network) :
32
33 >>> import cloudfiles
34 >>> conn = cloudfiles.get_connection('jsmith', '1234567890', servicenet=True)
35 >>> conn.connection_args[0]
36 'snet-storage4.clouddrive.com'
37
38 If you define the environment variable RACKSPACE_SERVICENET it will automatically
39 connect via the servicenet network.
40
41 Creating Containers and adding Objects to them:
42
43 >>> pic_container = conn.create_container('pictures')
44 >>> my_dog = pic_container.create_object('fido.jpg')
45 >>> my_dog.load_from_file('images/IMG-0234.jpg')
46 >>> text_obj = pic_container.create_object('sample.txt')
47 >>> text_obj.write('This is not the object you are looking for.\\n')
48 >>> text_obj.read()
49 'This is not the object you are looking for.'
50
51 Object instances support streaming through the use of a generator:
52
53 >>> deb_iso = pic_container.get_object('debian-40r3-i386-netinst.iso')
54 >>> f = open('/tmp/debian.iso', 'w')
55 >>> for chunk in deb_iso.stream():
56 .. f.write(chunk)
57 >>> f.close()
58
59 Marking a Container as CDN-enabled/public with a TTL of 30 days
60
61 >>> pic_container.make_public(2592000)
62 >>> pic_container.public_uri()
63 'http://c0001234.cdn.cloudfiles.rackspacecloud.com'
64 >>> my_dog.public_uri()
65 'http://c0001234.cdn.cloudfiles.rackspacecloud.com/fido.jpg'
66
67 Set the logs retention on CDN-enabled/public Container
68
69 >>> pic_container.log_retention(True)
70
71 See COPYING for license information.
72 """
73
74 from cloudfiles.connection import Connection, ConnectionPool
75 from cloudfiles.container import Container
76 from cloudfiles.storage_object import Object
77 from cloudfiles.consts import __version__
78
80 """
81 Helper function for creating connection instances.
82
83 @type username: string
84 @param username: a Mosso username
85 @type api_key: string
86 @param api_key: a Mosso API key
87 @rtype: L{Connection}
88 @returns: a connection object
89 """
90 return Connection(*args, **kwargs)
91