Introduction

Marrow Mongo is a collection of small, focused utilities written to enhance use of the PyMongo native MongoDB driver without the overhead, glacial update cycle, complexity, and head-space requirements of stateful active mapper patterns. This project grew out of the need (both personal and commercial) to find a viable, simple, well-tested alternative to existing ODMs. We believe that Marrow Mongo hits the Goldilocks zone for a supportive MongoDB experience in Python without getting in the way, offering elegant and Pythonic approaches to document storage modelling, access, and interaction.

This is a living document, evolving as the framework evolves. You can always browse any point in time within the source repository to review previous versions of these instructions. (Try using the "edit this page" link in the upper right if viewing this document on the official site.)

Overview

Plugin Package Namespaces

Explicit is better than implicit, with fields, traits, and document classes registered as entry_point plugins and made accessible through the standard import mechanism.

Learn more about plugin registration and discovery.

from marrow.mongo import Document, Index
from marrow.mongo.field import String
from marrow.mongo.trait import Queryable

Declarative document modeling.

Instantiate field objects and associate them with custom Document sub-classes to model your data declaratively.

Learn more about constructing documents.

class Television(Document):
    model = String()

Refined, Pythonic data access object interactions.

Utilize Document instances as attribute access mutable mappings with value typecasting, directly usable with PyMongo APIs. Attention is paid to matching Python language expectations, such as allowing instantiation using positional arguments. Values are always stored in the PyMongo-preferred MongoDB native format, and cast on attribute access as needed.

Learn more about interacting with documents.

tv = Television('D50u-D1')
assert tv.model == \
    tv[~Television.model] == \
    tv['model'] == \
    'D50u-D1'

Collection and index metadata, and creation shortcuts.

Keep information about your data model with your data model and standardize access.

Learn more about indexing.

class Television(Queryable):
    __collection__ = 'tv'

    model = String()
    brand = String()

    _model = Index('model')

collection = Television.create_collection(database)
Television('D50u-D1').insert_one()

Filter construction through rich comparison.

Construct filter documents through comparison of (or method calls on) field instances accessed as class attributes.

Learn more about querying documents.

exact = Television.model == 'D50u-D1'
prefix = Television.model.re(r'^D50\w')

tv_a = Television.find_one(exact)
tv_b = Television.find_one(prefix)

assert tv_a.model == tv_b.model == 'D50u-D1'
assert tv_a['_id'] == tv_b['_id']

Parametric filter, projection, sort, and update document construction.

Many Python active record object relational mappers (ORMs) and object document mappers (ODMs) provide a short-hand involving the transformation of named parameters into database concepts.

Learn more about the parametric helpers.

filter_doc = F(Television, model__ne='XY-zzy')
update_doc = U(Television, set__brand='Vizio')

tv = Television.find_one(model='D50u-D1')

assert tv.brand == 'Vizio'

Advanced GeoJSON support.

Marrow Mongo comes with GeoJSON batteries included, having extensive support for querying, constructing, and manipulating GeoJSON data.

Learn more about working with geospatial data.

position = Point(longitude, latitude)
collection.find(Battleship.location.near(position))

Code Quality

Guaranteed to be fully tested before any release.

We utilize Travis continuous integration, with test coverage reporting provided by Codecov.io. We also monitor requirements for security concerns and deprecation using Requires.io. Extensive static analysis through Landscape.io, proactive use of tools such as pre-commit with plugins such as the infosec analyzer OpenStack Bandit, and various linting tools help to keep code maintainable and secure.

Extensively documented, with a > 1:1 code to comment ratio.

Every developer has run into those objects that fail to produce sensible or useful programmers' representation, generate meaningless exception messages, or fail to provide introspective help. With more documentation in the code than code, you won't find that problem here. Code should be self-descriptive and obvious; we feel comments and docstrings are integral to this.

A considered road map.

Changes to the library demand meditation to ensure feature creep and organic growth are kept in check. Where possible, solutions involving objects passed to standard PyMongo functions and methods are preferred to solutions involving wrapping, proxying, or middleware. All but minor changes are isolated in pull requests to aid in code review.

MIT Licensed

The MIT License is highly permissive, allowing commercial and non-commercial use, reproduction, modification, republication, redistribtution, sublicensing, and sale of the software (and associated documentation) or its components. The license notice must be included in the reproduced work, and any warranty or liability on behalf of the Marrow Open Source Collective or project contributors waived.