Metadata-Version: 1.0
Name: simples3
Version: 0.4.1
Summary: Simple, quick Amazon AWS S3 interface
Home-page: http://lericson.blogg.se/code/
Author: Ludvig Ericson
Author-email: ludvig@lericson.se
License: UNKNOWN
Description: `simples3` is a fairly simple, decently quick interface to Amazon's S3 storage
        service.
        
        It grew out of frustration with other libraries that were either written too
        pragmatically (slow), too bloatedly, or just half-done.
        
        The module aims for:
        
        * simplicity,
        * decent speed,
        * non-intrusiveness.
        
        It really is designed to fit into programmer memory. The three basic operations
        are as easy as with dictionaries.
        
        Out of simplicity comes no dependencies - the code relies solely on Python
        standard libraries.
        
        `simples3` requires Python 2.5 or a newer 2.x release.
        
        Usage
        -----
        
        A Simple Amazon AWS S3 interface
        
        And it really is simple.
        
        Setup::
        
        >>> s = S3Bucket(bucket,
        ...              access_key=access_key,
        ...              secret_key=secret_key)
        ...
        >>> print s  # doctest: +ELLIPSIS
        <S3Bucket ... at 'https://s3.amazonaws.com/...'>
        
        or if you'd like to use virtual host S3::
        
        >>> s = S3Bucket(bucket,
        ...              access_key=access_key,
        ...              secret_key=secret_key,
        ...              base_url=base_url)
        >>> print s  # doctest: +ELLIPSIS
        <S3Bucket ... at 'http...'>
        
        Note that missing slash above, it's important. Think of it as
        "The prefix to which all calls are made." Also the scheme can be `https` or
        regular `http`, or any other urllib2-compatible scheme (that is: you can
        register your own.)
        
        Now, let's start doing something useful. Start out by putting a simple file
        onto there::
        
        >>> s.put("my file", "my content")
        
        Alright, and fetch it back::
        
        >>> f = s.get("my file")
        >>> f.read()
        'my content'
        
        Nice and tidy, but what if we want to know more about our fetched file? Easy::
        
        >>> f.s3_info["modify"]  # doctest: +ELLIPSIS
        datetime.datetime(...)
        >>> f.s3_info["mimetype"]
        'application/octet-stream'
        >>> f.s3_info.keys()
        ['mimetype', 'modify', 'headers', 'date', 'size', 'metadata']
        >>> f.close()
        
        Note that the type was octet stream. That's simply because we didn't specify
        anything else. Do that using the `mimetype` keyword argument::
        
        >>> s.put("my new file!", "Improved content!\nMultiple lines!",
        ...       mimetype="text/plain")
        
        Let's be cool and use the very Pythonic API to do fetch::
        
        >>> f = s["my new file!"]
        >>> print f.read()
        Improved content!
        Multiple lines!
        >>> f.s3_info["mimetype"]
        'text/plain'
        >>> f.close()
        
        Great job, huh. Now, let's delete it::
        
        >>> del s["my new file!"]
        
        Could've used the `delete` method instead, but we didn't.
        
        If you just want to know about a key, ask and ye shall receive::
        
        >>> from pprint import pprint
        >>> s["This is a testfile."] = S3File("Hi!", metadata={"hairdo": "Secret"})
        >>> pprint(s.info("This is a testfile."))  # doctest: +ELLIPSIS
        {'date': datetime.datetime(...),
        'headers': {'content-length': '3',
        'content-type': 'application/octet-stream',
        'date': '...',
        'etag': '"..."',
        'last-modified': '...',
        'server': 'AmazonS3',
        'x-amz-id-2': '...',
        'x-amz-meta-hairdo': 'Secret',
        'x-amz-request-id': '...'},
        'metadata': {'hairdo': 'Secret'},
        'mimetype': 'application/octet-stream',
        'modify': datetime.datetime(...),
        'size': 3}
        
        Notable is that you got the metadata parsed out in the `metadata` key. You
        might also have noticed how the file was uploaded, using an `S3File` object
        like that. That's a nicer way to do it, in a way.
        
        The `S3File` simply takes its keyword arguments, and passes them on to `put`
        later. Other than that, it's a str subclass.
        
        And the last dict-like behavior is in tests::
        
        >>> "This is a testfile." in s
        True
        >>> del s["This is a testfile."]
        >>> "This is a testfile." in s
        False
        
        You can also set a canned ACL using `put`, which is too simple::
        
        >>> s.put("test/foo", "test", acl="public-read")
        >>> s.put("test/bar", "rawr", acl="public-read")
        
        Boom. What's more? Listing the bucket::
        
        >>> for (key, modify, etag, size) in s.listdir(prefix="test/"):
        ...     print "%r (%r) is size %r, modified %r" % (key, etag, size, modify)
        ... # doctest: +ELLIPSIS
        'test/bar' ('"..."') is size 4, modified datetime.datetime(...)
        'test/foo' ('"..."') is size 4, modified datetime.datetime(...)
        
        That about sums it up.
        
        Changes in simples3 0.4
        -----------------------
        
        * Minor fixes, released as 0.4 mostly because the previous version naming
        scheme was a bad idea.
        * 0.4.1: Made the put method retry on HTTP 500.
        * 0.4.1: Fix a critical error in signature generation when metadata is given.
        
        Changes in simples3 0.3
        -----------------------
        
        * Add a `url_for` method on buckets which lets you use expiring URLs. Thanks
        t o Pavel Repin.
        * Much better test coverage.
        * `simples3` now works on Python 2.6's `mimetypes` module.
        * r1: Handle HTTP errors in exception parser better, which broke the existence
        test.
        
Platform: UNKNOWN
