1. adorsk
  2. sqlalchemy

Commits

Mike Bayer  committed b96595e

Add some `Sphinx` related version informations paragraph-level markups,
such as ``.. versionaddedd::``, ``.. versionchanged::`` and ``.. deprecated::``.

  • Participants
  • Parent commits 39d8025
  • Branches rel_0_5

Comments (0)

Files changed (3)

File doc/build/dbengine.rst

View file
  • Ignore whitespace
 
 The above SQL construct is known as a ``select()``.  The full range of SQL constructs available are described in :ref:`sqlexpression_toplevel`.
 
-Both ``Connection`` and ``Engine`` fulfill an interface known as ``Connectable`` which specifies common functionality between the two objects, namely being able to call ``connect()`` to return a ``Connection`` object (``Connection`` just returns itself), and being able to call ``execute()`` to get a result set.   Following this, most SQLAlchemy functions and objects which accept an ``Engine`` as a parameter or attribute with which to execute SQL will also accept a ``Connection``.  As of SQLAlchemy 0.3.9, this argument is named ``bind``::
+Both ``Connection`` and ``Engine`` fulfill an interface known as ``Connectable`` which specifies common functionality between the two objects, namely being able to call ``connect()`` to return a ``Connection`` object (``Connection`` just returns itself), and being able to call ``execute()`` to get a result set.   Following this, most SQLAlchemy functions and objects which accept an ``Engine`` as a parameter or attribute with which to execute SQL will also accept a ``Connection``, named ``bind``::
 
     engine = create_engine('sqlite:///:memory:')
     
     connection = engine.connect()
     table.drop(bind=connection)
 
+.. versionchanged:: 0.3.9
+    ``Connection`` parameter or attribute named ``bind`` for most functions
+    and objects accepting an ``Engine`` as a parameter or attribute.
+
 .. index::
    single: thread safety; connections
 
 Transaction Facts:
 
 * the Transaction object, just like its parent Connection, is **not thread-safe**.
-* SQLAlchemy 0.4 will feature transactions with two-phase commit capability as well as SAVEPOINT capability.
+* .. versionadded:: 0.4
+      SQLAlchemy feature transactions with two-phase commit capability
+      as well as SAVEPOINT capability.
 
 Understanding Autocommit
 ------------------------

File doc/build/mappers.rst

View file
  • Ignore whitespace
 Controlling Ordering 
 ---------------------
 
-As of version 0.5, the ORM does not generate ordering for any query unless explicitly configured.
+.. versionchanged:: 0.5
+    The ORM does not generate ordering for any query unless
+    explicitly configured.
 
 The "default" ordering for a collection, which applies to list-based collections, can be configured using the ``order_by`` keyword argument on ``relation()``::
 
 
 The "non primary mapper" is a rarely needed feature of SQLAlchemy; in most cases, the ``Query`` object can produce any kind of query that's desired.  It's recommended that a straight ``Query`` be used in place of a non-primary mapper unless the mapper approach is absolutely needed.  Current use cases for the "non primary mapper" are when you want to map the class to a particular select statement or view to which additional query criterion can be added, and for when the particular mapped select statement or view is to be placed in a ``relation()`` of a parent mapper.
 
-Versions of SQLAlchemy previous to 0.5 included another mapper flag called "entity_name", as of version 0.5.0 this feature has been removed (it never worked very well).
+.. versionchanged:: 0.5
+    Versions of SQLAlchemy previous to 0.5 included another mapper flag
+    called "entity_name", as of version 0.5.0 this feature has been removed
+    (it never worked very well).
 
 Constructors and Object Initialization 
 ---------------------------------------
 Mutable Primary Keys / Update Cascades 
 ---------------------------------------
 
-As of SQLAlchemy 0.4.2, the primary key attributes of an instance can be changed freely, and will be persisted upon flush.  When the primary key of an entity changes, related items which reference the primary key must also be updated as well.  For databases which enforce referential integrity, it's required to use the database's ON UPDATE CASCADE functionality in order to propagate primary key changes.  For those which don't, the ``passive_updates`` flag can be set to ``False`` which instructs SQLAlchemy to issue UPDATE statements individually.  The ``passive_updates`` flag can also be ``False`` in conjunction with ON UPDATE CASCADE functionality, although in that case it issues UPDATE statements unnecessarily.
+The primary key attributes of an instance can be changed freely, and will be persisted upon flush.  When the primary key of an entity changes, related items which reference the primary key must also be updated as well.  For databases which enforce referential integrity, it's required to use the database's ON UPDATE CASCADE functionality in order to propagate primary key changes.  For those which don't, the ``passive_updates`` flag can be set to ``False`` which instructs SQLAlchemy to issue UPDATE statements individually.  The ``passive_updates`` flag can also be ``False`` in conjunction with ON UPDATE CASCADE functionality, although in that case it issues UPDATE statements unnecessarily.
+
+.. versionchanged:: 0.4.2
+    The primary key attributes of an instance can be changed freely.
 
 A typical mutable primary key setup might look like:
 

File doc/build/session.rst

View file
  • Ignore whitespace
     user_mapper = class_mapper(User)
     session.query(user_mapper)
 
-When ``Query`` returns results, each object instantiated is stored within the identity map.   When a row matches an object which is already present, the same object is returned.  In the latter case, whether or not the row is populated onto an existing object depends upon whether the attributes of the instance have been *expired* or not.  As of 0.5, a default-configured ``Session`` automatically expires all instances along transaction boundaries, so that with a normally isolated transaction, there shouldn't be any issue of instances representing data which is stale with regards to the current transaction.
+When ``Query`` returns results, each object instantiated is stored within the identity map.   When a row matches an object which is already present, the same object is returned.  In the latter case, whether or not the row is populated onto an existing object depends upon whether the attributes of the instance have been *expired* or not.
+
+.. versionchanged:: 0.5
+    A default-configured ``Session`` automatically expires all instances along transaction boundaries, so that with a normally isolated transaction, there shouldn't be any issue of instances representing data which is stale with regards to the current transaction.
 
 Adding New or Existing Items
 ----------------------------
   * Objects which were marked as *deleted* within the lifespan of the transaction are promoted back to the *persistent* state, corresponding to their DELETE statement being rolled back.  Note that if those objects were first *pending* within the transaction, that operation takes precedence instead.
   * All objects not expunged are fully expired.  
 
-With that state understood, the ``Session`` may safely continue usage after a rollback occurs (note that this is a new feature as of version 0.5).
+.. versionadded:: 0.5
+    With that state understood, the ``Session`` may safely continue usage after a rollback occurs.
 
 When a ``flush()`` fails, typically for reasons like primary key, foreign key, or "not nullable" constraint violations, a ``rollback()`` is issued automatically (it's currently not possible for a flush to continue after a partial failure).  However, the flush process always uses its own transactional demarcator called a *subtransaction*, which is described more fully in the docstrings for ``Session``.  What it means here is that even though the database transaction has been rolled back, the end user must still issue ``rollback()`` to fully reset the state of the ``Session``.
 
                         Session.remove() <-
     web response   <-  
 
-The above example illustrates an explicit call to ``Session.remove()``.  This has the effect such that each web request starts fresh with a brand new session.   When integrating with a web framework, there's actually many options on how to proceed for this step, particularly as of version 0.5:
+The above example illustrates an explicit call to ``Session.remove()``.  This has the effect such that each web request starts fresh with a brand new session.
+
+.. versionchanged:: 0.5
+    When integrating with a web framework, there's actually many options on how to proceed for this step.
 
 * Session.remove() - this is the most cut and dry approach; the ``Session`` is thrown away, all of its transactional/connection resources are closed out, everything within it is explicitly gone.  A new ``Session`` will be used on the next request.
 * Session.close() - Similar to calling ``remove()``, in that all objects are explicitly expunged and all transactional/connection resources closed, except the actual ``Session`` object hangs around.  It doesn't make too much difference here unless the start of the web request would like to pass specific options to the initial construction of ``Session()``, such as a specific ``Engine`` to bind to.