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