SQLAlchemy 0.3 Documentation - module sqlalchemy.orm.session

# SQLAlchemy 0.3 Documentation

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

### module sqlalchemy.orm.session

### Module Functions

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

### 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

### class SessionTransaction(object)

Represents a Session-level Transaction.

This corresponds to one or more sqlalchemy.engine.Transaction instances behind the scenes, with one Transaction per Engine in use.

The SessionTransaction object is not threadsafe.

def __init__(self, session, parent=None, autoflush=True)
def add(self, bind)
def close(self)
def commit(self)
def connection(self, mapper_or_class, entity_name=None)
def get_or_add(self, bind)
def rollback(self)
back to section top