Package: datastore
# datastore## simple, unified API for multiple data storesdatastore is a generic layer of abstraction for data store and database access.It is a **simple** API with the aim to enable application development in adatastore-agnostic way, allowing datastores to be swapped seamlessly withoutchanging application code. Thus, one can leverage different datastores withdifferent strengths without committing the application to one datastorethroughout its lifetime. It looks like this:+---------------+|  application  |    <--- No cumbersome SQL or Mongo specific queries!+---------------+|            <--- simple datastore API calls+---------------+|   datastore   |    <--- datastore implementation for underlying db+---------------+|            <--- database specific calls+---------------+|  various dbs  |    <--- MySQL, Redis, MongoDB, FS, ...+---------------+In addition, grouped datastores significantly simplify interesting data accesspatterns (such as caching and sharding).## About### InstallFrom pypi (using pip):sudo pip install datastoreFrom pypi (using setuptools):sudo easy_install datastoreFrom source:git clone https://github.com/datastore/datastore/cd datastoresudo python setup.py install### Subprojects* [datastore.aws](https://github.com/datastore/datastore.aws) - aws s3 implementation* [datastore.git](https://github.com/datastore/datastore-git) - git implementation* [datastore.mongo](https://github.com/datastore/datastore.mongo) - monogdb implementation* [datastore.memcached](https://github.com/datastore/datastore.memcached) - memcached implementation* [datastore.pylru](https://github.com/datastore/datastore.pylru) - pylru cache implementation* [datastore.redis](https://github.com/datastore/datastore.redis) - redis implementation### DocumentationThe documentation can be found at:http://datastore.readthedocs.org/en/latest/### Licensedatastore is under the MIT License.### Contactdatastore is written by [Juan Batiz-Benet](https://github.com/jbenet). Itwas originally part of [py-dronestore](https://github.com/jbenet/py-dronestore).On December 2011, it was re-written as a standalone project.Project Homepage:[https://github.com/datastore/datastore](https://github.com/datastore/datastore)Feel free to contact me. But please file issues in github first. Cheers!## Contributing### ImplementationsPlease write and contribute implementations for other data stores. This projectcan only be complete with lots of help.### StylePlease follow proper pythonic style in your code.See [PEP 8](http://www.python.org/dev/peps/pep-0008/) and the [Google PythonStyle Guide](http://google-styleguide.googlecode.com/svn/trunk/pyguide.html).### DocsPlease document all code. ``datastore`` uses ``sphinx`` for documentation. Takea look at the ``docs/`` directory.To make sure the documentation compiles, run:cd docsmake htmlopen .build/html/index.htmlWhich should -- if all goes well -- open your favorite browser on thenewly-built docs.## Examples### Hello World>>> import datastore.core>>> ds = datastore.DictDatastore()>>>>>> hello = datastore.Key('hello')>>> ds.put(hello, 'world')>>> ds.contains(hello)True>>> ds.get(hello)'world'>>> ds.delete(hello)>>> ds.get(hello)None#### Hello filesystem>>> import datastore.filesystem>>>>>> ds = datastore.filesystem.FileSystemDatastore('/tmp/.test_datastore')>>>>>> hello = datastore.Key('hello')>>> ds.put(hello, 'world')>>> ds.contains(hello)True>>> ds.get(hello)'world'>>> ds.delete(hello)>>> ds.get(hello)None#### Hello Tiered Access>>> import pymongo>>> import datastore.core>>>>>> from datastore.mongo import MongoDatastore>>> from datastore.pylru import LRUCacheDatastore>>> from datastore.filesystem import FileSystemDatastore>>>>>> conn = pymongo.Connection()>>> mongo = MongoDatastore(conn.test_db)>>>>>> cache = LRUCacheDatastore(1000)>>> fs = FileSystemDatastore('/tmp/.test_db')>>>>>> ds = datastore.TieredDatastore([cache, mongo, fs])>>>>>> hello = datastore.Key('hello')>>> ds.put(hello, 'world')>>> ds.contains(hello)True>>> ds.get(hello)'world'>>> ds.delete(hello)>>> ds.get(hello)None#### Hello Sharding>>> import datastore.core>>>>>> shards = [datastore.DictDatastore() for i in range(0, 10)]>>>>>> ds = datastore.ShardedDatastore(shards)>>>>>> hello = datastore.Key('hello')>>> ds.put(hello, 'world')>>> ds.contains(hello)True>>> ds.get(hello)'world'>>> ds.delete(hello)>>> ds.get(hello)None## APIThe datastore API places an emphasis on  **simplicity** and elegance. Only fourcore methods must be implemented (get, put, delete, query).### get(key)Return the object named by key or None if it does not exist.Args:key: Key naming the object to retrieveReturns:object or None### put(key, value)Stores the object `value` named by `key`.How to serialize and store objects is up to the underlying datastore.It is recommended to use simple objects (strings, numbers, lists, dicts).Args:key: Key naming `value`value: the object to store.### delete(key)Removes the object named by `key`.Args:key: Key naming the object to remove.### query(query):Returns an iterable of objects matching criteria expressed in `query`Implementations of query will be the largest differentiating factoramongst datastores. All datastores **must** implement query, even usingquery's worst case scenario, see Query class for details.Args:query: Query object describing the objects to return.Returns:iterable cursor with all objects matching criteria### Specialized FeaturesDatastore implementors are free to implement specialized features, pertinentonly to a subset of datastores, with the understanding that these should aimfor generality and will most likely not be implemented across other datastores.When implementings such features, please remember the goal of this project:simple, unified API for multiple data stores. When making heavy use of aparticular library's specific functionality, perhaps one should not usedatastore and should directly use that library.### KeyA Key represents the unique identifier of an object.Our Key scheme is inspired by file systems and the Google App Engine keymodel.Keys are meant to be unique across a system. Keys are hierarchical,incorporating increasingly specific namespaces. Thus keys can be deemed'children' or 'ancestors' of other keys.Key('/Comedy')Key('/Comedy/MontyPython')Also, every namespace can be parametrized to embed relevant objectinformation. For example, the Key `name` (most specific namespace) couldinclude the object type:Key('/Comedy/MontyPython/Actor:JohnCleese')Key('/Comedy/MontyPython/Sketch:CheeseShop')Key('/Comedy/MontyPython/Sketch:CheeseShop/Character:Mousebender')