Support the SQLAlchemy 2.0 DeclarativeBase models

CHANGES.rst

@@ -3,6 +3,8 @@ Version 3.1.0
 
 Unreleased
 
+-   Add support for the SQLAlchemy 2.x API via ``model_class`` parameter. :issue:`1140`
+-   Bump minimum version of SQLAlchemy to 2.0.16.
 -   Remove previously deprecated code.
 -   Pass extra keyword arguments from ``get_or_404`` to ``session.get``. :issue:`1149`
 

docs/api.rst

@@ -32,13 +32,32 @@ Model
         If the ``__table__`` or ``__tablename__`` is set explicitly, that will be used
         instead.
 
+Metaclass mixins (SQLAlchemy 1.x)
+---------------------------------
+
+If your code uses the SQLAlchemy 1.x API (the default for code that doesn't specify a ``model_class``),
+then these mixins are automatically applied to the ``Model`` class. They can also be used
+directly to create custom metaclasses. See :doc:`customizing` for more information.
+
 .. autoclass:: DefaultMeta
 
 .. autoclass:: BindMetaMixin
 
 .. autoclass:: NameMetaMixin
 
 
+Base class mixins (SQLAlchemy 2.x)
+----------------------------------
+
+If your code uses the SQLAlchemy 2.x API by passing a subclass of ``DeclarativeBase``
+or ``DeclarativeBaseNoMeta`` as the ``model_class``, then the following classes
+are automatically added as additional base classes.
+
+.. autoclass:: BindMixin
+
+.. autoclass:: NameMixin
+
+
 Session
 -------
 

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)

docs/models.rst

@@ -30,6 +30,19 @@ For convenience, the extension object provides access to names in the ``sqlalche
 ``sqlalchemy.orm`` modules. So you can use ``db.Column`` instead of importing and using
 ``sqlalchemy.Column``, although the two are equivalent.
 
+It's also possible to use the SQLAlchemy 2.x style of defining models,
+as long as you initialized the extension with an appropriate 2.x model base class
+(as described in the quickstart).
+
+.. code-block:: python
+
+    from sqlalchemy.orm import Mapped, mapped_column
+
+    class User(db.Model):
+        id: Mapped[int] = mapped_column(db.Integer, primary_key=True)
+        username: Mapped[str] = mapped_column(db.String, unique=True, nullable=False)
+        email: Mapped[str] = mapped_column(db.String)
+
 Defining a model does not create it in the database. Use :meth:`~.SQLAlchemy.create_all`
 to create the models and tables after defining them. If you define models in submodules,
 you must import them so that SQLAlchemy knows about them before calling ``create_all``.

docs/quickstart.rst

@@ -40,9 +40,76 @@ For example, to install or update the latest version using pip:
 .. _PyPI: https://pypi.org/project/Flask-SQLAlchemy/
 
 
+Initialize the Extension
+------------------------
+
+First create the ``db`` object using the ``SQLAlchemy`` constructor.
+The initialization step depends on which version of ``SQLAlchemy`` you're using.
+This extension supports both SQLAlchemy 1 and 2, but defaults to SQLAlchemy 1.
+
+.. _sqlalchemy1-initialization:
+
+Using the SQLAlchemy 1 API
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To use the SQLAlchemy 1.x API, you do not need to pass any arguments to the ``SQLAlchemy`` constructor.
+
+.. code-block:: python
+
+    from flask import Flask
+    from flask_sqlalchemy import SQLAlchemy
+    from sqlalchemy.orm import DeclarativeBase
+
+    db = SQLAlchemy()
+
+.. _sqlalchemy2-initialization:
+
+Using the SQLAlchemy 2 API
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To use the new SQLAlchemy 2.x API, pass a subclass of either `DeclarativeBase`_ or `DeclarativeBaseNoMeta`_
+to the constructor.
+
+.. code-block:: python
+
+    from flask import Flask
+    from flask_sqlalchemy import SQLAlchemy
+    from sqlalchemy.orm import DeclarativeBase
+
+    class Base(DeclarativeBase):
+      pass
+
+    db = SQLAlchemy(model_class=Base)
+
+If desired, you can enable `SQLAlchemy's native support for data classes`_
+by adding `MappedAsDataclass` as an additional parent class.
+
+.. code-block:: python
+
+    from sqlalchemy.orm import DeclarativeBase, MappedAsDataclass
+
+    class Base(DeclarativeBase, MappedAsDataclass):
+      pass
+
+    db = SQLAlchemy(model_class=Base)
+
+.. _DeclarativeBase: https://docs.sqlalchemy.org/en/20/orm/mapping_api.html#sqlalchemy.orm.DeclarativeBase
+.. _DeclarativeBaseNoMeta: https://docs.sqlalchemy.org/en/20/orm/mapping_api.html#sqlalchemy.orm.DeclarativeBaseNoMeta
+.. _SQLAlchemy's native support for data classes: https://docs.sqlalchemy.org/en/20/changelog/whatsnew_20.html#native-support-for-dataclasses-mapped-as-orm-models
+
+About the ``SQLAlchemy`` object
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Once constructed, the ``db`` object gives you access to the :attr:`db.Model <.SQLAlchemy.Model>` class to
+define models, and the :attr:`db.session <.SQLAlchemy.session>` to execute queries.
+
+The :class:`SQLAlchemy` object also takes additional arguments to customize the
+objects it manages.
+
 Configure the Extension
 -----------------------
 
+The next step is to connect the extension to your Flask app.
 The only required Flask app config is the :data:`.SQLALCHEMY_DATABASE_URI` key. That
 is a connection string that tells SQLAlchemy what database to connect to.
 
@@ -53,24 +120,15 @@ which is stored in the app's instance folder.
 
 .. code-block:: python
 
-    from flask import Flask
-    from flask_sqlalchemy import SQLAlchemy
-
-    # create the extension
-    db = SQLAlchemy()
     # create the app
     app = Flask(__name__)
     # configure the SQLite database, relative to the app instance folder
     app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///project.db"
     # initialize the app with the extension
     db.init_app(app)
 
-The ``db`` object gives you access to the :attr:`db.Model <.SQLAlchemy.Model>` class to
-define models, and the :attr:`db.session <.SQLAlchemy.session>` to execute queries.
-
 See :doc:`config` for an explanation of connections strings and what other configuration
-keys are used. The :class:`SQLAlchemy` object also takes some arguments to customize the
-objects it manages.
+keys are used.
 
 
 Define Models
@@ -81,6 +139,8 @@ Subclass ``db.Model`` to define a model class. The ``db`` object makes the names
 The model will generate a table name by converting the ``CamelCase`` class name to
 ``snake_case``.
 
+This example uses the SQLAlchemy 1.x style of defining models:
+
 .. code-block:: python
 
     class User(db.Model):
@@ -90,6 +150,20 @@ The model will generate a table name by converting the ``CamelCase`` class name
 
 The table name ``"user"`` will automatically be assigned to the model's table.
 
+It's also possible to use the SQLAlchemy 2.x style of defining models,
+as long as you initialized the extension with an appropriate 2.x model base class
+as described in :ref:`sqlalchemy2-initialization`.
+
+.. code-block:: python
+
+    from sqlalchemy.orm import Mapped, mapped_column
+
+    class User(db.Model):
+        id: Mapped[int] = mapped_column(db.Integer, primary_key=True)
+        username: Mapped[str] = mapped_column(db.String, unique=True, nullable=False)
+        email: Mapped[str] = mapped_column(db.String)
+
+
 See :doc:`models` for more information about defining and creating models and tables.
 
 

pyproject.toml

@@ -16,7 +16,7 @@ classifiers = [
 requires-python = ">=3.7"
 dependencies = [
     "flask>=2.2.5",
-    "sqlalchemy>=1.4.18",
+    "sqlalchemy>=2.0.16",
 ]
 dynamic = ["version"]
 

requirements/mypy.txt

@@ -5,8 +5,6 @@
 #
 #    pip-compile-multi
 #
-greenlet==2.0.2
-    # via sqlalchemy
 iniconfig==2.0.0
     # via pytest
 mypy==1.4.1

requirements/tests-min.in

@@ -1,3 +1,3 @@
 flask==2.2.5
 werkzeug<2.3
-sqlalchemy==1.4.18
+sqlalchemy==2.0.16

requirements/tests-min.txt

@@ -1,4 +1,4 @@
-# SHA1:46c532e5c6f44988d3c02d047503f87ea25a2f72
+# SHA1:8cae0f9c9bfdb0c4ddf46f9fb41a746cc14300a7
 #
 # This file is autogenerated by pip-compile-multi
 # To update, run:
@@ -9,8 +9,6 @@ click==8.1.3
     # via flask
 flask==2.2.5
     # via -r requirements/tests-min.in
-greenlet==2.0.2
-    # via sqlalchemy
 itsdangerous==2.1.2
     # via flask
 jinja2==3.1.2
@@ -19,8 +17,10 @@ markupsafe==2.1.3
     # via
     #   jinja2
     #   werkzeug
-sqlalchemy==1.4.18
+sqlalchemy==2.0.16
     # via -r requirements/tests-min.in
+typing-extensions==4.6.3
+    # via sqlalchemy
 werkzeug==2.2.3
     # via
     #   -r requirements/tests-min.in