- Tickets [ticket:1200].

- Added note about create_session() defaults.

- Added section about metadata.reflect().

- Updated `TypeDecorator` section.

- Rewrote the "threadlocal" strategy section of
the docs due to recent confusion over this
feature.

- ordered the init arguments in the docs for sessionmaker().

- other edits

2 files changed, 32 insertions, 21 deletions

diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index 15e751cca..a0f2f1f52 100644
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -83,18 +83,6 @@ def sessionmaker(bind=None, class_=None, autoflush=True, autocommit=False,
       by any of these methods, the ``Session`` is ready for the next usage,
       which will again acquire and maintain a new connection/transaction.
 
-    expire_on_commit
-      Defaults to ``True``. When ``True``, all instances will be fully expired after
-      each ``commit()``, so that all attribute/object access subsequent to a completed
-      transaction will load from the most recent database state.
-
-    _enable_transaction_accounting
-      Defaults to ``True``.  A legacy-only flag which when ``False``
-      disables *all* 0.5-style object accounting on transaction boundaries,
-      including auto-expiry of instances on rollback and commit, maintenance of
-      the "new" and "deleted" lists upon rollback, and autoflush
-      of pending changes upon begin(), all of which are interdependent.
-
     autoflush
       When ``True``, all query operations will issue a ``flush()`` call to
       this ``Session`` before proceeding. This is a convenience feature so
@@ -138,6 +126,18 @@ def sessionmaker(bind=None, class_=None, autoflush=True, autocommit=False,
       Deprecated.  Use
       ``logging.getLogger('sqlalchemy.orm.unitofwork').setLevel(logging.DEBUG)``.
 
+    _enable_transaction_accounting
+      Defaults to ``True``.  A legacy-only flag which when ``False``
+      disables *all* 0.5-style object accounting on transaction boundaries,
+      including auto-expiry of instances on rollback and commit, maintenance of
+      the "new" and "deleted" lists upon rollback, and autoflush
+      of pending changes upon begin(), all of which are interdependent.
+
+    expire_on_commit
+      Defaults to ``True``. When ``True``, all instances will be fully expired after
+      each ``commit()``, so that all attribute/object access subsequent to a completed
+      transaction will load from the most recent database state.
+
     extension
       An optional [sqlalchemy.orm.session#SessionExtension] instance, or
       a list of such instances, which
@@ -145,6 +145,10 @@ def sessionmaker(bind=None, class_=None, autoflush=True, autocommit=False,
       post-rollback event.  User- defined code may be placed within these
       hooks using a user-defined subclass of ``SessionExtension``.
 
+    query_cls
+      Class which should be used to create new Query objects, as returned
+      by the ``query()`` method.  Defaults to [sqlalchemy.orm.query#Query].
+
     twophase
       When ``True``, all transactions will be started using
       [sqlalchemy.engine_TwoPhaseTransaction]. During a ``commit()``, after
@@ -153,10 +157,6 @@ def sessionmaker(bind=None, class_=None, autoflush=True, autocommit=False,
       called. This allows each database to roll back the entire transaction,
       before each transaction is committed.
 
-    query_cls
-      Class which should be used to create new Query objects, as returned
-      by the ``query()`` method.  Defaults to [sqlalchemy.orm.query#Query].
-
     weak_identity_map
       When set to the default value of ``False``, a weak-referencing map is
       used; instances which are not externally referenced will be garbage
diff --git a/lib/sqlalchemy/schema.py b/lib/sqlalchemy/schema.py
index 74f3e6093..aad119906 100644
--- a/lib/sqlalchemy/schema.py
+++ b/lib/sqlalchemy/schema.py
@@ -1417,6 +1417,9 @@ class MetaData(SchemaItem):
     ``Connection``.  If bound, the [sqlalchemy.schema#Table] objects in the
     collection and their columns may participate in implicit SQL execution.
 
+    The `Table` objects themselves are stored in the `metadata.tables` 
+    dictionary.
+    
     The ``bind`` property may be assigned to dynamically.  A common pattern is
     to start unbound and then bind later when an engine is available::
 
@@ -1448,8 +1451,8 @@ class MetaData(SchemaItem):
           Defaults to False. ``bind`` is required when this option is set.
           For finer control over loaded tables, use the ``reflect`` method of
           ``MetaData``.
-        """
 
+        """
         self.tables = {}
         self.bind = bind
         self.metadata = self
@@ -1488,8 +1491,8 @@ class MetaData(SchemaItem):
           string or ``URL``, will be passed to ``create_engine()`` along with
           ``\**kwargs`` to produce the engine which to connect to.  Otherwise
           connects directly to the given ``Engine``.
+          
         """
-
         global URL
         if URL is None:
             from sqlalchemy.engine.url import URL
@@ -1505,6 +1508,7 @@ class MetaData(SchemaItem):
         This property may be assigned an ``Engine`` or ``Connection``, or
         assigned a string or URL to automatically create a basic ``Engine``
         for this bind with ``create_engine()``.
+        
         """
         return self._bind
 
@@ -1523,14 +1527,21 @@ class MetaData(SchemaItem):
     bind = property(bind, _bind_to)
 
     def clear(self):
+        """Clear all Table objects from this MetaData."""
+        # TODO: why have clear()/remove() but not all
+        # other accesors/mutators for the tables dict ?
         self.tables.clear()
 
     def remove(self, table):
+        """Remove the given Table object from this MetaData."""
+        
         # TODO: scan all other tables and remove FK _column
         del self.tables[table.key]
 
     @util.deprecated('Deprecated. Use ``metadata.sorted_tables``')
     def table_iterator(self, reverse=True, tables=None):
+        """Deprecated - use metadata.sorted_tables()."""
+        
         from sqlalchemy.sql.util import sort_tables
         if tables is None:
             tables = self.tables.values()
@@ -1578,8 +1589,8 @@ class MetaData(SchemaItem):
           filter the list of potential table names.  The callable is called
           with a table name and this ``MetaData`` instance as positional
           arguments and should return a true value for any table to reflect.
-        """
 
+        """
         reflect_opts = {'autoload': True}
         if bind is None:
             bind = _bind_or_error(self)
@@ -1644,8 +1655,8 @@ class MetaData(SchemaItem):
 
           # triggers MetaData listeners too:
           some.table.create()
-        """
 
+        """
         if event not in self.ddl_events:
             raise LookupError(event)
         self.ddl_listeners[event].append(listener)
@@ -1694,8 +1705,8 @@ class MetaData(SchemaItem):
         checkfirst
           Defaults to True, only issue DROPs for tables confirmed to be present
           in the target database.
-        """
 
+        """
         if bind is None:
             bind = _bind_or_error(self)
         for listener in self.ddl_listeners['before-drop']: