yikit.logging package#

Logging utilities of yikit.

yikit writes its log messages to the "yikit" logger and its children (for example "yikit.feature_selection._filter"). The first call of get_root_logger() configures the "yikit" logger once. get_child_logger() calls it, and the yikit modules that log (such as yikit.feature_selection) call get_child_logger() when they are imported, so importing them configures the logger as follows.

  • The default handler, a logging.StreamHandler that writes to sys.stderr, is attached. Its formatter is colored when colorlog is installed, the NO_COLOR environment variable is not set, and sys.stderr is a terminal.

  • The level is set to INFO, so messages of INFO and above are printed.

  • propagate is set to False, so the messages are not passed to the handlers of the Python root logger and are not printed twice.

Later calls do not change the logger again, so the level, handlers and propagate set afterwards are kept. The level and propagate set on logging.getLogger("yikit") before that first configuration are overwritten by it, so change them on the logger returned by get_root_logger(), which configures the logger first; this works whether yikit’s modules are imported before or after. To silence or replace the default handler:

  • get_root_logger().setLevel(WARNING) keeps only warnings and errors.

  • disable_default_handler() detaches the default handler and enable_default_handler() attaches it again. catch_default_handler detaches it only inside a with block. If the "yikit" logger has no other handler, Python’s last-resort handler (logging.lastResort) still writes messages of WARNING and above to sys.stderr. To hide them too, also add a logging.NullHandler with get_root_logger().addHandler(logging.NullHandler()), or raise the level.

  • To use your own handler, detach the default handler and add yours (for example, one made by get_handler()) with get_root_logger().addHandler(handler).

  • To use the handlers of the Python root logger instead, detach the default handler and set get_root_logger().propagate = True.

The logging levels CRITICAL, DEBUG, ERROR, INFO, NOTSET, and WARNING are re-exported from the standard logging module.

Examples

Print yikit’s messages with your own handler instead of the default one:

>>> import logging
>>> import sys
>>> from yikit.logging import (
...     INFO,
...     WARNING,
...     disable_default_handler,
...     enable_default_handler,
...     get_handler,
...     get_root_logger,
... )
>>> logger = get_root_logger()
>>> handler = get_handler(
...     logging.StreamHandler(sys.stdout),
...     formatter=logging.Formatter("%(levelname)s:%(name)s:%(message)s"),
... )
>>> disable_default_handler()
>>> logger.addHandler(handler)
>>> logger.info("fitted")
INFO:yikit:fitted

Keep only warnings and errors:

>>> logger.setLevel(WARNING)
>>> logger.info("fitted")
>>> logger.warning("not converged")
WARNING:yikit:not converged

Go back to the default configuration:

>>> logger.setLevel(INFO)
>>> logger.removeHandler(handler)
>>> enable_default_handler()
class yikit.logging.catch_default_handler#

Bases: object

Context manager that detaches the default handler inside a block.

On entering, the default handler is detached from the "yikit" logger. On exiting, also when an exception is raised inside the block, the default handler goes back to the state before entering: it is attached again if it was attached, and stays detached if it was detached. Other handlers are not touched. The same instance may be entered again while it is active; each exit restores the state of the matching entry.

Inside the block, if the "yikit" logger has no other handler, Python’s last-resort handler (logging.lastResort) still writes messages of WARNING and above to sys.stderr; see disable_default_handler().

Raises:

RuntimeError – On exiting without entering, or if the default handler does not exist after configuring the logger.

See also

disable_default_handler

Detach the default handler.

Examples

>>> from yikit.logging import catch_default_handler, get_root_logger
>>> logger = get_root_logger()
>>> with catch_default_handler():
...     logger.info("This message is not printed by the default handler.")
>>> logger.info("This message is printed again.")
yikit.logging.disable_default_handler() → None#

Detach the default handler from the "yikit" logger.

The default handler no longer prints yikit’s messages. Handlers that the user attached are kept. Calling it again does nothing.

If the "yikit" logger has no other handler, Python’s last-resort handler (logging.lastResort) still writes messages of WARNING and above to sys.stderr. To hide them too, also add a logging.NullHandler to the logger returned by get_root_logger(), or raise its level.

Return type:

None

Raises:

RuntimeError – If the default handler does not exist after configuring the logger.

See also

enable_default_handler

Attach the default handler again.

catch_default_handler

Detach the default handler inside a block.

Examples

>>> from yikit.logging import (
...     disable_default_handler,
...     enable_default_handler,
... )
>>> disable_default_handler()  # the default handler stops printing
>>> enable_default_handler()  # it prints yikit's messages again
yikit.logging.enable_default_handler() → None#

Attach the default handler to the "yikit" logger.

It undoes disable_default_handler(). The handler is never attached twice, so calling it again does nothing.

Return type:

None

Raises:

RuntimeError – If the default handler does not exist after configuring the logger.

See also

disable_default_handler

Detach the default handler.

catch_default_handler

Detach the default handler inside a block.

Examples

>>> from yikit.logging import enable_default_handler
>>> enable_default_handler()
yikit.logging.get_child_logger(name: str, propagate: bool = True) → Logger#

Return a child of the "yikit" logger for a module.

Pass __name__. A module inside yikit ("yikit.<module>") gets the logger of the same name, and a script run as __main__ gets the "yikit.__main__" logger. The "yikit" logger is configured first (see get_root_logger()), so the messages of the child are printed by the default handler while propagate is True.

Parameters:
  • name (str) – The module name, __name__. It must be a module inside yikit ("yikit.<module>") or "__main__".

  • propagate (bool, default=True) – Whether the messages of the child are passed to the handlers of the "yikit" logger. It is set on the returned logger.

Returns:

The child logger.

Return type:

logging.Logger

Raises:

ValueError – If name is neither a module inside yikit nor "__main__".

Examples

>>> from yikit.logging import get_child_logger
>>> get_child_logger("yikit.feature_selection").name
'yikit.feature_selection'
>>> get_child_logger("__main__").name
'yikit.__main__'
yikit.logging.get_handler(handler: HandlerType, formatter: Formatter | None = None, level: int = 0) → HandlerType#

Configure a log handler with a formatter and a log level.

Use it to build a handler that replaces or complements the default handler of the "yikit" logger.

Parameters:
  • handler (logging.Handler) – The log handler to configure. It is modified in place.

  • formatter (logging.Formatter or None, default=None) – The formatter to set on the handler. If None, a new default formatter (the one the default handler uses) is set.

  • level (int, default=logging.NOTSET) – The level to set on the handler (e.g., logging.DEBUG, logging.INFO).

Returns:

The same handler, configured.

Return type:

logging.Handler

Examples

>>> import logging
>>> from yikit.logging import WARNING, get_handler
>>> handler = get_handler(logging.StreamHandler(), level=WARNING)
>>> handler.level == WARNING
True
yikit.logging.get_root_logger() → Logger#

Return the "yikit" logger, configuring it on the first call.

The first call attaches the default handler (a logging.StreamHandler that writes to sys.stderr with the default formatter) to the "yikit" logger, sets its level to logging.INFO, and sets propagate to False so that the messages are not printed again by the handlers of the Python root logger. Later calls return the logger without changing it, so the level, handlers and propagate set afterwards are kept. The level and propagate set on logging.getLogger("yikit") before the first call are overwritten, so change them on the logger that this function returns.

Returns:

The "yikit" logger.

Return type:

logging.Logger

See also

disable_default_handler

Detach the default handler.

get_child_logger

Return a child of the "yikit" logger.

Examples

>>> from yikit.logging import get_root_logger
>>> get_root_logger().name
'yikit'