μMongo: sync/async ODM

μMongo is a Python MongoDB ODM. It inception comes from two needs: the lack of async ODM and the difficulty to do document (un)serialization with existing ODMs.

From this point, μMongo made a few design choices:

• Stay close to the standards MongoDB driver to keep the same API when possible: use find({"field": "value"}) like usual but retrieve your data nicely OO wrapped !
• Work with multiple drivers (PyMongo, TxMongo, motor_asyncio and mongomock for the moment)
• Tight integration with Marshmallow serialization library to easily dump and load your data with the outside world
• i18n integration to localize validation error messages
• Free software: MIT license
• Test with 90%+ coverage ;-)

µMongo requires MongoDB 4.2+ (tested with MongoDB 7.0) and Python 3.7+.

Quick example

import datetime as dt
from pymongo import MongoClient
from umongo import Document, fields, validate
from umongo.frameworks import PyMongoInstance

db = MongoClient().test
instance = PyMongoInstance(db)

@instance.register
class User(Document):
    email = fields.EmailField(required=True, unique=True)
    birthday = fields.DateTimeField(validate=validate.Range(min=dt.datetime(1900, 1, 1)))
    friends = fields.ListField(fields.ReferenceField("User"))

    class Meta:
        collection_name = "user"

# Make sure that unique indexes are created
User.ensure_indexes()

goku = User(email='[email protected]', birthday=dt.datetime(1984, 11, 20))
goku.commit()
vegeta = User(email='[email protected]', friends=[goku])
vegeta.commit()

vegeta.friends
# <object umongo.data_objects.List([<object umongo.dal.pymongo.PyMongoReference(document=User, pk=ObjectId('5717568613adf27be6363f78'))>])>
vegeta.dump()
# {id': '570ddb311d41c89cabceeddc', 'email': '[email protected]', friends': ['570ddb2a1d41c89cabceeddb']}
User.find_one({"email": '[email protected]'})
# <object Document __main__.User({'id': ObjectId('570ddb2a1d41c89cabceeddb'), 'friends': <object umongo.data_objects.List([])>,
#                                 'email': '[email protected]', 'birthday': datetime.datetime(1984, 11, 20, 0, 0)})>

Get it now:

$ pip install umongo           # This installs umongo with pymongo
$ pip install my-mongo-driver  # Other MongoDB drivers must be installed manually

Or to get it along with the MongoDB driver you're planing to use:

$ pip install umongo[motor]
$ pip install umongo[txmongo]
$ pip install umongo[mongomock]

Development Setup

For local development and testing, umongo includes comprehensive build scripts that replicate the CI/CD pipeline locally.

Prerequisites

• Python 3.7+ with pip
• Docker (for MongoDB testing) or local MongoDB installation
• Git

Quick Start

Build and test locally:

$ git clone https://github.com/Scille/umongo.git
$ cd umongo
$ ./build-local.sh deps    # Install development dependencies
$ ./build-local.sh         # Run full build pipeline (lint, test, build)

Build Script Commands

The build-local.sh script supports several commands:

$ ./build-local.sh lint         # Run code linting with flake8
$ ./build-local.sh test         # Run tests with multiple backends
$ ./build-local.sh build        # Build distribution packages
$ ./build-local.sh clean        # Clean build artifacts
$ ./build-local.sh mongo-start  # Start MongoDB 7.0 in Docker
$ ./build-local.sh mongo-stop   # Stop MongoDB Docker container
$ ./build-local.sh deps         # Install development dependencies

MongoDB via Docker

The build script automatically handles MongoDB via Docker, eliminating the need for local MongoDB installation:

$ ./build-local.sh mongo-start  # Starts MongoDB 7.0 container
$ ./build-local.sh test         # Runs tests against Docker MongoDB
$ ./build-local.sh clean-mongo  # Removes MongoDB container

Testing Multiple Backends

The build script tests against multiple Python MongoDB drivers:

$ ./build-local.sh test 3.8 3.9  # Test specific Python versions

Supported backends: - PyMongo (with mongomock for testing) - Motor (async driver) - TxMongo (Twisted async driver)

Package Distribution

Create a local package index for team distribution:

$ ./create-package-index.sh create  # Create package index
$ ./create-package-index.sh serve   # Serve packages at http://localhost:8080
$ ./create-package-index.sh docker  # Create Docker setup for package index

Install from local package index:

$ pip install --index-url http://localhost:8080/simple/ --trusted-host localhost umongo

Docker Development Environment

For containerized development:

$ ./create-package-index.sh docker  # Creates Dockerfile and docker-compose.yml
$ docker-compose up -d              # Start package index server

Integration with Other Projects

Use the built wheel in other projects:

# requirements.txt
/path/to/umongo/dist/umongo-3.2.0-py2.py3-none-any.whl

# Or for development
-e /path/to/umongo

See USAGE_EXAMPLES.md for comprehensive integration examples.

MongoDB Compatibility

umongo is tested against:

• MongoDB 4.2+ (minimum supported version)
• MongoDB 7.0 (recommended, used in development)
• Docker-based development environments
• Local MongoDB installations

The development environment uses MongoDB 7.0 via Docker for consistent testing across different platforms and easy setup without system-level MongoDB installation.

Contributing

1. Fork the repository
2. Set up development environment: ./build-local.sh deps
3. Start MongoDB: ./build-local.sh mongo-start
4. Run tests: ./build-local.sh test
5. Make your changes
6. Run linting: ./build-local.sh lint
7. Run full build: ./build-local.sh
8. Submit a pull request

The build scripts ensure consistent development environment setup across different platforms and contributors.