Eloquent 0.3 is now out. This is the first official release of the ORM.
What is Eloquent
The Eloquent ORM provides a simple and beautiful ActiveRecord implementation for Python.
It is inspired by the database part of the Laravel framework but largely modified to be more pythonic.
The full documentation is available here: http://eloquent.readthedocs.org.
I started Eloquent because of a personal need for simplicity when defining models and accessing databases, which is one of the things that i find quite appealing in a framework like Ruby On Rails.
So I wanted Eloquent to follow the ActiveRecord pattern which provides less configuration and verbosity compared to the data mapper pattern which pretty much all of the Python ORMs follow.
I also wanted it to be really simple to read and write, with useful features out of the box (like timestampable models, soft deletes, protection against mass assigment, model events). Some of these features are not ready yet.
You can install Eloquent in 2 different ways:
- The easier and more straightforward is to use pip
- Install from source using the official repository (https://github.com/sdispater/eloquent)
The different dbapi packages are not part of the package dependencies, so you must install them in order to connect to corresponding databases:
- Sqlite: The
sqlite3module is bundled with Python by default
All you need to get you started is the configuration describing your database connections
and passing it to a
Defining a model
Note that we did not tell the ORM which table to use for the
User model. The plural "snake case" name of the
class name will be used as the table name unless another name is explicitly specified.
In this case, the ORM will assume the
User model stores records in the
You can specify a custom table by defining a
__table__ property on your model:
The ORM will also assume that each table has a primary key column named ``id``.
You can define a
__primary_key__ property to override this convention.
Likewise, you can define a
__connection__ property to override the name of the database
connection that should be used when using the model.
Once a model is defined, you are ready to start retrieving and creating records in your table.
Note that you will need to place
created_at columns on your table by default.
If you do not wish to have these columns automatically maintained,
__timestamps__ property on your model to
Retrieving all models
Retrieving a record by primary key
Querying using models
You can also use the query builder aggregate functions:
If you feel limited by the builder's fluent interface, you can use the
If you need to process a lot of records, you can use the
chunk method to avoid
consuming a lot of RAM:
Specifying the query connection
You can specify which database connection to use when querying a model by using the
If you are using read / write connections, you can force the query to use the "write" connection with the following method:
When creating a new model, you pass attributes to the model constructor. These attributes are then assigned to the model via mass-assignment. Though convenient, this can be a serious security concern when passing user input into a model, since the user is then free to modify any and all of the model's attributes. For this reason, all models protect against mass-assignment by default.
To get started, set the
__guarded__ properties on your model.
Defining fillable attributes on a model
__fillable__ property specifies which attributes can be mass-assigned.
Defining guarded attributes on a model
__guarded__ is the inverse and acts as "blacklist".
You can also block all attributes from mass-assignment:
Insert, update and delete
Saving a new model
To create a new record in the database, simply create a new model instance and call the
You can also use the
create method to save a model in a single line, but you will need to specify
__guarded__ property on the model since all models are protected against
mass-assigment by default.
After saving or creating a new model with auto-incrementing IDs, you can retrieve the ID by accessing
Using the create method
Updating a retrieved model
You can also run updates as queries against a set of models:
Deleting an existing model
To delete a model, simply call the
Deleting an existing model by key
You can also run a delete query on a set of models:
Updating only the model's timestamps
If you want to only update the timestamps on a model, you can use the
By default, the ORM will maintain the
updated_at columns on your database table
automatically. Simply add these
timestamp columns to your table. If you do not wish for the ORM to maintain
these columns, just add the
Converting to dictionaries / JSON
Converting a model to a dictionary
When building JSON APIs, you may often need to convert your models and relationships to dictionaries or JSON.
So, Eloquent includes methods for doing so. To convert a model and its loaded relationship to a dictionary,
you may use the
Note that entire collections of models can also be converted to dictionaries:
Converting a model to JSON
To convert a model to JSON, you can use the
There is a lot more you can do with Eloquent, just give a look at the documentation to see all available features.
And if you are interested by how it all works, you can just check out the Github Repository, and feel free to contribute.
And, finally, here are some features targeted for the 0.4 version:
- A schema builder to create and modify tables:
- Support for soft delete and other mixins:
You can check the advancement on the Github project