clean up config.from_file docs

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

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
+Configuring from Data Files
-your choice, for example to load from a TOML (or JSON) formatted
+---------------------------
-file::
 
-   import json
+It is also possible to load configuration from a file in a format of
-   import toml
+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)
+.. code-block:: python
-   # Alternatively, if you prefer JSON
+
-   app.config.from_file("config.json", load=json.load)
+    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

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
+        """Update the values in the config from a file that is loaded
-        the *load* argument. This method passes the loaded Mapping
+        using the ``load`` parameter. The loaded data is passed to the
-        to the :meth:`from_mapping` function.
+        :meth:`from_mapping` method.
 
-        :param filename: the filename of the JSON file.  This can either be an
+        .. code-block:: python
-                         absolute filename or a filename relative to the
+
-                         root path.
+            import toml
-        :param load: a callable that takes a file handle and returns a mapping
+            app.config.from_file("config.toml", load=toml.load)
-                     from the file.
+
-        :type load: Callable[[Reader], Mapping]. Where Reader is a Protocol
+        :param filename: The path to the data file. This can be an
-                    that implements a read method.
+            absolute path or relative to the config root path.
-        :param silent: set to ``True`` if you want silent failure for missing
+        :param load: A callable that takes a file handle and returns a
-                       files.
+            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_:
+            with open(filename) as f:
-                obj = load(file_)
+                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
+        """Update the values in the config from a JSON file. The loaded
-        behaves as if the JSON object was a dictionary and passed to the
+        data is passed to the :meth:`from_mapping` method.
-        :meth:`from_mapping` function.
 
-        :param filename: the filename of the JSON file.  This can either be an
+        :param filename: The path to the JSON file. This can be an
-                         absolute filename or a filename relative to the
+            absolute path or relative to the config root path.
-                         root path.
+        :param silent: Ignore the file if it doesn't exist.
-        :param silent: set to ``True`` if you want silent failure for missing
+
-                       files.
+        .. 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."
-                '"from_json" is deprecated and will be removed in 2.0. Use'
+            " Use 'from_file(filename, load=json.load)' instead.",
-                ' "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