clearly point out the surprising behavior of --reload, --user, --group, --config (+ unlock a few previously impossible combinations)

.github/workflows/tox.yml

@@ -21,8 +21,7 @@ jobs:
          - macos-13
          # Not testing Windows, because tests need Unix-only fcntl, grp, pwd, etc.
         python-version:
-         # CPython <= 3.7 is EoL since 2023-06-27
-         - "3.7"
+         # CPython <= 3.8 is EoL since 2024-10-07 https://peps.python.org/pep-0569/
          - "3.8"
          - "3.9"
          - "3.10"

docs/gunicorn_ext.py

@@ -52,7 +52,10 @@ def fmt_setting(s):
         val = s.default_doc
     elif callable(s.default):
         val = inspect.getsource(s.default)
-        val = "\n".join("    %s" % line for line in val.splitlines())
+        # defaults are def'd inside class; strip the @decorator
+        val = "\n".join("    %s" % line
+                        for line in val.splitlines()
+                        if not line.strip() == "@staticmethod")
         val = "\n\n.. code-block:: python\n\n" + val
     elif s.default == '':
         val = "``''``"

docs/source/settings.rst

@@ -85,6 +85,10 @@ because it consumes less system resources.
 .. note::
    In order to use the inotify reloader, you must have the ``inotify``
    package installed.
+.. warning::
+   By default, enabling this will modify the handling of application errors
+   such that sensitive information is shared in response to any request;
+   see :ref:`on-fatal` for details.
 
 .. _reload-engine:
 
@@ -114,10 +118,13 @@ Valid engines are:
 
 **Default:** ``[]``
 
-Extends :ref:`reload` option to also watch and reload on additional files
-(e.g., templates, configurations, specifications, etc.).
+Reload when these files appear modified. Can be used either on its own or to extend
+ the :ref:`reload` option to also watch and reload on additional files
+ (e.g., templates, configurations, specifications, etc.).
 
 .. versionadded:: 19.8
+.. versionchanged:: 23.1.0
+   Now effective also when :ref:`reload` is not enabled.
 
 .. _spew:
 
@@ -1136,6 +1143,9 @@ A valid user id (as an integer) or the name of a user that can be
 retrieved with a call to ``pwd.getpwnam(value)`` or ``None`` to not
 change the worker process user.
 
+.. note::
+   Leaving this option unspecified does not skip username lookup.
+
 .. _group:
 
 ``group``
@@ -1148,9 +1158,14 @@ change the worker process user.
 Switch worker process to run as this group.
 
 A valid group id (as an integer) or the name of a user that can be
-retrieved with a call to ``pwd.getgrnam(value)`` or ``None`` to not
+retrieved with a call to ``grp.getgrnam(value)`` or ``None`` to not
 change the worker processes group.
 
+.. note::
+   Leaving this option unspecified does not skip username lookup.
+.. warning::
+   This sets effective group ID - beware of supplemental groups!
+
 .. _umask:
 
 ``umask``
@@ -1183,6 +1198,8 @@ groups of which the specified username is a member, plus the specified
 group id.
 
 .. versionadded:: 19.7
+.. note::
+   Silently ignored when username lookup fails.
 
 .. _tmp-upload-dir:
 
@@ -1560,6 +1577,30 @@ on a proxy in front of Gunicorn.
 
 .. versionadded:: 22.0.0
 
+.. _on-fatal:
+
+``on_fatal``
+~~~~~~~~~~~~
+
+**Command line:** ``--on-fatal``
+
+**Default:** ``'world-readable-with-reload'``
+
+Configure what to do if loading the application fails
+
+If set to ``world-readable``, send the traceback to the client.
+If set to ``brief``, repond with a simple error status.
+If set to ``refuse``, stop processing requests.
+The default behavior is ``world-readable-with-reload``, which is equivalent
+to ``world-readable`` when :ref:`reload` is enabled, or ``refuse`` otherwise.
+
+The behaviour of ``world-readable`` (or, the default in conjunction with
+``reload``) risks exposing sensitive code and data and is not suitable
+for production use.
+
+.. versionadded:: 23.1.0
+   The new *default* matches the previous behavior.
+
 Server Socket
 -------------
 

gunicorn/app/base.py

@@ -101,8 +101,12 @@ def get_config_from_filename(self, filename):
             if ext in [".py", ".pyc"]:
                 spec = importlib.util.spec_from_file_location(module_name, filename)
             else:
-                msg = "configuration file should have a valid Python extension.\n"
-                util.warn(msg)
+                if filename == getattr(os, "devnull", "/dev/null"):
+                    # unambiguous and generally deliberate. no need to warn in this case.
+                    pass
+                else:
+                    msg = "configuration file should have a valid Python extension.\n"
+                    util.warn(msg)
                 loader_ = importlib.machinery.SourceFileLoader(module_name, filename)
                 spec = importlib.util.spec_from_file_location(module_name, filename, loader=loader_)
             mod = importlib.util.module_from_spec(spec)