module documentation
(source)

Logging and metrics infrastructure.

Variable EventDict Undocumented
Class ILogContext Actually, this interface is just a synonym for the dictionary interface, but it serves as a key for the default information in a log.
Interface ILogObserver An observer which can do something with log events.
Function callWithContext Undocumented
Function callWithLogger Utility method which wraps a function in a try:/except:, logs a failure if one occurs, and uses the system's logPrefix.
Function err Write a failure to the log.
Class Logger This represents a class which may 'own' a log. Used by subclassing.
Class LogPublisher Class for singleton log message publishing.
Variable theLogPublisher Undocumented
Function addObserver Add a log observer to the global publisher.
Function removeObserver Remove a log observer from the global publisher.
Function msg Publish a message to the global log publisher.
Function showwarning Publish a Python warning through the global log publisher.
Function textFromEventDict Extract text from an event dict passed to a log observer. If it cannot handle the dict, it returns None.
Class FileLogObserver Log observer that writes to a file-like object.
Class PythonLoggingObserver Output twisted messages to Python standard library logging module.
Class StdioOnnaStick Class that pretends to be stdout/err, and turns writes into log messages.
Function startLogging Initialize logging to a specified file.
Function startLoggingWithObserver Initialize logging to a specified observer. If setStdout is true (defaults to yes), also redirect sys.stdout and sys.stderr to the specified file.
Class NullFile A file-like object that discards everything.
Function discardLogs Discard messages logged via the global logfile object.
Variable logfile Undocumented
Variable logerr Undocumented
Class DefaultObserver Default observer.
Variable defaultObserver Undocumented
Function _actually A decorator that returns its argument rather than the thing it is decorating.
Function _safeFormat Try to format a string, swallowing all errors to always return a string.
Class _GlobalStartStopObserver Mix-in for global log observers that can start and stop.
EventDict = (source)

Undocumented

def callWithContext(ctx, func, *args, **kw): (source)

Undocumented

def callWithLogger(logger, func, *args, **kw): (source)

Utility method which wraps a function in a try:/except:, logs a failure if one occurs, and uses the system's logPrefix.

def err(_stuff=None, _why=None, **kw): (source)

Write a failure to the log.

The _stuff and _why parameters use an underscore prefix to lessen the chance of colliding with a keyword argument the application wishes to pass. It is intended that they be supplied with arguments passed positionally, not by keyword.

Parameters_stuffThe failure to log. If _stuff is None a new Failure will be created from the current exception state. If _stuff is an Exception instance it will be wrapped in a Failure. (type: None, Exception, or Failure.)
_whyThe source of this failure. This will be logged along with _stuff and should describe the context in which the failure occurred. (type: str)
kwUndocumented
def _actually(something): (source)

A decorator that returns its argument rather than the thing it is decorating.

This allows the documentation generator to see an alias for a method or constant as an object with a docstring and thereby document it and allow references to it statically.

ParameterssomethingAn object to create an alias for. (type: object)
Returnsa 1-argument callable that returns something (type: object)
theLogPublisher = (source)

Undocumented

@_actually(theLogPublisher.addObserver)
def addObserver(observer): (source)

Add a log observer to the global publisher.

Parametersobservera log observer (type: callable)
See AlsoLogPublisher.addObserver
@_actually(theLogPublisher.removeObserver)
def removeObserver(observer): (source)

Remove a log observer from the global publisher.

Parametersobservera log observer previously added with addObserver (type: callable)
See AlsoLogPublisher.removeObserver
@_actually(theLogPublisher.msg)
def msg(*message, **event): (source)

Publish a message to the global log publisher.

Parametersmessagethe log message (type: tuple of str (native string))
eventfields for the log event (type: dict mapping str (native string) to object)
See AlsoLogPublisher.msg
@_actually(theLogPublisher.showwarning)
def showwarning(): (source)

Publish a Python warning through the global log publisher.

See AlsoLogPublisher.showwarning
def _safeFormat(fmtString, fmtDict): (source)

Try to format a string, swallowing all errors to always return a string.

ParametersfmtStringa %-format string (type: str)
fmtDictstring formatting arguments for fmtString (type: Dict[str, Any])
ReturnsA native string, formatted from fmtString and fmtDict. (type: str)
NoteFor backward-compatibility reasons, this function ensures that it returns a native string, meaning bytes in Python 2 and str in Python 3.
def textFromEventDict(eventDict): (source)

Extract text from an event dict passed to a log observer. If it cannot handle the dict, it returns None.

The possible keys of eventDict are:

  • message: by default, it holds the final text. It's required, but can be empty if either isError or format is provided (the first having the priority).
  • isError: boolean indicating the nature of the event.
  • failure: failure.Failure instance, required if the event is an error.
  • why: if defined, used as header of the traceback in case of errors.
  • format: string format used in place of message to customize the event. It uses all keys present in eventDict to format the text.

Other keys will be used when applying the format, or ignored.

ParameterseventDictUndocumented (type: EventDict)
ReturnsUndocumented (type: Optional[str])
def startLogging(file, *a, **kw): (source)

Initialize logging to a specified file.

ReturnsA FileLogObserver if a new observer is added, None otherwise.
def startLoggingWithObserver(observer, setStdout=1): (source)

Initialize logging to a specified observer. If setStdout is true (defaults to yes), also redirect sys.stdout and sys.stderr to the specified file.

def discardLogs(): (source)

Discard messages logged via the global logfile object.

logfile = (source)

Undocumented

logerr = (source)

Undocumented

defaultObserver = (source)

Undocumented

API Documentation for Twisted, generated by pydoctor 20.12.1 at 2021-02-28 19:53:36.