Basic Usage¶
A Minimal Application¶
Note
This example application will not go into details as to how the ORM works. You can refer to the Orator documentation for more information.
Setting up Flask-Orator for a single Flask application is quite simple.
Create your application, load its configuration and then create an Orator
object.
The Orator
object behaves like a DatabaseManager
instance set up
to work flawlessly with Flask.
from flask import Flask
from flask_orator import Orator
app = Flask(__name__)
app.config['ORATOR_DATABASES'] = {
'development': {
'driver': 'sqlite',
'database': '/tmp/test.db'
}
}
db = Orator(app)
class User(db.Model):
__fillable__ = ['name', 'email']
def __repr__(self):
return '<User %r>' % self.name
Now, you need to create the database and the users
table using the embedded CLI application.
Let’s create a file named db.py
which has the following content:
from your_application import db
if __name__ == '__main__':
db.cli.run()
This file, when executed, gives you access to useful commands to manage you databases.
Note
For the exhaustive list of commands see the CLI section.
You first need to make a migration file to create the table:
python db.py make:migration create_users_table --table users --create
This will add a file in the migrations
folder named create_users_table
and prefixed by a timestamp:
from orator.migrations import Migration
class CreateTableUsers(Migration):
def up(self):
"""
Run the migrations.
"""
with self.schema.create('users') as table:
table.increments('id')
table.timestamps()
def down(self):
"""
Revert the migrations.
"""
self.schema.drop('users')
You need to modify this file to add the name
and email
columns:
with self.schema.create('users') as table:
table.increments('id')
table.string('name').unique()
table.string('email').unique()
table.timestamps()
Then, you can run the migration:
python db.py migrate
Confirm and you database and the table will be created.
Once your database set up, you can create some users:
from your_application import User
admin = User.create(name='admin', email='admin@example.com')
guest = Guest.create(name='guest', email='guest@example.com')
The create()
method will create the users instantly. But you can also
initiate them and save them later:
admin = User(name='admin', email='admin@example.com')
# Do something else...
admin.save()
Note
Optionally you can use a transaction.
from your_application import db, User
with db.transaction():
admin = User.create(name='admin', email='admin@example.com')
guest = Guest.create(name='guest', email='guest@example.com')
You can now retrieve them easily from the database:
users = User.all()
admin = User.where('name', 'admin').first()
Relationships¶
Setting up relationships between tables is a breeze.
Let’s create a Post
model with the User
model as a parent:
from orator.orm import belongs_to
class Post(db.Model):
__fillable__ = ['title', 'content']
@belongs_to
def user(self):
return User
And we add the posts
relationship to the User
model:
from orator.orm import has_many
class User(db.Model):
@has_many
def posts(self):
return Post
Before we can play with these models we need to create the posts
table
and set up the relationship at database level:
python db.py make:migration create_posts_table --table posts --create
And we modify the generated file to look like this:
from orator.migrations import Migration
class CreatePostsTable(Migration):
def up(self):
"""
Run the migrations.
"""
with self.schema.create('posts') as table:
table.increments('id')
table.string('title')
table.text('content')
table.integer('user_id', unsigned=True)
table.timestamps()
table.foreign('user_id').references('id').on('users')
def down(self):
"""
Revert the migrations.
"""
self.schema.drop('posts')
Finally we run it:
python db.py migrate
We can now instantiate some posts:
admin_post = Post(title='Admin Post',
description='This is a restricted post')
guest_post = Post(title='Guest Post',
description='This is a guest post')
and associate them with users:
# Associate from user.posts relation
admin.posts().save(admin_post)
# Associate from post.user relation
guest_post.user().associate(guest)
Note
You can also create the posts directly.
admin.posts().create(
title='Admin Post',
description='This is a restricted post'
)
Relationships properties are dynamic properties
meaning that user.posts
is the underlying collection of posts so we can do things like:
user.posts.first()
user.posts[2:7]
user.posts.is_empty()
But, if we need to retrieve a more fine-grained portion of posts we can actually to so:
user.posts().where('title', 'like', '%admin%').get()
user.posts().first()
Pagination¶
Flask-Orator supports pagination:
users = User.paginate(15)
This will retrieve 15
users. The current page is determined by default by the ?page
query string
parameter of the request.
This behavior can be modified if needed, either by explicitely specifying the current page:
users = User.paginate(15, request.args['index'])
or by changing the default Paginator
current page resolver:
from flask import request
from orator import Paginator
def current_page_resolver():
return request.args.get('index', 1)
Paginator.current_page_resolver(current_page_resolver)
What’s more?¶
Like said in the introduction Flask-Orator is a wrapper around Orator to integrate it more easily with Flask applications. So, basically, everything you can do with Orator is also possible with Flask-Orator.
Referer to the Orator documentation to see the features available.