gino.api module

class gino.api.Gino(bind=None, model_classes=None, query_ext=True, schema_ext=True, ext=True, **kwargs)

Bases: sqlalchemy.sql.schema.MetaData

All-in-one API class of GINO, providing several shortcuts.

This class is a subclass of SQLAlchemy MetaData, therefore its instances can be used as a normal MetaData object, e.g. used in Alembic. In usual cases, you would want to define one global Gino instance, usually under the name of db, representing the database used in your application.

You may define tables in the official way SQLAlchemy core recommended, but more often in GINO we define model classes with db.Model as their parent class to represent tables, for its objective interface and CRUD operations. Please read CRUD for more information.

For convenience, Gino instance delegated all properties publicly exposed by sqlalchemy, so that you can define tables / models without importing sqlalchemy:

id = db.Column(db.BigInteger(), primary_key=True)

Similar to MetaData, a Gino object can bind to a GinoEngine instance, hereby allowing “implicit execution” through the gino extension on Executable or SchemaItem constructs:

await User.query.gino.first()
await db.gino.create_all()

Differently, GINO encourages the use of implicit execution and manages transactional context correctly.

Binding to a connection object is not supported.

To set a bind property, you can simply set your GinoEngine object on db.bind, or set it to None to unbind. However, the creation of engine usually happens at the same time. Therefore, GINO provided several convenient ways doing so:

1. with_bind() returning an asynchronous context manager:

   async with db.with_bind('postgresql://...') as engine:
   

2. set_bind() and pop_bind():

   engine = await db.set_bind('postgresql://...')
   await db.pop_bind().close()
   

3. Directly await on Gino instance:

   db = await gino.Gino('postgresql://...')
   await db.pop_bind().close()
   

Note

SQLAlchemy allows creating the engine by:

metadata.bind = 'postgresql://...'

While in GINO this only sets a string to bind, because creating an engine requires await, which is exactly what set_bind() does.

At last, Gino delegates all query APIs on the bound GinoEngine.

property Model

Declarative base class for models, subclass of gino.declarative.Model. Defining subclasses of this class will result new tables added to this Gino metadata.

acquire(*args, **kwargs)

A delegate of GinoEngine.acquire().

async all(clause, *multiparams, **params)

A delegate of GinoEngine.all().

property bind

An GinoEngine to which this Gino is bound.

This is a simple property with no getter or setter hook - what you set is what you get. To achieve the same result as it is in SQLAlchemy - setting a string or URL and getting an engine instance, use set_bind() (or await on this Gino object after setting a string or URL).

compile(elem, *multiparams, **params)

A delegate of GinoEngine.compile().

async first(clause, *multiparams, **params)

A delegate of GinoEngine.first().

iterate(clause, *multiparams, **params)

A delegate of GinoEngine.iterate().

model_base_classes = (<class 'gino.crud.CRUDModel'>,)

Overridable default model classes to build the Model.

Default is (CRUDModel, ).

no_delegate = {'create_engine', 'engine_from_config'}

A set of symbols from sqlalchemy which is not delegated by Gino.

async one(clause, *multiparams, **params)

A delegate of GinoEngine.one().

async one_or_none(clause, *multiparams, **params)

A delegate of GinoEngine.one_or_none().

pop_bind()

Unbind self, and return the bound engine.

This is usually used in a chained call to close the engine:

await db.pop_bind().close()

Returns

GinoEngine or None if self is not bound.

query_executor

The overridable gino extension class on Executable.

This class will be set as the getter method of the property gino on Executable and its subclasses, if ext and query_ext arguments are both True. Default is GinoExecutor.

alias of GinoExecutor

async scalar(clause, *multiparams, **params)

A delegate of GinoEngine.scalar().

schema_visitor

alias of gino.schema.GinoSchemaVisitor

async set_bind(bind, loop=None, **kwargs)

Bind self to the given GinoEngine and return it.

If the given bind is a string or URL, all arguments will be sent to create_engine() to create a new engine, and return it.

Returns

GinoEngine

async status(clause, *multiparams, **params)

A delegate of GinoEngine.status().

transaction(*args, **kwargs)

A delegate of GinoEngine.transaction().

with_bind(bind, loop=None, **kwargs)

Shortcut for set_bind() and pop_bind() plus closing engine.

This method accepts the same arguments of create_engine(). This allows inline creating an engine and binding self on enter, and unbinding self and closing the engine on exit:

async with db.with_bind('postgresql://...') as engine:
    # play with engine

Returns

An asynchronous context manager.

class gino.api.GinoExecutor(query)

Bases: object

The default gino extension on Executable constructs for implicit execution.

Instances of this class are created when visiting the gino property of Executable instances (also referred as queries or clause elements), for example:

await User.query.gino.first()

This allows GINO to add the asynchronous query APIs (all(), first(), one(), one_or_none(), scalar(), status(), iterate()) to SQLAlchemy query clauses without messing up with existing synchronous ones. Calling these asynchronous query APIs has the same restriction - the relevant metadata (the Gino instance) must be bound to an engine, or an AttributeError will be raised.

Note

Executable clause elements that are completely irrelevant with any table - for example db.select([db.text('now()')]) - has no metadata, hence no engine. Therefore, this will always fail:

await db.select([db.text('now()')]).gino.scalar()

You should use conn.scalar(), engine.scalar() or even db.scalar() in this case.

async all(*multiparams, **params)

Returns engine.all() with this query as the first argument, and other arguments followed, where engine is the GinoEngine to which the metadata (Gino) is bound, while metadata is found in this query.

async first(*multiparams, **params)

Returns engine.first() with this query as the first argument, and other arguments followed, where engine is the GinoEngine to which the metadata (Gino) is bound, while metadata is found in this query.

iterate(*multiparams, **params)

Returns engine.iterate() with this query as the first argument, and other arguments followed, where engine is the GinoEngine to which the metadata (Gino) is bound, while metadata is found in this query.

load(value)

Shortcut to set execution option loader in a chaining call.

For example to load Book instances with their authors:

query = Book.join(User).select()
books = await query.gino.load(Book.load(author=User)).all()

Read execution_options() for more information.

model(model)

Shortcut to set execution option model in a chaining call.

Read execution_options() for more information.

async one(*multiparams, **params)

Returns engine.one() with this query as the first argument, and other arguments followed, where engine is the GinoEngine to which the metadata (Gino) is bound, while metadata is found in this query.

async one_or_none(*multiparams, **params)

Returns engine.one_or_none() with this query as the first argument, and other arguments followed, where engine is the GinoEngine to which the metadata (Gino) is bound, while metadata is found in this query.

property query

Get back the chained Executable.

In a chained query calls, occasionally the previous query clause is needed after a .gino. chain, you can use .query. to resume the chain back. For example:

await User.query.gino.model(FOUser).query.where(...).gino.all()

return_model(switch)

Shortcut to set execution option return_model in a chaining call.

Read execution_options() for more information.

async scalar(*multiparams, **params)

Returns engine.scalar() with this query as the first argument, and other arguments followed, where engine is the GinoEngine to which the metadata (Gino) is bound, while metadata is found in this query.

async status(*multiparams, **params)

Returns engine.status() with this query as the first argument, and other arguments followed, where engine is the GinoEngine to which the metadata (Gino) is bound, while metadata is found in this query.

timeout(timeout)

Shortcut to set execution option timeout in a chaining call.

Read execution_options() for more information.