So above, the assignment of ``i1.order = o1`` will append ``i1`` to the ``items``
collection of ``o1``, but will not add ``i1`` to the session. You can, of
-course, :func:`~.Session.add` ``i1`` to the session at a later point. This option
-may be helpful for situations where an object needs to be kept out of a
+course, :meth:`~.Session.add` ``i1`` to the session at a later point. This
+option may be helpful for situations where an object needs to be kept out of a
session until it's construction is completed, but still needs to be given
associations to objects which are already persistent in the target session.
session.rollback()
raise
-The :func:`.Session.begin` method also returns a
-transactional token which is compatible with the Python 2.6 ``with``
-statement::
+The :meth:`.Session.begin` method also returns a transactional token which is
+compatible with the Python 2.6 ``with`` statement::
Session = sessionmaker(bind=engine, autocommit=True)
session = Session()
Above, the :func:`declarative_base` callable returns a new base class from
which all mapped classes should inherit. When the class definition is
-completed, a new :class:`.Table` and
-:func:`.mapper` will have been generated.
+completed, a new :class:`.Table` and :func:`.mapper` will have been generated.
The resulting table and mapper are accessible via
``__table__`` and ``__mapper__`` attributes on the
Attributes may be added to the class after its construction, and they will be
added to the underlying :class:`.Table` and
-:func:`.mapper()` definitions as appropriate::
+:func:`.mapper` definitions as appropriate::
SomeClass.data = Column('data', Unicode)
SomeClass.related = relationship(RelatedInfo)
Classes which are constructed using declarative can interact freely
-with classes that are mapped explicitly with :func:`mapper`.
+with classes that are mapped explicitly with :func:`.mapper`.
It is recommended, though not required, that all tables
share the same underlying :class:`~sqlalchemy.schema.MetaData` object,
engine = create_engine('sqlite://')
Base.metadata.create_all(engine)
-The usual techniques of associating :class:`.MetaData:` with :class:`.Engine`
-apply, such as assigning to the ``bind`` attribute::
-
- Base.metadata.bind = create_engine('sqlite://')
-
-To associate the engine with the :func:`declarative_base` at time
-of construction, the ``bind`` argument is accepted::
-
- Base = declarative_base(bind=create_engine('sqlite://'))
-
:func:`declarative_base` can also receive a pre-existing
:class:`.MetaData` object, which allows a
declarative setup to be associated with an already
id = Column(Integer, primary_key=True)
keywords = relationship("Keyword", secondary=keywords)
-Like other :func:`.relationship` arguments, a string is accepted as well,
-passing the string name of the table as defined in the ``Base.metadata.tables``
-collection::
+Like other :func:`~sqlalchemy.orm.relationship` arguments, a string is accepted
+as well, passing the string name of the table as defined in the
+``Base.metadata.tables`` collection::
class Author(Base):
__tablename__ = 'authors'
As with traditional mapping, its generally not a good idea to use
a :class:`.Table` as the "secondary" argument which is also mapped to
-a class, unless the :class:`.relationship` is declared with ``viewonly=True``.
+a class, unless the :func:`.relationship` is declared with ``viewonly=True``.
Otherwise, the unit-of-work system may attempt duplicate INSERT and
DELETE statements against the underlying table.
Relationships created by :func:`~sqlalchemy.orm.relationship` are provided
with declarative mixin classes exclusively using the
-:func:`.declared_attr` approach, eliminating any ambiguity
+:class:`.declared_attr` approach, eliminating any ambiguity
which could arise when copying a relationship and its possibly column-bound
contents. Below is an example which combines a foreign key column and a
relationship so that two classes ``Foo`` and ``Bar`` can both be configured to
specified with declarative mixins, you may want to combine
some parameters from several mixins with those you wish to
define on the class iteself. The
-:func:`.declared_attr` decorator can be used
+:class:`.declared_attr` decorator can be used
here to create user-defined collation routines that pull
from multiple collections::
Note that ``declarative`` does nothing special with sessions, and is
only intended as an easier way to configure mappers and
:class:`~sqlalchemy.schema.Table` objects. A typical application
-setup using :func:`~sqlalchemy.orm.scoped_session` might look like::
+setup using :class:`~sqlalchemy.orm.scoped_session` might look like::
engine = create_engine('postgresql://scott:tiger@localhost/test')
Session = scoped_session(sessionmaker(autocommit=False,
query_cls=query.Query):
"""Construct a new Session.
- See also the :func:`.sessionmaker` function which is used to
+ See also the :class:`.sessionmaker` function which is used to
generate a :class:`.Session`-producing callable with a given
set of arguments.
"""Flush pending changes and commit the current transaction.
If no transaction is in progress, this method raises an
- InvalidRequestError.
+ :exc:`~sqlalchemy.exc.InvalidRequestError`.
By default, the :class:`.Session` also expires all database
loaded state on all ORM-managed attributes after transaction commit.
This so that subsequent operations load the most recent
data from the database. This behavior can be disabled using
- the ``expire_on_commit=False`` option to :func:`.sessionmaker` or
+ the ``expire_on_commit=False`` option to :class:`.sessionmaker` or
the :class:`.Session` constructor.
If a subtransaction is in effect (which occurs when begin() is called
"""Prepare the current transaction in progress for two phase commit.
If no transaction is in progress, this method raises an
- InvalidRequestError.
+ :exc:`~sqlalchemy.exc.InvalidRequestError`.
Only root transactions of two phase sessions can be prepared. If the
- current transaction is not such, an InvalidRequestError is raised.
+ current transaction is not such, an
+ :exc:`~sqlalchemy.exc.InvalidRequestError` is raised.
"""
if self.transaction is None:
linked to the :class:`.MetaData` ultimately
associated with the :class:`.Table` or other
selectable to which the mapper is mapped.
- 6. No bind can be found, :class:`.UnboundExecutionError`
+ 6. No bind can be found, :exc:`~sqlalchemy.exc.UnboundExecutionError`
is raised.
:param mapper:
"""Associate an object with this :class:`.Session` for related
object loading.
- Accesses of attributes mapped with :class:`.relationship`
+ Accesses of attributes mapped with :func:`.relationship`
will attempt to load a value from the database using this
:class:`.Session` as the source of connectivity. The values
will be loaded based on foreign key values present on this
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
