A simple library for interacting with Amazon S3.
Switch branches/tags
Clone or download
kennethreitz Merge pull request #15 from spbrien/master
Enables setting Content-Type for S3 objects
Latest commit 2d79584 May 30, 2017
Failed to load latest commit information.
tests Add unit tests and Travis CI Apr 22, 2017
HISTORY.txt update history/readme Jan 27, 2017
LICENSE layer up Jan 27, 2017
Pipfile basics in place Jan 27, 2017
Pipfile.lock updated pipfile.lock for python3 Jan 27, 2017
bucketstore.py Merge pull request #15 from spbrien/master May 30, 2017
setup.py v0.1.2 Jan 27, 2017
tox.ini Add unit tests and Travis CI Apr 22, 2017


BucketStore: A simple Amazon S3 Client, for Python.

BucketStore is a very simple Amazon S3 client, written in Python. It aims to be much more straight-forward to use than boto3, and specializes only in Amazon S3, ignoring the rest of the AWS ecosystem.


  • Treats S3 Buckets as Key/Value stores.
  • Automatic support for AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables.
  • Easily make keys (or entire buckets) publically accessable.
  • Easily get the public URL for a given key.
  • Generates temporary URLs for a given key.


Get (or create) a bucket, easily:

import bucketstore

# Create the bucket if it doesn't exist.
bucket = bucketstore.get('bucketstore-playground', create=True)

Treat the bucket like a key/value store:

>>> bucket
<S3Bucket name='bucketstore-playground'>

>>> bucket['foo'] = 'bar'
>>> bucket['foo']

>>> bucket.set('foo2', 'bar2')
>>> bucket.get('foo2')

>>> bucket.list()
[u'foo', u'foo2']

>>> bucket.all()
[<S3Key name=u'foo' bucket='bucketstore-playground'>, <S3Key name=u'foo2' bucket='bucketstore-playground'>]

Interact with S3 keys:

>>> bucket.key('foo')
<S3Key bucket='bucketstore-playground' name=u'foo'>

>>> foo = _
>>> foo.set('new value')

# Generate a temporary share URL.
>>> foo.temp_url(duration=1200)

# Make key publically accessable.
>>> foo.make_public()
>>> foo.url

# Get / set metadata for key.
>>> foo.meta = {'foo': 'bar'}
>>> foo.meta
{'foo': 'bar}

# Rename key to 'foo3'.
>>> foo.rename('foo3')

# Delete the key.
>>> foo.delete()

# Create a key with metadata at the same time.
>>> foo = bucket.key('foo.html')
>>> foo.set('<h1>bar</h1>', {'content_type': 'text/html'})

Other methods include bucketstore.login(access_key_id, secret_access_key), bucketstore.list(), and bucketstore.get(bucket_name, create=False).


Tests are run through Tox.

# Run tests against all environments.
$ tox
# Run against a specific version.
$ tox -e py35
# Run with pytest arguments.
$ tox -- --pdb


$ pip install bucketstore