twisted.python.log

Logging and metrics infrastructure.

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.
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.
Class	DefaultObserver	Default observer.
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	_GlobalStartStopMixIn	Mix-in for global log observers that can start and stop.

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

Undocumented

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

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):

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	_stuff	The 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`.)
	_why	The source of this failure. This will be logged along with `_stuff` and should describe the context in which the failure occurred. (type: `str`)

def _actually(something):

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.

Parameters	something	An object to create an alias for. (type: `object`)
Returns	a 1-argument callable that returns `something` (type: `object`)

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

Add a log observer to the global publisher.

Parameters	observer	a log observer (type: `callable`)
See Also	`LogPublisher.addObserver`

@_actually(theLogPublisher.removeObserver)
def removeObserver(observer):

Remove a log observer from the global publisher.

Parameters	observer	a log observer previously added with `addObserver` (type: `callable`)
See Also	`LogPublisher.removeObserver`

@_actually(theLogPublisher.msg)
def msg(*message, **event):

Publish a message to the global log publisher.

Parameters	message	the log message (type: `tuple` of `str` (native string))
	event	fields for the log event (type: `dict` mapping `str` (native string) to `object`)
See Also	`LogPublisher.msg`

@_actually(theLogPublisher.showwarning)
def showwarning():

Publish a Python warning through the global log publisher.

See Also LogPublisher.showwarning

def _safeFormat(fmtString, fmtDict):

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

Parameters	fmtString	a `%`-format string
	fmtDict	string formatting arguments for `fmtString`
Returns	A native string, formatted from `fmtString` and `fmtDict`. (type: `str`)
Note	For backward-compatibility reasons, this function ensures that it returns a native string, meaning `bytes` in Python 2 and `unicode` in Python 3.

def textFromEventDict(eventDict):

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.

def startLogging(file, *a, **kw):

Initialize logging to a specified file.

Returns A FileLogObserver if a new observer is added, None otherwise.

def startLoggingWithObserver(observer, setStdout=1):

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():

Discard messages logged via the global logfile object.

API Documentation for twisted, generated by pydoctor at 2020-03-25 17:34:30.

twisted.python.log module documentation

`twisted.python.log` module documentation