munetauvsim.logger

Logging configuration for AUV simulations.

Provides centralized logging setup with custom formatting, multiple handlers, simulation time tracking, and flexible logger management. Supports console and file output with independent configuration for main and communication logging.

Functions

Setup Functions:

setupMain(fileName, fileFormat, fileLevel, outFormat, outLevel)

Configure and return main program logger.

setupComm(name, fileName, file, out)

Configure and return communication module logger.

Logger Management:

addLog(name)

Create logger that uses main logger handlers.

noneLog(name)

Create logger with no handlers (warnings only).

removeLog(name)

Remove logger and close unshared handlers.

deepRemoveLog(name)

Remove logger and close all its handlers.

Handler Management:

addMainHandlers(subLog)

Add main logger handlers to sublevel logger.

removeHandlers(name)

Remove all handlers from logger, closing unshared ones.

closeHandler(handler)

Close handler and update global variables.

deepRemoveHandler(handler)

Remove handler from all loggers and close it.

Custom Features:

customRecordFactory(args, kwargs)

Add simulation time field to log records.

CustomFormatter

Format log records with bracketed function names and multi-line support.

Global Variables

loglogging.Logger

Main simulation logger instance.

consoleHandlerlogging.StreamHandler

Shared console output handler.

fileHandlerlogging.FileHandler

Shared file output handler.

simTimestr

Current simulation time for log records (format: “MM:SS”).

Notes

The module uses a custom log record factory to inject simulation time into all log records. Update simTime via direct assignment before logging. This is done by the Simulator in each iteration loop by the _simulateX methods.

Functions

addLog(name)	Create logger that shares main logger handlers.
addMainHandlers(subLog)	Add main logger handlers (console, file) to sublevel logger.
closeHandler(handler)	Close handler and update global handler variables.
customRecordFactory(*args, **kwargs)	Create log record with custom simTime field.
deepRemoveHandler(handler)	Remove handler from all loggers and close it.
deepRemoveLog(name)	Remove logger and close all its handlers.
noneLog(name)	Create or configure logger with no handlers.
removeHandlers(name)	Remove all handlers from logger, closing unshared ones.
removeLog(name)	Remove logger and close unshared handlers.
setupComm([name, fileName, file, out])	Configure and return communication module logger.
setupMain([fileName, fileFormat, fileLevel, ...])	Configure and return main program logger with console and file handlers.

Classes

CustomFormatter([fmt, datefmt])	Custom log formatter with bracketed function names and multi-line support.
datetime(year, month, day[, hour[, minute[, ...)	The year, month and day arguments are required.
oldFactory	alias of LogRecord

class munetauvsim.logger.CustomFormatter(fmt=None, datefmt=None)

Bases: Formatter

Custom log formatter with bracketed function names and multi-line support.

Wraps function names in brackets with padding and preserves log prefix formatting when messages contain newline characters.

Parameters:

• fmt (str, optional) – Log record format string.

• datefmt (str, optional) – Date/time format string.

__init__(fmt=None, datefmt=None)

Initialize formatter with parent class.

Parameters:

• fmt (str | None) –

• datefmt (str | None) –

Return type:

None

format(record)

Apply custom formatting to log record.

Parameters:

record (logging.LogRecord) – Log record to format.

Returns:

formatted (str) – Formatted log message string.

Notes

Transformations:

• Function name wrapped in brackets: [funcName] with 19-char width

• Multi-line messages: Log prefix inserted at each newline

munetauvsim.logger.customRecordFactory(*args, **kwargs)

Create log record with custom simTime field.

Returns:

record (logging.LogRecord) – Log record with simTime attribute from global simTime variable.

Notes

• Wraps original log record factory to inject simulation time.

• Set via: logging.setLogRecordFactory(customRecordFactory)

munetauvsim.logger.addMainHandlers(subLog)

Add main logger handlers (console, file) to sublevel logger.

Parameters:

subLog (logging.Logger) – Logger to receive main handlers.

Return type:

None

Notes

• Only adds handlers that exist (not None).

• Logs debug message on successful activation.

munetauvsim.logger.setupMain(fileName='mnAUVsim.log', fileFormat='|%(simTime)8s %(asctime)s| %(name)-8s %(levelname)-7s %(funcName)s : %(message)s', fileLevel=10, outFormat='|%(simTime)8s| %(name)-8s : %(levelname)-7s > %(message)s', outLevel=20)

Configure and return main program logger with console and file handlers.

Parameters:

• fileName (str, default='mnAUVsim.log') – Log file name. If None, file output disabled.

• fileFormat (str, optional) – Format string for file handler. If None, file output disabled.

• fileLevel (int, default=DEBUG) – Minimum log level for file handler.

• outFormat (str, optional) – Format string for console handler. If None, console output disabled.

• outLevel (int, default=INFO) – Minimum log level for console handler.

Returns:

log (logging.Logger) – Main logger instance with configured handlers.

Return type:

Logger

Notes

• Sets custom log record factory for simulation time field.

• Processes pending loggers that were created before main logger setup.

• Global variables updated: log, consoleHandler, fileHandler.

munetauvsim.logger.addLog(name)

Create logger that shares main logger handlers.

Parameters:

name (str) – Logger name.

Returns:

logger (logging.Logger) – New or existing logger with main handlers.

Return type:

Logger

Notes

• If main logger not yet created, logger is added to pending list.

• Returns existing logger if name already registered.

munetauvsim.logger.noneLog(name)

Create or configure logger with no handlers.

Parameters:

name (str) – Logger name.

Returns:

logger (logging.Logger) – Logger with no handlers. WARNING+ messages go to stderr.

Return type:

Logger

Notes

• If logger exists: Removes/closes non-shared handlers.

• If logger is main logger: Closes all handlers.

• Sets level to WARNING.

munetauvsim.logger.closeHandler(handler)

Close handler and update global handler variables.

Parameters:

handler (logging.Handler) – Handler to close.

Return type:

None

Notes

If handler is consoleHandler or fileHandler, sets global to None.

munetauvsim.logger.removeHandlers(name)

Remove all handlers from logger, closing unshared ones.

Parameters:

name (str) – Logger name.

Return type:

None

Notes

• Iterates through all handlers and removes them.

• Closes handlers not shared with other loggers.

munetauvsim.logger.deepRemoveHandler(handler)

Remove handler from all loggers and close it.

Parameters:

handler (logging.Handler) – Handler to remove and close.

Return type:

None

Notes

• Searches all registered loggers for this handler.

• Removes from each logger found, then closes handler.

munetauvsim.logger.removeLog(name)

Remove logger and close unshared handlers.

Parameters:

name (str) – Logger name to remove.

Return type:

None

Notes

• Handlers shared with other loggers are not closed.

• If removing main logger, sets global log to None.

munetauvsim.logger.deepRemoveLog(name)

Remove logger and close all its handlers.

Parameters:

name (str) – Logger name to remove.

Return type:

None

Notes

• Closes all handlers regardless of sharing with other loggers.

• If removing main logger, sets global log to None.

munetauvsim.logger.setupComm(name='comm', fileName='comm.log', file=True, out=True)

Configure and return communication module logger.

Parameters:

• name (str, default='comm') – Logger name.

• fileName (str, default='comm.log') – Communication log file name.

• file (bool, default=True) – Enable separate communication log file.

• out (bool, default=True) – Enable console output for communication logs.

Returns:

commLog (logging.Logger) – Communication logger with configured handlers.

Return type:

Logger

Notes

• If the main logger has the console handler turned off, then the comms logger will not print to the console even if turned on.

• If the comms logger is set to print to its own log file, then it will not print log records in the main logger file.