sphinx.util.logging

module documentation

Logging utility functions for Sphinx.

Unknown Field: copyright
Copyright 2007-2022 by the Sphinx team, see AUTHORS.
Unknown Field: license
BSD, see LICENSE for details.
Class ​Sphinx​Logger​Adapter LoggerAdapter allowing type and subtype keywords.
Function get​Logger Get logger wrapped by sphinx.util.logging.SphinxLoggerAdapter.
Function pending​_logging Context manager to postpone logging all logs temporarily.
Function pending​_warnings Context manager to postpone logging warnings temporarily.
Function prefixed​_warnings Context manager to prepend prefix to all warning log records temporarily.
Constant COLOR​_MAP Undocumented
Constant LEVEL​_NAMES Undocumented
Constant NAMESPACE Undocumented
Constant VERBOSE Undocumented
Constant VERBOSITY​_MAP Undocumented
Class ​Colorize​Formatter Undocumented
Class ​Disable​Warning​Is​Error​Filter Disable WarningIsErrorFilter if this filter installed.
Class ​Info​Filter Filter error and warning messages.
Class ​Info​Log​Record​Translator LogRecordTranslator for INFO level log records.
Class ​Last​Messages​Writer Stream writer storing last 10 messages in memory to save trackback
Class ​Log​Collector Undocumented
Class ​Memory​Handler Handler buffering all logs.
Class ​Message​Prefix​Filter Prepend prefix to all log records.
Class ​New​Line​Stream​Handler StreamHandler which switches line terminator by record.nonl flag.
Class ​Once​Filter Show the message only once.
Class ​Safe​Encoding​Writer Stream writer which ignores UnicodeEncodeError silently
Class ​Sphinx​Info​Log​Record Info log record class supporting location
Class ​Sphinx​Log​Record Log record class supporting location
Class ​Sphinx​Log​Record​Translator Converts a log record to one Sphinx expects
Class ​Sphinx​Warning​Log​Record Warning log record class supporting location
Class ​Warning​Is​Error​Filter Raise exception if warning emitted.
Class ​Warning​Log​Record​Translator LogRecordTranslator for WARNING level log records.
Class ​Warning​Stream​Handler StreamHandler for warnings.
Class ​Warning​Suppressor Filter logs by suppress_warnings.
Function convert​_serializable Convert LogRecord serializable.
Function get​_node​_location Undocumented
Function is​_suppressed​_warning Check whether the warning is suppressed or not.
Function setup Setup root logger for Sphinx
Function skip​_warningiserror Context manager to skip WarningIsErrorFilter temporarily.
Function suppress​_logging Context manager to suppress logging all logs temporarily.
def getLogger(name):

Get logger wrapped by sphinx.util.logging.SphinxLoggerAdapter.

Sphinx logger always uses sphinx.* namespace to be independent from settings of root logger. It ensures logging is consistent even if a third-party extension or imported application resets logger settings.

Example usage:

>>> from sphinx.util import logging
>>> logger = logging.getLogger(__name__)
>>> logger.info('Hello, this is an extension!')
Hello, this is an extension!
Parameters
name:strUndocumented
Returns
SphinxLoggerAdapterUndocumented
@contextmanager
def pending_logging():

Context manager to postpone logging all logs temporarily.

For example:

>>> with pending_logging():
>>>     logger.warning('Warning message!')  # not flushed yet
>>>     some_long_process()
>>>
Warning message!  # the warning is flushed here
Returns
Generator[MemoryHandler, None, None]Undocumented
@contextmanager
def pending_warnings():

Context manager to postpone logging warnings temporarily.

Similar to pending_logging.

Returns
Generator[logging.Handler, None, None]Undocumented
@contextmanager
def prefixed_warnings(prefix):

Context manager to prepend prefix to all warning log records temporarily.

For example:

>>> with prefixed_warnings("prefix:"):
>>>     logger.warning('Warning message!')  # => prefix: Warning message!
New in version 2.0.
Parameters
prefix:strUndocumented
Returns
Generator[None, None, None]Undocumented
COLOR_MAP =

Undocumented

Value
defaultdict((lambda : 'blue'),
            {logging.ERROR: 'darkred',
             logging.WARNING: 'red',
             logging.DEBUG: 'darkgray'})
LEVEL_NAMES: Dict[str, int] =

Undocumented

Value
defaultdict((lambda : logging.WARNING))
NAMESPACE: str =

Undocumented

Value
'sphinx'
VERBOSE: int =

Undocumented

Value
15
VERBOSITY_MAP: Dict[int, int] =

Undocumented

Value
defaultdict((lambda : 0))
def convert_serializable(records):
Convert LogRecord serializable.
Parameters
records:List[logging.LogRecord]Undocumented
def get_node_location(node):

Undocumented

Parameters
node:NodeUndocumented
Returns
Optional[str]Undocumented
def is_suppressed_warning(type, subtype, suppress_warnings):
Check whether the warning is suppressed or not.
Parameters
type:strUndocumented
subtype:strUndocumented
suppress​_warnings:List[str]Undocumented
Returns
boolUndocumented
def setup(app, status, warning):
Setup root logger for Sphinx
Parameters
app:SphinxUndocumented
status:IOUndocumented
warning:IOUndocumented
@contextmanager
def skip_warningiserror(skip=True):
Context manager to skip WarningIsErrorFilter temporarily.
Parameters
skip:boolUndocumented
Returns
Generator[None, None, None]Undocumented
@contextmanager
def suppress_logging():

Context manager to suppress logging all logs temporarily.

For example:

>>> with suppress_logging():
>>>     logger.warning('Warning message!')  # suppressed
>>>     some_long_process()
>>>
Returns
Generator[MemoryHandler, None, None]Undocumented