- declarative.declarative_base():

  takes a 'metaclass' arg, defaulting to DeclarativeMeta
  renamed 'engine' arg to 'bind', backward compat
  documented

diff --git a/doc/build/content/plugins.txt b/doc/build/content/plugins.txt
index 29d9c4b62375cfaa24c314d53b7e026b9389b8df..be769113d0e342b18f634530a228a38b57b77d11 100644 (file)
--- a/doc/build/content/plugins.txt
+++ b/doc/build/content/plugins.txt
@@ -45,10 +45,10 @@ The `declarative_base` base class contains a `MetaData` object where newly defin
     engine = create_engine('sqlite://')
     Base.metadata.create_all(engine)
 
-The `Engine` created above may also be directly associated with the declarative base class using the `engine` keyword argument, where it will be associated with the underlying `MetaData` object and allow SQL operations involving that metadata and its tables to make use of that engine automatically:
+The `Engine` created above may also be directly associated with the declarative base class using the `bind` keyword argument, where it will be associated with the underlying `MetaData` object and allow SQL operations involving that metadata and its tables to make use of that engine automatically:
 
     {python}
-    Base = declarative_base(engine=create_engine('sqlite://'))
+    Base = declarative_base(bind=create_engine('sqlite://'))
 
 Or, as `MetaData` allows, at any time using the `bind` attribute:
 

diff --git a/lib/sqlalchemy/ext/declarative.py b/lib/sqlalchemy/ext/declarative.py
index f8008ab8b0a662e094e27772e3d3fe52e58c0b2a..fd70e6b0bad60725088028fb87addeb537ecbd8f 100644 (file)
--- a/lib/sqlalchemy/ext/declarative.py
+++ b/lib/sqlalchemy/ext/declarative.py
@@ -408,12 +408,46 @@ def comparable_using(comparator_factory):
         return comparable_property(comparator_factory, fn)
     return decorate
 
-def declarative_base(engine=None, metadata=None, mapper=None, cls=object):
+def declarative_base(bind=None, metadata=None, mapper=None, cls=object,
+                     metaclass=DeclarativeMeta, engine=None):
+    """Construct a base class for declarative class definitions.
+
+    The new base class will be given a metaclass that invokes
+    `instrument_declarative()` upon each subclass definition, and routes
+    later Column- and Mapper-related attribute assignments made on the class
+    into Table and Mapper assignments.  See the `declarative` module
+    documentation for examples.
+
+    cls
+      Defaults to `object`.  A class to use as the base for the generated
+      declarative base class.
+
+    metaclass
+      Defaults to `DeclarativeMeta`.  A metaclass or __metaclass__
+      compatible callable to use as the meta type of the generated
+      declarative base class.
+
+    metadata
+      An optional `MetaData` instance.  All Tables implicitly declared by
+      subclasses of the base will share this MetaData.  A MetaData instance
+      will be create if none is provided.  The MetaData instance will be
+      available via the `metadata` attribute of the generated declarative
+      base class.
+
+    bind
+      An optional `Connectable`, will be assigned to the `metadata.bind`.
+      The `engine` keyword argument is a deprecated synonym for `bind`.
+
+    mapper
+      An optional callable, defaults to `sqlalchemy.orm.mapper`.  Will be
+      used to map subclasses to their Tables.
+
+    """
     lcl_metadata = metadata or MetaData()
-    if engine:
-        lcl_metadata.bind = engine
+    if bind or engine:
+        lcl_metadata.bind = bind or engine
     class Base(cls):
-        __metaclass__ = DeclarativeMeta
+        __metaclass__ = metaclass
         metadata = lcl_metadata
         if mapper:
             __mapper_cls__ = mapper