Getting started A five minute walk-through of MongoFrames' key features and how to start using them.

The purpose of this brief guide is to get you familiar enough with MongoFrames to decide if you want to use it on your next project. If you do decide to then there's lots of additional documentation and examples in the API docs and Snippets page - if by the end you're screaming "WHAT THE FOOBAR" at the screen, well, at least you didn't waste much time on it.

Prerequisites

You'll need access to a MongoDB database and to run your code using Python 3.4+.

It's probably safe to use Python 3+ but we don't run tests for versions below 3.4.

Installing

MongoFrames is on the Python Package Index (PyPI), so it can be installed using pip:

$ pip install MongoFrames

Connecting to the database

MongoFrames builds on the excellent PyMongo library for working with MongoDB, the simplest way to connect to your database is using the MongoClient class provided by PyMongo like so:

By default the collection name will be the same as the class name (the collection doesn't need to exist on the database beforehand). If you want to override this behaviour you can specify the collection directly using the _collection class attribute.

Inserting, updating and deleting

The Frame class provides a set of methods for inserting, updating and deleting documents either individually or in multiples:

Dereferencing

Projections also allow reference fields (typically fields containing an ObjectId) to be dereferenced (mapped to a document).

To be clear when I talk about reference fields in MongoFrames' projections I am describing a scenario where a field's value consists of one or more reference values (typically ObjectIds) that reference other documents in the same database by their _id field. It is of course perfectly possible in MongoDB for an ObjectId to not be a reference to another document. This is a construct of MongoFrames and not MongoDB.

Let's imagine that each dragon has a lair field that stores the ID of a document in the Lair collection:

Listening for events

Any of the Frame's insert, update, and delete methods will trigger events, one before the action is taken and one after, for example the events triggered when you call insert or insert_many are insert and inserted.

You can listen and react to events by binding a function to a named event using the listen method:

There's a more detailed description of events (and the integrity methods available; nullify, cascade and pull) in the Events section of Frames and SubFrames API.

Fin

That's all for our brief tour of MongoFrames, if I've done enough to convince you it's worth trying for your next project then I recommend you review the API and Snippet sections which provide more extensive documentation and detailed usage examples.

But what about validation, indexes and space boots?

By design MongoFrames provides a concise set of features, you can dissect and understand the entire code base in an hour or so, magic is kept to a minimum and consequently you'll feel comfortable modifying and extending the library to meet your needs from the get go.

To that end we've collected together a number of snippets that provide behaviour we think is neat or that we know some users expect from their ODM (like data validation) - even if we don't :)

MongoFrames was created by Anthony Blackshaw - a founder of and developer at getme. The project is maintained by the crew at getme along with our contributors. The project's documentation (this site) is managed using ContentTools. The code is licensed under MIT.