Quick Start

Let’s go through creating a mincepy compatible type and learn how to store, search for, annotate and get the history of objects stored in the database.

Creating types

import mincepy
import uuid


class Person(mincepy.SimpleSavable):
    TYPE_ID = uuid.UUID('26798d9e-8c78-430a-ab2c-b17d612ef5fe')
    ATTRS = ('name', 'age')

    def __init__(self, name, age):
        super().__init__()
        self.name = name
        self.age = age

Here, we’ve defined a simple object and told mincepy:

1. that the attributes name and age should be stored when saving Person objects, and,
2. that this type can be identified by the ID given in TYPE_ID

Storing objects

Now, let’s save some people! First we get a historian which is responsible for keeping track of all object being saved and loaded:

historian = mincepy.create_historian('mongodb://127.0.0.1/mince-quick-start')
mincepy.set_historian(historian) # Tell mincepy to use this as the default

Finally, we can instantiate and save some people!

martin = Person('Martin', 34)
martin_id = historian.save(martin)

# Let's save a couple more
sonia_id, upul_id = historian.save(Person('Sonia', 30), Person('Upul', 35))

# With `SimpleSavable`s we can also do this:
gavin = Person('Gavin', 34)
gavin_id = gavin.save()

print(martin_id, sonia_id)

5e99d6451220e72072cc6996 5e99d6451220e72072cc6997

Above, we see some of the IDs assigned to our objects. These serve to uniquely identify them and can be used to load them from the database.

Loading objects

Ok, now let’s load.

del martin

martin, sonia = historian.load(martin_id, sonia_id)
print("{}, {}".format(martin.name, martin.age))

Martin, 34

Finding objects

Now, let’s do a search

for person in historian.find(Person, state=dict(age=34)):
    print('{}, {}'.format(person.name, person.age))

Gavin, 34
Martin, 34

Modifying objects

Simple, just mutate our object and save!

sonia.age = 31
sonia.save()

# Let's double check!
del sonia
sonia = historian.load(sonia_id)
print(sonia.age)

31

Annotating objects

Objects can be annotated by setting a metadata dictionary.

historian.meta.set(sonia, {'city': 'Copenhagen'})
historian.meta.set(martin, {'city': 'Copenhagen'})
historian.meta.set(gavin, {'city': 'Glasgow'})

print(historian.meta.get(gavin))

{'city': 'Glasgow'}

Ok, that’s cool so now what?

Well, we can also search the metadata.

Searching metadata

for person in historian.find(Person, state=dict(age=34), meta=dict(city='Glasgow')):
    print("{}, {}".format(person.name, person.age))

Gavin, 34

Nice.

Indeed, have a look at Historian.find() for a full lowdown on how to find stuff.

So what else can I do?

How about looking into the past?

Version control

records = historian.history(sonia, as_objects=False)
for record in records:
    print("{}, {}".format(record.version, record.state))

0, {'name': 'Sonia', 'age': 30}
1, {'name': 'Sonia', 'age': 31}

Here we see two records that were fetched from the archive for Sonia. One with the original age value and the other with the current. MincePy will by default keep a record of any modifications you make to objects, think of as being like git, but for objects. We can use a historical record to load the object as it was then:

past_sonia = historian.load(records[0].get_reference())
print("{}, {}".format(past_sonia.name, past_sonia.age))

Sonia, 30