release version 3.1.0 (#1254)

CHANGES.rst

@@ -1,7 +1,7 @@
 Version 3.1.0
 -------------
 
-Unreleased
+Released 2023-09-10
 
 -   Drop support for Python 3.7.  :pr:`1251`
 -   Add support for the SQLAlchemy 2.x API via ``model_class`` parameter. :issue:`1140`

src/flask_sqlalchemy/__init__.py

@@ -2,7 +2,7 @@
 
 from .extension import SQLAlchemy
 
-__version__ = "3.1.0.dev"
+__version__ = "3.1.0"
 
 __all__ = [
     "SQLAlchemy",

src/flask_sqlalchemy/extension.py

@@ -708,6 +708,34 @@ def engine(self) -> sa.engine.Engine:
         """
         return self.engines[None]
 
+    def get_engine(
+        self, bind_key: str | None = None, **kwargs: t.Any
+    ) -> sa.engine.Engine:
+        """Get the engine for the given bind key for the current application.
+        This requires that a Flask application context is active.
+
+        :param bind_key: The name of the engine.
+
+        .. deprecated:: 3.0
+            Will be removed in Flask-SQLAlchemy 3.2. Use ``engines[key]`` instead.
+
+        .. versionchanged:: 3.0
+            Renamed the ``bind`` parameter to ``bind_key``. Removed the ``app``
+            parameter.
+        """
+        warnings.warn(
+            "'get_engine' is deprecated and will be removed in Flask-SQLAlchemy"
+            " 3.2. Use 'engine' or 'engines[key]' instead. If you're using"
+            " Flask-Migrate or Alembic, you'll need to update your 'env.py' file.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
+        if "bind" in kwargs:
+            bind_key = kwargs.pop("bind")
+
+        return self.engines[bind_key]
+
     def get_or_404(
         self,
         entity: type[_O],