update example to work with new collections class

some comparison fixes

- Applied some safe collections optimizations and annotated a few key places
  for future optimization.  As-is, masseagerload shows a speed up and overall
  function reduction compared to 0.4 pre-collections.
- Some minor cleanups in collections + related

- Replaced collection api: The "InstrumentedList" proxy is replaced with
  a proxy-free, decorator-based approach for user-space instrumentation and
  a "view" adapter for interaction with the user's collection within the orm.
  Fixes [ticket:213], [ticket:548], [ticket:563].
- This needs many more unit tests.  There is significant indirect coverage
  through association proxy, but direct tests are needed, specifically in
  the decorators and add/remove event firing.
- Collections are now instrumented via decorations rather than
  proxying.  You can now have collections that manage their own
  membership, and your class instance will be directly exposed on the
  relation property.  The changes are transparent for most users.
- InstrumentedList (as it was) is removed, and relation properties no
  longer have 'clear()', '.data', or any other added methods beyond those
  provided by the collection type.  You are free, of course, to add them
  to a custom class.
- __setitem__-like assignments now fire remove events for the existing
  value, if any.
- dict-likes used as collection classes no longer need to change __iter__
  semantics- itervalues() is used by default instead.  This is a backwards
  incompatible change.
- subclassing dict for a mapped collection is no longer needed in most cases.
  orm.collections provides canned implementations that key objects by a
  specified column or a custom function of your choice.
- collection assignment now requires a compatible type- assigning None
  to clear a collection or assinging a list to a dict collection will now
  raise an argument error.
- AttributeExtension moved to interfaces, and .delete is now .remove
  The event method signature has also been swapped around.

merge from trunk fix for undetected disconnects for mysql (ticket #625), r2793

merge 2791 from trunk, fix for bad error message (ticket #607)

merge compound select grouping patch from trunk (ticket #623)

merge from trunk #624 fix, modulo operator escaping

merged between precedence from trunk ([2785])

merged operator precedence fixes/tests IN fixes/tests from trunk r2782-r2783

docstring cleanup, removal of some ORM cruft

moved "clone" conditional blocks into separate copy_internals() method; was a
conflation of tasks having them in the same place like that.

removed ConnectionProvider.  engines have a "pool" attribute now.

merged trunk r2755-r2778

- fixed  limit/offset compilation for postgres

- merge of generative_sql branch
- copy_container() removed.  ClauseVisitor.traverse() now features "clone"
flag which allows traversal with copy-and-modify-in-place behavior
- select() objects copyable now [ticket:52] [ticket:569]
- improved support for custom column_property() attributes which
  feature correlated subqueries...work better with eager loading now.
- accept_visitor()  methods removed.  ClauseVisitor now genererates method
names based on class names, or an optional __visit_name__ attribute.  calls
regular visit_XXX methods as they exist, can optionally call an additional
"pre-descent" enter_XXX method to allow stack-based operations on traversals
- select() and union()'s now have "generative" behavior.  methods like
order_by() and group_by() return a *new* instance - the original instance
is left unchanged.  non-generative methods remain as well.
- the internals of select/union vastly simplified - all decision making
regarding "is subquery" and "correlation" pushed to SQL generation phase.
select() elements are now *never* mutated by their enclosing containers
or by any dialect's compilation process

- Added missing orm import

- expanded assignment test, ensure that re-assigning the value of
  an association mutates the backing object (rather than a delete and
  create with new primary keys)

- merged trunk r2730-r2755
- removed "clear_mapper()" method

update changelog

added a unit test to test PK "collapsing" as in [changeset:2636], to help illustrate for [ticket:611]

fixed overly eager check for ClauseElement type in filter()

fixed outerjoin() to use correct start point

- finally figured out how to get setuptools version in, available
as sqlalchemy.__version__ [ticket:428]

filter() checks for ClauseElement [ticket:535]

- merged last_inserted_ids() fix from trunk [changeset:2743]

- Eh, dummy_threading trick didn't actually work for no-op'ing overflow.
  Works now, but less readable.
- Shaped the script from ticket #608 into a test case

- Put a mutex around the QueuePool's overflow handlings

- Added testbase.Table and testbase.Column, interceptors that can set up
  test-run- and dialect-specific options on those objects
  All tests re-pointed to go through the interceptors
- Removed mysql_engine= from table declarations, replaced with a general
  flag indicating storage requirements
- Added ability to choose a global MySQL storage engine for all tests
  --mysql-engine=<whatever>
  If none is specified, tests use the old db-default/InnoDB behavior
- Added ability to append arbitrary table creation params
  --table-option=KEY=VALUE
  For MySQL 3, use this to set mysql_type instead of --mysql-engine
- Removed a couple dead test modules

unit test fix

- added "explcit" create/drop/execute support for sequences
(i.e. you can pass a "connectable" to each of those methods
on Sequence)
- checkfirst flag propigates for sequence creates/drops

- merged trunk 2629-2730
- fixes to is_select() which is now an important method
- mysql unit tests fixes

 - result sets from CRUD operations close their underlying cursor immediately.
    will also autoclose the connection if defined for the operation; this
    allows more efficient usage of connections for successive CRUD operations
    with less chance of "dangling connections".

fixed up really old tests to work without legacy engine syntax

r/m psycopg1 support

add explanation of prefab db connections

fix apparent typo

merge 2684-2686 from trunk

- Faster FOR UPDATE tests

- Added tests for SELECT ... FOR UPDATE
- Added postgres support for FOR UPDATE NOWAIT via select(for_update='nowait')

  - result.last_inserted_ids() should return a list that is identically
    sized to the primary key constraint of the table.  values that were
    "passively" created and not available via cursor.lastrowid will be None.

- MetaData loses 'name' attribute
- no more global_connect()

added separate test for metadata
some cleanup to query.py unit test
added settable "engine" property on MetaData

- added "aliased joins" feature to query.filter_by()
- further work on modernizing/cleaning up unit tests

merged StaticPool implementation

version number

added test for testing against "outerjoin"

- added a third layer of inheritance to polymorph test
- added some extra logic to mapper to try to convert a "foreign key" holding PK-col
into a non-FK col
- apparently, polymorphic loading can now be achieved with LEFT OUTER JOINs quite easily (i.e. no UNIONs).
this needs to be studied further (i.e. why was I making everyone use UNION ALL all this time)

- fixed bug where selectable.corresponding_column(selectable.c.col)
would not return selectable.c.col, if the selectable is a join
of a table and another join involving the same table.  messed
up ORM decision making [ticket:593]
- removed is_natural_case function from ANSIIdentifierPreparer

- moved another chunk of mapper.py tests to query.py test suite
- got all tests/extensions working with new APIs
- axed proxyengine until further notice
- SelectResults folds into a 10 line wrapper for Query, loses join_to() (use join())
- test cleanup

Query refactoring is complete.  just needs filter_by([args], **kwargs) feature and it should then
comply with the 0.4 spec

- added 'fields' to reserved words [ticket:590]

- long-identifier detection fixed to use > rather than >= for
max ident length [ticket:589]
- reformat changelog

more paring down...

refactoring step 2.  all deprecated functions now express their functionality
in terms of generative behavior.  also the thing will run like crap right now until
the next refactor stage...stay tuned

migrating all the "deprecated" methods away from the current methods.
step two will be to change the deprecated methods to all express their functionality (primarily) in
 terms of the non-deprecated methods.

- added all(), first(), and one()
- created new test framework for query.  migrating old test/orm/mapper.py tests over to new query.py

join() will check existing objects in the FROM clause and not re-join to one which is already present

- interfaces lib in docstrings
- query.join() resets the joinpoint
- added filter(), filter_by() to assignmapper

- removed cascade_mappers().  long overdue.
- removed sqlalchemy.orm from sqlalchemy.__init__ namespace.  still
needs updates in documentation, tutorial pages
- moved MapperExtension to interfaces package
- moved ExtensionCarrier to orm.util

added a self-creating dict that takes advantage of 2.5's __missing__, implemented in
ResultProxy, [ticket:582]

- added undefer_group() MapperOption, sets a set of "deferred" columns joined by a
"group" to load as "undeferred".

Added util.defaultdict for ticket #582

remove func call for getting at result proxy dialect.  func call count drops below 60K for masseagerload !

ResultProxy pre-caches the dialect_impl()s for each TypeEngine, saving the
method calls later.  knocks 5000 function calls off the masseagerload.py test.

self-referential refs in this test work just fine

- most of the __init__ decoration has been removed from mapper, save for
that the mappers all get compiled when an instance of a mapped class is first constructed.
the SessionContextExt extension gets all the "add object to the session" logic now and the
_sa_session and _sa_entity_name arguments only apply to when the SessionContextExt is in use.
Some extra methods to MapperExtension to support __init__ decoration.
- assignmapper loses "join_to", gains "join".  id like to replace all those methods with just "query"
but i think they are too popular, so it should probably get filter(), filter_by() also.

- merged "find the equivalent columns" logic together (although both methodologies are needed....)
- uniqueappender has to use a set to handle staggered joins

i just re-took 7th grade, helped a million

more speed improvements, built hotshot prof into masseagerload test

- merged trunk r2653
- small orm fixes

further minute speedups

attempting to cut down on function call overhead

some change to populate_instance etc., allows poly secondary load to re-use popoulate_instance

- refactor !  MapperProperty now has create_row_processor() method, returns
a tuple of (rowprocessor, post_processor) functions.  this is called
once per mapper per result set, given just one row (usually the first row)
in the result set, so that all MapperProperty objects can make decisions based on that row
which get saved for all successive rows.
essentially it allows lots of decision making and pre-calculations to happen per-result
instead of per-row, and decreases how much state needs to be placed in SelectContext.attributes
since the functions are closures.

- added 'fetchmode' capability to deferred polymorphic loading.
can load immediately via second select or via deferred columns.
needs work to reduce complexity and possibly to improve upon unnecessary work
performed by ColumnLoader objects hitting lots of non-existent columns
- would like to add post_exec() step to MapperProperty...but need to devise some way
such that MapperProperty instances can register themselves in the SelectContext as
requiring post_exec....otherwise we add huge method call overhead (and there is too
much already)
- fix to deferred loading so that the attributes loaded by "group" deferred loading
get proper CommittedState
- some refactoring to attributes to support setting attributes as committed

- redefined how the mapper determines primary keys.  this is to help with the new deferred
polymorphic loading.  it takes stock of all the primary keys of all of its tables in all cases,
including when a custom primary key is sent, to maximize its chances of being able to INSERT into each table.
then, whether or not the custom primary key is sent, it gathers together columns which are equivalent via
a foreign key relationship to each other or via a common parent column, similarly to how Join does it.
this continues along the path first set up from [ticket:185].  so primary keys of mappers are always
going to be "minimized" as far as number of columns.  finally, the list of pk cols is normalized to the
mapped table.  this becomes the mapper's "primary key" and is distinct from all the per-table pk column
collections.
- added "deferred poly load" versions to magazine test, cut down on table recreates in polymorph test.

- factored some fixes from trunk to lazyloader use_get, logging
- deferred inheritance loading: polymorphic mappers can be constructed *without*
a select_table argument.  inheriting mappers whose tables were not
represented in the initial load will issue a second SQL query immediately,
once per instance (i.e. not very efficient for large lists),
in order to load the remaining columns.

separate package for inheritance tests, renamed files

0.4 dev branch

- removed "no group by's in a select thats part of a UNION"
restriction [ticket:578]

correct typo

- the "primary_key" argument to mapper() is propigated to the "polymorphic"
mapper.  primary key columns in this list get normalized to that of the mapper's
local table.

- fix to select_by(<propname>=<object instance>) -style joins in conjunction
with many-to-many relationships, bug introduced in r2556
- the "reverse_direction" flag in _create_lazy_clause works correctly for a many-to-many
relationship (i.e. the reverse is on which clause, not which column in the clause, in the
case of m2m)

added test for "assign a list of objects", ensure cascade/persistence functions

fixed LoggingClauseVisitor

restored outerjoin test

- fix to polymorphic query which allows the original polymorphic_union
to be embedded into a correlated subquery [ticket:577]

- parenthesis are applied to clauses via a new _Grouping construct.
uses operator precedence to more intelligently apply parenthesis
to clauses, provides cleaner nesting of clauses (doesnt mutate
clauses placed in other clauses, i.e. no 'parens' flag)
- added 'modifier' keyword, works like func.<foo> except does not
add parenthesis.  e.g. select([modifier.DISTINCT(...)]) etc.

- _Label propigates "_hide_froms()" so that scalar selects
behave more properly with regards to FROM clause #574

propigated detach() and invalidate() methods to Connection.

- Connections can be detached from their pool, closing on dereference instead of returning to the pool for reuse

- set max identifier length to 31

- fix to long name generation when using oid_column as an order by
(oids used heavily in mapper queries)

- session.get() and session.load() propigate **kwargs through to query

- many-to-many relationships properly set the type of bind params
for delete operations on the association table
- many-to-many relationships check that the number of rows deleted
from the association table by a delete operation matches the expected
results

- shored up DBAPI descriptions
- added link to select() docs in sqlconstruction

clarifying some cascade-based unit tests, adding a little more coverage,
and trying to remove unneeded parts of dependency.py cascades.
also de-emphasizing the whole session.flush([oneobject]) thing since i dont really
agree it should be supported

- "delete-orphan" no longer implies "delete". ongoing effort to
separate the behavior of these two operations.

- _Label class overrides compare_self to return its ultimate object.
meaning, if you say someexpr.label('foo') == 5, it produces
the correct "someexpr == 5".