document declarative base made non-dynamically

officially document how to make declarative base
non-dynamically such that mypy and similar tools
can process it without plugins

Change-Id: I884f9a7c06c4a8b8111948a2dd64e308e7dce4fc
References: #4609

2 files changed, 14 insertions, 1 deletions

diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py
index 4793fc638..ac06efba6 100644
--- a/lib/sqlalchemy/orm/__init__.py
+++ b/lib/sqlalchemy/orm/__init__.py
@@ -22,6 +22,7 @@ from .attributes import QueryableAttribute  # noqa
 from .context import QueryContext  # noqa
 from .decl_api import as_declarative  # noqa
 from .decl_api import declarative_base  # noqa
+from .decl_api import DeclarativeMeta  # noqa
 from .decl_api import declared_attr  # noqa
 from .decl_api import has_inherited_table  # noqa
 from .decl_api import registry  # noqa
diff --git a/lib/sqlalchemy/orm/decl_api.py b/lib/sqlalchemy/orm/decl_api.py
index 8afdb3a50..1166d307e 100644
--- a/lib/sqlalchemy/orm/decl_api.py
+++ b/lib/sqlalchemy/orm/decl_api.py
@@ -657,11 +657,23 @@ class registry(object):
                 __tablename__ = "my_table"
                 id = Column(Integer, primary_key=True)
 
+        The above dynamically generated class is equivalent to the
+        non-dynamic example below::
+
+            from sqlalchemy.orm import registry
+            from sqlalchemy.orm.decl_api import DeclarativeMeta
+
+            mapper_registry = registry()
+
+            class Base(metaclass=DeclarativeMeta):
+                __abstract__ = True
+                registry = mapper_registry
+                metadata = mapper_registry.metadata
+
         The :meth:`_orm.registry.generate_base` method provides the
         implementation for the :func:`_orm.declarative_base` function, which
         creates the :class:`_orm.registry` and base class all at once.
 
-
         See the section :ref:`orm_declarative_mapping` for background and
         examples.