gino.loader module

class gino.loader.AliasLoader(alias, *columns, **extras)

Bases: gino.loader.ModelLoader

The same as ModelLoader, kept for compatibility.

class gino.loader.CallableLoader(func)

Bases: gino.loader.Loader

Load the row by calling a specified function.

Parameters

func – A callable() taking 2 positional arguments (row, context) that will be called in do_load(), returning the loaded result.

do_load(row, context)

Interface used by GINO to run the loader.

The arguments are simply passed to the given function.

Parameters

  • row – A RowProxy instance.

  • context – A dict that is reused across all loaders in one query.

Returns

The result calling the given function, followed by True.

class gino.loader.ColumnLoader(column)

Bases: gino.loader.Loader

Load a given column in the row.

Parameters

column – The column name as str, or a Column instance to avoid name conflict.

do_load(row, context)

Interface used by GINO to run the loader.

Parameters

  • row – A RowProxy instance.

  • context – Not used.

Returns

The value of the specified column, followed by True.

class gino.loader.Loader

Bases: object

The abstract base class of loaders.

Loaders are used to load raw database rows into expected results. GinoEngine will use the loader set on the loader value of the execution_options(), for example:

from sqlalchemy import text, create_engine
from gino.loader import ColumnLoader

e = await create_engine("postgresql://localhost/gino", strategy="gino")
q = text("SELECT now() as ts")
loader = ColumnLoader("ts")
ts = await e.first(q.execution_options(loader=loader))  # datetime
do_load(row, context)

Interface used by GINO to run the loader.

Must be implemented in subclasses.

Parameters

  • row – A RowProxy instance.

  • context – A dict that is reused across all loaders in one query.

Returns

Any result that the loader is supposed to return, followed by a boolean value indicating if the result is distinct.

classmethod get(value)

Automatically create a loader based on the type of the given value.

value type

loader type

tuple

TupleLoader

callable()

CallableLoader

Column, Label

ColumnLoader

Model

ModelLoader

Alias

AliasLoader

Loader

as is

any other types

ValueLoader
Parameters

value – Any supported value above.

Returns

A loader instance.

get_columns()

Generate a list of selectables from this loader.

This is an experimental feature, this method is supposed to be called by query.

Returns

A list of SQLAlchemy selectables.

get_from()

Generate a clause to be used in select_from() from this loader.

This is an experimental feature, this method is supposed to be called by query.

Returns

A FromClause instance, or None.

property query

Generate a query from this loader.

This is an experimental feature, not all loaders support this.

Returns

A query instance with the loader execution option set to self.

class gino.loader.ModelLoader(model, *columns, **extras)

Bases: gino.loader.Loader

A loader that loads a row into a GINO model instance.

This loader generates an instance of the given model type and fills the instance with attributes according to the other given parameters:

  • Load each column attribute listed in the given columns positional arguments.

  • If columns is not given, all defined columns of the model will be loaded.

  • For each keyword argument, its value will be used to generate a loader using Loader.get(), and the loaded value will be setattr() to the model instance under the name of the key.

For example, the simplest select and load:

sqlalchemy.select([User]).execution_options(loader=ModelLoader(User))

Select only the name column, and still load it into model instances:

sqlalchemy.select(
    [User.name]
).execution_options(
    loader=ModelLoader(User, User.name)
)

This would also yield User instances, with all column attributes as None but name.

Nest a ValueLoader:

sqlalchemy.select(
    [User.name]
).execution_options(
    loader=ModelLoader(User, id=1)
)

1 is then converted into a ValueLoader and mocked the id attribute of all returned User instances as 1.

Nest another ModelLoader:

sqlalchemy.select(
    [user.outerjoin(Company)]
).execution_options(
    loader=ModelLoader(User, company=Company)
)

Likewise, Company is converted into a ModelLoader to load the Company columns from the joined result, and the Company instances are set to the company attribute of each User instance using setattr().

Parameters

  • model – A subclass of Model to instantiate.

  • columns – A list of Column or str to load, default is all the columns in the model.

  • extras – Additional attributes to load on the model instance.

distinct(*columns)

Configure this loader to reuse instances that have the same values of all the give columns.

Parameters

columns – Preferably Column instances.

Returns

self for chaining.

do_load(row, context)

Interface used by GINO to run the loader.

Parameters

  • row – A RowProxy instance.

  • context – A dict that is reused across all loaders in one query.

Returns

The model instance, followed by a boolean value indicating if the result is distinct.

get_columns()

Generate a list of selectables from this loader.

This is an experimental feature, this method is supposed to be called by query.

Returns

A list of SQLAlchemy selectables.

get_from()

Generate a clause to be used in select_from() from this loader.

This is an experimental feature, this method is supposed to be called by query.

Returns

A FromClause instance, or None.

load(*columns, **extras)

Update the loader with new rules.

After initialization, the rules of this loader can still be updated. This is useful when using the model class as a shortcut of ModelLoader where possible, chaining with a load() to initialize the rules, for example:

sqlalchemy.select(
    [user.outerjoin(Company)]
).execution_options(
    loader=ModelLoader(User, company=Company.load('name'))
)
Parameters

  • columns – If provided, replace the columns to load with the given ones.

  • extras – Update the loader with new extras.

Returns

self for chaining.

none_as_none(enabled=True)

Deprecated method for compatibility, does nothing.

on(on_clause)

Specify the on_clause for generating joined queries.

This is an experimental feature, used by get_from().

Parameters

on_clause – An expression to feed into join().

Returns

self for chaining.

class gino.loader.TupleLoader(values)

Bases: gino.loader.Loader

Load multiple values into a tuple.

Parameters

values – A tuple, each item is converted into a loader with Loader.get().

do_load(row, context)

Interface used by GINO to run the loader.

The arguments are simply passed to sub-loaders.

Parameters

  • row – A RowProxy instance.

  • context – A dict that is reused across all loaders in one query.

Returns

A tuple with loaded results from all sub-loaders, followed by True.

class gino.loader.ValueLoader(value)

Bases: gino.loader.Loader

A loader that always return the specified value.

Parameters

value – The value to return on load.

do_load(row, context)

Interface used by GINO to run the loader.

Parameters

  • row – Not used.

  • context – Not used.

Returns

The given value, followed by True.