← Back to branch summary

~ubuntu-branches/debian/sid/sqlalchemy/sid

« back to all changes in this revision

Viewing changes to doc/build/orm/session.rst

  • Committer: Package Import Robot
  • Author(s): Piotr Ożarowski
  • Date: 2014-06-27 20:17:13 UTC
  • mfrom: (1.4.28)
  • Revision ID: package-import@ubuntu.com-20140627201713-g6p1kq8q1qenztrv
Tags: 0.9.6-1
http://bugs.debian.org/747852
http://bugs.debian.org/752145
* New upstream release
* Remove Python 3.X build tag files, thanks to Matthias Urlichs for the
  patch (closes: #747852)
* python-fdb isn't in the Debian archive yet so default dialect for firebird://
  URLs is changed to obsolete kinterbasdb, thanks to Russell Stuart for the
  patch (closes: #752145)

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/build/orm/session.rst
196
196
operations (such as trying to save the same object to two different sessions
197
197
at the same time).
198
198
 
 
199
Getting the Current State of an Object
 
200
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
201
 
 
202
The actual state of any mapped object can be viewed at any time using
 
203
the :func:`.inspect` system::
 
204
 
 
205
  >>> from sqlalchemy import inspect
 
206
  >>> insp = inspect(my_object)
 
207
  >>> insp.persistent
 
208
  True
 
209
 
 
210
.. seealso::
 
211
 
 
212
    :attr:`.InstanceState.transient`
 
213
 
 
214
    :attr:`.InstanceState.pending`
 
215
 
 
216
    :attr:`.InstanceState.persistent`
 
217
 
 
218
    :attr:`.InstanceState.detached`
 
219
 
 
220
 
199
221
.. _session_faq:
200
222
 
201
223
Session Frequently Asked Questions
612
634
* The new instance is returned.
613
635
 
614
636
With :meth:`~.Session.merge`, the given "source"
615
 
instance is not modifed nor is it associated with the target :class:`.Session`,
 
637
instance is not modified nor is it associated with the target :class:`.Session`,
616
638
and remains available to be merged with any number of other :class:`.Session`
617
639
objects.  :meth:`~.Session.merge` is useful for
618
640
taking the state of any kind of object structure without regard for its
641
663
  copies of itself that are local to individual :class:`~.Session`
642
664
  objects.
643
665
 
644
 
  In the caching use case, it's common that the ``load=False`` flag
645
 
  is used to remove the overhead of reconciling the object's state
 
666
  In the caching use case, it's common to use the ``load=False``
 
667
  flag to remove the overhead of reconciling the object's state
646
668
  with the database.   There's also a "bulk" version of
647
669
  :meth:`~.Session.merge` called :meth:`~.Query.merge_result`
648
670
  that was designed to work with cache-extended :class:`.Query`
664
686
 
665
687
:meth:`~.Session.merge` is an extremely useful method for many purposes.  However,
666
688
it deals with the intricate border between objects that are transient/detached and
667
 
those that are persistent, as well as the automated transferrence of state.
 
689
those that are persistent, as well as the automated transference of state.
668
690
The wide variety of scenarios that can present themselves here often require a
669
691
more careful approach to the state of objects.   Common problems with merge usually involve
670
692
some unexpected state regarding the object being passed to :meth:`~.Session.merge`.
1501
1523
      relationship, SQLAlchemy's default behavior of setting a foreign key
1502
1524
      to ``NULL`` can be caught in one of two ways:
1503
1525
 
1504
 
        * The easiest and most common is just to to set the
 
1526
        * The easiest and most common is just to set the
1505
1527
          foreign-key-holding column to ``NOT NULL`` at the database schema
1506
1528
          level.  An attempt by SQLAlchemy to set the column to NULL will
1507
1529
          fail with a simple NOT NULL constraint exception.
1801
1823
    of usage, and can in some cases lead to concurrent connection
1802
1824
    checkouts.
1803
1825
 
1804
 
    In the absense of a demarcated transaction, the :class:`.Session`
 
1826
    In the absence of a demarcated transaction, the :class:`.Session`
1805
1827
    cannot make appropriate decisions as to when autoflush should
1806
1828
    occur nor when auto-expiration should occur, so these features
1807
1829
    should be disabled with ``autoflush=False, expire_on_commit=False``.
1846
1868
A subtransaction indicates usage of the :meth:`.Session.begin` method in conjunction with
1847
1869
the ``subtransactions=True`` flag.  This produces a non-transactional, delimiting construct that
1848
1870
allows nesting of calls to :meth:`~.Session.begin` and :meth:`~.Session.commit`.
1849
 
It's purpose is to allow the construction of code that can function within a transaction
 
1871
Its purpose is to allow the construction of code that can function within a transaction
1850
1872
both independently of any external code that starts a transaction,
1851
1873
as well as within a block that has already demarcated a transaction.
1852
1874
 
2021
2043
            self.connection = engine.connect()
2022
2044
 
2023
2045
            # begin a non-ORM transaction
2024
 
            self.trans = connection.begin()
 
2046
            self.trans = self.connection.begin()
2025
2047
 
2026
2048
            # bind an individual Session to the connection
2027
2049
            self.session = Session(bind=self.connection)
2453
2475
 
2454
2476
.. autofunction:: make_transient
2455
2477
 
 
2478
.. autofunction:: make_transient_to_detached
 
2479
 
2456
2480
.. autofunction:: object_session
2457
2481
 
2458
2482
.. autofunction:: sqlalchemy.orm.util.was_deleted