From 829aa65e642baf2f90bc29f940c8cbf180848dbc Mon Sep 17 00:00:00 2001 From: pgjones Date: Fri, 11 Oct 2019 11:52:29 +0100 Subject: [PATCH 1/2] Support loading configuration from text files TOML is a very popular format now, and is taking hold in the Python ecosystem via pyproject.toml (among others). This allows toml config files via, app.config.from_file("config.toml", toml.loads) it also allows for any other file format whereby there is a loader that takes a string and returns a mapping. --- docs/config.rst | 18 +++++++++++++++-- src/flask/config.py | 47 +++++++++++++++++++++++++++++++++----------- tests/test_config.py | 13 ++++++------ 3 files changed, 59 insertions(+), 19 deletions(-) diff --git a/docs/config.rst b/docs/config.rst index d4036f52..eeb74863 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -393,8 +393,8 @@ The following configuration values are used internally by Flask: Added :data:`MAX_COOKIE_SIZE` to control a warning from Werkzeug. -Configuring from Files ----------------------- +Configuring from Python Files +----------------------------- Configuration becomes more useful if you can store it in a separate file, ideally located outside the actual application package. This makes @@ -440,6 +440,20 @@ methods on the config object as well to load from individual files. For a complete reference, read the :class:`~flask.Config` object's documentation. +Configuring from files +---------------------- + +It is also possible to load configure from a flat file in a format of +your choice, for example to load from a TOML (or JSON) formatted +file:: + + import json + import toml + + app.config.from_file("config.toml", load=toml.load) + # Alternatively, if you prefer JSON + app.config.from_file("config.json", load=json.load) + Configuring from Environment Variables -------------------------------------- diff --git a/src/flask/config.py b/src/flask/config.py index 809de336..acfcb2d1 100644 --- a/src/flask/config.py +++ b/src/flask/config.py @@ -11,6 +11,7 @@ import errno import os import types +import warnings from werkzeug.utils import import_string @@ -176,6 +177,34 @@ class Config(dict): if key.isupper(): self[key] = getattr(obj, key) + def from_file(self, filename, load, silent=False): + """Update the values in the config from a file that is loaded using + the *load* argument. This method passes the loaded Mapping + to the :meth:`from_mapping` function. + + :param filename: the filename of the JSON file. This can either be an + absolute filename or a filename relative to the + root path. + :param load: a callable that takes a file handle and returns a mapping + from the file. + :type load: Callable[[Reader], Mapping]. Where Reader is a Protocol + that implements a read method. + :param silent: set to ``True`` if you want silent failure for missing + files. + + .. versionadded:: 1.2 + """ + filename = os.path.join(self.root_path, filename) + try: + with open(filename) as file_: + obj = load(file_) + except IOError as e: + if silent and e.errno in (errno.ENOENT, errno.EISDIR): + return False + e.strerror = "Unable to load configuration file (%s)" % e.strerror + raise + return self.from_mapping(obj) + def from_json(self, filename, silent=False): """Updates the values in the config from a JSON file. This function behaves as if the JSON object was a dictionary and passed to the @@ -189,17 +218,13 @@ class Config(dict): .. versionadded:: 0.11 """ - filename = os.path.join(self.root_path, filename) - - try: - with open(filename) as json_file: - obj = json.loads(json_file.read()) - except IOError as e: - if silent and e.errno in (errno.ENOENT, errno.EISDIR): - return False - e.strerror = "Unable to load configuration file (%s)" % e.strerror - raise - return self.from_mapping(obj) + warnings.warn( + DeprecationWarning( + '"from_json" is deprecated and will be removed in 2.0. Use' + ' "from_file(filename, load=json.load)" instead.' + ) + ) + return self.from_file(filename, json.load, silent=silent) def from_mapping(self, *mapping, **kwargs): """Updates the config like :meth:`update` ignoring items with non-upper diff --git a/tests/test_config.py b/tests/test_config.py index be40f379..450af8ce 100644 --- a/tests/test_config.py +++ b/tests/test_config.py @@ -6,6 +6,7 @@ :copyright: 2010 Pallets :license: BSD-3-Clause """ +import json import os import textwrap from datetime import timedelta @@ -27,7 +28,7 @@ def common_object_test(app): assert "TestConfig" not in app.config -def test_config_from_file(): +def test_config_from_pyfile(): app = flask.Flask(__name__) app.config.from_pyfile(__file__.rsplit(".", 1)[0] + ".py") common_object_test(app) @@ -39,10 +40,10 @@ def test_config_from_object(): common_object_test(app) -def test_config_from_json(): +def test_config_from_file(): app = flask.Flask(__name__) current_dir = os.path.dirname(os.path.abspath(__file__)) - app.config.from_json(os.path.join(current_dir, "static", "config.json")) + app.config.from_file(os.path.join(current_dir, "static", "config.json"), json.load) common_object_test(app) @@ -116,16 +117,16 @@ def test_config_missing(): assert not app.config.from_pyfile("missing.cfg", silent=True) -def test_config_missing_json(): +def test_config_missing_file(): app = flask.Flask(__name__) with pytest.raises(IOError) as e: - app.config.from_json("missing.json") + app.config.from_file("missing.json", load=json.load) msg = str(e.value) assert msg.startswith( "[Errno 2] Unable to load configuration file (No such file or directory):" ) assert msg.endswith("missing.json'") - assert not app.config.from_json("missing.json", silent=True) + assert not app.config.from_file("missing.json", load=json.load, silent=True) def test_custom_config_class(): From aac0f585b944cc65a1b570c1cc26d840f03e2f72 Mon Sep 17 00:00:00 2001 From: David Lord Date: Fri, 18 Oct 2019 09:15:00 -0700 Subject: [PATCH 2/2] clean up config.from_file docs --- CHANGES.rst | 3 +++ docs/config.rst | 26 ++++++++++++------- src/flask/config.py | 63 +++++++++++++++++++++++++-------------------- 3 files changed, 54 insertions(+), 38 deletions(-) diff --git a/CHANGES.rst b/CHANGES.rst index f1806fa4..fb211c08 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -7,6 +7,9 @@ Unreleased - Add :meth:`sessions.SessionInterface.get_cookie_name` to allow setting the session cookie name dynamically. :pr:`3369` +- Add :meth:`Config.from_file` to load config using arbitrary file + loaders, such as ``toml.load`` or ``json.load``. + :meth:`Config.from_json` is deprecated in favor of this. :pr:`3398` Version 1.1.2 diff --git a/docs/config.rst b/docs/config.rst index eeb74863..8f74b566 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -440,19 +440,25 @@ methods on the config object as well to load from individual files. For a complete reference, read the :class:`~flask.Config` object's documentation. -Configuring from files ----------------------- -It is also possible to load configure from a flat file in a format of -your choice, for example to load from a TOML (or JSON) formatted -file:: +Configuring from Data Files +--------------------------- - import json - import toml +It is also possible to load configuration from a file in a format of +your choice using :meth:`~flask.Config.from_file`. For example to load +from a TOML file: - app.config.from_file("config.toml", load=toml.load) - # Alternatively, if you prefer JSON - app.config.from_file("config.json", load=json.load) +.. code-block:: python + + import toml + app.config.from_file("config.toml", load=toml.load) + +Or from a JSON file: + +.. code-block:: python + + import json + app.config.from_file("config.json", load=json.load) Configuring from Environment Variables diff --git a/src/flask/config.py b/src/flask/config.py index acfcb2d1..4746bb64 100644 --- a/src/flask/config.py +++ b/src/flask/config.py @@ -15,7 +15,6 @@ import warnings from werkzeug.utils import import_string -from . import json from ._compat import iteritems from ._compat import string_types @@ -178,53 +177,61 @@ class Config(dict): self[key] = getattr(obj, key) def from_file(self, filename, load, silent=False): - """Update the values in the config from a file that is loaded using - the *load* argument. This method passes the loaded Mapping - to the :meth:`from_mapping` function. + """Update the values in the config from a file that is loaded + using the ``load`` parameter. The loaded data is passed to the + :meth:`from_mapping` method. - :param filename: the filename of the JSON file. This can either be an - absolute filename or a filename relative to the - root path. - :param load: a callable that takes a file handle and returns a mapping - from the file. - :type load: Callable[[Reader], Mapping]. Where Reader is a Protocol - that implements a read method. - :param silent: set to ``True`` if you want silent failure for missing - files. + .. code-block:: python + + import toml + app.config.from_file("config.toml", load=toml.load) + + :param filename: The path to the data file. This can be an + absolute path or relative to the config root path. + :param load: A callable that takes a file handle and returns a + mapping of loaded data from the file. + :type load: ``Callable[[Reader], Mapping]`` where ``Reader`` + implements a ``read`` method. + :param silent: Ignore the file if it doesn't exist. .. versionadded:: 1.2 """ filename = os.path.join(self.root_path, filename) + try: - with open(filename) as file_: - obj = load(file_) + with open(filename) as f: + obj = load(f) except IOError as e: if silent and e.errno in (errno.ENOENT, errno.EISDIR): return False + e.strerror = "Unable to load configuration file (%s)" % e.strerror raise + return self.from_mapping(obj) def from_json(self, filename, silent=False): - """Updates the values in the config from a JSON file. This function - behaves as if the JSON object was a dictionary and passed to the - :meth:`from_mapping` function. + """Update the values in the config from a JSON file. The loaded + data is passed to the :meth:`from_mapping` method. - :param filename: the filename of the JSON file. This can either be an - absolute filename or a filename relative to the - root path. - :param silent: set to ``True`` if you want silent failure for missing - files. + :param filename: The path to the JSON file. This can be an + absolute path or relative to the config root path. + :param silent: Ignore the file if it doesn't exist. + + .. deprecated:: 1.2 + Use :meth:`from_file` with :meth:`json.load` instead. .. versionadded:: 0.11 """ warnings.warn( - DeprecationWarning( - '"from_json" is deprecated and will be removed in 2.0. Use' - ' "from_file(filename, load=json.load)" instead.' - ) + "'from_json' is deprecated and will be removed in 2.0." + " Use 'from_file(filename, load=json.load)' instead.", + DeprecationWarning, + stacklevel=2, ) - return self.from_file(filename, json.load, silent=silent) + from .json import load + + return self.from_file(filename, load, silent=silent) def from_mapping(self, *mapping, **kwargs): """Updates the config like :meth:`update` ignoring items with non-upper