SQLAlchemy 0.3 Documentation - module sqlalchemy.orm

# SQLAlchemy 0.3 Documentation

Multiple Pages | One Page
Version: 0.3.10 Last Updated: 07/20/07 17:20:04

### module sqlalchemy.orm

The mapper package provides object-relational functionality, building upon the schema and sql packages and tying operations to class properties and constructors.

### Module Functions

def backref(name, **kwargs)

Create a BackRef object with explicit arguments, which are the same arguments one can send to `relation()`.

Used with the backref keyword argument to `relation()` in place of a string argument.

def cascade_mappers(*classes_or_mappers)

Attempt to create a series of `relations()` between mappers automatically, via introspecting the foreign key relationships of the underlying tables.

Given a list of classes and/or mappers, identify the foreign key relationships between the given mappers or corresponding class mappers, and create `relation()` objects representing those relationships, including a backreference. Attempt to find the secondary table in a many-to-many relationship as well.

The names of the relations will be a lowercase version of the related class. In the case of one-to-many or many-to-many, the name will be pluralized, which currently is based on the English language (i.e. an 's' or 'es' added to it).

NOTE: this method usually works poorly, and its usage is generally not advised.

def class_mapper(class_, entity_name=None, compile=True)

Given a class and optional entity_name, return the primary Mapper associated with the key.

If no mapper can be located, raises `InvalidRequestError`.

def clear_mapper(m)

Remove the given mapper from the storage of mappers.

When a new mapper is created for the previous mapper's class, it will be used as that classes' new primary mapper.

def clear_mappers()

Remove all mappers that have been created thus far.

When new mappers are created, they will be assigned to their classes as their primary mapper.

def column_property(*args, **kwargs)

Provide a column-level property for use with a Mapper.

Normally, custom column-level properties that represent columns directly or indirectly present within the mapped selectable can just be added to the `properties` dictionary directly, in which case this function's usage is not necessary.

In the case of a `ColumnElement` directly present within the `properties` dictionary, the given column is converted to be the exact column located within the mapped selectable, in the case that the mapped selectable is not the exact parent selectable of the given column, but shares a common base table relationship with that column.

Use this function when the column expression being added does not correspond to any single column within the mapped selectable, such as a labeled function or scalar-returning subquery, to force the element to become a mapped property regardless of it not being present within the mapped selectable.

Note that persistence of instances is driven from the collection of columns within the mapped selectable, so column properties attached to a Mapper which have no direct correspondence to the mapped selectable will effectively be non-persisted attributes.

def compile_mappers()

Compile all mappers that have been defined.

This is equivalent to calling `compile()` on any individual mapper.

def contains_alias(alias)

Return a `MapperOption` that will indicate to the query that the main table has been aliased.

alias is the string name or `Alias` object representing the alias.

def contains_eager(key, alias=None, decorator=None)

Return a `MapperOption` that will indicate to the query that the given attribute will be eagerly loaded.

Used when feeding SQL result sets directly into `query.instances()`. Also bundles an `EagerLazyOption` to turn on eager loading in case it isnt already.

alias is the string name of an alias, or an `sql.Alias` object, which represents the aliased columns in the query. This argument is optional.

decorator is mutually exclusive of alias and is a row-processing function which will be applied to the incoming row before sending to the eager load handler. use this for more sophisticated row adjustments beyond a straight alias.

def defer(name)

Return a `MapperOption` that will convert the column property of the given name into a deferred load.

Used with `query.options()`

def deferred(*columns, **kwargs)

Return a `DeferredColumnProperty`, which indicates this object attributes should only be loaded from its corresponding table column when first accessed.

Used with the properties dictionary sent to `mapper()`.

def eagerload(name)

Return a `MapperOption` that will convert the property of the given name into an eager load.

Used with `query.options()`.

def extension(ext)

Return a `MapperOption` that will insert the given `MapperExtension` to the beginning of the list of extensions that will be called in the context of the `Query`.

Used with `query.options()`.

def lazyload(name)

Return a `MapperOption` that will convert the property of the given name into a lazy load.

Used with `query.options()`.

def mapper(class_, table=None, *args, **params)

Return a new `Mapper` object.

See the `Mapper` class for a description of arguments.

def noload(name)

Return a `MapperOption` that will convert the property of the given name into a non-load.

Used with `query.options()`.

def object_mapper(object, entity_name=None, raiseerror=True)

Given an object, return the primary Mapper associated with the object instance.

object
  The object instance.
entity_name
  Entity name of the mapper to retrieve, if the given instance is transient. Otherwise uses the entity name already associated with the instance.
raiseerror
  Defaults to True: raise an `InvalidRequestError` if no mapper can be located. If False, return None.

def object_session(obj)

Return the `Session` to which the given object is bound, or `None` if none.

def polymorphic_union(table_map, typecolname, aliasname='p_union')

Create a `UNION` statement used by a polymorphic mapper.

See the SQLAlchemy advanced mapping docs for an example of how this is used.

def relation(*args, **kwargs)

Provide a relationship of a primary Mapper to a secondary Mapper.

This corresponds to a parent-child or associative table relationship.

def synonym(name, proxy=False)

Set up name as a synonym to another `MapperProperty`.

Used with the properties dictionary sent to `mapper()`.

def undefer(name)

Return a `MapperOption` that will convert the column property of the given name into a non-deferred (regular column) load.

Used with `query.options()`.

### class MapperExtension(object)

Base implementation for an object that provides overriding behavior to various Mapper functions. For each method in MapperExtension, a result of EXT_PASS indicates the functionality is not overridden.

def after_delete(self, mapper, connection, instance)

Receive an object instance after that instance is DELETEed.

def after_insert(self, mapper, connection, instance)

Receive an object instance after that instance is INSERTed.

def after_update(self, mapper, connection, instance)

Receive an object instance after that instance is UPDATEed.

def append_result(self, mapper, selectcontext, row, instance, identitykey, result, isnew)

Receive an object instance before that instance is appended to a result list.

If this method returns EXT_PASS, result appending will proceed normally. if this method returns any other value or None, result appending will not proceed for this instance, giving this extension an opportunity to do the appending itself, if desired.

mapper
  The mapper doing the operation.
selectcontext
  SelectionContext corresponding to the instances() call.
row
  The result row from the database.
instance
  The object instance to be appended to the result.
identitykey
  The identity key of the instance.
result
  List to which results are being appended.
isnew
  Indicates if this is the first time we have seen this object instance in the current result set. if you are selecting from a join, such as an eager load, you might see the same object instance many times in the same result set.

def before_delete(self, mapper, connection, instance)

Receive an object instance before that instance is DELETEed.

def before_insert(self, mapper, connection, instance)

Receive an object instance before that instance is INSERTed into its table.

This is a good place to set up primary key values and such that aren't handled otherwise.

def before_update(self, mapper, connection, instance)

Receive an object instance before that instance is UPDATEed.

def create_instance(self, mapper, selectcontext, row, class_)

Receive a row when a new object instance is about to be created from that row.

The method can choose to create the instance itself, or it can return None to indicate normal object creation should take place.

mapper
  The mapper doing the operation
selectcontext
  SelectionContext corresponding to the instances() call
row
  The result row from the database
class_
  The class we are mapping.

def get(self, query, *args, **kwargs)

Override the get method of the Query object.

The return value of this method is used as the result of `query.get()` if the value is anything other than EXT_PASS.

def get_by(self, query, *args, **kwargs)

Override the get_by method of the Query object.

The return value of this method is used as the result of `query.get_by()` if the value is anything other than EXT_PASS.

def get_session(self)

Retrieve a contextual Session instance with which to register a new object.

Note: this is not called if a session is provided with the __init__ params (i.e. _sa_session).

def load(self, query, *args, **kwargs)

Override the load method of the Query object.

The return value of this method is used as the result of `query.load()` if the value is anything other than EXT_PASS.

def populate_instance(self, mapper, selectcontext, row, instance, identitykey, isnew)

Receive a newly-created instance before that instance has its attributes populated.

The normal population of attributes is according to each attribute's corresponding MapperProperty (which includes column-based attributes as well as relationships to other classes). If this method returns EXT_PASS, instance population will proceed normally. If any other value or None is returned, instance population will not proceed, giving this extension an opportunity to populate the instance itself, if desired.

def select(self, query, *args, **kwargs)

Override the select method of the Query object.

The return value of this method is used as the result of `query.select()` if the value is anything other than EXT_PASS.

def select_by(self, query, *args, **kwargs)

Override the select_by method of the Query object.

The return value of this method is used as the result of `query.select_by()` if the value is anything other than EXT_PASS.

def translate_row(self, mapper, context, row)

Perform pre-processing on the given result row and return a new row instance.

This is called as the very first step in the `_instance()` method.

back to section top

### class Query(object)

Encapsulates the object-fetching operations provided by Mappers.

Note that this particular version of Query contains the 0.3 API as well as most of the 0.4 API for forwards compatibility. A large part of the API here is deprecated (but still present) in the 0.4 series.

def __init__(self, class_or_mapper, session=None, entity_name=None, lockmode=None, with_options=None, extension=None, **kwargs)
def add_column(self, column)

add a SQL ColumnElement to the list of result columns to be returned.

This will have the effect of all result-returning methods returning a tuple of results, the first element being an instance of the primary class for this Query, and subsequent elements matching columns or entities which were specified via add_column or add_entity.

When adding columns to the result, its generally desireable to add limiting criterion to the query which can associate the primary entity of this Query along with the additional columns, if the column is based on a table or selectable that is not the primary mapped selectable. The Query selects from all tables with no joining criterion by default.

> column
>   a string column name or sql.ColumnElement to be added to the results.

def add_entity(self, entity)

add a mapped entity to the list of result columns to be returned.

This will have the effect of all result-returning methods returning a tuple of results, the first element being an instance of the primary class for this Query, and subsequent elements matching columns or entities which were specified via add_column or add_entity.

When adding entities to the result, its generally desireable to add limiting criterion to the query which can associate the primary entity of this Query along with the additional entities. The Query selects from all tables with no joining criterion by default.

> entity
>   a class or mapper which will be added to the results.

def all(self)

Return the results represented by this `Query` as a list.

This results in an execution of the underlying query.

def apply_avg(self, col)

apply the SQL `avg()` function against the given column to the query and return the newly resulting `Query`.

def apply_max(self, col)

apply the SQL `max()` function against the given column to the query and return the newly resulting `Query`.

def apply_min(self, col)

apply the SQL `min()` function against the given column to the query and return the newly resulting `Query`.

def apply_sum(self, col)

apply the SQL `sum()` function against the given column to the query and return the newly resulting `Query`.

def avg(self, col)

Execute the SQL `avg()` function against the given column.

def compile(self, whereclause=None, **kwargs)

Given a WHERE criterion, produce a ClauseElement-based statement suitable for usage in the execute() method.

the arguments to this function are deprecated and are removed in version 0.4.

def count(self, whereclause=None, params=None, **kwargs)

Given a `WHERE` criterion, create a `SELECT COUNT` statement, execute and return the resulting count value.

the additional arguments to this method are is deprecated in 0.4.

def count_by(self, *args, **params)

Return the count of instances based on the given clauses and key/value criterion.

The criterion is constructed in the same way as the `select_by()` method.

this method is deprecated in 0.4.

def distinct(self)

Apply a `DISTINCT` to the query and return the newly resulting `Query`.

def execute(self, clauseelement, params=None, *args, **kwargs)

Execute the given ClauseElement-based statement against this Query's session/mapper, return the resulting list of instances.

this method is deprecated in 0.4. Use from_statement() instead.

def filter(self, criterion)

apply the given filtering criterion to the query and return the newly resulting `Query`

the criterion is any sql.ClauseElement applicable to the WHERE clause of a select.

def filter_by(self, *args, **kwargs)

apply the given filtering criterion to the query and return the newly resulting `Query`

The criterion is constructed in the same way as the `select_by()` method.

def first(self)

Return the first result of this `Query`.

This results in an execution of the underlying query.

this method is for forwards-compatibility with 0.4.

def from_statement(self, statement)

execute a full select() statement, or literal textual string as a SELECT statement.

this method is for forwards compatibility with 0.4.

def get(self, ident, **kwargs)

Return an instance of the object based on the given identifier, or None if not found.

The ident argument is a scalar or tuple of primary key column values in the order of the table def's primary key columns.

def get_by(self, *args, **params)

Like `select_by()`, but only return the first as a scalar, or None if no object found. Synonymous with `selectfirst_by()`.

The criterion is constructed in the same way as the `select_by()` method.

this method is deprecated in 0.4.

def group_by(self, criterion)

apply one or more GROUP BY criterion to the query and return the newly resulting `Query`

def instances(self, cursor, *mappers_or_columns, **kwargs)

Return a list of mapped instances corresponding to the rows in a given cursor (i.e. `ResultProxy`).

*mappers_or_columns is an optional list containing one or more of classes, mappers, strings or sql.ColumnElements which will be applied to each row and added horizontally to the result set, which becomes a list of tuples. The first element in each tuple is the usual result based on the mapper represented by this `Query`. Each additional element in the tuple corresponds to an entry in the *mappers_or_columns list.

For each element in *mappers_or_columns, if the element is a mapper or mapped class, an additional class instance will be present in the tuple. If the element is a string or sql.ColumnElement, the corresponding result column from each row will be present in the tuple.

Note that when *mappers_or_columns is present, "uniquing" for the result set is disabled, so that the resulting tuples contain entities as they actually correspond. this indicates that multiple results may be present if this option is used.

def join(self, prop)

create a join of this `Query` object's criterion to a relationship and return the newly resulting `Query`.

'prop' may be a string property name in which it is located in the same manner as keyword arguments in `select_by`, or it may be a list of strings in which case the property is located by direct traversal of each keyname (i.e. like join_via()).

def join_by(self, *args, **params)

Return a `ClauseElement` representing the `WHERE` clause that would normally be sent to `select_whereclause()` by `select_by()`.

The criterion is constructed in the same way as the `select_by()` method.

this method is deprecated in 0.4.

def join_to(self, key)

Given the key name of a property, will recursively descend through all child properties from this Query's mapper to locate the property, and will return a ClauseElement representing a join from this Query's mapper to the endmost mapper.

this method is deprecated in 0.4.

def join_via(self, keys)

Given a list of keys that represents a path from this Query's mapper to a related mapper based on names of relations from one mapper to the next, return a ClauseElement representing a join from this Query's mapper to the endmost mapper.

this method is deprecated in 0.4.

def limit(self, limit)

Apply a `LIMIT` to the query and return the newly resulting `Query`.

def list(self)

Return the results represented by this `Query` as a list.

This results in an execution of the underlying query.

this method is deprecated in 0.4. use all() instead.

def load(self, ident, **kwargs)

Return an instance of the object based on the given identifier.

If not found, raises an exception. The method will remove all pending changes to the object already existing in the Session. The ident argument is a scalar or tuple of primary key column values in the order of the table def's primary key columns.

def max(self, col)

Execute the SQL `max()` function against the given column.

def min(self, col)

Execute the SQL `min()` function against the given column.

def offset(self, offset)

Apply an `OFFSET` to the query and return the newly resulting `Query`.

def one(self)

Return the first result of this `Query`, raising an exception if more than one row exists.

This results in an execution of the underlying query.

this method is for forwards-compatibility with 0.4.

def options(self, *args, **kwargs)

Return a new Query object, applying the given list of MapperOptions.

def order_by(self, criterion)

apply one or more ORDER BY criterion to the query and return the newly resulting `Query`

def outerjoin(self, prop)

create a left outer join of this `Query` object's criterion to a relationship and return the newly resulting `Query`.

'prop' may be a string property name in which it is located in the same manner as keyword arguments in `select_by`, or it may be a list of strings in which case the property is located by direct traversal of each keyname (i.e. like join_via()).

def params(self, **kwargs)

add values for bind parameters which may have been specified in filter().

primary_key_columns = property()
def query_from_parent(cls, instance, property, **kwargs)

return a newly constructed Query object, with criterion corresponding to a relationship to the given parent instance.

> instance
>   a persistent or detached instance which is related to class represented by this query.
> property
>   string name of the property which relates this query's class to the instance.
> **kwargs
>   all extra keyword arguments are propigated to the constructor of Query.

def reset_joinpoint(self)

return a new Query reset the 'joinpoint' of this Query reset back to the starting mapper. Subsequent generative calls will be constructed from the new joinpoint.

This is an interim method which will not be needed with new behavior to be released in 0.4.

def scalar(self)

Return the first result of this `Query`.

This results in an execution of the underlying query.

this method will be deprecated in 0.4; first() is added for forwards-compatibility.

def select(self, arg=None, **kwargs)

Select instances of the object from the database.

arg can be any ClauseElement, which will form the criterion with which to load the objects.

For more advanced usage, arg can also be a Select statement object, which will be executed and its resulting rowset used to build new object instances.

In this case, the developer must ensure that an adequate set of columns exists in the rowset with which to build new object instances.

this method is deprecated in 0.4.

def select_by(self, *args, **params)

Return an array of object instances based on the given clauses and key/value criterion.

*args
  a list of zero or more `ClauseElements` which will be connected by `AND` operators.
**params

  > a set of zero or more key/value parameters which are converted into `ClauseElements`. the keys are mapped to property or column names mapped by this mapper's Table, and the values are coerced into a `WHERE` clause separated by `AND` operators. If the local property/column names dont contain the key, a search will be performed against this mapper's immediate list of relations as well, forming the appropriate join conditions if a matching property is located.

  > if the located property is a column-based property, the comparison value should be a scalar with an appropriate type. If the property is a relationship-bound property, the comparison value should be an instance of the related class.

  > E.g.:

  >     result = usermapper.select_by(user_name = 'fred')

  this method is deprecated in 0.4.

def select_from(self, from_obj)

Set the from_obj parameter of the query and return the newly resulting `Query`.

from_obj is a list of one or more tables.

def select_statement(self, statement, **params)

Given a `ClauseElement`-based statement, execute and return the resulting instances.

this method is deprecated in 0.4.

def select_text(self, text, **params)

Given a literal string-based statement, execute and return the resulting instances.

this method is deprecated in 0.4. use from_statement() instead.

def select_whereclause(self, whereclause=None, params=None, **kwargs)

Given a `WHERE` criterion, create a `SELECT` statement, execute and return the resulting instances.

this method is deprecated in 0.4.

def selectfirst(self, arg=None, **kwargs)

Query for a single instance using the given criterion.

Arguments are the same as `select()`. In the case that the given criterion represents `WHERE` criterion only, LIMIT 1 is applied to the fully generated statement.

this method is deprecated in 0.4.

def selectfirst_by(self, *args, **params)

Like `select_by()`, but only return the first as a scalar, or None if no object found. Synonymous with `get_by()`.

The criterion is constructed in the same way as the `select_by()` method.

this method is deprecated in 0.4.

def selectone(self, arg=None, **kwargs)

Query for a single instance using the given criterion.

Unlike `selectfirst`, this method asserts that only one row exists. In the case that the given criterion represents `WHERE` criterion only, LIMIT 2 is applied to the fully generated statement.

this method is deprecated in 0.4.

def selectone_by(self, *args, **params)

Like `selectfirst_by()`, but throws an error if not exactly one result was returned.

The criterion is constructed in the same way as the `select_by()` method.

this method is deprecated in 0.4.

session = property()
def sum(self, col)

Execute the SQL `sum()` function against the given column.

table = property()
def with_lockmode(self, mode)

Return a new Query object with the specified locking mode.

def with_parent(self, instance, property=None)

add a join criterion corresponding to a relationship to the given parent instance.

> instance
>   a persistent or detached instance which is related to class represented by this query.
> property
>   string name of the property which relates this query's class to the instance. if None, the method will attempt to find a suitable property.

currently, this method only works with immediate parent relationships, but in the future may be enhanced to work across a chain of parent mappers.

back to section top

### class Session(object)

Encapsulates a set of objects being operated upon within an object-relational operation.

The Session object is not threadsafe. For thread-management of Sessions, see the `sqlalchemy.ext.sessioncontext` module.

def __init__(self, bind=None, bind_to=None, hash_key=None, import_session=None, echo_uow=False, weak_identity_map=False)
def bind_mapper(self, mapper, bind)

Bind the given mapper to the given `Engine` or `Connection`.

All subsequent operations involving this `Mapper` will use the given bind.

def bind_table(self, table, bind)

Bind the given table to the given `Engine` or `Connection`.

All subsequent operations involving this `Table` will use the given bind.

bind_to = property()
def clear(self)

Remove all object instances from this `Session`.

This is equivalent to calling `expunge()` for all objects in this `Session`.

def close(self)

Close this Session.

def connect(self, mapper=None, **kwargs)

Return a unique connection corresponding to the given mapper.

This connection will not be part of any pre-existing transactional context.

def connection(self, mapper, **kwargs)

Return a `Connection` corresponding to the given mapper.

Used by the `execute()` method which performs select operations for `Mapper` and `Query`.

If this `Session` is transactional, the connection will be in the context of this session's transaction. Otherwise, the connection is returned by the `contextual_connect()` method, which some Engines override to return a thread-local connection, and will have close_with_result set to True.

The given **kwargs will be sent to the engine's `contextual_connect()` method, if no transaction is in progress.

def create_transaction(self, **kwargs)

Return a new `SessionTransaction` corresponding to an existing or new transaction.

If the transaction is new, the returned `SessionTransaction` will have commit control over the underlying transaction, else will have rollback control only.

def delete(self, object)

Mark the given instance as deleted.

The delete operation occurs upon `flush()`.

deleted = property()

A `Set` of all objects marked as 'deleted' within this `Session`

dirty = property()

A `Set` of all objects marked as 'dirty' within this `Session`

echo_uow = property()
def execute(self, mapper, clause, params, **kwargs)

Using the given mapper to identify the appropriate `Engine` or `Connection` to be used for statement execution, execute the given `ClauseElement` using the provided parameter dictionary.

Return a `ResultProxy` corresponding to the execution's results.

If this method allocates a new `Connection` for the operation, then the `ResultProxy` 's `close()` method will release the resources of the underlying `Connection`, otherwise its a no-op.

def expire(self, obj)

Mark the given object as expired.

This will add an instrumentation to all mapped attributes on the instance such that when an attribute is next accessed, the session will reload all attributes on the instance from the database.

def expunge(self, object)

Remove the given object from this `Session`.

This will free all internal references to the object. Cascading will be applied according to the expunge cascade rule.

def flush(self, objects=None)

Flush all the object modifications present in this session to the database.

objects is a list or tuple of objects specifically to be flushed; if `None`, all new and modified objects are flushed.

def get(self, class_, ident, **kwargs)

Return an instance of the object based on the given identifier, or `None` if not found.

The ident argument is a scalar or tuple of primary key column values in the order of the table def's primary key columns.

The entity_name keyword argument may also be specified which further qualifies the underlying Mapper used to perform the query.

def get_bind(self, mapper)

Return the `Engine` or `Connection` which is used to execute statements on behalf of the given mapper.

Calling `connect()` on the return result will always result in a `Connection` object. This method disregards any `SessionTransaction` that may be in progress.

The order of searching is as follows:

1. if an `Engine` or `Connection` was bound to this `Mapper` specifically within this `Session`, return that `Engine` or `Connection`.
2. if an `Engine` or `Connection` was bound to this mapper 's underlying `Table` within this `Session` (i.e. not to the `Table` directly), return that `Engine` or `Connection`.
3. if an `Engine` or `Connection` was bound to this `Session`, return that `Engine` or `Connection`.
4. finally, return the `Engine` which was bound directly to the `Table` 's `MetaData` object.

If no `Engine` is bound to the `Table`, an exception is raised.

def has_key(self, key)
def identity_key(self, *args, **kwargs)

Get an identity key.

Valid call signatures:

- `identity_key(class, ident, entity_name=None)`

  class

    mapped class (must be a positional argument)

  ident

    primary key, if the key is composite this is a tuple

  entity_name

    optional entity name

- `identity_key(instance=instance)`

  instance

    object instance (must be given as a keyword arg)

- `identity_key(class, row=row, entity_name=None)`

  class

    mapped class (must be a positional argument)

  row

    result proxy row (must be given as a keyword arg)

  entity_name

    optional entity name (must be given as a keyword arg)

identity_map = property()

A dictionary consisting of all objects within this `Session` keyed to their _instance_key value.

def import_instance(self, *args, **kwargs)

Deprecated. A synynom for `merge()`.

def is_expired(self, obj, unexpire=False)

Return True if the given object has been marked as expired.

def load(self, class_, ident, **kwargs)

Return an instance of the object based on the given identifier.

If not found, raises an exception. The method will remove all pending changes to the object already existing in the `Session`. The ident argument is a scalar or tuple of primary key columns in the order of the table def's primary key columns.

The entity_name keyword argument may also be specified which further qualifies the underlying `Mapper` used to perform the query.

def mapper(self, class_, entity_name=None)

Given a `Class`, return the primary `Mapper` responsible for persisting it.

def merge(self, object, entity_name=None, _recursive=None)

Copy the state of the given object onto the persistent object with the same identifier.

If there is no persistent instance currently associated with the session, it will be loaded. Return the persistent instance. If the given instance is unsaved, save a copy of and return it as a newly persistent instance. The given instance does not become associated with the session.

This operation cascades to associated instances if the association is mapped with `cascade="merge"`.

new = property()

A `Set` of all objects marked as 'new' within this `Session`.

def query(self, mapper_or_class, *addtl_entities, **kwargs)

Return a new `Query` object corresponding to this `Session` and the mapper, or the classes' primary mapper.

def refresh(self, obj)

Reload the attributes for the given object from the database, clear any changes made.

def save(self, object, entity_name=None)

Add a transient (unsaved) instance to this `Session`.

This operation cascades the save_or_update method to associated instances if the relation is mapped with `cascade="save-update"`.

The entity_name keyword argument will further qualify the specific `Mapper` used to handle this instance.

def save_or_update(self, object, entity_name=None)

Save or update the given object into this `Session`.

The presence of an _instance_key attribute on the instance determines whether to `save()` or `update()` the instance.

def scalar(self, mapper, clause, params, **kwargs)

Like execute() but return a scalar result.

sql = property()
def update(self, object, entity_name=None)

Bring the given detached (saved) instance into this `Session`.

If there is a persistent instance with the same identifier already associated with this `Session`, an exception is thrown.

This operation cascades the save_or_update method to associated instances if the relation is mapped with `cascade="save-update"`.

back to section top