import repository from arizona
[raven.git] / 2.0 / python / s3 / README
1 This is one of a collection of interface libraries that can be used to interact
2 with the Amazon S3 system in a number of different languages.  They each expose
3 two main interface classes, AWSAuthConnection and QueryStringAuthGenerator.
4 The first actually performs all the operations using the appropriate libraries
5 for the language, including header signing.  The second,
6 QueryStringAuthGenerator, has the same interface, but instead of performing
7 the operation, this class will return urls with the right query string
8 authentication parameters set.
9
10
11 Basic Operations:
12
13 object requests:
14
15 GetResponse get(bucket_name, key_name) - retrieves an object
16 GetResponse get_acl(bucket_name, key_name) - returns the xml acl doc
17 Response put(bucket_name, key_name, object) - writes an object
18 Response put_acl(bucket_name, key_name, aclXMLDoc) - sets the xml acl doc
19 Response delete(bucket_name, key_name) - deletes an object
20
21 bucket requests:
22
23 Response create_bucket(bucket_name) - creates a bucket
24 ListResponse list_bucket(bucket_name) - lists a bucket's contents
25 GetResponse get_bucket_acl(bucket_name) - returns the xml representation of this bucket's access control list
26 Response put_bucket_acl(bucket_name, acl_xml_doc) - sets xml representation of the bucket acl
27 Response delete_bucket(bucket_name) - delete an empty bucket
28 GetResponse get_bucket_logging(bucket_name) - returns the xml representation of this bucket's access logging configuration
29 Response put_bucket_logging(bucket_name, logging_xml_doc) - sets the xml representation of the bucket logging configuration
30
31 ListAllMyBucketsResponse list_all_my_buckets() - returns a list of all buckets owned by this AWS Access Key Id
32
33
34
35 Dependencies:
36
37 None other than the standard libraries.
38
39
40 Limitations:
41
42 One of the main limitations of these sample AWSAuthConnection implementations
43 is that the interfaces are not streaming.  This means that you have to pass the
44 data in as a string or as a byte array and the operation returns a string or a
45 byte array back.  This is conceptually simpler, and fine for smaller objects,
46 but large objects, say a couple megabytes or greater, will show poor
47 performance, since everything is being passed around in memory.  More
48 sophisticated libraries would pass streams in and out, and would only read the
49 data on-demand, rather than storing it all in memory (S3 itself would have no
50 problem with such streaming applications).  Another upshot of this is that the
51 interfaces are all blocking---that is, you cannot look at the data until all of
52 it has downloaded.  Again, this is fine for smaller objects, but unacceptable
53 for larger ones.
54
55 These libraries have nearly non-existent error handling.  All errors from lower
56 libraries are simply passed up.  The response code in the connection object needs
57 to be checked after each request to verify whether the request succeeded.
58
59 Only the java library has proper handling for repeated headers.  The others
60 assume that each header will have only one value.
61
62 It is our intention that these libraries act as a starting point for future
63 development.  They are meant to show off the various operations and provide an
64 example of how to negotiate the authentication process.
65
66
67
68 This software code is made available "AS IS" without warranties of any        
69 kind.  You may copy, display, modify and redistribute the software            
70 code either by itself or as incorporated into your code; provided that        
71 you do not remove any proprietary notices.  Your use of this software         
72 code is at your own risk and you waive any claim against Amazon               
73 Digital Services, Inc. or its affiliates with respect to your use of          
74 this software code. (c) 2006 Amazon Digital Services, Inc. or its             
75 affiliates.