Introduction

Why use sheraf?

Sheraf allows you to create models, and indexing them in a database. Using sheraf should be somewhat similar to other ORM like MongoEngine, SQLAlchemy or Django ORM. However the database backend of sheraf is a fully pythonic ZODB.

General concepts

sheraf is about storing and reading data in a database. You will mainly encounter the following objects:

  • BaseModel represents a coherent set of data you want to store in a database;

  • Attribute are model parameters that will serialize and deserialize your data. They come in several flavors such as int, string, etc.

  • Index are model parameters that will control how you register and how you search for a model in the database;

  • QuerySet holds the result of a model search;

  • Database holds the connection context to your database.

Here is a quick example of sheraf usage:

>>> # Declare a model with attributes
... class Cowboy(sheraf.Model):
...     first_name = sheraf.StringAttribute()
...     last_name = sheraf.StringAttribute()
...     age = sheraf.IntegerAttribute()
...
...     name = sheraf.Index(first_name, last_name, unique=True)
...
>>> # Initialize a database context
... sheraf.Database("zeo://localhost:8000"): 
...
>>> # Open a connection to the database
... with sheraf.connection(commit=True):
...     # Create a model instance and store it in the database
...     Cowboy.create(first_name="George", last_name="Abitbol", age=51)
<Cowboy id=...>
>>> with sheraf.connection():
...     # Find the model based on its indexed parameters
...     cowboys = Cowboy.search(name="Abitbol")
...
...     # Unpack the QuerySet
...     george = cowboys.get()
...     george.age
51

Why use sheraf instead of plain ZODB?

Sheraf aims to provide tools to make the development with ZODB more quick and easy. The indexation mechanism and the model definition is taking care of by sheraf, allowing you to avoid boilerplate and focus on the valuable parts of your application.

  • Models: ZODB does not provide a model layer. Its usage is mainly about storing Persistent objects, and it is up to you to choose which parts of your object you want to save. Sheraf propose a unified - but flexible - way to define models, and take care of the saving mechanism for you.

  • Indexation: ZODB does not provide an indexation layer. Instead it provides you datastructures like BTrees and let you use them as you like to index your data. sheraf use those datastructures to offer an unified - but flexible - way to index your models. Indexing a model on one of its attributes is generally one line of code away.

  • Migrations: This is a work still in progress, but sheraf aims to offer a complete set of tools to painlessly migrate your data so your models can smoothly evolve with the changes happening in your software.

Sheraf only depends on ZODB and a few side projects (BTrees, persistent etc.), so you do not need any other project from the Zope/Plone galaxy.

Who are we?

Yaal is a cooperative company based in Bordeaux, France. We are specialized in python development, and we are FOSS lovers. We have been using sheraf in production for years, and in 2020 we have cleaned the code and opened the sourcecode.