Xqt has submitted this change. ( https://gerrit.wikimedia.org/r/c/pywikibot/core/+/786339 )

Change subject: [doc] Update documentation for logging system and user interfaces ......................................................................

[doc] Update documentation for logging system and user interfaces

Change-Id: I6ea61d051071f4ed2357b681e3eaf8ec907a5221 --- M docs/api_ref/pywikibot.rst M docs/api_ref/pywikibot.userinterfaces.rst M docs/scripts_ref/scripts.rst M pywikibot/bot.py M pywikibot/userinterfaces/__init__.py M pywikibot/userinterfaces/buffer_interface.py 6 files changed, 68 insertions(+), 37 deletions(-)

Approvals: jenkins-bot: Verified Xqt: Looks good to me, approved

diff --git a/docs/api_ref/pywikibot.rst b/docs/api_ref/pywikibot.rst index 4721eeb..02bd83a 100644 --- a/docs/api_ref/pywikibot.rst +++ b/docs/api_ref/pywikibot.rst @@ -3,8 +3,8 @@

.. automodule:: pywikibot

-Subpackages ------------ +Pywikibot Subpackages +---------------------

.. toctree::

diff --git a/docs/api_ref/pywikibot.userinterfaces.rst b/docs/api_ref/pywikibot.userinterfaces.rst index 6d0b506..0c05a30 100644 --- a/docs/api_ref/pywikibot.userinterfaces.rst +++ b/docs/api_ref/pywikibot.userinterfaces.rst @@ -28,6 +28,11 @@

.. automodule:: pywikibot.userinterfaces.terminal_interface_win32

+buffer_interface module +------------------------ + +.. automodule:: pywikibot.userinterfaces.buffer_interface + gui module ----------

diff --git a/docs/scripts_ref/scripts.rst b/docs/scripts_ref/scripts.rst index d4c262d..0bda098 100644 --- a/docs/scripts_ref/scripts.rst +++ b/docs/scripts_ref/scripts.rst @@ -3,8 +3,8 @@

.. automodule:: scripts

-Subpackages ------------ +Scripts Subpackages +-------------------

.. toctree::

diff --git a/pywikibot/bot.py b/pywikibot/bot.py index 00f0e5f..b7eb314 100644 --- a/pywikibot/bot.py +++ b/pywikibot/bot.py @@ -190,9 +190,6 @@ ] PageLinkType = Union['pywikibot.page.Link', 'pywikibot.page.Page']

-ui = None # type: Optional[pywikibot.userinterfaces._interface_base.ABUIC] - - _GLOBAL_HELP = """ GLOBAL OPTIONS ============== @@ -270,13 +267,24 @@

"""

+ui = None # type: Optional[pywikibot.userinterfaces._interface_base.ABUIC] +"""Holds a user interface object defined in +:mod:`pywikibot.userinterfaces` subpackage. +""" +

def set_interface(module_name: str) -> None: - """Configures any bots to use the given interface module.""" + """Configures any bots to use the given interface module. + + Search for user interface module in the + :mod:`pywikibot.userinterfaces` subdirectory and initialize UI. + Calls :func:`init_handlers` to re-initialize if we were already + initialized with another UI. + + .. versionadded:: 6.4 + """ global ui

- # User interface initialization - # search for user interface module in the 'userinterfaces' subdirectory ui_module = __import__('pywikibot.userinterfaces.{}_interface' .format(module_name), fromlist=['UI']) ui = ui_module.UI() @@ -284,47 +292,39 @@ atexit.register(ui.flush) pywikibot.argvu = ui.argvu()

- # re-initialize if we were already initialized with another UI + # re-initialize

if _handlers_initialized: init_handlers()

-# Initialize the handlers and formatters for the logging system. -# -# This relies on the global variable 'ui' which is a UserInterface object -# defined in the 'userinterface' subpackage. -# -# The UserInterface object must define its own init_handlers() method -# which takes the root logger as its only argument, and which adds to that -# logger whatever handlers and formatters are needed to process output and -# display it to the user. The default (terminal) interface sends level -# STDOUT to sys.stdout (as all interfaces should) and sends all other -# levels to sys.stderr; levels WARNING and above are labeled with the -# level name. -# -# UserInterface objects must also define methods input(), input_choice(), -# and editText(), all of which are documented in -# userinterfaces/terminal_interface.py - _handlers_initialized = False

def handler_namer(name: str) -> str: - """Modify the filename of a log file when rotating.""" + """Modify the filename of a log file when rotating. + + .. versionadded:: 6.5 + """ path, qualifier = name.rsplit('.', 1) root, ext = os.path.splitext(path) return '{}.{}{}'.format(root, qualifier, ext)

def init_handlers() -> None: - """Initialize logging system for terminal-based bots. + """Initialize the handlers and formatters for the logging system.

+ This relies on the global variable :attr:`ui` which is a UI object. + + .. seealso:: :mod:`pywikibot.userinterfaces` + + Calls :func:`writelogheader` after handlers are initialized. This function must be called before using any input/output methods; - and must be called again if ui handler is changed.. + and must be called again if ui handler is changed. Use + :func:`set_interface` to set the new interface which initializes it.

- Note: this function is called by any user input and output function, - so it should normally not need to be called explicitly. + .. note:: this function is called by any user input and output + function, so it should normally not need to be called explicitly.

All user output is routed through the logging module. Each type of output is handled by an appropriate handler object. @@ -343,8 +343,13 @@ - ERROR: user error messages. - CRITICAL: fatal error messages.

+ .. seealso:: + * :mod:`pywikibot.logging` + * :python:`Python Logging Levels<library/logging.html#logging-levels>` + Accordingly, do **not** use print statements in bot code; instead, - use pywikibot.output function. + use :func:`pywikibot.output` function and other functions from + :mod:`pywikibot.logging` module.

.. versionchanged:: 6.2 Different logfiles are used if multiple processes of the same diff --git a/pywikibot/userinterfaces/__init__.py b/pywikibot/userinterfaces/__init__.py index b57ecdc..fa9afbd 100644 --- a/pywikibot/userinterfaces/__init__.py +++ b/pywikibot/userinterfaces/__init__.py @@ -1 +1,16 @@ -"""User interfaces.""" +"""User interfaces Module. + +The user interface object must define its own `init_handlers()` method +which takes the root logger as its only argument, and which adds to that +logger whatever handlers and formatters are needed to process output and +display it to the user. The default +(:mod:`terminal<pywikibot.userinterfaces.terminal_interface_base>`) +interface sends level :const:`STDOUT` to `sys.stdout` (as all interfaces +should) and sends all other levels to `sys.stderr`; levels +:const:`WARNING` and above are labeled with the level name. + +UserInterface objects must also define methods `input()`, +`input_choice()`, `input_list_choice()`, `output()` and `editText()`, +all of which are documented in the abstract class +:class:`pywikibot.userinterfaces._interface_base.ABUIC`. +""" diff --git a/pywikibot/userinterfaces/buffer_interface.py b/pywikibot/userinterfaces/buffer_interface.py index b12ba02..3da1975 100644 --- a/pywikibot/userinterfaces/buffer_interface.py +++ b/pywikibot/userinterfaces/buffer_interface.py @@ -1,4 +1,7 @@ -"""Non-interactive interface that stores output.""" +"""Non-interactive interface that stores output. + +.. versionadded:: 6.4 +""" # # (C) Pywikibot team, 2021-2022 # @@ -15,7 +18,10 @@

class UI(ABUIC):

- """Collects output into an unseen buffer.""" + """Collects output into an unseen buffer. + + .. versionadded:: 6.4 + """

def __init__(self) -> None: """Initialize the UI."""