Guides¶
Some “quickstart” guides follow for bread, to handle some common tasks.
Getting started¶
To install bread, make sure you are running a recent version of pip:
pip install -U pip
and then run:
pip install git+ssh://git@bitbucket.org/leadbrite/bread@v1.4.2#egg=bread --process-dependency-links --trusted-host bitbucket.org
Bread’s setup.py will take case of installing any other dependencies
(including LeadPages’ libraries) upon installation.
Setting a Backend¶
>>> from bread.backends import CloudDatastoreBackend
>>> bread.set_backend(
... CloudDatastoreBackend(),
... dataset="my-dataset",
... collection="my-collection",
... model_name_prefix="MyPrefix"
... )
Setting a backend is simple in bread. You simply pass an instantiated
backend to the bread.set_backend() method, along with an (optional)
dataset, collection and model name prefix. The dataset, collection and
model name prefix can be set (and updated) as properties.
Bread is opinionated about the hierarchy of the backend: it supports two organizational constructs, “datasets” and “collections” (analagous to a database/table pair for an RDBMS like PostgreSQL, or database/collection pair for something like MongoDB). These can be passed to the backend setup method as keyword arguments, as shown.
Using Datasets and Collections¶
>>> from bread.backends import CloudDatastoreBackend
>>> bread.set_backend(CloudDatastoreBackend(), dataset="my-dataset", collection="my-collection")
>>> class MyModel(bread.Model):
>>> collection = bread.StringProperty(default='mymodels')
>>> m = MyModel()
>>> m.save()
>>> bread.get_backend().collection = 'othermodels'
>>> MyModel.get(m.key)
>>> bread.get_backend().collection = 'mymodels'
>>> MyModel.get(m.key)
MyModel(key=Key(of_type=<class '...'>, uuid=u'...'), ...)
Datasets and collections provide two levels of organization, as discussed in
Setting a Backend. Datasets and collections may be specified on a model, so
that entities created and retreived will automatically use the datasets and
collections specified. Essentailly, bread will automatically switch context to
the dataset or collection as needed. The dataset and collection are specified
on the model as plain string properties, where the default keyword argument
to the property constructor is set to the desired dataset or collection.
Datasets and collections isolate entities; as shown in the example, you must be in the same dataset and collection as the entity to access it.
Using the model name prefix¶
FIXME
Asynchronous operations¶
FIXME