class documentation

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: Optional[int] = None): (source)

Initialize this LogBeginner.

Parameters
publisher:LogPublisherUndocumented
errorStream:IO[Any]Undocumented
stdio:objectUndocumented
warningsModule:AnyUndocumented
initialBufferSize:Optional[int]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:boolWhether to discard the buffer and not re-play it to the added observers. (This argument is provided mainly for compatibility with legacy concerns.)
redirectStandardIO:boolIf 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: Optional[IO[Any]] = None, line: Optional[str] = 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:strA warning message to emit.
category:Type[Warning]A warning category to associate with message.
filename:strA file name for the source code file issuing the warning.
lineno:intA line number in the source file where the warning was issued.
file:Optional[IO[Any]]A file to write the warning message to. If None, write to sys.stderr.
line:Optional[str]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.

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.

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

_temporaryObserver: Optional[ILogObserver] = (source)

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

_warningsModule = (source)

Undocumented