Xqt has submitted this change. (
https://gerrit.wikimedia.org/r/c/pywikibot/core/+/640171
)
Change subject: [doc] Improved doc string for logging.py function
......................................................................
[doc] Improved doc string for logging.py function
Extended doc strings for logging.py functions such as error, exception,
stdout, log, critical and debug.
Bug: T85271
Change-Id: I265a5258d711a6e038b1974e4f1cf29fd5c0f650
---
M pywikibot/logging.py
1 file changed, 51 insertions(+), 5 deletions(-)
Approvals:
jenkins-bot: Verified
Xqt: Looks good to me, approved
diff --git a/pywikibot/logging.py b/pywikibot/logging.py
index ed4e842..457e276 100644
--- a/pywikibot/logging.py
+++ b/pywikibot/logging.py
@@ -137,7 +137,15 @@
def stdout(text, decoder=None, newline=True, **kwargs):
- """Output script results to the user via the
userinterface."""
+ """Output script results to the user via the userinterface.
+
+ @param text: the message printed via stdout logger to the user.
+ @param decoder: If None, text should be a unicode string else it should
+ be encoded in the given encoding.
+ @param newline: If True, a line feed will be added after printing the text.
+ @param kwargs: The keyword arguments can be found in the python doc:
+
https://docs.python.org/3/howto/logging-cookbook.html.
+ """
logoutput(text, decoder, newline, STDOUT, **kwargs)
@@ -146,7 +154,7 @@
"""Output a warning message to the user via the userinterface.
@param text: the message the user wants to display.
- @param decoder: If None, text should be a unicode string. Otherwise it
+ @param decoder: If None, text should be a unicode string else it
should be encoded in the given encoding.
@param newline: If True, a line feed will be added after printing the text.
@param kwargs: The keyword arguments can be found in the python doc:
@@ -156,23 +164,53 @@
def error(text, decoder=None, newline=True, **kwargs):
- """Output an error message to the user via the
userinterface."""
+ """Output an error message to the user via the userinterface.
+
+ @param text: the message containing the error which occured.
+ @param decoder: If None, text should be a unicode string else it should
+ be encoded in the given encoding.
+ @param newline: If True, a line feed will be added after printing the text.
+ @param kwargs: The keyword arguments can be found in the python doc:
+
https://docs.python.org/3/howto/logging-cookbook.html.
+ """
logoutput(text, decoder, newline, ERROR, **kwargs)
def log(text, decoder=None, newline=True, **kwargs):
- """Output a record to the log file."""
+ """Output a record to the log file.
+
+ @param text: the message which is to be logged to the log file.
+ @param decoder: If None, text should be a unicode string else it should
+ be encoded in the given encoding.
+ @param newline: If True, a line feed will be added after printing the text.
+ @param kwargs: The keyword arguments can be found in the python doc:
+
https://docs.python.org/3/howto/logging-cookbook.html.
+ """
logoutput(text, decoder, newline, VERBOSE, **kwargs)
def critical(text, decoder=None, newline=True, **kwargs):
- """Output a critical record to the user via the
userinterface."""
+ """Output a critical record to the user via the userinterface.
+
+ @param text: the critical message which is to be displayed to the user.
+ @param decoder: If None, text should be a unicode string else it should
+ be encoded in the given encoding.
+ @param newline: If True, a line feed will be added after printing the text.
+ @param kwargs: The keyword arguments can be found in the python doc:
+
https://docs.python.org/3/howto/logging-cookbook.html.
+ """
logoutput(text, decoder, newline, CRITICAL, **kwargs)
def debug(text, layer, decoder=None, newline=True, **kwargs):
"""Output a debug record to the log file.
+ @param text: the message of the debug record to be logged to the log file.
+ @param decoder: If None, text should be a unicode string else it should
+ be encoded in the given encoding.
+ @param newline: If True, a line feed will be added after printing the text.
+ @param kwargs: The keyword arguments can be found in the python doc:
+
https://docs.python.org/3/howto/logging-cookbook.html.
@param layer: The name of the logger that text will be sent to.
"""
logoutput(text, decoder, newline, DEBUG, layer, **kwargs)
@@ -195,6 +233,14 @@
pywikibot.exception(e)
...
+ This function should only be called from an Exception handler.
+
+ @param msg: If not None,contains the description of the exception occured.
+ @param decoder: If None, text should be a unicode string else it should
+ be encoded in the given encoding.
+ @param newline: If True, a line feed will be added after printing the text.
+ @param kwargs: The keyword arguments can be found in the python doc:
+
https://docs.python.org/3/howto/logging-cookbook.html.
@param tb: Set to True in order to output traceback also.
"""
if isinstance(msg, BaseException):
--
To view, visit
https://gerrit.wikimedia.org/r/c/pywikibot/core/+/640171
To unsubscribe, or for help writing mail filters, visit
https://gerrit.wikimedia.org/r/settings
Gerrit-Project: pywikibot/core
Gerrit-Branch: master
Gerrit-Change-Id: I265a5258d711a6e038b1974e4f1cf29fd5c0f650
Gerrit-Change-Number: 640171
Gerrit-PatchSet: 9
Gerrit-Owner: Homeboy 445 <akshitsan13(a)gmail.com>
Gerrit-Reviewer: Xqt <info(a)gno.de>
Gerrit-Reviewer: jenkins-bot
Gerrit-MessageType: merged