]> git.ipfire.org Git - thirdparty/sqlalchemy/sqlalchemy.git/commitdiff
documentation updates
authorMike Bayer <mike_mp@zzzcomputing.com>
Fri, 7 Aug 2009 22:17:24 +0000 (22:17 +0000)
committerMike Bayer <mike_mp@zzzcomputing.com>
Fri, 7 Aug 2009 22:17:24 +0000 (22:17 +0000)
doc/build/dbengine.rst
doc/build/intro.rst
doc/build/mappers.rst
doc/build/ormtutorial.rst
doc/build/session.rst
doc/build/sqlexpression.rst
lib/sqlalchemy/schema.py

index df1088bcd2c481812a83e9664af93a6dc8f717a8..ec407658efd977806f0e1427ad16767a2a4df071 100644 (file)
@@ -193,7 +193,7 @@ The ``execute()`` methods on both ``Engine`` and ``Connection`` can also receive
 
 The above SQL construct is known as a ``select()``.  The full range of SQL constructs available are described in `sql`.
 
-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``.  This argument is named ``bind``::
 
     engine = create_engine('sqlite:///:memory:')
     
@@ -270,7 +270,6 @@ Note that SQLAlchemy's Object Relational Mapper also provides a way to control t
 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.
 
 Understanding Autocommit
 ------------------------
index e491b6561d0519440eb4939add64b1e83c08bba2..f18bffb7b860c8fd4334713d1ffd882d56d0596e 100644 (file)
@@ -76,7 +76,7 @@ SQLAlchemy is designed to operate with a `DB-API <http://www.python.org/doc/peps
 Checking the Installed SQLAlchemy Version
 =========================================
 
-This documentation covers SQLAlchemy version 0.5.  If you're working on a system that already has SQLAlchemy installed, check the version from your Python prompt like this:
+This documentation covers SQLAlchemy version 0.6.  If you're working on a system that already has SQLAlchemy installed, check the version from your Python prompt like this:
 
 .. sourcecode:: python+sql
 
@@ -84,7 +84,7 @@ This documentation covers SQLAlchemy version 0.5.  If you're working on a system
      >>> sqlalchemy.__version__ # doctest: +SKIP
      0.5.0
 
-0.4 to 0.5 Migration 
+0.5 to 0.6 Migration 
 =====================
 
-Notes on what's changed from 0.4 to 0.5 is available on the SQLAlchemy wiki at `05Migration <http://www.sqlalchemy.org/trac/wiki/05Migration>`_.
+Notes on what's changed from 0.5 to 0.6 is available on the SQLAlchemy wiki at `06Migration <http://www.sqlalchemy.org/trac/wiki/06Migration>`_.
index 20a23b0c4c7c5daa871466be7c5a176cd2e637df..22b1a0d443a2823f48fc3e8d2e69f2f4575a64f5 100644 (file)
@@ -312,7 +312,7 @@ The "equals" comparison operation by default produces an AND of all correspondin
 Controlling Ordering 
 ---------------------
 
-As of version 0.5, the ORM does not generate ordering for any query unless explicitly configured.
+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()``::
 
@@ -806,7 +806,6 @@ Above, the "customers" table is joined against the "orders" table to produce a f
 Multiple Mappers for One Class 
 -------------------------------
 
-
 The first mapper created for a certain class is known as that class's "primary mapper."  Other mappers can be created as well on the "load side" - these are called **secondary mappers**.   This is a mapper that must be constructed with the keyword argument ``non_primary=True``, and represents a load-only mapper.  Objects that are loaded with a secondary mapper will have their save operation processed by the primary mapper.  It is also invalid to add new ``relation()`` objects to a non-primary mapper. To use this mapper with the Session, specify it to the ``query`` method:
 
 example:
@@ -824,8 +823,6 @@ example:
 
 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).
-
 Constructors and Object Initialization 
 ---------------------------------------
 
@@ -1765,7 +1762,7 @@ When ``passive_deletes`` is applied, the ``children`` relation will not be loade
 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_cascades`` flag can be set to ``False`` which instructs SQLAlchemy to issue UPDATE statements individually.  The ``passive_cascades`` flag can also be ``False`` in conjunction with ON UPDATE CASCADE functionality, although in that case it issues UPDATE statements unnecessarily.
+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_cascades`` flag can be set to ``False`` which instructs SQLAlchemy to issue UPDATE statements individually.  The ``passive_cascades`` flag can also be ``False`` in conjunction with ON UPDATE CASCADE functionality, although in that case it issues UPDATE statements unnecessarily.
 
 A typical mutable primary key setup might look like:
 
index c10d457f14949ae176ac4a9d1516ff6afbb6f374..ee751f95a8edbbe14832c6135c3d170cb833c656 100644 (file)
@@ -8,11 +8,11 @@ In this tutorial we will cover a basic SQLAlchemy object-relational mapping scen
 Version Check
 =============
 
-A quick check to verify that we are on at least **version 0.5** of SQLAlchemy::
+A quick check to verify that we are on at least **version 0.6** of SQLAlchemy::
 
     >>> import sqlalchemy
     >>> sqlalchemy.__version__ # doctest:+SKIP
-    0.5.0
+    0.6.0
 
 Connecting
 ==========
index c704dc7928377f5ab9f85b14c8381397751ef9e6..d8f01d5fc02ab05f50d6e1748eeb24dc1bae25fb 100644 (file)
@@ -179,7 +179,7 @@ The ``query()`` function takes one or more *entities* and returns a new ``Query`
     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.  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
 ----------------------------
@@ -290,7 +290,7 @@ Rolling Back
   * 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).
+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``.
 
@@ -632,7 +632,7 @@ A (really, really) common question is when does the contextual session get creat
                         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.   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.
index 2bcaa631d22652a5d0e5bd6f9950ece398bf909e..de5b1dd5faab9ffaf661db5cb2f9bac860e422d2 100644 (file)
@@ -10,13 +10,13 @@ Version Check
 =============
 
 
-A quick check to verify that we are on at least **version 0.5** of SQLAlchemy:
+A quick check to verify that we are on at least **version 0.6** of SQLAlchemy:
 
 .. sourcecode:: pycon+sql
 
     >>> import sqlalchemy
     >>> sqlalchemy.__version__ # doctest:+SKIP
-    0.5.0
+    0.6.0
     
 Connecting
 ==========
index 231496676c11c2f82fbebacd152edb0cedcf8171..ec7a9f394d74ec8a5a65a9cbe36cafeace23ba0d 100644 (file)
@@ -465,21 +465,47 @@ class Column(SchemaItem, expression.ColumnClause):
           argument is available such as ``server_default``, ``default``
           and ``unique``.
 
-        :param autoincrement: This flag may be set to ``False`` to disable
-          SQLAlchemy indicating at the DDL level that an integer primary 
-          key column should have autoincrementing behavior.  This 
-          is an oft misunderstood flag and has no effect whatsoever unless
-          all of the following conditions are met:
+        :param autoincrement: This flag may be set to ``False`` to 
+          indicate an integer primary key column that should not be
+          considered to be the "autoincrement" column, that is
+          the integer primary key column which generates values 
+          implicitly upon INSERT and whose value is usually returned
+          via the DBAPI cursor.lastrowid attribute.   It defaults
+          to ``True`` to satisfy the common use case of a table
+          with a single integer primary key column.  If the table
+          has a composite primary key consisting of more than one
+          integer column, set this flag to True only on the 
+          column that should be considered "autoincrement".
+          
+          The setting *only* has an effect for columns which are:
+          
+          * Integer derived (i.e. INT, SMALLINT, BIGINT)
+          
+          * Part of the primary key
+          
+          * Are not referenced by any foreign keys
+          
+          * have no server side or client side defaults (with the exception
+            of Postgresql SERIAL).
+            
+          The setting has these two effects on columns that meet the
+          above criteria:
+          
+          * DDL issued for the column will include database-specific
+            keywords intended to signify this column as an
+            "autoincrement" column, such as AUTO INCREMENT on MySQL,
+            SERIAL on Postgresql, and IDENTITY on MS-SQL.  It does 
+            *not* issue AUTOINCREMENT for SQLite since this is a
+            special SQLite flag that is not required for autoincrementing
+            behavior.
             
-          * The column is of the :class:`~sqlalchemy.types.Integer` datatype.
-          * The column has the ``primary_key`` flag set, or is otherwise
-            a member of a :class:`PrimaryKeyConstraint` on this table.
-          * a CREATE TABLE statement is being issued via :meth:`create()`
-            or :meth:`create_all()`.  The flag has no relevance at any
-            other time.
-          * The database supports autoincrementing behavior, such as 
-            PostgreSQL or MySQL, and this behavior can be disabled (which does
-            not include SQLite).
+          * The column will be considered to be available as 
+            cursor.lastrowid or equivalent, for those dialects which
+            "post fetch" newly inserted identifiers after a row has
+            been inserted (SQLite, MySQL, MS-SQL).  It does not have 
+            any effect in this regard for databases that use sequences 
+            to generate primary key identifiers (i.e. Firebird, Postgresql, 
+            Oracle).
 
         :param default: A scalar, Python callable, or :class:`~sqlalchemy.sql.expression.ClauseElement`
           representing the *default value* for this column, which will be