Skip to main content

Small MongoDB object layer.

Project description

A small, efficient, easy to use [MongoDB][1] object layer built on top of [PyMongo][2].

[![Build Status](](

BearField has some fun features:

- Lazy field decoding. Grabbing documents is fast because BearField doesn't do anything with them
until you do.
- Simple field declarations: `value = Field(str)`
- Subdocuments are easy, too: `subdoc = Field(MyDocument)`
- All the field types: Document, date, time, datetime, list, set, dict, and all the builtins
- Query chaining: `Q({'type': 'grizzly'}) | Q({'type': 'kodiak'})`
- Multiple connections and databases.

Add a new connection:

from bearfield import connection
connection.add('example', 'mongodb://localhost/example')

Now create a document type associated with our example connection:

from bearfield import Document, Field

class Bear(Document):
class Meta:
connection = 'example'

name = Field(str)
type = Field(str)
height = Field(float)

You'll notice we use a `Meta` class for document metadata. Relevant options are `connection`, which
defines which named connection we're storing documents in, and `collection` which defaults to the
snake cased document class name if it is not provided. Additional options are ignored for forward

Working with objects of that type is easy. Let's make a 9.8ft grizzly bear:

bear = Bear(name='timmy', type='grizzly', height='9.8')

Easy. This will set the `_id` field on our `bear` object. Now lets go searching for bears:

bears = Bear.find({'type': 'grizzly'})
for bear in bears:
print("This grizzly is {}ft tall!".format(bear.height))

Or you can get just one bear:

bear = Bear.find_one({'_id': bear_identifier})
print("My bear is {}ft tall!".format(bear.height))

The `find_one` method does not raise an exception if it can't find your bear. Instead it will
return `None`. This is good because bears do not like exceptions.

The `update` method will only update fields that have changed on a document. This is more performant
than save which updates the entire document at once. So this is what happens when our bear grows

bear = Bear.find_one({'_id': bear_identifier})
bear.height = 10.3

The `update` method will raise an exception if the bear object has no `_id` field.

You can perform the same operation without first retrieving the object from the database:

old_bear = Bear.find_and_modify({'_id': bear_identifier}, {'height': 10.3})
print("My bear used to be {}ft tall! But he's bigger now!".format(old_bear.height))

Notice that `find_and_modify` returns the old value of the object. This is important since you did
not have a bear to play with before calling `find_and_modify`.

What about subdocuments? Let's define a `BearType` and redefine our `Bear` document to use it:

class BearType(Document):
name = Field(str)
avg_height = Field(int)
colors = Field({str})

class Bear(Document):
class Meta:
connection = 'example'

name = Field(str)
type = Field(BearType)
height = Field(float)

We've changed the type of our `type` field to `BearType`. The `BearType` does not require a `Meta`
class because it is not associated with a collection. Using it is still easy:

grizzly = BearType(name='grizzly', avg_height=9.3, colors={'brown'})
bear = Bear(name='timmy', type=grizzly, height=10.3)

See, bears like it when things are easy.

Copyright (c) 2014 WiFast, Inc. This project and all of its contents is licensed under the
BSD-derived license as found in the included [LICENSE][3] file.

[1]: "MongoDB"
[2]: "PyMongo"
[3]: "LICENSE"

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

bearfield-1.0.tar.gz (20.2 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page