Welcome to mincePy’s documentation!

Coveralls Travis CI Latest Version https://img.shields.io/pypi/wheel/mincepy.svg https://img.shields.io/pypi/pyversions/mincepy.svg https://img.shields.io/pypi/l/mincepy.svg

mincePy: move the database to one side and let your objects take centre stage.

MincePy is an object-document mapper (ODM) designed to make any of your Python object storable and queryable in a MongoDB database. It is designed with machine learning and big-data computational and experimental science applications in mind but is entirely general and can be useful to anyone looking to organise, share, or process large amounts data with as little change to their current workflow as possible.

Why was mincePy built?

For Python we already have MongoEngine, Django, SQLAlchemy, Storm and a bunch of other great ORMs, so why do we need mincePy? Well, in a typical ORM you subclass some kind of model class thus every object is a database object plus whatever else the object is designed to do. This is great for applications where there is a tight coupling to the database but what if you can’t or don’t want to subclass from a model? What if you want to store a numpy array, a PyTorch neural network configuration or any arbitrary Python object and have it be queryable? This is where mincePy excels: You tell mincePy about the type you want to store and it takes care of the rest.

The other big thing that differentiates mincePy is version control. Many of us are used to git and other VCS for code but what if we want to track changes to our data, made either by us a collaborator? MincePy achieves this by keeping a snapshot of your object each time you save it so you can always retrieve an older version and see how it mutated over time.


  • Out-of-the-box support for commonly used scientific types, including:
    • NumPy
    • pandas
    • ASE
  • Ability to work locally or collaboratively on a shared database
  • Automatic tracking of in-memory objects (identity map)
  • Easy addition of new Python types
  • Object version control
  • Tracking of references between objects
  • Optimistic locking
  • Plugin system makes it easy to extend mincePy to support new types
  • Python 3.5+ compatible
  • A responsive, Qt, gui:
The mincePy GUI


Installation with pip:

pip install mincepy

Or if you’d like to include plugins for storing common scientific types, use:

pip install mincepy[sci]

Installation from git:

# via pip
pip install https://github.com/muhrin/mincepy/archive/master.zip

# manually
git clone https://github.com/muhrin/mincepy.git
cd mincepy
python setup.py install

Next you’ll need MongoDB, in Ubuntu it’s as simple as:

apt install mongodb

see here, for other platforms.


This software follows Semantic Versioning