gino.api module

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

基类：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()
   

注解

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.

参数

• 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.

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

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

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.

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

返回

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.

GinoExecutor 的别名

schema_visitor

gino.schema.GinoSchemaVisitor 的别名

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

返回

An asynchronous context manager.

class gino.api.GinoExecutor(query)

基类：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.

注解

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.

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.

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.

timeout(timeout)

Shortcut to set execution option timeout in a chaining call.

Read execution_options() for more information.