Add disable_autonaming

Author: pamelafox

docs/customizing.rst

@@ -160,71 +160,25 @@ To customize only ``session.query``, pass the ``query_cls`` key to the
     db = SQLAlchemy(session_options={"query_cls": GetOrQuery})
 
 
-Model Metaclass
----------------
-
-.. warning::
-    Metaclasses are an advanced topic, and you probably don't need to customize them to
-    achieve what you want. It is mainly documented here to show how to disable table
-    name generation.
-
-The model metaclass is responsible for setting up the SQLAlchemy internals when defining
-model subclasses. Flask-SQLAlchemy adds some extra behaviors through mixins; its default
-metaclass, :class:`~.DefaultMeta`, inherits them all.
-
--   :class:`.BindMetaMixin`: ``__bind_key__`` sets the bind to use for the model.
--   :class:`.NameMetaMixin`: If the model does not specify a ``__tablename__`` but does
-    specify a primary key, a name is automatically generated.
-
-You can add your own behaviors by defining your own metaclass and creating the
-declarative base yourself. Be sure to still inherit from the mixins you want (or just
-inherit from the default metaclass).
-
-Passing a declarative base class instead of a simple model base class to ``model_class``
-will cause Flask-SQLAlchemy to use this base instead of constructing one with the
-default metaclass.
-
-.. code-block:: python
-
-    from sqlalchemy.orm import declarative_base
-    from flask_sqlalchemy import SQLAlchemy
-    from flask_sqlalchemy.model import DefaultMeta, Model
-
-    class CustomMeta(DefaultMeta):
-        def __init__(cls, name, bases, d):
-            # custom class setup could go here
-
-            # be sure to call super
-            super(CustomMeta, cls).__init__(name, bases, d)
-
-        # custom class-only methods could go here
-
-    CustomModel = declarative_base(cls=Model, metaclass=CustomMeta, name="Model")
-    db = SQLAlchemy(model_class=CustomModel)
-
-You can also pass whatever other arguments you want to
-:func:`~sqlalchemy.orm.declarative_base` to customize the base class.
-
-
 Disabling Table Name Generation
-```````````````````````````````
+-------------------------------
 
 Some projects prefer to set each model's ``__tablename__`` manually rather than relying
 on Flask-SQLAlchemy's detection and generation. The simple way to achieve that is to
 set each ``__tablename__`` and not modify the base class. However, the table name
-generation can be disabled by defining a custom metaclass with only the
-``BindMetaMixin`` and not the ``NameMetaMixin``.
+generation can be disabled by setting `disable_autonaming=True` in the `SQLAlchemy` constructor.
+
+Example code using the SQLAlchemy 1.x (legacy) API:
 
 .. code-block:: python
 
-    from sqlalchemy.orm import DeclarativeMeta, declarative_base
-    from flask_sqlalchemy.model import BindMetaMixin, Model
+    db = SQLAlchemy(app, disable_autonaming=True)
 
-    class NoNameMeta(BindMetaMixin, DeclarativeMeta):
-        pass
+Example code using the SQLAlchemy 2.x declarative base:
 
-    CustomModel = declarative_base(cls=Model, metaclass=NoNameMeta, name="Model")
-    db = SQLAlchemy(model_class=CustomModel)
+.. code-block:: python
+
+    class Base(sa_orm.DeclarativeBase):
+        pass
 
-This creates a base that still supports the ``__bind_key__`` feature but does not
-generate table names.
+    db = SQLAlchemy(app, model_class=Base, disable_autonaming=True)

src/flask_sqlalchemy/extension.py

@@ -17,6 +17,7 @@
 from .model import _QueryProperty
 from .model import BindMixin
 from .model import DefaultMeta
+from .model import DefaultMetaNoName
 from .model import Model
 from .model import NameMixin
 from .pagination import Pagination
@@ -86,6 +87,10 @@ class SQLAlchemy:
     :param add_models_to_shell: Add the ``db`` instance and all model classes to
         ``flask shell``.
 
+    .. versionchanged:: 3.1.0
+        Added the ``disable_autonaming`` parameter and changed ``model_class`` parameter
+        to accept a SQLAlchemy 2.0-style declarative base subclass.
+
     .. versionchanged:: 3.0
         An active Flask application context is always required to access ``session`` and
         ``engine``.
@@ -147,6 +152,7 @@ def __init__(
         model_class: t.Type[_FSA_MC] = Model,  # type: ignore[assignment]
         engine_options: dict[str, t.Any] | None = None,
         add_models_to_shell: bool = True,
+        disable_autonaming: bool = False,
     ):
         if session_options is None:
             session_options = {}
@@ -207,7 +213,9 @@ def __init__(
             This is a subclass of SQLAlchemy's ``Table`` rather than a function.
         """
 
-        self.Model = self._make_declarative_base(model_class)
+        self.Model = self._make_declarative_base(
+            model_class, disable_autonaming=disable_autonaming
+        )
         """A SQLAlchemy declarative model class. Subclass this to define database
         models.
 
@@ -467,6 +475,7 @@ def __new__(
     def _make_declarative_base(
         self,
         model_class: t.Type[_FSA_MC],
+        disable_autonaming: bool = False,
     ) -> t.Type[_FSAModel]:
         """Create a SQLAlchemy declarative model class. The result is available as
         :attr:`Model`.
@@ -482,8 +491,11 @@ def _make_declarative_base(
         :param model_class: A model base class, or an already created declarative model
         class.
 
-        .. versionchanged:: 3.0.4
+        :param disable_autonaming: Turns off automatic tablename generation in models.
+
+        .. versionchanged:: 3.1.0
             Added support for passing SQLAlchemy 2.x base class as model class.
+            Added optional ``disable_autonaming`` parameter.
 
         .. versionchanged:: 3.0
             Renamed with a leading underscore, this method is internal.
@@ -505,16 +517,20 @@ def _make_declarative_base(
             )
         elif len(declarative_bases) == 1:
             body = {"__fsa__": self}
+            mixin_classes = [BindMixin, NameMixin, Model]
+            if disable_autonaming:
+                mixin_classes.remove(NameMixin)
             model = types.new_class(
                 "FlaskSQLAlchemyBase",
-                (BindMixin, NameMixin, Model, *model_class.__bases__),
+                (*mixin_classes, *model_class.__bases__),
                 {"metaclass": type(declarative_bases[0])},
                 lambda ns: ns.update(body),
             )
         elif not isinstance(model_class, sa_orm.DeclarativeMeta):
             metadata = self._make_metadata(None)
+            metaclass = DefaultMetaNoName if disable_autonaming else DefaultMeta
             model = sa_orm.declarative_base(
-                metadata=metadata, cls=model_class, name="Model", metaclass=DefaultMeta
+                metadata=metadata, cls=model_class, name="Model", metaclass=metaclass
             )
         else:
             model = model_class

src/flask_sqlalchemy/model.py

@@ -314,3 +314,9 @@ class DefaultMeta(BindMetaMixin, NameMetaMixin, sa_orm.DeclarativeMeta):
     """SQLAlchemy declarative metaclass that provides ``__bind_key__`` and
     ``__tablename__`` support.
     """
+
+
+class DefaultMetaNoName(BindMetaMixin, sa_orm.DeclarativeMeta):
+    """SQLAlchemy declarative metaclass that provides ``__bind_key__`` and
+    ``__tablename__`` support.
+    """

tests/test_model.py

@@ -4,6 +4,7 @@
 
 import pytest
 import sqlalchemy as sa
+import sqlalchemy.exc as sa_exc
 import sqlalchemy.orm as sa_orm
 from flask import Flask
 
@@ -68,3 +69,26 @@ class Base(sa_orm.DeclarativeBase, sa_orm.DeclarativeBaseNoMeta):  # type: ignor
 
     with pytest.raises(ValueError):
         SQLAlchemy(app, model_class=Base)
+
+
+@pytest.mark.usefixtures("app_ctx")
+def test_disable_autonaming_true_sql1(app: Flask) -> None:
+    db = SQLAlchemy(app, disable_autonaming=True)
+
+    with pytest.raises(sa_exc.InvalidRequestError):
+
+        class User(db.Model):
+            id = sa.Column(sa.Integer, primary_key=True)
+
+
+@pytest.mark.usefixtures("app_ctx")
+def test_disable_autonaming_true_sql2(app: Flask) -> None:
+    class Base(sa_orm.DeclarativeBase):
+        pass
+
+    db = SQLAlchemy(app, model_class=Base, disable_autonaming=True)
+
+    with pytest.raises(sa_exc.InvalidRequestError):
+
+        class User(db.Model):
+            id: sa_orm.Mapped[int] = sa_orm.mapped_column(sa.Integer, primary_key=True)