Go to the latest version of this document.

# ``twisted`.`logger`.`LogBeginner``

class documentation

`class LogBeginner: (source)`

Constructor: `LogBeginner(publisher, errorStream, stdio, warningsModule, ...)`

View In Hierarchy

A `LogBeginner` holds state related to logging before logging has begun, and begins logging when told to do so. Logging "begins" when someone has selected a set of observers, like, for example, a `FileLogObserver` that writes to a file on disk, or to standard output.

Applications will not typically need to instantiate this class, except those which intend to initialize the global logging system themselves, which may wish to instantiate this for testing. The global instance for the current process is exposed as `twisted.logger.globalLogBeginner`.

Before logging has begun, a `LogBeginner` will:

1. Log any critical messages (e.g.: unhandled exceptions) to the given file-like object.
2. Save (a limited number of) log events in a `LimitedHistoryLogObserver`.

Method | `__init__` | Initialize this `LogBeginner`.
Method | `beginLoggingTo` | Begin logging to the given set of observers. This will:
Method | `showwarning` | Twisted-enabled wrapper around `warnings.showwarning`.
Constant | `_DEFAULT_BUFFER_SIZE` | The default size for the initial log events buffer.
Instance Variable | `_initialBuffer` | A buffer of messages logged before logging began.
Instance Variable | `_log` | The logger used to log messages about the operation of the `LogBeginner` itself.
Instance Variable | `_oldshowwarning` | Undocumented
Instance Variable | `_previousBegin` | Undocumented
Instance Variable | `_publisher` | The log publisher passed in to `LogBeginner`'s constructor.
Instance Variable | `_stdio` | An object with `stderr` and `stdout` attributes (like the `sys` module) which will be replaced when redirecting standard I/O.
Instance Variable | `_temporaryObserver` | If not `None`, an `ILogObserver` that observes events on `_publisher` for this `LogBeginner`.
Instance Variable | `_warningsModule` | Undocumented

def __init__(self, publisher: `LogPublisher`, errorStream: `IO[Any]`, stdio: `object`, warningsModule: `Any`, initialBufferSize: `int | None` = None): (source)

Initialize this `LogBeginner`.

Parameters
publisher:`LogPublisher` | Undocumented
errorStream:`IO[Any]` | Undocumented
stdio:`object` | Undocumented
warningsModule:`Any` | Undocumented
initialBufferSize:`int | None` | The size of the event buffer into which events are collected until `beginLoggingTo` is called. Or `None` to use the default size.

def beginLoggingTo(self, observers: `Iterable[ILogObserver]`, discardBuffer: `bool` = False, redirectStandardIO: `bool` = True): (source)

Begin logging to the given set of observers. This will:

1. Add all the observers given in `observers` to the `LogPublisher` associated with this `LogBeginner`.
2. Optionally re-direct standard output and standard error streams to the logging system.
3. Re-play any messages that were previously logged to that publisher to the new observers, if `discardBuffer` is not set.
4. Stop logging critical errors from the `LogPublisher` as strings to the `errorStream` associated with this `LogBeginner`, and allow them to be logged normally.
5. Re-direct warnings from the `warnings` module associated with this `LogBeginner` to log messages.

Parameters
observers:`Iterable[ILogObserver]` | The observers to register.
discardBuffer:`bool` | Whether to discard the buffer and not re-play it to the added observers. (This argument is provided mainly for compatibility with legacy concerns.)
redirectStandardIO:`bool` | If true, redirect standard output and standard error to the observers.

Note
Since a `LogBeginner` is designed to encapsulate the transition between process-startup and log-system-configuration, this method is intended to be invoked once.

def showwarning(self, message: `str`, category: `type[Warning]`, filename: `str`, lineno: `int`, file: `IO[Any] | None` = None, line: `str | None` = None): (source)

Twisted-enabled wrapper around `warnings.showwarning`.

If `file` is `None`, the default behaviour is to emit the warning to the log system, otherwise the original `warnings.showwarning` Python function is called.

Parameters
message:`str` | A warning message to emit.
category:`type[Warning]` | A warning category to associate with `message`.
filename:`str` | A file name for the source code file issuing the warning.
lineno:`int` | A line number in the source file where the warning was issued.
file:`IO[Any] | None` | A file to write the warning message to. If `None`, write to `sys.stderr`.
line:`str | None` | A line of source code to include with the warning message. If `None`, attempt to read the line from `filename` and `lineno`.

_DEFAULT_BUFFER_SIZE: `int` = (source)

The default size for the initial log events buffer.

Value

    200

_initialBuffer = (source)

A buffer of messages logged before logging began.

_log = (source)

The logger used to log messages about the operation of the `LogBeginner` itself.

_oldshowwarning = (source)

Undocumented

_previousBegin = (source)

Undocumented

_publisher = (source)

The log publisher passed in to `LogBeginner`'s constructor.

_stdio = (source)

An object with `stderr` and `stdout` attributes (like the `sys` module) which will be replaced when redirecting standard I/O.

_temporaryObserver: `ILogObserver | None` = (source)

If not `None`, an `ILogObserver` that observes events on `_publisher` for this `LogBeginner`.

_warningsModule = (source)

Undocumented