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 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
.- Parameters
bind – A
GinoEngine
instance to bind. Also accepts string orURL
, which will be passed tocreate_engine()
when thisGino
instance is awaited. Default isNone
.model_classes – A
tuple
of base class and mixin classes to create theModel
class. Default is(CRUDModel, )
.query_ext – Boolean value to control the installation of the
gino
extension onExecutable
for implicit execution. Default is to install (True
).schema_ext – Boolean value to control the installation of the
gino
extension onSchemaItem
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 toTrue
(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 thisGino
metadata.
-
acquire
(*args, **kwargs)[source]¶ A delegate of
GinoEngine.acquire()
.
-
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)[source]¶ A delegate of
GinoEngine.compile()
.
-
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 byGino
.
-
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
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
GinoExecutor
-
schema_visitor
¶ alias of
gino.schema.GinoSchemaVisitor
-
transaction
(*args, **kwargs)[source]¶ A delegate of
GinoEngine.transaction()
.
-
with_bind
(bind, loop=None, **kwargs)[source]¶ 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)[source]¶ 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.-
iterate
(*multiparams, **params)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ Shortcut to set execution option
return_model
in a chaining call.Read
execution_options()
for more information.
-
timeout
(timeout)[source]¶ Shortcut to set execution option
timeout
in a chaining call.Read
execution_options()
for more information.
-