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 normalMetaData
object, e.g. used in Alembic. In usual cases, you would want to define one globalGino
instance, usually under the name ofdb
, 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 bysqlalchemy
, so that you can define tables / models without importingsqlalchemy
:id = db.Column(db.BigInteger(), primary_key=True)
Similar to
MetaData
, aGino
object can bind to aGinoEngine
instance, hereby allowing “implicit execution” through thegino
extension onExecutable
orSchemaItem
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 ondb.bind
, or set it toNone
to unbind. However, the creation of engine usually happens at the same time. Therefore, GINO provided several convenient ways doing so:with_bind()
returning an asynchronous context manager:async with db.with_bind('postgresql://...') as engine:
set_bind()
andpop_bind()
:engine = await db.set_bind('postgresql://...') await db.pop_bind().close()
Directly
await
onGino
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 requiresawait
, which is exactly whatset_bind()
does.At last,
Gino
delegates all query APIs on the boundGinoEngine
.- property Model¶
Declarative base class for models, subclass of
gino.declarative.Model
. Defining subclasses of this class will result new tables added to thisGino
metadata.
- acquire(*args, **kwargs)¶
A delegate of
GinoEngine.acquire()
.
- async all(clause, *multiparams, **params)¶
A delegate of
GinoEngine.all()
.
- bake(func_or_elem=None, **execution_options)¶
A delegate of
Bakery.bake()
.New in version 1.1.
- property bind¶
An
GinoEngine
to which thisGino
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, useset_bind()
(orawait
on thisGino
object after setting a string orURL
).
- 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 byGino
.
- 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
orNone
if self is not bound.
- query_executor¶
The overridable
gino
extension class onExecutable
.This class will be set as the getter method of the property
gino
onExecutable
and its subclasses, ifext
andquery_ext
arguments are bothTrue
. Default isGinoExecutor
.alias of
gino.api.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 orURL
, all arguments will be sent tocreate_engine()
to create a new engine, and return it.- Returns
- 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()
andpop_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 onExecutable
constructs for implicit execution.Instances of this class are created when visiting the
gino
property ofExecutable
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 (theGino
instance) must be bound to an engine, or anAttributeError
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 evendb.scalar()
in this case.- async all(*multiparams, **params)¶
Returns
engine.all()
with this query as the first argument, and other arguments followed, whereengine
is theGinoEngine
to which the metadata (Gino
) is bound, while metadata is found in this query.
- execution_options(**options)¶
Set execution options to this query in a chaining call.
Read
execution_options()
for more information.- Parameters
options – Multiple execution options.
New in version 1.1.
- async first(*multiparams, **params)¶
Returns
engine.first()
with this query as the first argument, and other arguments followed, whereengine
is theGinoEngine
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, whereengine
is theGinoEngine
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, whereengine
is theGinoEngine
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, whereengine
is theGinoEngine
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, whereengine
is theGinoEngine
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, whereengine
is theGinoEngine
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.