From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Sat, 4 Sep 2010 14:25:58 +0000 (-0400)
Subject: restore the deprecated docs
X-Git-Tag: rel_0_7b1~253^2~23
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b6fe3a83e9127996cb903ae176701ddfbcca5b12;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

restore the deprecated docs
---

diff --git a/doc/build/reference/sqlalchemy/schema.rst b/doc/build/reference/sqlalchemy/schema.rst
index 32ebaa6169..3352cb1a2a 100644
--- a/doc/build/reference/sqlalchemy/schema.rst
+++ b/doc/build/reference/sqlalchemy/schema.rst
@@ -102,8 +102,13 @@ Default Generators and Markers
 
 .. _schema_api_ddl:
 
-DDL Generation
---------------
+DDL Generation and Events
+--------------------------
+
+.. autoclass:: DDLEvents
+    :members:
+    :undoc-members:
+    :show-inheritance:
 
 .. autoclass:: DDLElement
     :members:
@@ -155,15 +160,3 @@ DDL Generation
     :undoc-members:
     :show-inheritance:
 
-Internals
----------
-
-.. autoclass:: SchemaItem
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-.. autoclass:: SchemaVisitor
-    :members:
-    :undoc-members:
-    :show-inheritance:
diff --git a/lib/sqlalchemy/interfaces.py b/lib/sqlalchemy/interfaces.py
index 2c16935ce4..ff29f1969e 100644
--- a/lib/sqlalchemy/interfaces.py
+++ b/lib/sqlalchemy/interfaces.py
@@ -13,7 +13,7 @@ class PoolListener(object):
 
     .. note:: :class:`PoolListener` is deprecated.   Please
        refer to :func:`event.listen` as well as 
-       :attr:`.Pool.events`.
+       :class:`.PoolEvents`.
     
     Usage::
     
diff --git a/lib/sqlalchemy/schema.py b/lib/sqlalchemy/schema.py
index 4882c0d150..3e7cad70e4 100644
--- a/lib/sqlalchemy/schema.py
+++ b/lib/sqlalchemy/schema.py
@@ -2170,11 +2170,33 @@ class DDLElement(expression.Executable, expression.ClauseElement):
             bind.engine.logger.info(
                         "DDL execution skipped, criteria not met.")
 
+    @util.deprecated("0.7", "See :class:`.DDLEvents`, as well as "
+        ":meth:`.DDLEvent.execute_if`.")
     def execute_at(self, event_name, target):
         """Link execution of this DDL to the DDL lifecycle of a SchemaItem.
         
-        Deprecated.  See :class:`.DDLEvents`, as well as
-        :meth:`.DDLEvent.execute_if`.
+        Links this ``DDLElement`` to a ``Table`` or ``MetaData`` instance,
+        executing it when that schema item is created or dropped. The DDL
+        statement will be executed using the same Connection and transactional
+        context as the Table create/drop itself. The ``.bind`` property of
+        this statement is ignored.
+        
+        :param event:
+          One of the events defined in the schema item's ``.ddl_events``;
+          e.g. 'before-create', 'after-create', 'before-drop' or 'after-drop'
+
+        :param target:
+          The Table or MetaData instance for which this DDLElement will
+          be associated with.
+
+        A DDLElement instance can be linked to any number of schema items. 
+
+        ``execute_at`` builds on the ``append_ddl_listener`` interface of
+        :class:`MetaData` and :class:`Table` objects.
+
+        Caveat: Creating or dropping a Table in isolation will also trigger
+        any DDL set to ``execute_at`` that Table's MetaData.  This may change
+        in a future release.
         
         """
         
@@ -2323,6 +2345,42 @@ class DDL(DDLElement):
         :param on:
           Deprecated.  See :meth:`.DDLElement.execute_if`.
 
+          Optional filtering criteria.  May be a string, tuple or a callable
+          predicate.  If a string, it will be compared to the name of the
+          executing database dialect::
+
+            DDL('something', on='postgresql')
+
+          If a tuple, specifies multiple dialect names::
+
+            DDL('something', on=('postgresql', 'mysql'))
+
+          If a callable, it will be invoked with four positional arguments
+          as well as optional keyword arguments:
+            
+            :ddl:
+              This DDL element.
+              
+            :event:
+              The name of the event that has triggered this DDL, such as
+              'after-create' Will be None if the DDL is executed explicitly.
+
+            :target:
+              The ``Table`` or ``MetaData`` object which is the target of 
+              this event. May be None if the DDL is executed explicitly.
+
+            :connection:
+              The ``Connection`` being used for DDL execution
+
+            :tables:  
+              Optional keyword argument - a list of Table objects which are to
+              be created/ dropped within a MetaData.create_all() or drop_all()
+              method call.
+
+              
+          If the callable returns a true value, the DDL statement will be
+          executed.
+
         :param context:
           Optional dictionary, defaults to None.  These values will be
           available for use in string substitutions on the DDL statement.