batgrl.logging#

Logging related classes and functions.

Because default logging opens stdout/stderr which disables batgrl output, logging must be setup with a file handler instead. To ensure a file handler has been added, all library logging should use get_logger (essentially, just an alias of stdlib logging.getLogger) from this module.

Additional log levels, ANSI and EVENTS, are added to standard logging levels.

Module Attributes

`ANSI_LEVEL`	`ANSI` log level.
`EVENTS_LEVEL`	`EVENTS` log level.

Functions

get_logger([name])

Return a logger with a specified name.

Classes

`CustomLogger`(name[, level])	A standard logger with methods for `ANSI` and `EVENTS` logging.
`LogLevel`(*values)	Standard logging levels with additional `ANSI` and `EVENTS` levels.

batgrl.logging.ANSI_LEVEL: Final = 3#

ANSI log level.

Show generated ANSI in logs.

class batgrl.logging.CustomLogger(name, level=0)#

Bases: Logger

A standard logger with methods for ANSI and EVENTS logging.

Methods

`addFilter`(filter)	Add the specified filter to this handler.
`addHandler`(hdlr)	Add the specified handler to this logger.
`ansi`(msg, args, *kwargs)	Log the given message with the severity `"ANSI"`.
`callHandlers`(record)	Pass a record to all relevant handlers.
`critical`(msg, args, *kwargs)	Log 'msg % args' with severity 'CRITICAL'.
`debug`(msg, args, *kwargs)	Log 'msg % args' with severity 'DEBUG'.
`error`(msg, args, *kwargs)	Log 'msg % args' with severity 'ERROR'.
`events`(msg, args, *kwargs)	Log the given message with the severity `"EVENTS"`.
`exception`(msg, *args[, exc_info])	Convenience method for logging an ERROR with exception information.
`fatal`(msg, args, *kwargs)	Don't use this method, use critical() instead.
`filter`(record)	Determine if a record is loggable by consulting all the filters.
`findCaller`([stack_info, stacklevel])	Find the stack frame of the caller so that we can note the source file name, line number and function name.
`getChild`(suffix)	Get a logger which is a descendant to this one.
`getEffectiveLevel`()	Get the effective level for this logger.
`handle`(record)	Call the handlers for the specified record.
`hasHandlers`()	See if this logger has any handlers configured.
`info`(msg, args, *kwargs)	Log 'msg % args' with severity 'INFO'.
`isEnabledFor`(level)	Is this logger enabled for level 'level'?
`is_enabled_for`(log_level)	Similar to `Logger.isEnabledFor`, but also accepts level names.
`log`(level, msg, args, *kwargs)	Log 'msg % args' with the integer severity 'level'.
`makeRecord`(name, level, fn, lno, msg, args, ...)	A factory method which can be overridden in subclasses to create specialized LogRecords.
`removeFilter`(filter)	Remove the specified filter from this handler.
`removeHandler`(hdlr)	Remove the specified handler from this logger.
`setLevel`(level)	Set the logging level of this logger.
`warning`(msg, args, *kwargs)	Log 'msg % args' with severity 'WARNING'.

getChildren
warn

addFilter(filter)#: Add the specified filter to this handler.

addHandler(hdlr)#: Add the specified handler to this logger.

ansi(msg: str, *args, **kwargs) → None#: Log the given message with the severity "ANSI".

callHandlers(record)#

Pass a record to all relevant handlers.

Loop through all handlers for this logger and its parents in the logger hierarchy. If no handler was found, output a one-off error message to sys.stderr. Stop searching up the hierarchy whenever a logger with the “propagate” attribute set to zero is found - that will be the last logger whose handlers are called.

critical(msg, *args, **kwargs)#

Log ‘msg % args’ with severity ‘CRITICAL’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.critical(“Houston, we have a %s”, “major disaster”, exc_info=True)

debug(msg, *args, **kwargs)#

Log ‘msg % args’ with severity ‘DEBUG’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.debug(“Houston, we have a %s”, “thorny problem”, exc_info=True)

error(msg, *args, **kwargs)#

Log ‘msg % args’ with severity ‘ERROR’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.error(“Houston, we have a %s”, “major problem”, exc_info=True)

events(msg: str, *args, **kwargs) → None#: Log the given message with the severity "EVENTS".

exception(msg, *args, exc_info=True, **kwargs)#: Convenience method for logging an ERROR with exception information.

fatal(msg, *args, **kwargs)#: Don’t use this method, use critical() instead.

filter(record)#

Determine if a record is loggable by consulting all the filters.

The default is to allow the record to be logged; any filter can veto this by returning a false value. If a filter attached to a handler returns a log record instance, then that instance is used in place of the original log record in any further processing of the event by that handler. If a filter returns any other true value, the original log record is used in any further processing of the event by that handler.

If none of the filters return false values, this method returns a log record. If any of the filters return a false value, this method returns a false value.

Changed in version 3.2: Allow filters to be just callables.

Changed in version 3.12: Allow filters to return a LogRecord instead of modifying it in place.

findCaller(stack_info=False, stacklevel=1)#: Find the stack frame of the caller so that we can note the source file name, line number and function name.

getChild(suffix)#

Get a logger which is a descendant to this one.

This is a convenience method, such that

logging.getLogger(‘abc’).getChild(‘def.ghi’)

is the same as

logging.getLogger(‘abc.def.ghi’)

It’s useful, for example, when the parent logger is named using __name__ rather than a literal string.

getChildren()#

getEffectiveLevel()#

Get the effective level for this logger.

Loop through this logger and its parents in the logger hierarchy, looking for a non-zero logging level. Return the first one found.

handle(record)#

Call the handlers for the specified record.

This method is used for unpickled records received from a socket, as well as those created locally. Logger-level filtering is applied.

hasHandlers()#

See if this logger has any handlers configured.

Loop through all handlers for this logger and its parents in the logger hierarchy. Return True if a handler was found, else False. Stop searching up the hierarchy whenever a logger with the “propagate” attribute set to zero is found - that will be the last logger which is checked for the existence of handlers.

info(msg, *args, **kwargs)#

Log ‘msg % args’ with severity ‘INFO’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.info(“Houston, we have a %s”, “notable problem”, exc_info=True)

isEnabledFor(level)#: Is this logger enabled for level ‘level’?

is_enabled_for(log_level: LogLevel | str) → bool#: Similar to Logger.isEnabledFor, but also accepts level names.

log(level, msg, *args, **kwargs)#

Log ‘msg % args’ with the integer severity ‘level’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.log(level, “We have a %s”, “mysterious problem”, exc_info=True)

makeRecord(name, level, fn, lno, msg, args, exc_info, func=None, extra=None, sinfo=None)#: A factory method which can be overridden in subclasses to create specialized LogRecords.

manager = <logging.Manager object>#

removeFilter(filter)#: Remove the specified filter from this handler.

removeHandler(hdlr)#: Remove the specified handler from this logger.

root = <RootLogger root (WARNING)>#

setLevel(level)#: Set the logging level of this logger. level must be an int or a str.

warn(msg, *args, **kwargs)#

warning(msg, *args, **kwargs)#

Log ‘msg % args’ with severity ‘WARNING’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.warning(“Houston, we have a %s”, “bit of a problem”, exc_info=True)

batgrl.logging.EVENTS_LEVEL: Final = 5#

EVENTS log level.

Show generated input events.

class batgrl.logging.LogLevel(*values)#

Bases: IntEnum

Standard logging levels with additional ANSI and EVENTS levels.

Attributes:

denominator: the denominator of a rational number in lowest terms
imag: the imaginary part of a complex number
numerator: the numerator of a rational number in lowest terms
real: the real part of a complex number

Methods

`as_integer_ratio`(/)	Return a pair of integers, whose ratio is equal to the original int.
`bit_count`(/)	Number of ones in the binary representation of the absolute value of self.
`bit_length`(/)	Number of bits necessary to represent self in binary.
`conjugate`	Returns self, the complex conjugate of any int.
`from_bytes`(/, bytes[, byteorder, signed])	Return the integer represented by the given array of bytes.
`is_integer`(/)	Returns True.
`to_bytes`(/[, length, byteorder, signed])	Return an array of bytes representing an integer.

batgrl.logging.get_logger(name: str | None = None) → CustomLogger#

Return a logger with a specified name.

Because there are several entry points into batgrl and default logging opens stderr/stdout which will disable batgrl output, all library logging must use this alias of logging.getLogger to ensure logging has been set to output to a file.

Parameters:

namestr | None, default: None: Name of logger. If not specified, return the root logger.

Returns:

CustomLogger: The specified logger.

batgrl.logging#

This Page