jenkins-bot has submitted this change. (
https://gerrit.wikimedia.org/r/c/pywikibot/core/+/1044651?usp=email )
Change subject: [doc] keyword arguments are strictly recommended for logging
functions.
......................................................................
[doc] keyword arguments are strictly recommended for logging functions.
Change-Id: I75bc98248125e4c20490ce7bb363c9f07930ded5
---
M ROADMAP.rst
M pywikibot/logging.py
2 files changed, 30 insertions(+), 20 deletions(-)
Approvals:
jenkins-bot: Verified
Xqt: Looks good to me, approved
diff --git a/ROADMAP.rst b/ROADMAP.rst
index e407eb6..ed7c20a 100644
--- a/ROADMAP.rst
+++ b/ROADMAP.rst
@@ -73,6 +73,8 @@
* 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`)
diff --git a/pywikibot/logging.py b/pywikibot/logging.py
index 6965fd6..225b30f 100644
--- a/pywikibot/logging.py
+++ b/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 @@
**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 @@
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 @@
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 @@
.. 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 @@
.. 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 @@
.. 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 @@
.. 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 @@
.. 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 @@
.. 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 @@
.. 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::
--
To view, visit
https://gerrit.wikimedia.org/r/c/pywikibot/core/+/1044651?usp=email
To unsubscribe, or for help writing mail filters, visit
https://gerrit.wikimedia.org/r/settings?usp=email
Gerrit-MessageType: merged
Gerrit-Project: pywikibot/core
Gerrit-Branch: master
Gerrit-Change-Id: I75bc98248125e4c20490ce7bb363c9f07930ded5
Gerrit-Change-Number: 1044651
Gerrit-PatchSet: 1
Gerrit-Owner: Xqt <[email protected]>
Gerrit-Reviewer: Xqt <[email protected]>
Gerrit-Reviewer: jenkins-bot
_______________________________________________
Pywikibot-commits mailing list -- [email protected]
To unsubscribe send an email to [email protected]
