SQLAlchemy 0.3 Documentation
module sqlalchemy.orm.session
Module Functions
Given a class and optional entity_name, return the primary Mapper associated with the key.
If no mapper can be located, raises InvalidRequestError.
Given an object, return the primary Mapper associated with the object instance.
- object
- The object instance.
- raiseerror
- Defaults to True: raise an InvalidRequestError if no mapper can be located. If False, return 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.
Bind the given Mapper to the given Engine or Connection.
All subsequent operations involving this Mapper will use the given bindto.
Bind the given Table to the given Engine or Connection.
All subsequent operations involving this Table will use the given bindto.
Remove all object instances from this Session.
This is equivalent to calling expunge() for all objects in this Session.
Return a unique connection corresponding to the given mapper.
This connection will not be part of any pre-existing transactional context.
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.
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.
Mark the given instance as deleted.
The delete operation occurs upon flush().
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.
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.
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.
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.
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.
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:
- if an Engine or Connection was bound to this Mapper specifically within this Session, return that Engine or Connection.
- 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 Conneciton.
- if an Engine or Connection was bound to this Session, return that Engine or Connection.
- 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.
Get an identity key.
Valid call signatures:
- identity_key(class_, ident, entity_name=None)
- class_
- mapped class
- ident
- primary key, if the key is composite this is a tuple
- entity_name
- optional entity name. May be given as a positional arg or as a keyword arg.
- identity_key(instance=instance)
- instance
- object instance (must be given as a keyword arg)
- identity_key(row=row, class=class_, entity_name=None)
- row
- result proxy row (must be given as a keyword arg)
A dictionary consisting of all objects within this Session keyed to their _instance_key value.
Return True if the given object has been marked as expired.
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.
Given an Class, return the primary Mapper responsible for persisting it.
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".
return a new Query object corresponding to this Session and the mapper, or the classes' primary mapper.
reload the attributes for the given object from the database, clear any changes made.
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.
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.
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".
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.