r4695 merged to trunk; trunk now becomes 0.5.

0.4 development continues at /sqlalchemy/branches/rel_0_4

1 files changed, 211 insertions, 142 deletions

diff --git a/CHANGES b/CHANGES
index 35d53ab61..894be6116 100644
--- a/CHANGES
+++ b/CHANGES
@@ -1,11 +1,76 @@
+-*- coding: utf-8; fill-column: 68 -*-
+
 =======
 CHANGES
 =======
 
+user_defined_state
+==================
+
+    - The "__init__" trigger/decorator added by mapper now attempts
+      to exactly mirror the argument signature of the original
+      __init__.  The pass-through for '_sa_session' is no longer
+      implicit- you must allow for this keyword argument in your
+      constructor.
+
+    - ClassState is renamed to ClassManager.
+
+    - Classes may supply their own InstrumentationManager by
+      providing a __sa_instrumentation_manager__ property.
+
+    - Custom instrumentation may use any mechanism to associate a
+      ClassManager with a class and an InstanceState with an
+      instance.  Attributes on those objects are still the default
+      association mechanism used by SQLAlchemy's native
+      instrumentation.
+
+    - Moved entity_name, _sa_session_id, and _instance_key from the
+      instance object to the instance state.  These values are still
+      available in the old way, which is now deprecated, using
+      descriptors attached to the class.  A deprecation warning will
+      be issued when accessed.
+
+    - attribute savepoint/rollback capability has been added.  For
+      starters, this takes effect within the flush() call, so that
+      attribute changes which occur within flush() are rolled back
+      when the flush fails.  Since it's primarily new primary key
+      values that get assigned within flush(), expiring those
+      attributes is not an option.  The next place we might use
+      savepoints is within SAVEPOINT transactions, since rolling
+      back to a savepoint is a transaction-contained operation.
+
+    - The _prepare_instrumentation alias for prepare_instrumentation
+      has been removed.
+
+    - sqlalchemy.exceptions has been renamed to sqlalchemy.exc.  The
+      module may be imported under either name.
+
+    - ORM-related exceptions are now defined in sqlalchemy.orm.exc.
+      ConcurrentModificationError, FlushError, and
+      UnmappedColumnError compatibility aliases are installed in
+      sqlalchemy.exc during the import of sqlalchemy.orm.
+
+    - sqlalchemy.logging has been renamed to sqlalchemy.log.
+
+    - The transitional sqlalchemy.log.SADeprecationWarning alias for
+      the warning's definition in sqlalchemy.exc has been removed.
+
+    - exc.AssertionError has been removed and usage replaced with
+      Python's built-in AssertionError.
+
+    - The behavior of MapperExtensions attached to multiple,
+      entity_name= primary mappers for a single class has been
+      altered.  The first mapper() defined for a class is the only
+      mapper eligible for the MapperExtension 'instrument_class',
+      'init_instance' and 'init_failed' events.  This is backwards
+      incompatible; previously the extensions of last mapper defined
+      would receive these events.
+
+
 0.4.6
 =====
 - orm
-    - A fix to the recent relation() refactoring which fixes
+    - Fix to the recent relation() refactoring which fixes
       exotic viewonly relations which join between local and
       remote table multiple times, with a common column shared
       between the joins.
@@ -13,12 +78,7 @@ CHANGES
     - Also re-established viewonly relation() configurations
       that join across multiple tables.
 
-    - contains_eager(), the hot function of the week, suppresses
-      the eager loader's own generation of the LEFT OUTER JOIN,
-      so that it is reasonable to use any Query, not just those
-      which use from_statement().  
-      
-    - Added an experimental relation() flag to help with
+    - Added experimental relation() flag to help with
       primaryjoins across functions, etc.,
       _local_remote_pairs=[tuples].  This complements a complex
       primaryjoin condition allowing you to provide the
@@ -32,44 +92,39 @@ CHANGES
       Query.order_by() if clause adaption had taken place.
       [ticket:1027]
       
-    - Removed an ancient assertion that mapped selectables
-      require "alias names" - the mapper creates its own alias
-      now if none is present.  Though in this case you need to
-      use the class, not the mapped selectable, as the source of
+    - Removed ancient assertion that mapped selectables require
+      "alias names" - the mapper creates its own alias now if
+      none is present.  Though in this case you need to use the
+      class, not the mapped selectable, as the source of column
+      attributes - so a warning is still issued.
+
+    - fixes to the "exists" function involving inheritance (any(), has(),
+      ~contains()); the full target join will be rendered into the
+      EXISTS clause for relations that link to subclasses.
+      
+    - restored usage of append_result() extension method for primary 
+      query rows, when the extension is present and only a single-
+      entity result is being returned.
+    
+    - Also re-established viewonly relation() configurations that
+      join across multiple tables.
+      
+    - removed ancient assertion that mapped selectables require
+      "alias names" - the mapper creates its own alias now if
+      none is present.  Though in this case you need to use 
+      the class, not the mapped selectable, as the source of
       column attributes - so a warning is still issued.
-
-    - Fixes to the "exists" function involving inheritance
-      (any(), has(), ~contains()); the full target join will be
-      rendered into the EXISTS clause for relations that link to
-      subclasses.
-
-    - Restored usage of append_result() extension method for
-      primary query rows, when the extension is present and only
-      a single- entity result is being returned.
-
-    - Fixed Class.collection==None for m2m relationships
-      [ticket:4213]
-
-    - Refined mapper._save_obj() which was unnecessarily calling
+      
+    - refined mapper._save_obj() which was unnecessarily calling
       __ne__() on scalar values during flush [ticket:1015]
-
-    - Added a feature to eager loading whereby subqueries set as
-      column_property() with explicit label names (which is not
-      necessary, btw) will have the label anonymized when the
-      instance is part of the eager join, to prevent conflicts
-      with a subquery or column of the same name on the parent
-      object.  [ticket:1019]
-
-    - Same as [ticket:1019] but repaired the non-labeled use
-      case [ticket:1022]
-
-    - Adjusted class-member inspection during attribute and
-      collection instrumentation that could be problematic when
-      integrating with other frameworks.
-
-    - Fixed duplicate append event emission on repeated
-      instrumented set.add() operations.
-
+      
+    - added a feature to eager loading whereby subqueries set
+      as column_property() with explicit label names (which is not
+      necessary, btw) will have the label anonymized when
+      the instance is part of the eager join, to prevent
+      conflicts with a subquery or column of the same name 
+      on the parent object.  [ticket:1019]
+      
     - set-based collections |=, -=, ^= and &= are stricter about
       their operands and only operate on sets, frozensets or
       subclasses of the collection type. Previously, they would
@@ -79,6 +134,16 @@ CHANGES
       a simple way to place dictionary behavior on top of 
       a dynamic_loader.
 
+- declarative extension
+    - Joined table inheritance mappers use a slightly relaxed
+      function to create the "inherit condition" to the parent
+      table, so that other foreign keys to not-yet-declared 
+      Table objects don't trigger an error.
+      
+    - fixed reentrant mapper compile hang when 
+      a declared attribute is used within ForeignKey, 
+      ie. ForeignKey(MyOtherClass.someattribute)
+      
 - sql
     - Added COLLATE support via the .collate(<collation>)
       expression operator and collate(<expr>, <collation>) sql
@@ -87,38 +152,29 @@ CHANGES
     - Fixed bug with union() when applied to non-Table connected
       select statements
 
-    - Improved behavior of text() expressions when used as FROM
-      clauses, such as select().select_from(text("sometext"))
+    - improved behavior of text() expressions when used as 
+      FROM clauses, such as select().select_from(text("sometext"))
       [ticket:1014]
 
-    - Column.copy() respects the value of "autoincrement", fixes
-      usage with Migrate [ticket:1021]
-
+    - Column.copy() respects the value of "autoincrement",
+      fixes usage with Migrate [ticket:1021]
+      
 - engines
     - Pool listeners can now be provided as a dictionary of
       callables or a (possibly partial) duck-type of
       PoolListener, your choice.
+      
+    - added "rollback_returned" option to Pool which will 
+      disable the rollback() issued when connections are 
+      returned.  This flag is only safe to use with a database
+      which does not support transactions (i.e. MySQL/MyISAM).
 
-    - Added "reset_on_return" option to Pool which will disable
-      the database state cleanup step (e.g. issuing a
-      rollback()) when connections are returned to the pool.
-
--extensions
+-ext
     - set-based association proxies |=, -=, ^= and &= are
       stricter about their operands and only operate on sets,
       frozensets or other association proxies. Previously, they
       would accept any duck-typed set.
 
-- declarative extension
-    - Joined table inheritance mappers use a slightly relaxed
-      function to create the "inherit condition" to the parent
-      table, so that other foreign keys to not-yet-declared
-      Table objects don't trigger an error.
-
-    - Fixed re-entrant mapper compile hang when a declared
-      attribute is used within ForeignKey,
-      i.e. ForeignKey(MyOtherClass.someattribute)
-
 - mssql
     - Added "odbc_autotranslate" parameter to engine / dburi
       parameters. Any given string will be passed through to the
@@ -135,11 +191,11 @@ CHANGES
       This should obviate the need of adding a myriad of ODBC
       options in the future.
 
+
 - firebird
     - Handle the "SUBSTRING(:string FROM :start FOR :length)"
       builtin.
 
-
 0.4.5
 =====
 - orm
@@ -175,81 +231,78 @@ CHANGES
     - Added comparable_property(), adds query Comparator
       behavior to regular, unmanaged Python properties
 
-    - The functionality of query.with_polymorphic() has been
-      added to mapper() as a configuration option.
+    - the functionality of query.with_polymorphic() has 
+      been added to mapper() as a configuration option.  
 
       It's set via several forms:
-
             with_polymorphic='*'
             with_polymorphic=[mappers]
             with_polymorphic=('*', selectable)
             with_polymorphic=([mappers], selectable)
-
-      This controls the default polymorphic loading strategy for
-      inherited mappers. When a selectable is not given, outer
-      joins are created for all joined-table inheriting mappers
-      requested. Note that the auto-create of joins is not
-      compatible with concrete table inheritance.
-
-      The existing select_table flag on mapper() is now
-      deprecated and is synonymous with:
-
-        with_polymorphic('*', select_table).
-
-      Note that the underlying "guts" of select_table have been
-      completely removed and replaced with the newer, more
-      flexible approach.
-
-      The new approach also automatically allows eager loads to
-      work for subclasses, if they are present, for example
-
+    
+      This controls the default polymorphic loading strategy
+      for inherited mappers. When a selectable is not given,
+      outer joins are created for all joined-table inheriting
+      mappers requested. Note that the auto-create of joins
+      is not compatible with concrete table inheritance.
+
+      The existing select_table flag on mapper() is now 
+      deprecated and is synonymous with 
+      with_polymorphic('*', select_table).  Note that the
+      underlying "guts" of select_table have been 
+      completely removed and replaced with the newer,
+      more flexible approach.  
+      
+      The new approach also automatically allows eager loads
+      to work for subclasses, if they are present, for
+      example
         sess.query(Company).options(
          eagerload_all(
           [Company.employees.of_type(Engineer), 'machines']
         ))
-
       to load Company objects, their employees, and the
       'machines' collection of employees who happen to be
       Engineers. A "with_polymorphic" Query option should be
       introduced soon as well which would allow per-Query
       control of with_polymorphic() on relations.
-
-    - Added two "experimental" features to Query, "experimental"
-      in that their specific name/behavior is not carved in
-      stone just yet: _values() and _from_self().  We'd like
-      feedback on these.
-
-      - _values(*columns) is given a list of column expressions,
-        and returns a new Query that only returns those
-        columns. When evaluated, the return value is a list of
-        tuples just like when using add_column() or
-        add_entity(), the only difference is that "entity zero",
-        i.e. the mapped class, is not included in the
-        results. This means it finally makes sense to use
-        group_by() and having() on Query, which have been
-        sitting around uselessly until now.
-
+    
+    - added two "experimental" features to Query, 
+      "experimental" in that their specific name/behavior
+      is not carved in stone just yet:  _values() and
+      _from_self().  We'd like feedback on these.
+      
+      - _values(*columns) is given a list of column
+        expressions, and returns a new Query that only
+        returns those columns. When evaluated, the return
+        value is a list of tuples just like when using
+        add_column() or add_entity(), the only difference is
+        that "entity zero", i.e. the mapped class, is not
+        included in the results. This means it finally makes
+        sense to use group_by() and having() on Query, which
+        have been sitting around uselessly until now.  
+        
         A future change to this method may include that its
         ability to join, filter and allow other options not
         related to a "resultset" are removed, so the feedback
         we're looking for is how people want to use
-        _values()...i.e. at the very end, or do people prefer to
-        continue generating after it's called.
-
-      - _from_self() compiles the SELECT statement for the Query
-        (minus any eager loaders), and returns a new Query that
-        selects from that SELECT. So basically you can query
-        from a Query without needing to extract the SELECT
-        statement manually. This gives meaning to operations
-        like query[3:5]._from_self().filter(some
-        criterion). There's not much controversial here except
-        that you can quickly create highly nested queries that
-        are less efficient, and we want feedback on the naming
-        choice.
-
-    - query.order_by() and query.group_by() will accept multiple
-      arguments using *args (like select() already does).
-
+        _values()...i.e. at the very end, or do people prefer
+        to continue generating after it's called.
+
+      - _from_self() compiles the SELECT statement for the
+        Query (minus any eager loaders), and returns a new
+        Query that selects from that SELECT. So basically you
+        can query from a Query without needing to extract the
+        SELECT statement manually. This gives meaning to
+        operations like query[3:5]._from_self().filter(some
+        criterion). There's not much controversial here
+        except that you can quickly create highly nested
+        queries that are less efficient, and we want feedback
+        on the naming choice.
+      
+    - query.order_by() and query.group_by() will accept
+      multiple arguments using *args (like select() 
+      already does).
+      
     - Added some convenience descriptors to Query:
       query.statement returns the full SELECT construct,
       query.whereclause returns just the WHERE part of the
@@ -293,10 +346,9 @@ CHANGES
         - Delete cascade with delete-orphan will delete orphans
           whether or not it remains attached to its also-deleted
           parent.
-
-        - delete-orphan casacde is properly detected on
-          relations that are present on superclasses when using
-          inheritance.
+          
+        - delete-orphan casacde is properly detected on relations
+          that are present on superclasses when using inheritance.
 
     - Fixed order_by calculation in Query to properly alias
       mapper-config'ed order_by when using select_from()
@@ -309,16 +361,16 @@ CHANGES
       iterative to support deep object graphs.
 
 - sql
-    - Schema-qualified tables now will place the schemaname
+    - schema-qualified tables now will place the schemaname
       ahead of the tablename in all column expressions as well
       as when generating column labels.  This prevents cross-
       schema name collisions in all cases [ticket:999]
-
-    - Can now allow selects which correlate all FROM clauses and
-      have no FROM themselves.  These are typically used in a
-      scalar context, i.e. SELECT x, (SELECT x WHERE y) FROM
-      table.  Requires explicit correlate() call.
-
+      
+    - can now allow selects which correlate all FROM clauses
+      and have no FROM themselves.  These are typically
+      used in a scalar context, i.e. SELECT x, (SELECT x WHERE y)
+      FROM table.  Requires explicit correlate() call.
+      
     - 'name' is no longer a required constructor argument for
       Column().  It (and .key) may now be deferred until the
       column is added to a Table.
@@ -350,6 +402,24 @@ CHANGES
       SA will force explicit usage of either text() or
       literal().
 
+- oracle
+    - The "owner" keyword on Table is now deprecated, and is
+      exactly synonymous with the "schema" keyword.  Tables can
+      now be reflected with alternate "owner" attributes,
+      explicitly stated on the Table object or not using
+      "schema".
+
+    - All of the "magic" searching for synonyms, DBLINKs etc.
+      during table reflection are disabled by default unless you
+      specify "oracle_resolve_synonyms=True" on the Table
+      object.  Resolving synonyms necessarily leads to some
+      messy guessing which we'd rather leave off by default.
+      When the flag is set, tables and related tables will be
+      resolved against synonyms in all cases, meaning if a
+      synonym exists for a particular table, reflection will use
+      it when reflecting related tables.  This is stickier
+      behavior than before which is why it's off by default.
+
 - declarative extension
     - The "synonym" function is now directly usable with
       "declarative".  Pass in the decorated property using the
@@ -378,10 +448,10 @@ CHANGES
      - inheritance in declarative can be disabled when sending
        "inherits=None" to __mapper_args__.
 
-     - declarative_base() takes optional kwarg "mapper", which
-       is any callable/class/method that produces a mapper, such
-       as declarative_base(mapper=scopedsession.mapper).  This
-       property can also be set on individual declarative
+     - declarative_base() takes optional kwarg "mapper", which 
+       is any callable/class/method that produces a mapper,
+       such as declarative_base(mapper=scopedsession.mapper).
+       This property can also be set on individual declarative
        classes using the "__mapper_cls__" property.
 
 - postgres
@@ -408,18 +478,17 @@ CHANGES
       behavior than before which is why it's off by default.
 
 - mssql
-     - Reflected tables will now automatically load other tables
+     - Reflected tables will now automatically load other tables 
        which are referenced by Foreign keys in the auto-loaded
-       table, [ticket:979].
+       table, [ticket:979]. 
 
-     - Added executemany check to skip identity fetch,
-       [ticket:916].
+     - Added executemany check to skip identity fetch, [ticket:916].
 
      - Added stubs for small date type, [ticket:884]
 
-     - Added a new 'driver' keyword parameter for the pyodbc
-       dialect.  Will substitute into the ODBC connection string
-       if given, defaults to 'SQL Server'.
+     - Added a new 'driver' keyword parameter for the pyodbc dialect.
+       Will substitute into the ODBC connection string if given,
+       defaults to 'SQL Server'.
 
      - Added a new 'max_identifier_length' keyword parameter for
        the pyodbc dialect.