cosapp.utils.logging

Customized log handler for CoSApp simulation.

Functions

rollover_logfile()	Rollover logfile of CoSApp LogHandler.
set_log([filename, stream, level, context, ...])	Set the CoSApp simulation log behavior.

Classes

ContextFilter([context])
FileLogHandler([filename, backupCount, encoding])	Special RotatingFileHandler for CoSApp log message.
FilterWithContext()	Interface to add a context on an object.
HandlerWithContextFilters()	Add method to handlers for CoSApp log message.
LogFormat(value[, names, module, qualname, ...])	Expected format of the log message.
LogLevel(value[, names, module, qualname, ...])	CoSApp log level.
LoggerContext()	Interface for context object to connect to the logging system.
StreamLogHandler(stream)	Special StreamHandler for CoSApp log message.
TimeFilter(start_time)	Log record filter depending on the current time of a context.

class cosapp.utils.logging.ContextFilter(context: str | None = None)

Bases: FilterWithContext

filter(record: LogRecord) → int

Is the specified record to be logged? Returns zero for no, nonzero for yes. If deemed appropriate, the record may be modified in-place by this method.

Parameters:

record (logging.LogRecord) – Log record to test

Returns:

Non-zero if the record is to be logged.

Return type:

int

class cosapp.utils.logging.FileLogHandler(filename: str | Path = 'cosapp_trace.log', backupCount: int = 5, encoding: str | None = None)

Bases: RotatingFileHandler, HandlerWithContextFilters

Special RotatingFileHandler for CoSApp log message.

Parameters:

• filename (str or Path, optional) – Log filename; default “cosapp_trace.log”

• backupCount (int, optional) – Number of backup log files; default 5

• encoding (str, optional) – File encoding to be enforced

addFilter(filter)

Adds the specified filter filter to this handler.

handle(record: LogRecord) → bool

Conditionally emits the specified logging record, depending on filters which may have been added to the handler. Wraps the actual emission of the record with acquisition/release of the I/O thread lock.

Parameters:

record (logging.LogRecord) – Log record

Returns:

Is the record processed?

Return type:

bool

removeFilter(filter)

Removes the specified filter filter from this handler.

class cosapp.utils.logging.FilterWithContext

Bases: Filter

Interface to add a context on an object.

property current_context: LoggerContext

Current context

Type:

LoggerContext

class cosapp.utils.logging.HandlerWithContextFilters

Bases: object

Add method to handlers for CoSApp log message.

log(level: LogLevel, msg: str, name: str = '', fn: str = '', lino: int = 0, args: tuple = (), exc_info=None, func: str | None = None, extra: Mapping[str, Any] | None = None, sinfo: str | None = None) → None

Helper function to publish log message with this handler.

Parameters:

• level (LogLevel) – The numeric level of the logging event (one of DEBUG, INFO etc.) Note that this is converted to two attributes of the LogRecord: levelno for the numeric value and levelname for the corresponding level name.

• msg (str) – The event description message, possibly a format string with placeholders for variable data.

• name (str, optional) – The name of the logger used to log the event represented by this LogRecord. Note that this name will always have this value, even though it may be emitted by a handler attached to a different (ancestor) logger.

• pathname (str, optional) – The full pathname of the source file where the logging call was made.

• lineno (int, optional) – The line number in the source file where the logging call was made.

• args (tuple) – Variable data to merge into the msg argument to obtain the event description.

• exc_info (optional) – An exception tuple with the current exception information, or None if no exception information is available.

• func (str, optional) – The name of the function or method from which the logging call was invoked.

• sinfo (str, optional) – A text string representing stack information from the base of the stack in the current thread, up to the logging call.

needs_handling(record: LogRecord) → bool

Test the record to see if it needs to be processed or not.

Parameters:

record (logging.LogRecord) – Log record

Returns:

Is the record to be processed?

Return type:

bool

class cosapp.utils.logging.LogFormat(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Expected format of the log message.

RAW : Raw text

RAW = 0

class cosapp.utils.logging.LogLevel(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

CoSApp log level.

FULL_DEBUG : Detailed debug log DEBUG : Debug log INFO : Information log WARNING : Warning log ERROR : Error log CRITICAL : Critical log

CRITICAL = 50

DEBUG = 10

ERROR = 40

FULL_DEBUG = 9

INFO = 20

WARNING = 30

class cosapp.utils.logging.LoggerContext

Bases: object

Interface for context object to connect to the logging system.

CONTEXT_ENTER_MESSAGE: ClassVar[str] = 'Entering'

CONTEXT_EXIT_MESSAGE: ClassVar[str] = 'Exiting'

log_context(suffix: str = '') → None

Set this object as the context for the logger.

Parameters:

suffix (str, optional) – Suffix text to append to the log message

log_debug_message(handler: HandlerWithContextFilters, record: LogRecord, format: LogFormat = LogFormat.RAW) → bool

Callback method on the context object to log more detailed information.

This method will be called by the log handler when log_context() is active if the logging level is lower or equals to VERBOSE_LEVEL. It allows the object to send additional log message to help debugging a simulation.

Parameters:

• handler (HandlerWithContextFilters) – Log handler on which additional message should be published.

• record (logging.LogRecord) – Log record

• format (LogFormat) – Format of the message

Returns:

Should the provided records be logged?

Return type:

bool

class cosapp.utils.logging.StreamLogHandler(stream: ~io.TextIOBase = <object object>)

Bases: StreamHandler, HandlerWithContextFilters

Special StreamHandler for CoSApp log message.

addFilter(filter)

Adds the specified filter filter to this handler.

handle(record: LogRecord) → bool

Conditionally emits the specified logging record, depending on filters which may have been added to the handler. Wraps the actual emission of the record with acquisition/release of the I/O thread lock.

Parameters:

record (logging.LogRecord) – Log record

Returns:

Is the record processed?

Return type:

bool

removeFilter(filter)

Removes the specified filter filter from this handler.

class cosapp.utils.logging.TimeFilter(start_time: Number)

Bases: FilterWithContext

Log record filter depending on the current time of a context.

Parameters:

start_time (Number) – Time from which debug log will be recorded; default all time steps

filter(record: LogRecord) → int

Is the specified record to be logged? Returns zero for no, nonzero for yes. If deemed appropriate, the record may be modified in-place by this method.

Parameters:

record (logging.LogRecord) – Log record to test

Returns:

Non-zero if the record is to be logged.

Return type:

int

cosapp.utils.logging.rollover_logfile() → None

Rollover logfile of CoSApp LogHandler.

cosapp.utils.logging.set_log(filename: str | ~pathlib.Path | None = 'cosapp_trace.log', stream: ~io.TextIOBase | None = <object object>, level: int = LogLevel.INFO, context: str | None = None, start_time: ~numbers.Number | None = None, format: str = '%(message)s', encoding: str | None = None, backupCount: int = 5) → None

Set the CoSApp simulation log behavior.

If backupCount is nonzero, at most backupCount files will be kept, and if more would be created when rollover occurs, the oldest one is deleted.

The system will save old log files by appending extensions to the filename. The extensions are date-and-time based, using the strftime format %Y-%m-%d_%H-%M-%S.

By default the log messages are written to a file (specified by its filename) and to a stream. Set either filename or stream to deactivate the corresponding log handler.

Parameters:

• filename (str or Path or None, optional) – Log filename; default “cosapp_trace.log”

• stream (io.TextIOBase or None, optional) – Log stream; default sys.stdout

• level (int or LogLevel, optional) – Log level; default LogLevel.INFO

• context (str or None, optional) – Context on which to focus the log message; default None

• start_time (Number or None, optional) – Time from which debug log will be recorded; default all time steps

• format (str, optional) – Log record format; default “%(message)s” - for the available attributes (see https://docs.python.org/3/library/logging.html#logrecord-attributes)

• encoding (str, optional) – File encoding to be enforced

• backupCount (int, optional) – Number of backup log files; default 5