High-level (new) API

High-level API provides a single point for all async ORM calls. Meet the Manager class! The idea of Manager originally comes from Django, but it’s redesigned to meet new asyncio patterns.

First of all, once Manager is initialized with database and event loop, it’s easy and safe to perform async calls. And all async operations and transactions management methods are bundled with a single object. No need to pass around database instance, event loop, etc.

Also there’s no need to connect and re-connect before executing async queries with manager! It’s all automatic. But you can run Manager.connect() or Manager.close() when you need it.

OK, let’s provide an example:

import asyncio
import peewee
import logging
from peewee_async import Manager, PostgresqlDatabase

loop = asyncio.new_event_loop() # Note: custom loop!
database = PostgresqlDatabase('test')
objects = Manager(database, loop=loop)

– once objects is created with specified loop, all database connections automatically will be set up on that loop. Sometimes, it’s so easy to forget to pass custom loop instance, but now it’s not a problem! Just initialize with an event loop once.

Let’s define a simple model:

class PageBlock(peewee_async.AioModel):
    key = peewee.CharField(max_length=40, unique=True)
    text = peewee.TextField(default='')

    class Meta:
        database = database

– as you can see, nothing special in this code, just plain peewee_async.AioModel definition.

Now we need to create a table for model:

PageBlock.create_table(True)

– this code is sync, and will do absolutely the same thing as would do code with regular peewee.PostgresqlDatabase. This is intentional, I believe there’s just no need to run database initialization code asynchronously! Less code, less errors.

Finally, let’s do something async:

async def my_async_func():
    # Add new page block
    await PageBlock.aio_create(
        key='title',
        text="Peewee is AWESOME with async!"
    )

    # Get one by key
    title = await PageBlock.aio_get(PageBlock, key='title')
    print("Was:", title.text)

    # Save with new text using manager
    title.text = "Peewee is SUPER awesome with async!"
    await objects.update(title)
    print("New:", title.text)

loop.run_until_complete(my_async_func())
loop.close()

That’s it!

As you may notice you can use methods from Manager or from AioModel for operations like selecting, deleting etc. All of them are listed below.

Manager

class peewee_async.Manager(database=None)

Async peewee model’s manager.

Parameters:: database – (optional) async database driver

Example:

class User(peewee.Model):
    username = peewee.CharField(max_length=40, unique=True)

objects = Manager(PostgresqlDatabase('test'))

async def my_async_func():
    user0 = await objects.create(User, username='test')
    user1 = await objects.get(User, id=user0.id)
    user2 = await objects.get(User, username='test')
    # All should be the same
    print(user1.id, user2.id, user3.id)

If you don’t pass database to constructor, you should define database as a class member like that:

database = PostgresqlDatabase('test')

class MyManager(Manager):
    database = database

objects = MyManager()

Manager.database = None: Async database driver for manager. Must be provided in constructor or as a class member.

Manager.allow_sync()

Allow sync queries within context. Close the sync database connection on exit if connected.

Example:

with objects.allow_sync():
    PageBlock.create_table(True)

async Manager.get(source_, *args, **kwargs)

Get the model instance.

Parameters:: source – model or base query for lookup

Example:

async def my_async_func():
    obj1 = await objects.get(MyModel, id=1)
    obj2 = await objects.get(MyModel, MyModel.id==1)
    obj3 = await objects.get(MyModel.select().where(MyModel.id==1))

All will return MyModel instance with id = 1

async Manager.create(model_, **data): Create a new object saved to database.

async Manager.update(obj, only=None)

Update the object in the database. Optionally, update only the specified fields. For creating a new object use create()

Parameters:: only – (optional) the list/tuple of fields or field names to update

async Manager.delete(obj, recursive=False, delete_nullable=False): Delete object from database.

async Manager.get_or_create(model_, defaults=None, **kwargs)

Try to get an object or create it with the specified defaults.

Return 2-tuple containing the model instance and a boolean indicating whether the instance was created.

async Manager.create_or_get(model_, **kwargs): Try to create new object with specified data. If object already exists, then try to get it by unique fields.

async Manager.execute(query): Execute query asyncronously.

async Manager.prefetch(query, *subqueries, prefetch_type=2)

Asynchronous version of the prefetch() from peewee.

Returns:: Query that has already cached data for subqueries

async Manager.count(query, clear_limit=False)

Perform COUNT aggregated query asynchronously.

Returns:: number of objects in select() query

async Manager.scalar(query, as_tuple=False)

Get single value from select() query, i.e. for aggregation.

Returns:: result is the same as after sync query.scalar() call

async Manager.connect(): Open database async connection if not connected.

async Manager.close(): Close database async connection if connected.

Manager.atomic()

Similar to peewee.Database.atomic() method, but returns asynchronous context manager.

Example:

async with objects.atomic():
    await objects.create(
        PageBlock, key='intro',
        text="There are more things in heaven and earth, "
             "Horatio, than are dreamt of in your philosophy.")
    await objects.create(
        PageBlock, key='signature', text="William Shakespeare")

Manager.transaction(): Similar to peewee.Database.transaction() method, but returns asynchronous context manager.

Manager.savepoint(sid=None): Similar to peewee.Database.savepoint() method, but returns asynchronous context manager.

Databases

class peewee_async.PostgresqlDatabase(database, **kwargs)

PosgreSQL database driver providing single drop-in sync connection and single async connection interface.

Example:

database = PostgresqlDatabase('test')

class peewee_async.PooledPostgresqlDatabase(database, **kwargs)

PosgreSQL database driver providing single drop-in sync connection and async connections pool interface.

Parameters:: max_connections – connections pool size

Example:

database = PooledPostgresqlDatabase('test', max_connections=20)

class peewee_asyncext.PostgresqlExtDatabase(database, **kwargs)

PosgreSQL database extended driver providing single drop-in sync connection and single async connection interface.

JSON fields support is always enabled, HStore supports is enabled by default, but can be disabled with register_hstore=False argument.

Example:

database = PostgresqlExtDatabase('test', register_hstore=False)

class peewee_asyncext.PooledPostgresqlExtDatabase(database, **kwargs)

PosgreSQL database extended driver providing single drop-in sync connection and async connections pool interface.

JSON fields support is always enabled, HStore supports is enabled by default, but can be disabled with register_hstore=False argument.

Parameters:: max_connections – connections pool size

Example:

database = PooledPostgresqlExtDatabase('test', register_hstore=False,
                                       max_connections=20)

class peewee_async.MySQLDatabase(database, **kwargs)

MySQL database driver providing single drop-in sync connection and single async connection interface.

Example:

database = MySQLDatabase('test')

class peewee_async.PooledMySQLDatabase(database, **kwargs)

MySQL database driver providing single drop-in sync connection and async connections pool interface.

Parameters:: max_connections – connections pool size

Example:

database = MySQLDatabase('test', max_connections=10)

AioModel

class peewee_async.AioModel(*args, **kwargs)

Async version of peewee.Model that allows to execute queries asynchronously with aio_execute method

Example:

class User(peewee_async.AioModel):
    username = peewee.CharField(max_length=40, unique=True)

await User.select().where(User.username == 'admin').aio_execute()

Also it provides async versions of peewee.Model shortcuts

Example:

user = await User.aio_get(User.username == 'user')

async classmethod AioModel.aio_get(*query, **filters): Async version of peewee.Model.get

async classmethod AioModel.aio_get_or_none(*query, **filters): Async version of peewee.Model.get_or_none

async classmethod AioModel.aio_create(**data): INSERT new row into table and return corresponding model instance.