Module c.e.l.log

Part of coherence.extern.log View Source

Logging module.

Five levels of log information are defined. These are, in order of decreasing verbosity: log, debug, info, warning, error.

This module provides a Loggable class for objects, as well as various convenience methods for logging in general, and for logging with Twisted and failures in particular.

Maintainer: Thomas Vander Stichele
Line # Kind Name Docs
64 Function getLevelName Return the name of a log level.
72 Function getFormattedLevelName Undocumented
77 Function registerCategory Register a given category in the debug system.
112 Function getCategoryLevel
124 Function setLogSettings Update the current log settings.
143 Function getLogSettings Fetches the current log settings.
162 Function scrubFilename Scrub the filename to a relative path for all packages in our scrub list.
174 Function getFileLine Return the filename and line number for the given location.
216 Function ellipsize Ellipsize the representation of the given object.
227 Function getFormatArgs Helper function to create a format and args to use for logging.
246 Function doLog
301 Function errorObject Log a fatal error message in the given category.
316 Function warningObject Log a warning message in the given category.
323 Function infoObject Log an informational message in the given category.
329 Function debugObject Log a debug message in the given category.
335 Function logObject Log a log message. Used for debugging recurring events.
341 Function safeprintf Write to a file object, ignoring errors.
356 Function stderrHandler A log handler that writes to stderr.
409 Function init Initialize the logging system and parse the environment variable
435 Function setDebug Set the DEBUG string. This controls the log output.
448 Function getDebug Returns the currently active DEBUG string.
456 Function setPackageScrubList Set the package names to scrub from filenames.
467 Function reset Resets the logging system, removing all log handlers.
477 Function addLogHandler Add a custom log handler.
496 Function addLimitedLogHandler Add a custom log handler.
514 Function removeLogHandler Remove a registered log handler.
529 Function removeLimitedLogHandler Remove a registered limited log handler.
544 Function error Undocumented
547 Function warning Undocumented
550 Function info Undocumented
553 Function debug Undocumented
556 Function log Undocumented
560 Function getExceptionMessage Return a short message based on an exception, useful for debugging.
580 Function reopenOutputFiles Reopens the stdout and stderr output files, as set by
605 Function outputToFiles Redirect stdout and stderr to named files.
638 Class Loggable Base class for objects that want to be able to log messages with
758 Function getFailureMessage Return a short message based on twisted.python.failure.Failure.
773 Function warningFailure Log a warning about a Failure. Useful as an errback handler:
785 Function logTwisted Integrate twisted's logger with our logger.
818 Class TwistedLogObserver Twisted log observer that integrates with our logging.
def getLevelName(level): (source)
Return the name of a log level.
def getFormattedLevelName(level): (source)
Undocumented
def registerCategory(category): (source)
Register a given category in the debug system. A level will be assigned to it based on previous calls to setDebug.
def getCategoryLevel(category): (source)
Parameterscategory

string

Get the debug level at which this category is being logged, adding it if it wasn't registered yet.
def setLogSettings(state): (source)
Update the current log settings. This can restore an old saved log settings object returned by getLogSettings
Parameterssettingsthe settings to set
def getLogSettings(): (source)
Fetches the current log settings. The returned object can be sent to setLogSettings to restore the returned settings
Returnsthe current settings
def _canShortcutLogging(category, level): (source)
Undocumented
def scrubFilename(filename): (source)
Scrub the filename to a relative path for all packages in our scrub list.
def getFileLine(where=-1): (source)

Return the filename and line number for the given location.

If where is a negative integer, look for the code entry in the current stack that is the given number of frames above this module. If where is a function, look for the code entry of the function.
Parameterswherehow many frames to go back up, or function (type: int (negative) or function )
Returnstuple of (file, line) (type: tuple of (str, int) )
def ellipsize(o): (source)
Ellipsize the representation of the given object.
def getFormatArgs(startFormat, startArgs, endFormat, endArgs, args, kwargs): (source)
Helper function to create a format and args to use for logging. This avoids needlessly interpolating variables.
def doLog(level, object, category, format, args, where=-1, filePath=None, line=None): (source)
Parameterswherewhat to log file and line number for; -1 for one frame above log.py; -2 and down for higher up; a function for a (future) code object (type: int or callable )
filePathfile to show the message as coming from, if caller knows best (type: str )
lineline to show the message as coming from, if caller knows best (type: int )
Returnsdict of calculated variables, if they needed calculating. currently contains file and line; this prevents us from doing this work in the caller when it isn't needed because of the debug level
def errorObject(object, cat, format, *args): (source)
Log a fatal error message in the given category. This will also raise a SystemExit.
def warningObject(object, cat, format, *args): (source)
Log a warning message in the given category. This is used for non-fatal problems.
def infoObject(object, cat, format, *args): (source)
Log an informational message in the given category.
def debugObject(object, cat, format, *args): (source)
Log a debug message in the given category.
def logObject(object, cat, format, *args): (source)
Log a log message. Used for debugging recurring events.
def safeprintf(file, format, *args): (source)
Write to a file object, ignoring errors.
def stderrHandler(level, object, category, file, line, message): (source)
A log handler that writes to stderr.
Parameterslevel (type: string )
object (type: string (or None) )
category (type: string )
message (type: string )
def _preformatLevels(noColorEnvVarName): (source)
Undocumented
def init(envVarName, enableColorOutput=False): (source)
Initialize the logging system and parse the environment variable of the given name. Needs to be called before starting the actual application.
def setDebug(string): (source)
Set the DEBUG string. This controls the log output.
def getDebug(): (source)
Returns the currently active DEBUG string.
Returns (type: str )
def setPackageScrubList(*packages): (source)
Set the package names to scrub from filenames. Filenames from these paths in log messages will be scrubbed to their relative file path instead of the full absolute path.
Parameterspackages (type: list of str )
def reset(): (source)
Resets the logging system, removing all log handlers.
def addLogHandler(func): (source)
Add a custom log handler.
Parametersfunca function object with prototype (level, object, category, message) where level is either ERROR, WARN, INFO, DEBUG, or LOG, and the rest of the arguments are strings or None. Use getLevelName(level) to get a printable name for the log level. (type: a callable function )
RaisesTypeErrorif func is not a callable
def addLimitedLogHandler(func): (source)
Add a custom log handler.
Parametersfunca function object with prototype (level, object, category, message) where level is either ERROR, WARN, INFO, DEBUG, or LOG, and the rest of the arguments are strings or None. Use getLevelName(level) to get a printable name for the log level. (type: a callable function )
RaisesTypeErrorTypeError if func is not a callable
def removeLogHandler(func): (source)
Remove a registered log handler.
Parametersfunca function object with prototype (level, object, category, message) where level is either ERROR, WARN, INFO, DEBUG, or LOG, and the rest of the arguments are strings or None. Use getLevelName(level) to get a printable name for the log level. (type: a callable function )
RaisesValueErrorif func is not registered
def removeLimitedLogHandler(func): (source)
Remove a registered limited log handler.
Parametersfunca function object with prototype (level, object, category, message) where level is either ERROR, WARN, INFO, DEBUG, or LOG, and the rest of the arguments are strings or None. Use getLevelName(level) to get a printable name for the log level. (type: a callable function )
RaisesValueErrorif func is not registered
def error(cat, format, *args): (source)
Undocumented
def warning(cat, format, *args): (source)
Undocumented
def info(cat, format, *args): (source)
Undocumented
def debug(cat, format, *args): (source)
Undocumented
def log(cat, format, *args): (source)
Undocumented
def getExceptionMessage(exception, frame=-1, filename=None): (source)
Return a short message based on an exception, useful for debugging. Tries to find where the exception was triggered.
def reopenOutputFiles(): (source)
Reopens the stdout and stderr output files, as set by outputToFiles.
def outputToFiles(stdout=None, stderr=None): (source)

Redirect stdout and stderr to named files.

Records the file names so that a future call to reopenOutputFiles() can open the same files. Installs a SIGHUP handler that will reopen the output files.

Note that stderr is opened unbuffered, so if it shares a file with stdout then interleaved output may not appear in the order that you expect.
def _getTheTwistedLogObserver(): (source)
Undocumented
def getFailureMessage(failure): (source)
Return a short message based on twisted.python.failure.Failure. Tries to find where the exception was triggered.
def warningFailure(failure, swallow=True): (source)
Log a warning about a Failure. Useful as an errback handler: d.addErrback(warningFailure)
Parametersswallowwhether to swallow the failure or not (type: bool )
def logTwisted(): (source)

Integrate twisted's logger with our logger.

This is done in a separate method because calling this imports and sets up a reactor. Since we want basic logging working before choosing a reactor, we need to separate these.
API Documentation for Coherence, generated by pydoctor at 2007-12-08 21:02:38.