Skip to content

Commit 112fe40

Browse files
rsyringrsyring
committed
deprecate config/options that are replaced by engine configuration
1 parent 078a04b commit 112fe40

File tree

4 files changed

+134
-13
lines changed

4 files changed

+134
-13
lines changed

‎docs/config.rst

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,10 +39,16 @@ A list of configuration keys currently understood by the extension:
3939
on some Ubuntu versions) when used with
4040
improper database defaults that specify
4141
encoding-less databases.
42+
43+
**Deprecated** as of v2.4 and will be removed in v3.0.
4244
``SQLALCHEMY_POOL_SIZE`` The size of the database pool. Defaults
43-
to the engine's default (usually 5)
45+
to the engine's default (usually 5).
46+
47+
**Deprecated** as of v2.4 and will be removed in v3.0.
4448
``SQLALCHEMY_POOL_TIMEOUT`` Specifies the connection timeout in seconds
4549
for the pool.
50+
51+
**Deprecated** as of v2.4 and will be removed in v3.0.
4652
``SQLALCHEMY_POOL_RECYCLE`` Number of seconds after which a
4753
connection is automatically recycled.
4854
This is required for MySQL, which removes
@@ -53,11 +59,15 @@ A list of configuration keys currently understood by the extension:
5359
different default timeout value. For more
5460
information about timeouts see
5561
:ref:`timeouts`.
62+
63+
**Deprecated** as of v2.4 and will be removed in v3.0.
5664
``SQLALCHEMY_MAX_OVERFLOW`` Controls the number of connections that
5765
can be created after the pool reached
5866
its maximum size. When those additional
5967
connections are returned to the pool,
6068
they are disconnected and discarded.
69+
70+
**Deprecated** as of v2.4 and will be removed in v3.0.
6171
``SQLALCHEMY_TRACK_MODIFICATIONS`` If set to ``True``, Flask-SQLAlchemy will
6272
track modifications of objects and emit
6373
signals. The default is ``None``, which
@@ -88,7 +98,16 @@ A list of configuration keys currently understood by the extension:
8898
``SQLALCHEMY_TRACK_MODIFICATIONS`` will warn if unset.
8999

90100
.. versionchanged:: 2.4
91-
``SQLALCHEMY_ENGINE_OPTIONS`` configuration key was added.
101+
102+
* ``SQLALCHEMY_ENGINE_OPTIONS`` configuration key was added.
103+
* Deprecated keys
104+
105+
* ``SQLALCHEMY_NATIVE_UNICODE``
106+
* ``SQLALCHEMY_POOL_SIZE``
107+
* ``SQLALCHEMY_POOL_TIMEOUT``
108+
* ``SQLALCHEMY_POOL_RECYCLE``
109+
* ``SQLALCHEMY_MAX_OVERFLOW``
110+
92111

93112
Connection URI Format
94113
---------------------

‎flask_sqlalchemy/__init__.py

Lines changed: 30 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@
3131
from flask_sqlalchemy.model import Model
3232
from ._compat import itervalues, string_types, xrange
3333
from .model import DefaultMeta
34+
from . import utils
3435

3536
__version__ = '2.3.2'
3637

@@ -634,13 +635,18 @@ def create_app():
634635
the second case a :meth:`flask.Flask.app_context` has to exist.
635636
636637
By default Flask-SQLAlchemy will apply some backend-specific settings
637-
to improve your experience with them. As of SQLAlchemy 0.6 SQLAlchemy
638+
to improve your experience with them.
639+
640+
As of SQLAlchemy 0.6 SQLAlchemy
638641
will probe the library for native unicode support. If it detects
639642
unicode it will let the library handle that, otherwise do that itself.
640643
Sometimes this detection can fail in which case you might want to set
641644
``use_native_unicode`` (or the ``SQLALCHEMY_NATIVE_UNICODE`` configuration
642645
key) to ``False``. Note that the configuration key overrides the
643-
value you pass to the constructor.
646+
value you pass to the constructor. Direct support for ``use_native_unicode``
647+
and SQLALCHEMY_NATIVE_UNICODE are deprecated as of v2.4 and will be removed
648+
in v3.0. ``engine_options`` and ``SQLALCHEMY_ENGINE_OPTIONS`` may be used
649+
instead.
644650
645651
This class also provides access to all the SQLAlchemy functions and classes
646652
from the :mod:`sqlalchemy` and :mod:`sqlalchemy.orm` modules. So you can
@@ -696,6 +702,9 @@ class to be used in place of :class:`Model`.
696702
697703
.. versionadded:: 2.4
698704
The `engine_options` parameter was added.
705+
706+
.. versionchanged:: 2.4
707+
The `use_native_unicode` parameter was deprecated.
699708
"""
700709

701710
#: Default query class used by :attr:`Model.query` and other queries.
@@ -834,6 +843,12 @@ def init_app(self, app):
834843
'or False to suppress this warning.'
835844
))
836845

846+
# Deprecation warnings for config keys that should be replaced by SQLALCHEMY_ENGINE_OPTIONS.
847+
utils.engine_config_warning(app.config, '3.0', 'SQLALCHEMY_POOL_SIZE', 'pool_size')
848+
utils.engine_config_warning(app.config, '3.0', 'SQLALCHEMY_POOL_TIMEOUT', 'pool_timeout')
849+
utils.engine_config_warning(app.config, '3.0', 'SQLALCHEMY_POOL_RECYCLE', 'pool_recycle')
850+
utils.engine_config_warning(app.config, '3.0', 'SQLALCHEMY_MAX_OVERFLOW', 'max_overflow')
851+
837852
app.extensions['sqlalchemy'] = _SQLAlchemyState(self)
838853

839854
@app.teardown_appcontext
@@ -904,6 +919,19 @@ def apply_driver_hacks(self, app, sa_url, options):
904919
if not unu:
905920
options['use_native_unicode'] = False
906921

922+
if app.config['SQLALCHEMY_NATIVE_UNICODE'] is not None:
923+
warnings.warn(
924+
"The 'SQLALCHEMY_NATIVE_UNICODE' config option is deprecated and will be removed in"
925+
" v3.0. Use 'SQLALCHEMY_ENGINE_OPTIONS' instead.",
926+
DeprecationWarning
927+
)
928+
if not self.use_native_unicode:
929+
warnings.warn(
930+
"'use_native_unicode' is deprecated and will be removed in v3.0."
931+
" Use the 'engine_options' parameter instead.",
932+
DeprecationWarning
933+
)
934+
907935
@property
908936
def engine(self):
909937
"""Gives access to the engine. If the database configuration is bound

‎flask_sqlalchemy/utils.py

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import warnings
12

23
import sqlalchemy
34

@@ -32,3 +33,13 @@ def sqlalchemy_version(op, val):
3233
if op == '>=':
3334
return sa_ver >= target_ver
3435
return sa_ver == target_ver
36+
37+
38+
def engine_config_warning(config, version, deprecated_config_key, engine_option):
39+
if config[deprecated_config_key] is not None:
40+
warnings.warn(
41+
'The `{}` config option is deprecated and will be removed in'
42+
' v{}. Use `SQLALCHEMY_ENGINE_OPTIONS[\'{}\']` instead.'
43+
.format(deprecated_config_key, version, engine_option),
44+
DeprecationWarning
45+
)

‎tests/test_config.py

Lines changed: 72 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,16 @@
66
from flask_sqlalchemy import _compat, utils
77

88

9+
@pytest.fixture
10+
def app_nr(app):
11+
"""
12+
Signal/event registration with record queries breaks when
13+
sqlalchemy.create_engine() is mocked out.
14+
"""
15+
app.config['SQLALCHEMY_RECORD_QUERIES'] = False
16+
return app
17+
18+
919
class TestConfigKeys:
1020

1121
def test_defaults(self, app):
@@ -81,15 +91,68 @@ def test_engine_creation_ok(self, app, recwarn):
8191

8292
assert len(recwarn) == expected_warnings
8393

94+
@mock.patch.object(fsa.sqlalchemy, 'create_engine', autospec=True, spec_set=True)
95+
def test_native_unicode_deprecation_config_opt(self, m_create_engine, app_nr, recwarn):
96+
app_nr.config['SQLALCHEMY_NATIVE_UNICODE'] = False
97+
assert fsa.SQLAlchemy(app_nr).get_engine()
98+
assert len(recwarn) == 1
8499

85-
@pytest.fixture
86-
def app_nr(app):
87-
"""
88-
Signal/event registration with record queries breaks when
89-
sqlalchemy.create_engine() is mocked out.
90-
"""
91-
app.config['SQLALCHEMY_RECORD_QUERIES'] = False
92-
return app
100+
warning_msg = recwarn[0].message.args[0]
101+
assert 'SQLALCHEMY_NATIVE_UNICODE' in warning_msg
102+
assert 'deprecated and will be removed in v3.0' in warning_msg
103+
104+
@mock.patch.object(fsa.sqlalchemy, 'create_engine', autospec=True, spec_set=True)
105+
def test_native_unicode_deprecation_init_opt(self, m_create_engine, app_nr, recwarn):
106+
assert fsa.SQLAlchemy(app_nr, use_native_unicode=False).get_engine()
107+
assert len(recwarn) == 1
108+
109+
warning_msg = recwarn[0].message.args[0]
110+
assert 'use_native_unicode' in warning_msg
111+
assert 'deprecated and will be removed in v3.0' in warning_msg
112+
113+
@mock.patch.object(fsa.sqlalchemy, 'create_engine', autospec=True, spec_set=True)
114+
def test_deprecation_config_opt_pool_size(self, m_create_engine, app_nr, recwarn):
115+
app_nr.config['SQLALCHEMY_POOL_SIZE'] = 5
116+
assert fsa.SQLAlchemy(app_nr).get_engine()
117+
assert len(recwarn) == 1
118+
119+
warning_msg = recwarn[0].message.args[0]
120+
assert 'SQLALCHEMY_POOL_SIZE' in warning_msg
121+
assert 'deprecated and will be removed in v3.0.' in warning_msg
122+
assert 'pool_size' in warning_msg
123+
124+
@mock.patch.object(fsa.sqlalchemy, 'create_engine', autospec=True, spec_set=True)
125+
def test_deprecation_config_opt_pool_timeout(self, m_create_engine, app_nr, recwarn):
126+
app_nr.config['SQLALCHEMY_POOL_TIMEOUT'] = 5
127+
assert fsa.SQLAlchemy(app_nr).get_engine()
128+
assert len(recwarn) == 1
129+
130+
warning_msg = recwarn[0].message.args[0]
131+
assert 'SQLALCHEMY_POOL_TIMEOUT' in warning_msg
132+
assert 'deprecated and will be removed in v3.0.' in warning_msg
133+
assert 'pool_timeout' in warning_msg
134+
135+
@mock.patch.object(fsa.sqlalchemy, 'create_engine', autospec=True, spec_set=True)
136+
def test_deprecation_config_opt_pool_recycle(self, m_create_engine, app_nr, recwarn):
137+
app_nr.config['SQLALCHEMY_POOL_RECYCLE'] = 5
138+
assert fsa.SQLAlchemy(app_nr).get_engine()
139+
assert len(recwarn) == 1
140+
141+
warning_msg = recwarn[0].message.args[0]
142+
assert 'SQLALCHEMY_POOL_RECYCLE' in warning_msg
143+
assert 'deprecated and will be removed in v3.0.' in warning_msg
144+
assert 'pool_recycle' in warning_msg
145+
146+
@mock.patch.object(fsa.sqlalchemy, 'create_engine', autospec=True, spec_set=True)
147+
def test_deprecation_config_opt_max_overflow(self, m_create_engine, app_nr, recwarn):
148+
app_nr.config['SQLALCHEMY_MAX_OVERFLOW'] = 5
149+
assert fsa.SQLAlchemy(app_nr).get_engine()
150+
assert len(recwarn) == 1
151+
152+
warning_msg = recwarn[0].message.args[0]
153+
assert 'SQLALCHEMY_MAX_OVERFLOW' in warning_msg
154+
assert 'deprecated and will be removed in v3.0.' in warning_msg
155+
assert 'max_overflow' in warning_msg
93156

94157

95158
@mock.patch.object(fsa.sqlalchemy, 'create_engine', autospec=True, spec_set=True)
@@ -139,7 +202,7 @@ def test_pool_class_default(self, m_create_engine, app_nr):
139202
args, options = m_create_engine.call_args
140203
assert options['poolclass'].__name__ == 'StaticPool'
141204

142-
def test_pool_class_with_pool_size_zero(self, m_create_engine, app_nr):
205+
def test_pool_class_with_pool_size_zero(self, m_create_engine, app_nr, recwarn):
143206
app_nr.config['SQLALCHEMY_POOL_SIZE'] = 0
144207
with pytest.raises(RuntimeError) as exc_info:
145208
fsa.SQLAlchemy(app_nr).get_engine()

0 commit comments

Comments
 (0)