root/sqlalchemy/trunk/CHANGES

-*- 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
    - 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.

    - Also re-established viewonly relation() configurations
      that join across multiple tables.

    - 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
      individual column pairs which comprise the relation's
      local and remote sides.  Also improved lazy load SQL
      generation to handle placing bind params inside of
      functions and other expressions.  (partial progress
      towards [ticket:610])
    
    - Fixed "concatenate tuple" bug which could occur with
      Query.order_by() if clause adaption had taken place.
      [ticket:1027]
      
    - 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.
      
    - 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]
      
    - set-based collections |=, -=, ^= and &= are stricter about
      their operands and only operate on sets, frozensets or
      subclasses of the collection type. Previously, they would
      accept any duck-typed set.
      
    - added an example dynamic_dict/dynamic_dict.py, illustrating
      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
      function.

    - 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"))
      [ticket:1014]

    - 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).

-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.

- mssql
    - Added "odbc_autotranslate" parameter to engine / dburi
      parameters. Any given string will be passed through to the
      ODBC connection string as:

            "AutoTranslate=%s" % odbc_autotranslate

      [ticket:1005]

    - Added "odbc_options" parameter to engine / dburi
      parameters. The given string is simply appended to the
      SQLAlchemy-generated odbc connection string.

      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
    - A small change in behavior to session.merge() - existing
      objects are checked for based on primary key attributes, not
      necessarily _instance_key.  So the widely requested
      capability, that:

            x = MyObject(id=1)
            x = sess.merge(x)

      will in fact load MyObject with id #1 from the database if
      present, is now available.  merge() still copies the state
      of the given object to the persistent one, so an example
      like the above would typically have copied "None" from all
      attributes of "x" onto the persistent copy.  These can be
      reverted using session.expire(x).

    - Also fixed behavior in merge() whereby collection elements
      present on the destination but not the merged collection
      were not being removed from the destination.

    - Added a more aggressive check for "uncompiled mappers",
      helps particularly with declarative layer [ticket:995]

    - The methodology behind "primaryjoin"/"secondaryjoin" has
      been refactored.  Behavior should be slightly more
      intelligent, primarily in terms of error messages which
      have been pared down to be more readable.  In a slight
      number of scenarios it can better resolve the correct
      foreign key than before.

    - 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.  

      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
        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.  
        
        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).
      
    - Added some convenience descriptors to Query:
      query.statement returns the full SELECT construct,
      query.whereclause returns just the WHERE part of the
      SELECT construct.

    - Fixed/covered case when using a False/0 value as a
      polymorphic discriminator.

    - Fixed bug which was preventing synonym() attributes from
      being used with inheritance

    - Fixed SQL function truncation of trailing underscores
      [ticket:996]

    - When attributes are expired on a pending instance, an
      error will not be raised when the "refresh" action is
      triggered and no result is found.

    - Session.execute can now find binds from metadata

    - Adjusted the definition of "self-referential" to be any
      two mappers with a common parent (this affects whether or
      not aliased=True is required when joining with Query).

    - Made some fixes to the "from_joinpoint" argument to
      query.join() so that if the previous join was aliased and
      this one isn't, the join still happens successfully.

    - Assorted "cascade deletes" fixes:
        - Fixed "cascade delete" operation of dynamic relations,
          which had only been implemented for foreign-key
          nulling behavior in 0.4.2 and not actual cascading
          deletes [ticket:895]

        - Delete cascade without delete-orphan cascade on a
          many-to-one will not delete orphans which were
          disconnected from the parent before session.delete()
          is called on the parent (one-to-many already had
          this).

        - 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.

    - Fixed order_by calculation in Query to properly alias
      mapper-config'ed order_by when using select_from()

    - Refactored the diffing logic that kicks in when replacing
      one collection with another into collections.bulk_replace,
      useful to anyone building multi-level collections.

    - Cascade traversal algorithm converted from recursive to
      iterative to support deep object graphs.

- sql
    - 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.
      
    - '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.

    - like(), ilike(), contains(), startswith(), endswith() take
      an optional keyword argument "escape=<somestring>", which
      is set as the escape character using the syntax "x LIKE y
      ESCAPE '<somestring>'" [ticket:993], [ticket:791]

    - random() is now a generic sql function and will compile to
      the database's random implementation, if any.

    - update().values() and insert().values() take keyword
      arguments.

    - Fixed an issue in select() regarding its generation of
      FROM clauses, in rare circumstances two clauses could be
      produced when one was intended to cancel out the other.
      Some ORM queries with lots of eager loads might have seen
      this symptom.

    - The case() function now also takes a dictionary as its
      whens parameter.  It also interprets the "THEN"
      expressions as values by default, meaning case([(x==y,
      "foo")]) will interpret "foo" as a bound value, not a SQL
      expression.  use text(expr) for literal SQL expressions in
      this case.  For the criterion itself, these may be literal
      strings only if the "value" keyword is present, otherwise
      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
      "descriptor" keyword argument, e.g.: somekey =
      synonym('_somekey', descriptor=property(g, s))

    - The "deferred" function is usable with "declarative".
      Simplest usage is to declare deferred and Column together,
      e.g.: data = deferred(Column(Text))

    - Declarative also gained @synonym_for(...) and
      @comparable_using(...), front-ends for synonym and
      comparable_property.

    - Improvements to mapper compilation when using declarative;
      already-compiled mappers will still trigger compiles of
      other uncompiled mappers when used [ticket:995]

    - Declarative will complete setup for Columns lacking names,
      allows a more DRY syntax.

        class Foo(Base):
            __tablename__ = 'foos'
            id = Column(Integer, primary_key=True)

     - 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
       classes using the "__mapper_cls__" property.

- postgres
    - Got PG server side cursors back into shape, added fixed
      unit tests as part of the default test suite.  Added
      better uniqueness to the cursor ID [ticket:1001]

- 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.

- mssql
     - Reflected tables will now automatically load other tables 
       which are referenced by Foreign keys in the auto-loaded
       table, [ticket:979]. 

     - 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 'max_identifier_length' keyword parameter for
       the pyodbc dialect.

     - Improvements to pyodbc + Unix. If you couldn't get that
       combination to work before, please try again.

- mysql
     - The connection.info keys the dialect uses to cache server
       settings have changed and are now namespaced.

0.4.4
------
- sql
    - Can again create aliases of selects against textual FROM
      clauses, [ticket:975]

    - The value of a bindparam() can be a callable, in which
      case it's evaluated at statement execution time to get the
      value.

    - Added exception wrapping/reconnect support to result set
      fetching.  Reconnect works for those databases that raise
      a catchable data error during results (i.e. doesn't work
      on MySQL) [ticket:978]

    - Implemented two-phase API for "threadlocal" engine, via
      engine.begin_twophase(), engine.prepare() [ticket:936]

    - Fixed bug which was preventing UNIONS from being
      cloneable, [ticket:986]

    - Added "bind" keyword argument to insert(), update(),
      delete() and DDL(). The .bind property is now assignable
      on those statements as well as on select().

    - Insert statements can now be compiled with extra "prefix"
      words between INSERT and INTO, for vendor extensions like
      MySQL's INSERT IGNORE INTO table.

- orm
    - any(), has(), contains(), ~contains(), attribute level ==
      and != now work properly with self-referential relations -
      the clause inside the EXISTS is aliased on the "remote"
      side to distinguish it from the parent table.  This
      applies to single table self-referential as well as
      inheritance-based self-referential.

    - Repaired behavior of == and != operators at the relation()
      level when compared against NULL for one-to-one relations
      [ticket:985]

    - Fixed bug whereby session.expire() attributes were not
      loading on an polymorphically-mapped instance mapped by a
      select_table mapper.

    - Added query.with_polymorphic() - specifies a list of
      classes which descend from the base class, which will be
      added to the FROM clause of the query.  Allows subclasses
      to be used within filter() criterion as well as eagerly
      loads the attributes of those subclasses.

    - Your cries have been heard: removing a pending item from
      an attribute or collection with delete-orphan expunges the
      item from the session; no FlushError is raised.  Note that
      if you session.save()'ed the pending item explicitly, the
      attribute/collection removal still knocks it out.

    - session.refresh() and session.expire() raise an error when
      called on instances which are not persistent within the
      session

    - Fixed potential generative bug when the same Query was
      used to generate multiple Query objects using join().

    - Fixed bug which was introduced in 0.4.3, whereby loading
      an already-persistent instance mapped with joined table
      inheritance would trigger a useless "secondary" load from
      its joined table, when using the default "select"
      polymorphic_fetch.  This was due to attributes being
      marked as expired during its first load and not getting
      unmarked from the previous "secondary" load.  Attributes
      are now unexpired based on presence in __dict__ after any
      load or commit operation succeeds.

    - Deprecated Query methods apply_sum(), apply_max(),
      apply_min(), apply_avg().  Better methodologies are
      coming....

    - relation() can accept a callable for its first argument,
      which returns the class to be related.  This is in place
      to assist declarative packages to define relations without
      classes yet being in place.

    - Added a new "higher level" operator called "of_type()":
      used in join() as well as with any() and has(), qualifies
      the subclass which will be used in filter criterion, e.g.:

        query.filter(Company.employees.of_type(Engineer).
          any(Engineer.name=='foo'))

        or

        query.join(Company.employees.of_type(Engineer)).
          filter(Engineer.name=='foo')

    - Preventive code against a potential lost-reference bug in
      flush().

    - Expressions used in filter(), filter_by() and others, when
      they make usage of a clause generated from a relation
      using the identity of a child object (e.g.,
      filter(Parent.child==<somechild>)), evaluate the actual
      primary key value of <somechild> at execution time so that
      the autoflush step of the Query can complete, thereby
      populating the PK value of <somechild> in the case that
      <somechild> was pending.

    - setting the relation()-level order by to a column in the
      many-to-many "secondary" table will now work with eager
      loading, previously the "order by" wasn't aliased against
      the secondary table's alias.

    - Synonyms riding on top of existing descriptors are now
      full proxies to those descriptors.

- dialects
    - Invalid SQLite connection URLs now raise an error.

    - postgres TIMESTAMP renders correctly [ticket:981]

    - postgres PGArray is a "mutable" type by default; when used
      with the ORM, mutable-style equality/ copy-on-write
      techniques are used to test for changes.

- extensions
    - a new super-small "declarative" extension has been added,
      which allows Table and mapper() configuration to take
      place inline underneath a class declaration.  This
      extension differs from ActiveMapper and Elixir in that it
      does not redefine any SQLAlchemy semantics at all; literal
      Column, Table and relation() constructs are used to define
      the class behavior and table definition.

0.4.3
------
- sql
    - Added "schema.DDL", an executable free-form DDL statement.
      DDLs can be executed in isolation or attached to Table or
      MetaData instances and executed automatically when those
      objects are created and/or dropped.

    - Table columns and constraints can be overridden on a an
      existing table (such as a table that was already reflected)
      using the 'useexisting=True' flag, which now takes into
      account the arguments passed along with it.

    - Added a callable-based DDL events interface, adds hooks
      before and after Tables and MetaData create and drop.

    - Added generative where(<criterion>) method to delete() and
      update() constructs which return a new object with criterion
      joined to existing criterion via AND, just like
      select().where().

    - Added "ilike()" operator to column operations.  Compiles to
      ILIKE on postgres, lower(x) LIKE lower(y) on all
      others. [ticket:727]

    - Added "now()" as a generic function; on SQLite, Oracle
      and MSSQL compiles as "CURRENT_TIMESTAMP"; "now()" on
      all others. [ticket:943]

    - The startswith(), endswith(), and contains() operators now
      concatenate the wildcard operator with the given operand in
      SQL, i.e. "'%' || <bindparam>" in all cases, accept
      text('something') operands properly [ticket:962]

    - cast() accepts text('something') and other non-literal
      operands properly [ticket:962]

    - fixed bug in result proxy where anonymously generated
      column labels would not be accessible using their straight
      string name

    - Deferrable constraints can now be defined.

    - Added "autocommit=True" keyword argument to select() and
      text(), as well as generative autocommit() method on
      select(); for statements which modify the database through
      some user-defined means other than the usual INSERT/UPDATE/
      DELETE etc.  This flag will enable "autocommit" behavior
      during execution if no transaction is in progress.
      [ticket:915]

    - The '.c.' attribute on a selectable now gets an entry for
      every column expression in its columns clause.  Previously,
      "unnamed" columns like functions and CASE statements weren't
      getting put there.  Now they will, using their full string
      representation if no 'name' is available.

    - a CompositeSelect, i.e. any union(), union_all(),
      intersect(), etc. now asserts that each selectable contains
      the same number of columns.  This conforms to the
      corresponding SQL requirement.

    - The anonymous 'label' generated for otherwise unlabeled
      functions and expressions now propagates outwards at compile
      time for expressions like select([select([func.foo()])]).

    - Building on the above ideas, CompositeSelects now build up
      their ".c." collection based on the names present in the
      first selectable only; corresponding_column() now works
      fully for all embedded selectables.

    - Oracle and others properly encode SQL used for defaults like
      sequences, etc., even if no unicode idents are used since
      identifier preparer may return a cached unicode identifier.

    - Column and clause comparisons to datetime objects on the
      left hand side of the expression now work (d < table.c.col).
      (datetimes on the RHS have always worked, the LHS exception
      is a quirk of the datetime implementation.)

- orm
    - Every Session.begin() must now be accompanied by a
      corresponding commit() or rollback() unless the session is
      closed with Session.close().  This also includes the begin()
      which is implicit to a session created with
      transactional=True.  The biggest change introduced here is
      that when a Session created with transactional=True raises
      an exception during flush(), you must call
      Session.rollback() or Session.close() in order for that
      Session to continue after an exception.

    - Fixed merge() collection-doubling bug when merging transient
      entities with backref'ed collections.  [ticket:961]

    - merge(dont_load=True) does not accept transient entities,
      this is in continuation with the fact that
      merge(dont_load=True) does not accept any "dirty" objects
      either.

    - Added standalone "query" class attribute generated by a
      scoped_session.  This provides MyClass.query without using
      Session.mapper.  Use via:

        MyClass.query = Session.query_property()

    - The proper error message is raised when trying to access
      expired instance attributes with no session present
    
    - dynamic_loader() / lazy="dynamic" now accepts and uses
      the order_by parameter in the same way in which it works
      with relation().
      
    - Added expire_all() method to Session.  Calls expire() for
      all persistent instances.  This is handy in conjunction
      with...

    - Instances which have been partially or fully expired will
      have their expired attributes populated during a regular
      Query operation which affects those objects, preventing a
      needless second SQL statement for each instance.

    - Dynamic relations, when referenced, create a strong
      reference to the parent object so that the query still has a
      parent to call against even if the parent is only created
      (and otherwise dereferenced) within the scope of a single
      expression. [ticket:938]

    - Added a mapper() flag "eager_defaults". When set to True,
      defaults that are generated during an INSERT or UPDATE
      operation are post-fetched immediately, instead of being
      deferred until later.  This mimics the old 0.3 behavior.

    - query.join() can now accept class-mapped attributes as
      arguments. These can be used in place or in any combination
      with strings.  In particular this allows construction of
      joins to subclasses on a polymorphic relation, i.e.:

        query(Company).join(['employees', Engineer.name])

    - query.join() can also accept tuples of attribute name/some
      selectable as arguments.  This allows construction of joins
      *from* subclasses of a polymorphic relation, i.e.:

        query(Company).\
        join(
          [('employees', people.join(engineer)), Engineer.name]
        )

    - General improvements to the behavior of join() in
      conjunction with polymorphic mappers, i.e. joining from/to
      polymorphic mappers and properly applying aliases.

    - Fixed/improved behavior when a mapper determines the natural
      "primary key" of a mapped join, it will more effectively
      reduce columns which are equivalent via foreign key
      relation.  This affects how many arguments need to be sent
      to query.get(), among other things.  [ticket:933]

    - The lazy loader can now handle a join condition where the
      "bound" column (i.e. the one that gets the parent id sent as
      a bind parameter) appears more than once in the join
      condition.  Specifically this allows the common task of a
      relation() which contains a parent-correlated subquery, such
      as "select only the most recent child item". [ticket:946]

    - Fixed bug in polymorphic inheritance where an incorrect
      exception is raised when base polymorphic_on column does not
      correspond to any columns within the local selectable of an
      inheriting mapper more than one level deep

    - Fixed bug in polymorphic inheritance which made it difficult
      to set a working "order_by" on a polymorphic mapper.

    - Fixed a rather expensive call in Query that was slowing down
      polymorphic queries.

    - "Passive defaults" and other "inline" defaults can now be
      loaded during a flush() call if needed; in particular, this
      allows constructing relations() where a foreign key column
      references a server-side-generated, non-primary-key
      column. [ticket:954]

    - Additional Session transaction fixes/changes:
        - Fixed bug with session transaction management: parent
          transactions weren't started on the connection when
          adding a connection to a nested transaction.

        - session.transaction now always refers to the innermost
          active transaction, even when commit/rollback are called
          directly on the session transaction object.

        - Two-phase transactions can now be prepared.

        - When preparing a two-phase transaction fails on one
          connection, all the connections are rolled back.

        - session.close() didn't close all transactions when
          nested transactions were used.

        - rollback() previously erroneously set the current
          transaction directly to the parent of the transaction
          that could be rolled back to. Now it rolls back the next
          transaction up that can handle it, but sets the current
          transaction to it's parent and inactivates the
          transactions in between. Inactive transactions can only
          be rolled back or closed, any other call results in an
          error.

        - autoflush for commit() wasn't flushing for simple
          subtransactions.

        - unitofwork flush didn't close the failed transaction
          when the session was not in a transaction and commiting
          the transaction failed.

    - Miscellaneous tickets: [ticket:940] [ticket:964]

- general
    - Fixed a variety of hidden and some not-so-hidden
      compatibility issues for Python 2.3, thanks to new support
      for running the full test suite on 2.3.

    - Warnings are now issued as type exceptions.SAWarning.

- dialects
    - Better support for schemas in SQLite (linked in by ATTACH
      DATABASE ... AS name).  In some cases in the past, schema
      names were ommitted from generated SQL for SQLite.  This is
      no longer the case.

    - table_names on SQLite now picks up temporary tables as well.

    - Auto-detect an unspecified MySQL ANSI_QUOTES mode during
      reflection operations, support for changing the mode
      midstream.  Manual mode setting is still required if no
      reflection is used.

    - Fixed reflection of TIME columns on SQLite.

    - Finally added PGMacAddr type to postgres [ticket:580]

    - Reflect the sequence associated to a PK field (typically
      with a BEFORE INSERT trigger) under Firebird

    - Oracle assembles the correct columns in the result set
      column mapping when generating a LIMIT/OFFSET subquery,
      allows columns to map properly to result sets even if
      long-name truncation kicks in [ticket:941]

    - MSSQL now includes EXEC in the _is_select regexp, which
      should allow row-returning stored procedures to be used.

    - MSSQL now includes an experimental implementation of
      LIMIT/OFFSET using the ANSI SQL row_number() function, so it
      requires MSSQL-2005 or higher. To enable the feature, add
      "has_window_funcs" to the keyword arguments for connect, or
      add "?has_window_funcs=1" to your dburi query arguments.

- ext
    - Changed ext.activemapper to use a non-transactional session
      for the objectstore.

    - Fixed output order of "['a'] + obj.proxied" binary operation
      on association-proxied lists.

0.4.2p3
------
- general
    - sub version numbering scheme changed to suite
      setuptools version number rules; easy_install -u
      should now get this version over 0.4.2.

- sql
    - Text type is properly exported now and does not
      raise a warning on DDL create; String types with no
      length only raise warnings during CREATE TABLE
      [ticket:912]

    - new UnicodeText type is added, to specify an
      encoded, unlengthed Text type

    - fixed bug in union() so that select() statements
      which don't derive from FromClause objects can be
      unioned

- orm
    - fixed bug with session.dirty when using "mutable
      scalars" (such as PickleTypes)

    - added a more descriptive error message when flushing
      on a relation() that has non-locally-mapped columns
      in its primary or secondary join condition

- dialects
    - Fixed reflection of mysql empty string column
      defaults.

0.4.2b  (0.4.2p2)
------
- sql
    - changed name of TEXT to Text since its a "generic"
      type; TEXT name is deprecated until 0.5. The
      "upgrading" behavior of String to Text when no
      length is present is also deprecated until 0.5; will
      issue a warning when used for CREATE TABLE
      statements (String with no length for SQL expression
      purposes is still fine) [ticket:912]

    - generative select.order_by(None) / group_by(None)
      was not managing to reset order by/group by
      criterion, fixed [ticket:924]

- orm
    - suppressing *all* errors in
      InstanceState.__cleanup() now.

    - fixed an attribute history bug whereby assigning a
      new collection to a collection-based attribute which
      already had pending changes would generate incorrect
      history [ticket:922]
      
    - fixed delete-orphan cascade bug whereby setting the
      same object twice to a scalar attribute could log it
      as an orphan [ticket:925]
      
    - Fixed cascades on a += assignment to a list-based
      relation.
    
    - synonyms can now be created against props that don't
      exist yet, which are later added via add_property().
      This commonly includes backrefs. (i.e. you can make
      synonyms for backrefs without worrying about the
      order of operations) [ticket:919]

    - fixed bug which could occur with polymorphic "union"
      mapper which falls back to "deferred" loading of
      inheriting tables
      
    - the "columns" collection on a mapper/mapped class
      (i.e. 'c') is against the mapped table, not the
      select_table in the case of polymorphic "union"
      loading (this shouldn't be noticeable).
      
- ext
    - '+', '*', '+=' and '*=' support for association
      proxied lists.

- dialects
    - mssql - narrowed down the test for "date"/"datetime"
      in MSDate/ MSDateTime subclasses so that incoming
      "datetime" objects don't get mis-interpreted as
      "date" objects and vice versa, [ticket:923]

0.4.2a   (0.4.2p1)
------

- orm
    - fixed fairly critical bug whereby the same instance could be listed
      more than once in the unitofwork.new collection; most typically
      reproduced when using a combination of inheriting mappers and 
      ScopedSession.mapper, as the multiple __init__ calls per instance
      could save() the object with distinct _state objects

    - added very rudimentary yielding iterator behavior to Query.  Call
      query.yield_per(<number of rows>) and evaluate the Query in an 
      iterative context; every collection of N rows will be packaged up
      and yielded.  Use this method with extreme caution since it does
      not attempt to reconcile eagerly loaded collections across
      result batch boundaries, nor will it behave nicely if the same
      instance occurs in more than one batch.  This means that an eagerly
      loaded collection will get cleared out if it's referenced in more than
      one batch, and in all cases attributes will be overwritten on instances
      that occur in more than one batch.

   - Fixed in-place set mutation operators for set collections and association
     proxied sets. [ticket:920]

- dialects
    - Fixed the missing call to subtype result processor for the PGArray
      type. [ticket:913]

0.4.2
-----
- sql
    - generic functions ! we introduce a database of known SQL functions, such
      as current_timestamp, coalesce, and create explicit function objects
      representing them. These objects have constrained argument lists, are
      type aware, and can compile in a dialect-specific fashion. So saying
      func.char_length("foo", "bar") raises an error (too many args),
      func.coalesce(datetime.date(2007, 10, 5), datetime.date(2005, 10, 15))
      knows that its return type is a Date. We only have a few functions
      represented so far but will continue to add to the system [ticket:615]

    - auto-reconnect support improved; a Connection can now automatically
      reconnect after its underlying connection is invalidated, without
      needing to connect() again from the engine.  This allows an ORM session
      bound to a single Connection to not need a reconnect.
      Open transactions on the Connection must be rolled back after an invalidation 
      of the underlying connection else an error is raised.  Also fixed
      bug where disconnect detect was not being called for cursor(), rollback(),
      or commit().
      
    - added new flag to String and create_engine(),
      assert_unicode=(True|False|'warn'|None). Defaults to `False` or `None` on
      create_engine() and String, `'warn'` on the Unicode type. When `True`,
      results in all unicode conversion operations raising an exception when a
      non-unicode bytestring is passed as a bind parameter. 'warn' results
      in a warning. It is strongly advised that all unicode-aware applications 
      make proper use of Python unicode objects (i.e. u'hello' and not 'hello')
      so that data round trips accurately.

    - generation of "unique" bind parameters has been simplified to use the same
      "unique identifier" mechanisms as everything else.  This doesn't affect
      user code, except any code that might have been hardcoded against the generated
      names.  Generated bind params now have the form "<paramname>_<num>",
      whereas before only the second bind of the same name would have this form.
    
    - select().as_scalar() will raise an exception if the select does not have
      exactly one expression in its columns clause.
      
    - bindparam() objects themselves can be used as keys for execute(), i.e.
      statement.execute({bind1:'foo', bind2:'bar'})
    
    - added new methods to TypeDecorator, process_bind_param() and
      process_result_value(), which automatically take advantage of the processing
      of the underlying type.  Ideal for using with Unicode or Pickletype.
      TypeDecorator should now be the primary way to augment the behavior of any
      existing type including other TypeDecorator subclasses such as PickleType.

    - selectables (and others) will issue a warning when two columns in
      their exported columns collection conflict based on name.
      
    - tables with schemas can still be used in sqlite, firebird,
      schema name just gets dropped [ticket:890]

    - changed the various "literal" generation functions to use an anonymous
      bind parameter.  not much changes here except their labels now look 
      like ":param_1", ":param_2" instead of ":literal"
      
    - column labels in the form "tablename.columname", i.e. with a dot, are now
      supported.
      
    - from_obj keyword argument to select() can be a scalar or a list.
    
- orm
   - a major behavioral change to collection-based backrefs: they no 
     longer trigger lazy loads !  "reverse" adds and removes 
     are queued up and are merged with the collection when it is 
     actually read from and loaded; but do not trigger a load beforehand.
     For users who have noticed this behavior, this should be much more
     convenient than using dynamic relations in some cases; for those who 
     have not, you might notice your apps using a lot fewer queries than
     before in some situations. [ticket:871]

   - mutable primary key support is added. primary key columns can be
     changed freely, and the identity