Go to the latest version of this document.
search in docstrings

Search bar offers the following options:

- Term presence. The below example searches for documents that must contain “foo”, might contain “bar” and must not contain “baz”: `+foo bar -baz`
- Wildcards. The below example searches for documents with words beginning with “foo”: `foo*`
- Search in specific fields. The following search matches all objects in "twisted.mail" that matches “search”: `+qname:twisted.mail.* +search`

  Possible fields: 'name', 'qname' (fully qualified name), 'docstring', and 'kind'. Last two fields are only applicable if "search in docstrings" is enabled.

- Fuzzy matches. The following search matches all documents that have a word within 1 edit distance of “foo”: `foo~1`

Results provided by Lunr.js

# ``twisted`.`python`.`log``

module documentation
(source)

Logging and metrics infrastructure.

Interface | `ILogObserver` | An observer which can do something with log events.
Class | `DefaultObserver` | Default observer.
Class | `FileLogObserver` | Log observer that writes to a file-like object.
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.
Class | `Logger` | This represents a class which may 'own' a log. Used by subclassing.
Class | `LogPublisher` | Class for singleton log message publishing.
Class | `NullFile` | A file-like object that discards everything.
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 | `addObserver` | Add a log observer to the global publisher.
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 | `discardLogs` | Discard messages logged via the global `logfile` object.
Function | `err` | Write a failure to the log.
Function | `msg` | Publish a message to the global log publisher.
Function | `removeObserver` | Remove a log observer from the global publisher.
Function | `showwarning` | Publish a Python warning through the global log publisher.
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.
Function | `textFromEventDict` | Extract text from an event dict passed to a log observer. If it cannot handle the dict, it returns None.
Type Alias | `EventDict` | Undocumented
Variable | `defaultObserver` | Undocumented
Variable | `logerr` | Undocumented
Variable | `logfile` | Undocumented
Variable | `theLogPublisher` | Undocumented
Class | `_GlobalStartStopObserver` | Mix-in for global log observers that can start and stop.
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.

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

Add a log observer to the global publisher.

Parameters
observer:`callable` | a log observer
See Also
`LogPublisher.addObserver`

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

Discard messages logged via the global `logfile` object.

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
_stuff:`None`, `Exception`, or `Failure`. | 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`.
_why:`str` | The source of this failure. This will be logged along with `_stuff` and should describe the context in which the failure occurred.
**kw | Undocumented

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

Publish a message to the global log publisher.

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

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

Remove a log observer from the global publisher.

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

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

Publish a Python warning through the global log publisher.

See Also
`LogPublisher.showwarning`

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

Initialize logging to a specified file.

Returns
A `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 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.

Parameters
eventDict:`EventDict` | Undocumented
Returns
`Optional[str]` | Undocumented

EventDict = (source)

Undocumented

Value

    Dict[str, Any]

defaultObserver = (source)

Undocumented

logerr = (source)

Undocumented

logfile = (source)

Undocumented

theLogPublisher = (source)

Undocumented

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.

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

def _safeFormat(fmtString, fmtDict): (source)

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

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