smartinspectpython.sitextprotocol

@export
class SITextProtocol(smartinspectpython.sifileprotocol.SIFileProtocol):

Used for writing customizable plain text log files.

This class is used for writing plain text log files. This class is used when the 'text' protocol is specified in the SmartInspect.Connections.

For a list of available protocol options, please refer to the IsValidOption method.

Threadsafety:

The public members of this class are thread-safe.

SITextProtocol()

Initializes a new instance of the class.

DefaultFileName: str

Returns the default filename for this log file protocol.

The standard implementation of this method returns the string "log.txt" here. Derived classes can change this behavior by overriding this method.

Returns the formatter for this log file protocol.

The standard implementation of this method returns an instance of the SIBinaryFormatter class. Derived classes can change this behavior by overriding this method.

Name: str

Overridden. Returns "text".

def BuildOptions( self, builder: smartinspectpython.siconnectionsbuilder.SIConnectionsBuilder) -> None:

Overridden. Fills a SIConnectionsBuilder instance with the options currently used by this protocol.

Arguments:
  • builder (SIConnectionsBuilder): The SIConnectionsBuilder object to fill with the current options of this protocol.
def IsValidOption(self, name: str) -> bool:

Overridden. Validates if a protocol option is supported.

Arguments:
  • name (str): The option name to validate.
Returns:

True if the option is supported and false otherwise.

The following table lists all valid options, their default values and descriptions for the TEXT protocol.

Valid Options (default value) Description
indent (false) Indicates if the logging output should automatically be indented like in the Console.
pattern ("[%timestamp%] %level%: %title%") Specifies the pattern used to create a text representation of a packet.

Please note that this protocol DOES NOT support log file encryption.

For further options which affect the behavior of this protocol, please have a look at the documentation of the SIProtocol.IsValidOption method of the parent class.

Sample Code

# package imports.
from smartinspectpython.siauto import *

# the following are sample SI Connections options for this protocol.

# log messages using all default options ("log.sil", no indent).
SIAuto.Si.Connections = "text()"

# log messages using all default options ("log.sil", no indent).
SIAuto.Si.Connections = "text(filename=\"log.txt\")"

# log messages (appending) to file 'mylog.txt'.
SIAuto.Si.Connections = "text(filename=\"mylog.txt\", append=true)"

# log messages to rotating log file 'mylog.txt', that creates a new log 
# file every week.  since maxparts is not specified, log files will continue 
# to accumulate and must be manually deleted.
SIAuto.Si.Connections = "text(filename=\"mylog.txt\", append=true, rotate=weekly"

# log messages to rotating log file 'mylog.txt', that creates a new log 
# file every week; keep only 7 log files, automatically deleting outdated files.
SIAuto.Si.Connections = "text(filename=\"mylog.txt\", append=true, rotate=weekly, maxparts=7)"

# log messages to file "mylog.txt" using a custom pattern.
SIAuto.Si.Connections = "text(filename=\"mylog.txt\", append=true, pattern=\"%level% [%timestamp%]: %title%\")"

# log messages to rotating default file 'mylog.txt', that do not 
# exceed 16MB in size.
SIAuto.Si.Connections = "text(maxsize=\"16MB\")"

def LoadOptions(self) -> None:

Overridden. Loads and inspects specific options for this protocol.

This method loads all relevant options and ensures their correctness. See IsValidOption for a list of options which are recognized by the protocol.

def WriteFooter(self, stream: _io.BytesIO) -> None:

Intended to write the footer of a log file.

Arguments:
  • stream (BytesIO): The stream to which the footer should be written to.

The implementation of this method does nothing. Derived class may change this behavior by overriding this method.

def WriteHeader(self, stream: _io.BytesIO, size: int) -> int:

Overridden. Intended to write the header of a log file.

Arguments:
  • stream (BytesIO): The stream to which the header should be written to.
  • size (int): Specifies the current size of the supplied stream.
Returns:

The new size of the stream after writing the header. If no header is written, the supplied size argument is returned.

The implementation of this method writes the standard UTF8 BOM (byte order mark) to the supplied stream in order to identify the log file as text file in UTF8 encoding. Derived classes may change this behavior by overriding this method.