gino.api module

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

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 excatly what set_bind() does.

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

Parameters:
  • bind – A GinoEngine instance to bind. Also accepts string or URL, which will be passed to create_engine() when this Gino instance is awaited. Default is None.
  • model_classes – A tuple of base class and mixin classes to create the Model class. Default is (CRUDModel, ).
  • query_ext – Boolean value to control the installation of the gino extension on Executable for implicit execution. Default is to install (True).
  • schema_ext – Boolean value to control the installation of the gino extension on SchemaItem for implicit execution. Default is to install (True).
  • ext – Boolean value to control the installation of the two gino extensions. False for no extension at all, while it depends on the two individual switches when this is set to True (default).
  • kwargs – Other arguments accepted by MetaData.
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)[source]

A delegate of GinoEngine.acquire().

coroutine all(clause, *multiparams, **params)[source]

A delegate of GinoEngine.all().

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)[source]

A delegate of GinoEngine.compile().

coroutine first(clause, *multiparams, **params)[source]

A delegate of GinoEngine.first().

iterate(clause, *multiparams, **params)[source]

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.

pop_bind()[source]

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

coroutine scalar(clause, *multiparams, **params)[source]

A delegate of GinoEngine.scalar().

schema_visitor

alias of gino.schema.GinoSchemaVisitor

coroutine set_bind(bind, loop=None, **kwargs)[source]

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
coroutine status(clause, *multiparams, **params)[source]

A delegate of GinoEngine.status().

transaction(*args, **kwargs)[source]

A delegate of GinoEngine.transaction().

with_bind(bind, loop=None, **kwargs)[source]

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)[source]

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(), 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.

coroutine all(*multiparams, **params)[source]

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.

coroutine first(*multiparams, **params)[source]

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)[source]

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.

model(model)[source]

Shortcut to set execution option model in a chaining call.

Read execution_options() for more information.

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)[source]

Shortcut to set execution option return_model in a chaining call.

Read execution_options() for more information.

coroutine scalar(*multiparams, **params)[source]

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.

coroutine status(*multiparams, **params)[source]

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)[source]

Shortcut to set execution option timeout in a chaining call.

Read execution_options() for more information.