Logging

pshell uses logging to record all commands to the stderr or log file. By default, it uses the pshell logger; it can however be set to use an alternative, possibly context-local, logger.

Setting and retrieving the pshell logger

pshell.set_global_logger(logger: Logger | str | None) → Logger | None

Set the pshell global logger. This logger will be used by all pshell functions unless context_logger is defined.

Returns:

Previous global logger (not thread-safe).

pshell.context_logger = <ContextVar name='context_logger' default=None>

ContextVar. Context-local logger, for use in multithreaded and asynchronous code. On Python 3.14t and later free-threading nterpreters, this is inherited when creating a new thread; on most other interpreters, it’s not; see sys.flags.thread_inherit_context. See contextvars for more information on how context variables propagate.

Set to None to use the global logger instead.

pshell.get_logger() → Logger

1. If context_logger is set, return it.

2. Otherwise, if set_global_logger() was called, return the global logger.

3. Otherwise, return the pshell logger.

Using the pshell logger

pshell.log.debug(msg: str, *args: Any, stacklevel: int = 1, **kwargs: Any) → None

Wrapper around logging.Logger.debug() which uses the logger set by set_global_logger() or by context_logger.

pshell.log.info(msg: str, *args: Any, stacklevel: int = 1, **kwargs: Any) → None

Wrapper around logging.Logger.info() which uses the logger set by set_global_logger() or by context_logger.

pshell.log.warning(msg: str, *args: Any, stacklevel: int = 1, **kwargs: Any) → None

Wrapper around logging.Logger.warning() which uses the logger set by set_global_logger() or by context_logger.

pshell.log.error(msg: str, *args: Any, stacklevel: int = 1, **kwargs: Any) → None

Wrapper around logging.Logger.error() which uses the logger set by set_global_logger() or by context_logger.

pshell.log.critical(msg: str, *args: Any, stacklevel: int = 1, **kwargs: Any) → None

Wrapper around logging.Logger.critical() which uses the logger set by set_global_logger() or by context_logger.

pshell.log.inc_stacklevel(levels: int = 2) → Generator[None]

Function decorator to be added to helper functions. Will cause all log messages to be logged as if they were emitted by the function’s caller instead of the function itself.

Parameters:

levels – Number of stack levels to increase. Default: 2 (1 for contextlib, 1 for the decorated function)

Example:

>>> @sh.log.inc_stacklevel()
>>> def f():
...     sh.log.info("This is logged as coming from g()")
>>> def g():
...     f()