Merge "[doc] keyword arguments are strictly recommended for logging f…

…unctions."

ROADMAP.rst

@@ -73,6 +73,8 @@ Pending removal in Pywikibot 10
 * 7.3.0: Old color escape sequences like ``\03{color}`` is deprecated in favour of new color format like <<color>>
 * 7.3.0: ``linktrail`` method of :class:`family.Family` is deprecated; use :meth:`APISite.linktrail()
   <pywikibot.site._apisite.APISite.linktrail>` instead
+* 7.2.0: Positional arguments *decoder*, *layer* and *newline* for :mod:`logging` functions where dropped; keyword 
+  arguments must be used instead.
 * 7.2.0: ``tb`` parameter of :func:`exception()<pywikibot.exception>` function was renamed to ``exc_info``
 * 7.2.0: XMLDumpOldPageGenerator is deprecated in favour of a ``content`` parameter of
   :func:`XMLDumpPageGenerator<pagegenerators.XMLDumpPageGenerator>` (:phab:`T306134`)

pywikibot/logging.py

@@ -18,6 +18,10 @@
 The function :func:`debug` only logs its messages, they are never
 displayed on the user console. :func:`debug()` takes a required second
 argument, which is a string indicating the debugging layer.
+
+.. seealso::
+   - :pyhow:`Logging HOWTO<logging>`
+   - :python:`Logging Cookbook<howto/logging-cookbook.html>`
 """
 #
 # (C) Pywikibot team, 2010-2024
@@ -85,9 +89,9 @@ def logoutput(msg: Any,
               **kwargs: Any) -> None:
     """Format output and send to the logging module.
 
-    Helper function used by all the user-output convenience functions.
-    It can be used to implement your own high-level output function with
-    a different logging level.
+    Dispatch helper function used by all the user-output convenience
+    functions. It can be used to implement your own high-level output
+    function with a different logging level.
 
     `msg` can contain special sequences to create colored output. These
     consist of the color name in angle bracket, e. g. <<lightpurple>>.
@@ -97,21 +101,21 @@ def logoutput(msg: Any,
     the only argument that is useful is ``exc_info=True``, which causes
     the log message to include an exception traceback.
 
+    .. versionchanged:: 7.2
+       Positional arguments for *decoder* and *newline* are deprecated;
+       keyword arguments should be used.
+
     :param msg: The message to be printed.
     :param args: Not used yet; prevents positional arguments except `msg`.
     :param level: The logging level; supported by :func:`logoutput` only.
-    :keyword newline: If newline is True (default), a line feed will be
-        added after printing the msg.
-    :type newline: bool
-    :keyword layer: Suffix of the logger name separated by dot. By
+    :keyword bool newline: If newline is True (default), a line feed
+        will be added after printing the msg.
+    :keyword str layer: Suffix of the logger name separated by dot. By
         default no suffix is used.
-    :type layer: str
-    :keyword decoder: If msg is bytes, this decoder is used to decode.
-        Default is 'utf-8', fallback is 'iso8859-1'
-    :type decoder: str
+    :keyword str decoder: If msg is bytes, this decoder is used to
+        decode. Default is 'utf-8', fallback is 'iso8859-1'
     :param kwargs: For the other keyword arguments refer
         :python:`Logger.debug()<library/logging.html#logging.Logger.debug>`
-        and :pyhow:`logging-cookbook`
     """
     # invoke any init routines
     if _init_routines:
@@ -174,7 +178,9 @@ def info(msg: Any = '', *args: Any, **kwargs: Any) -> None:
     The arguments are interpreted as for :func:`logoutput`.
 
     .. versionadded:: 7.2
-       was renamed from :func:`output`.
+       was renamed from :func:`output`. Positional arguments for
+       *decoder* and *newline* are deprecated; keyword arguments should
+       be used. Keyword parameter *layer* was added.
 
     .. seealso::
        :python:`Logger.info()<library/logging.html#logging.Logger.info>`
@@ -189,7 +195,7 @@ def info(msg: Any = '', *args: Any, **kwargs: Any) -> None:
 .. versionchanged:: 7.2
    was renamed to :func:`info`; `text` was renamed to `msg`; `msg`
    paramerer may be omitted; only keyword arguments are allowed except
-   for `msg`.
+   for `msg`. Keyword parameter *layer* was added.
 .. seealso::
    :python:`Logger.info()<library/logging.html#logging.Logger.info>`
 """
@@ -209,7 +215,8 @@ def stdout(msg: Any = '', *args: Any, **kwargs: Any) -> None:
 
     .. versionchanged:: 7.2
        `text` was renamed to `msg`; `msg` parameter may be omitted;
-       only keyword arguments are allowed except for `msg`.
+       only keyword arguments are allowed except for `msg`. Keyword
+       parameter *layer* was added.
     .. seealso::
        - :python:`Logger.log()<library/logging.html#logging.Logger.log>`
        - https://en.wikipedia.org/wiki/Pipeline_%28Unix%29
@@ -227,7 +234,7 @@ def warning(msg: Any, *args: Any, **kwargs: Any) -> None:
 
     .. versionchanged:: 7.2
        `text` was renamed to `msg`; only keyword arguments are allowed
-       except for `msg`.
+       except for `msg`. Keyword parameter *layer* was added.
     .. seealso::
        :python:`Logger.warning()<library/logging.html#logging.Logger.warning>`
     """
@@ -244,7 +251,7 @@ def error(msg: Any, *args: Any, **kwargs: Any) -> None:
 
     .. versionchanged:: 7.2
        `text` was renamed to `msg`; only keyword arguments are allowed
-       except for `msg`.
+       except for `msg`. Keyword parameter *layer* was added.
     .. seealso::
        :python:`Logger.error()<library/logging.html#logging.Logger.error>`
     """
@@ -260,7 +267,7 @@ def log(msg: Any, *args: Any, **kwargs: Any) -> None:
 
     .. versionchanged:: 7.2
        `text` was renamed to `msg`; only keyword arguments are allowed
-       except for `msg`.
+       except for `msg`. Keyword parameter *layer* was added.
     .. seealso::
        :python:`Logger.log()<library/logging.html#logging.Logger.log>`
     """
@@ -277,7 +284,7 @@ def critical(msg: Any, *args: Any, **kwargs: Any) -> None:
 
     .. versionchanged:: 7.2
        `text` was renamed to `msg`; only keyword arguments are allowed
-       except for `msg`.
+       except for `msg`. Keyword parameter *layer* was added.
     .. seealso::
        :python:`Logger.critical()
        <library/logging.html#logging.Logger.critical>`
@@ -329,7 +336,8 @@ def exception(msg: Any = None, *args: Any,
 
     .. versionchanged:: 7.2
        only keyword arguments are allowed except for `msg`;
-       `exc_info` keyword is to be used instead of `tb`.
+       `exc_info` keyword is to be used instead of `tb`. Keyword
+       parameter *layer* was added.
     .. versionchanged:: 7.3
        `exc_info` is True by default
     .. seealso::