Package flumotion :: Package extern :: Package log :: Module log
[hide private]

Module log

source code

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

Classes [hide private]
  Loggable
Base class for objects that want to be able to log messages with different level of severity.
  TwistedLogObserver
Twisted log observer that integrates with our logging.
Functions [hide private]
str
getLevelName(level)
Return the name of a log level.
source code
list of str
getLevelNames()
Return a list with the level names
source code
int
getLevelInt(levelName)
Return the integer value of the levelName.
source code
 
getFormattedLevelName(level) source code
 
registerCategory(category)
Register a given category in the debug system.
source code
 
getCategoryLevel(category) source code
 
setLogSettings(state)
Update the current log settings.
source code
 
getLogSettings()
Fetches the current log settings.
source code
 
_canShortcutLogging(category, level) source code
 
scrubFilename(filename)
Scrub the filename to a relative path for all packages in our scrub list.
source code
tuple of (str, int)
getFileLine(where=-1)
Return the filename and line number for the given location.
source code
 
ellipsize(o)
Ellipsize the representation of the given object.
source code
 
getFormatArgs(startFormat, startArgs, endFormat, endArgs, args, kwargs)
Helper function to create a format and args to use for logging.
source code
 
doLog(level, object, category, format, args, where=-1, filePath=None, line=None)
Returns: dict of calculated variables, if they needed calculating.
source code
 
errorObject(object, cat, format, *args)
Log a fatal error message in the given category.
source code
 
warningObject(object, cat, format, *args)
Log a warning message in the given category.
source code
 
infoObject(object, cat, format, *args)
Log an informational message in the given category.
source code
 
debugObject(object, cat, format, *args)
Log a debug message in the given category.
source code
 
logObject(object, cat, format, *args)
Log a log message.
source code
 
safeprintf(file, format, *args)
Write to a file object, ignoring errors.
source code
 
stderrHandler(level, object, category, file, line, message)
A log handler that writes to stderr.
source code
 
_preformatLevels(noColorEnvVarName) source code
 
init(envVarName, enableColorOutput=False)
Initialize the logging system and parse the environment variable of the given name.
source code
 
setDebug(string)
Set the DEBUG string.
source code
str
getDebug()
Returns the currently active DEBUG string.
source code
 
setPackageScrubList(*packages)
Set the package names to scrub from filenames.
source code
 
reset()
Resets the logging system, removing all log handlers.
source code
 
addLogHandler(func)
Add a custom log handler.
source code
 
addLimitedLogHandler(func)
Add a custom log handler.
source code
 
removeLogHandler(func)
Remove a registered log handler.
source code
 
removeLimitedLogHandler(func)
Remove a registered limited log handler.
source code
 
error(cat, format, *args) source code
 
warning(cat, format, *args) source code
 
info(cat, format, *args) source code
 
debug(cat, format, *args) source code
 
log(cat, format, *args) source code
 
getExceptionMessage(exception, frame=-1, filename=None)
Return a short message based on an exception, useful for debugging.
source code
 
reopenOutputFiles()
Reopens the stdout and stderr output files, as set by outputToFiles.
source code
 
outputToFiles(stdout=None, stderr=None)
Redirect stdout and stderr to named files.
source code
 
_getTheTwistedLogObserver() source code
 
getFailureMessage(failure)
Return a short message based on twisted.python.failure.Failure.
source code
 
warningFailure(failure, swallow=True)
Log a warning about a Failure.
source code
 
logTwisted()
Integrate twisted's logger with our logger.
source code
Variables [hide private]
  _DEBUG = '*:1'
  _ENV_VAR_NAME = None
  _PACKAGE_SCRUB_LIST = []
  _categories = {'packager': 1}
  _log_handlers = []
  _log_handlers_limited = []
  _initialized = False
  _stdout = None
  _stderr = None
  _old_hup_handler = None
  COLORS = {1: 'RED', 2: 'YELLOW', 3: 'GREEN', 4: 'BLUE', 5: 'CY...
  _FORMATTED_LEVELS = []
  _LEVEL_NAMES = ['ERROR', 'WARN', 'INFO', 'DEBUG', 'LOG']
  _initializedTwisted = False
  __theTwistedLogObserver = None
  DEBUG = 4
  ERROR = 1
  INFO = 3
  LOG = 5
  WARN = 2
Function Details [hide private]

getLevelName(level)

source code 

Return the name of a log level.

Parameters:
  • level (int) - The level we want to know the name
Returns: str
The name of the level

getLevelNames()

source code 

Return a list with the level names

Returns: list of str
A list with the level names

getLevelInt(levelName)

source code 

Return the integer value of the levelName.

Parameters:
  • levelName (str) - The string value of the level name
Returns: int
The value of the level name we are interested in.

registerCategory(category)

source code 

Register a given category in the debug system. A level will be assigned to it based on previous calls to setDebug.

getCategoryLevel(category)

source code 
Parameters:
  • category - string

    Get the debug level at which this category is being logged, adding it if it wasn't registered yet.

setLogSettings(state)

source code 

Update the current log settings. This can restore an old saved log settings object returned by getLogSettings

Parameters:
  • state - the settings to set

getLogSettings()

source code 

Fetches the current log settings. The returned object can be sent to setLogSettings to restore the returned settings

Returns:
the current settings

getFileLine(where=-1)

source code 

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.

Parameters:
  • where (int (negative) or function) - how many frames to go back up, or function
Returns: tuple of (str, int)
tuple of (file, line)

getFormatArgs(startFormat, startArgs, endFormat, endArgs, args, kwargs)

source code 

Helper function to create a format and args to use for logging. This avoids needlessly interpolating variables.

doLog(level, object, category, format, args, where=-1, filePath=None, line=None)

source code 
Parameters:
  • where (int or callable) - what 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
  • filePath (str) - file to show the message as coming from, if caller knows best
  • line (int) - line to show the message as coming from, if caller knows best
Returns:
dict 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

errorObject(object, cat, format, *args)

source code 

Log a fatal error message in the given category. This will also raise a SystemExit.

warningObject(object, cat, format, *args)

source code 

Log a warning message in the given category. This is used for non-fatal problems.

logObject(object, cat, format, *args)

source code 

Log a log message. Used for debugging recurring events.

stderrHandler(level, object, category, file, line, message)

source code 

A log handler that writes to stderr.

Parameters:
  • category (string)
  • message (string)
  • object (string (or None))
  • level (string)

init(envVarName, enableColorOutput=False)

source code 

Initialize the logging system and parse the environment variable of the given name. Needs to be called before starting the actual application.

setDebug(string)

source code 

Set the DEBUG string. This controls the log output.

setPackageScrubList(*packages)

source code 

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.

Parameters:
  • packages (list of str)

addLogHandler(func)

source code 

Add a custom log handler.

Parameters:
  • func (a callable function) - a 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.
Raises:
  • TypeError - if func is not a callable

addLimitedLogHandler(func)

source code 

Add a custom log handler.

Parameters:
  • func (a callable function) - a 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.
Raises:
  • TypeError - TypeError if func is not a callable

removeLogHandler(func)

source code 

Remove a registered log handler.

Parameters:
  • func (a callable function) - a 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.
Raises:
  • ValueError - if func is not registered

removeLimitedLogHandler(func)

source code 

Remove a registered limited log handler.

Parameters:
  • func (a callable function) - a 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.
Raises:
  • ValueError - if func is not registered

getExceptionMessage(exception, frame=-1, filename=None)

source code 

Return a short message based on an exception, useful for debugging. Tries to find where the exception was triggered.

outputToFiles(stdout=None, stderr=None)

source code 

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.

getFailureMessage(failure)

source code 

Return a short message based on twisted.python.failure.Failure. Tries to find where the exception was triggered.

warningFailure(failure, swallow=True)

source code 

Log a warning about a Failure. Useful as an errback handler: d.addErrback(warningFailure)

Parameters:
  • swallow (bool) - whether to swallow the failure or not

logTwisted()

source code 

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.


Variables Details [hide private]

COLORS

Value:
{1: 'RED', 2: 'YELLOW', 3: 'GREEN', 4: 'BLUE', 5: 'CYAN'}