pyats.log package

class pyats.log.ColouredScreenFormatter

Bases: ColouredLogLevelFormatter, ScreenFormatter

Initialize the formatter with specified format strings.

Initialize the formatter either with the specified format string, or a default as described above. Allow for specialized date formatting with the optional datefmt argument. If datefmt is omitted, you get an ISO8601-like (or RFC 3339-like) format.

Use a style parameter of ‘%’, ‘{’ or ‘$’ to specify that you want to use one of %-formatting, str.format() ({}) formatting or string.Template formatting in your format string.

Changed in version 3.2: Added the style parameter.

MESSAGE_FORMAT = '%(asctime)s: %%%(cisco_appname)s-%(cisco_msgname)s: %(coloured_message)s'
class pyats.log.ScreenFormatter

Bases: CiscoLogFormatter

Initialize the formatter with specified format strings.

Initialize the formatter either with the specified format string, or a default as described above. Allow for specialized date formatting with the optional datefmt argument. If datefmt is omitted, you get an ISO8601-like (or RFC 3339-like) format.

Use a style parameter of ‘%’, ‘{’ or ‘$’ to specify that you want to use one of %-formatting, str.format() ({}) formatting or string.Template formatting in your format string.

Changed in version 3.2: Added the style parameter.

MESSAGE_FORMAT = '%(asctime)s: %%%(cisco_appname)s-%(cisco_msgname)s: %(message)s'
TIMESTAMP_FORMAT = '%Y-%m-%dT%H:%M:%S'
class pyats.log.ScreenHandler(stream=None, coloured=True)

Bases: StreamHandler

pyATS Logging Screen Handler, with baked-in default support for coloured screen log formatting

Initialize the handler.

If stream is not specified, sys.stderr is used.

property coloured
property stream
class pyats.log.TaskLogFormatter

Bases: ScreenFormatter

Initialize the formatter with specified format strings.

Initialize the formatter either with the specified format string, or a default as described above. Allow for specialized date formatting with the optional datefmt argument. If datefmt is omitted, you get an ISO8601-like (or RFC 3339-like) format.

Use a style parameter of ‘%’, ‘{’ or ‘$’ to specify that you want to use one of %-formatting, str.format() ({}) formatting or string.Template formatting in your format string.

Changed in version 3.2: Added the style parameter.

MESSAGE_FORMAT = '%(seqnum)s: %(hostname)s: %(asctime)s: %%%(cisco_appname)s-%(cisco_sev)s-%(cisco_msgname)s: %(tags)s%(message)s'
class pyats.log.TaskLogHandler(logfile, mode='a', encoding=None, coloured=False)

Bases: StreamHandler

pyATS Logging File Handler. Colour output is turned off by default in order to avoid confusing TRADe.

Initialize the handler.

If stream is not specified, sys.stderr is used.

changeFile(logfile)

log file must be full path or relative to previous logdir

close()

Closes the stream.

property coloured
concatenateLog(logfile, delete=True)

concatenate target log file’s content into the current logfile.

consolidate_next_forked_logfile()

API to automatically consolidate the next forked logfile into the current logfile. This api is to be used as a context manager, where a new process is forked within its context. Does nothing otherwise.

Example

# assuming you have a process you’re about to start >>> with tasklog.consolidate_next_forked_logfile(): … process.start() … process.join()

disableForked()

Disables forking behavior of this logger. All forked child process will revert back to the default behavior where it all logs to this file.

Multiple calls to this api does not generate exceptions.

enableForked(consolidate=False)

Enable forking behavior of this logger. All forked child process will redirect to a child TaskLog in the format of “<parentlog>:pid-<pid>”.

Multiple calls to this api does not generate exceptions.

Parameters:

consolidate (bool) – controls whether the child logs will get merged with its parent log after process exits. default to True.

property forkRegistered

Property, returning whether on-fork tasklog change was enabled.

static forked(instance)

forked staticmethod

Function called with a given TaskLogHandler isntance post-forking. This api is intended to be called by multiprocessing.util._run_finalizers, where the TaskLog is redirected to a child log file (so that multiple) processes do not all log into the same file.

forked_finalizer(parent_logfile, delete=True)

multiprocessing finalizer, concatenate forked child log file into log file’s content into parent logfile.

next_fork_logfile(logfile, consolidate=None)

API to allow the next forked process to take on the given file as its tasklog. This api is to be used as a context manager, where a new process is forked within its context. Does nothing otherwise.

Parameters:

logfile (str) – logfile name

Example

# assuming you have a process you’re about to start >>> with tasklog.next_fork_logfile(‘newlogfile.log’): … process.start() … process.join()

Subpackages

Submodules

class pyats.log.cisco.ColouredScreenFormatter

Bases: ColouredLogLevelFormatter, ScreenFormatter

Initialize the formatter with specified format strings.

Initialize the formatter either with the specified format string, or a default as described above. Allow for specialized date formatting with the optional datefmt argument. If datefmt is omitted, you get an ISO8601-like (or RFC 3339-like) format.

Use a style parameter of ‘%’, ‘{’ or ‘$’ to specify that you want to use one of %-formatting, str.format() ({}) formatting or string.Template formatting in your format string.

Changed in version 3.2: Added the style parameter.

MESSAGE_FORMAT = '%(asctime)s: %%%(cisco_appname)s-%(cisco_msgname)s: %(coloured_message)s'
class pyats.log.cisco.ScreenFormatter

Bases: CiscoLogFormatter

Initialize the formatter with specified format strings.

Initialize the formatter either with the specified format string, or a default as described above. Allow for specialized date formatting with the optional datefmt argument. If datefmt is omitted, you get an ISO8601-like (or RFC 3339-like) format.

Use a style parameter of ‘%’, ‘{’ or ‘$’ to specify that you want to use one of %-formatting, str.format() ({}) formatting or string.Template formatting in your format string.

Changed in version 3.2: Added the style parameter.

MESSAGE_FORMAT = '%(asctime)s: %%%(cisco_appname)s-%(cisco_msgname)s: %(message)s'
TIMESTAMP_FORMAT = '%Y-%m-%dT%H:%M:%S'
class pyats.log.cisco.ScreenHandler(stream=None, coloured=True)

Bases: StreamHandler

pyATS Logging Screen Handler, with baked-in default support for coloured screen log formatting

Initialize the handler.

If stream is not specified, sys.stderr is used.

property coloured
property stream
class pyats.log.cisco.TaskLogFormatter

Bases: ScreenFormatter

Initialize the formatter with specified format strings.

Initialize the formatter either with the specified format string, or a default as described above. Allow for specialized date formatting with the optional datefmt argument. If datefmt is omitted, you get an ISO8601-like (or RFC 3339-like) format.

Use a style parameter of ‘%’, ‘{’ or ‘$’ to specify that you want to use one of %-formatting, str.format() ({}) formatting or string.Template formatting in your format string.

Changed in version 3.2: Added the style parameter.

MESSAGE_FORMAT = '%(seqnum)s: %(hostname)s: %(asctime)s: %%%(cisco_appname)s-%(cisco_sev)s-%(cisco_msgname)s: %(tags)s%(message)s'
class pyats.log.cisco.TaskLogHandler(logfile, mode='a', encoding=None, coloured=False)

Bases: StreamHandler

pyATS Logging File Handler. Colour output is turned off by default in order to avoid confusing TRADe.

Initialize the handler.

If stream is not specified, sys.stderr is used.

changeFile(logfile)

log file must be full path or relative to previous logdir

close()

Closes the stream.

property coloured
concatenateLog(logfile, delete=True)

concatenate target log file’s content into the current logfile.

consolidate_next_forked_logfile()

API to automatically consolidate the next forked logfile into the current logfile. This api is to be used as a context manager, where a new process is forked within its context. Does nothing otherwise.

Example

# assuming you have a process you’re about to start >>> with tasklog.consolidate_next_forked_logfile(): … process.start() … process.join()

disableForked()

Disables forking behavior of this logger. All forked child process will revert back to the default behavior where it all logs to this file.

Multiple calls to this api does not generate exceptions.

enableForked(consolidate=False)

Enable forking behavior of this logger. All forked child process will redirect to a child TaskLog in the format of “<parentlog>:pid-<pid>”.

Multiple calls to this api does not generate exceptions.

Parameters:

consolidate (bool) – controls whether the child logs will get merged with its parent log after process exits. default to True.

property forkRegistered

Property, returning whether on-fork tasklog change was enabled.

static forked(instance)

forked staticmethod

Function called with a given TaskLogHandler isntance post-forking. This api is intended to be called by multiprocessing.util._run_finalizers, where the TaskLog is redirected to a child log file (so that multiple) processes do not all log into the same file.

forked_finalizer(parent_logfile, delete=True)

multiprocessing finalizer, concatenate forked child log file into log file’s content into parent logfile.

next_fork_logfile(logfile, consolidate=None)

API to allow the next forked process to take on the given file as its tasklog. This api is to be used as a context manager, where a new process is forked within its context. Does nothing otherwise.

Parameters:

logfile (str) – logfile name

Example

# assuming you have a process you’re about to start >>> with tasklog.next_fork_logfile(‘newlogfile.log’): … process.start() … process.join()

class pyats.log.colour.BgColour(value)

Bases: Palette, Enum

An enumeration.

BLACK = '\x1b[40m'
BLUE = '\x1b[44m'
BRIGHT_BLACK = '\x1b[100m'
BRIGHT_BLUE = '\x1b[104m'
BRIGHT_CYAN = '\x1b[106m'
BRIGHT_GREEN = '\x1b[102m'
BRIGHT_MAGENTA = '\x1b[105m'
BRIGHT_RED = '\x1b[101m'
BRIGHT_WHITE = '\x1b[107m'
BRIGHT_YELLOW = '\x1b[103m'
CYAN = '\x1b[46m'
GREEN = '\x1b[42m'
MAGENTA = '\x1b[45m'
RED = '\x1b[41m'
WHITE = '\x1b[47m'
YELLOW = '\x1b[43m'
class pyats.log.colour.ColouredLogLevelFormatter(fmt=None, datefmt=None, style='%', validate=True)

Bases: ColourizingFormatter

Initialize the formatter with specified format strings.

Initialize the formatter either with the specified format string, or a default as described above. Allow for specialized date formatting with the optional datefmt argument. If datefmt is omitted, you get an ISO8601-like (or RFC 3339-like) format.

Use a style parameter of ‘%’, ‘{’ or ‘$’ to specify that you want to use one of %-formatting, str.format() ({}) formatting or string.Template formatting in your format string.

Changed in version 3.2: Added the style parameter.

LEVEL_MAP = {10: <function ColouredLogLevelFormatter.<lambda>>, 30: <function ColouredLogLevelFormatter.<lambda>>, 40: <function ColouredLogLevelFormatter.<lambda>>, 50: <function ColouredLogLevelFormatter.<lambda>>}
class pyats.log.colour.ColourizingFormatter(fmt=None, datefmt=None, style='%', validate=True)

Bases: Formatter

Initialize the formatter with specified format strings.

Initialize the formatter either with the specified format string, or a default as described above. Allow for specialized date formatting with the optional datefmt argument. If datefmt is omitted, you get an ISO8601-like (or RFC 3339-like) format.

Use a style parameter of ‘%’, ‘{’ or ‘$’ to specify that you want to use one of %-formatting, str.format() ({}) formatting or string.Template formatting in your format string.

Changed in version 3.2: Added the style parameter.

formatMessage(record)
class pyats.log.colour.FgColour(value)

Bases: Palette, Enum

An enumeration.

BLACK = '\x1b[30m'
BLUE = '\x1b[34m'
BRIGHT_BLACK = '\x1b[90m'
BRIGHT_BLUE = '\x1b[94m'
BRIGHT_CYAN = '\x1b[96m'
BRIGHT_GREEN = '\x1b[92m'
BRIGHT_MAGENTA = '\x1b[95m'
BRIGHT_RED = '\x1b[91m'
BRIGHT_WHITE = '\x1b[97m'
BRIGHT_YELLOW = '\x1b[93m'
CYAN = '\x1b[36m'
GREEN = '\x1b[32m'
MAGENTA = '\x1b[35m'
RED = '\x1b[31m'
WHITE = '\x1b[37m'
YELLOW = '\x1b[33m'
class pyats.log.colour.Palette

Bases: object

apply(msg)
classmethod mix(*colours)

mixes multiple colors together and return one color code

classmethod paint(msg, *colours)
class pyats.log.colour.Style(value)

Bases: Palette, Enum

An enumeration.

BOLD = '\x1b[1m'
LIGHT = '\x1b[2m'
RESET = '\x1b[0m\x1b[39m'

Generic logging utilities.

class pyats.log.utils.ExtendableFormatter(prog, indent_increment=2, max_help_position=24, width=None)

Bases: RawTextHelpFormatter

Modify help print This formatter is designed to collect together usage/help details from other parsers.

A parser defining this class as its default formatter must not expect it to handle things like terminal width-driven help string line pagination.

format_help()
helps = []
usages = []
class pyats.log.utils.ReportingLogFile(file_, filename=None)

Bases: object

Tracks a growing file for reporting purposes.

Tracks current file length in bytes/lines.

As a file grows, instances of ReportingLogFile may be created at key points to mark the beginning and end of a reporting region.

When two instances of ReportingLogFile are subtracted a FileRegion object is returned which has the following fields:

  • begin_bytes : The byte offset of the start of the reporting region (0-based)

  • size_bytes : The size in bytes of the reporting region

  • begin_lines : The line offset of the start of the reporting region (0-based)

  • size_lines : The size in lines of the reporting region.

Produces a report indicating the beginning and size of the reporting region in bytes/lines.

Parameters:

  • file (File-like object or TaskLogHandler) – Used to flush the file. Also used to derive filename if not otherwise specified.

  • filename (str) – Use this filename instead of deriving it from file.

flush()

Request the file to be flushed to the file system.

get_summary(file_region)

Get a structured file summary

pyats.log.utils.banner(text, width=80, padding=8, h_margin='-', v_margin='|', align='center')

Banner api Create a banner text.

Parameters:

  • (str) (v_margin) –

  • (int) (padding) –

  • (int) – and side

  • (str) – Must be of size 1

  • (str) – Must be of size 1.

Example

import logging
from pyats.log.utils import banner
testlog = logging.getLogger(__name__)
testlog.info(banner("example banner"))
Output:
+----------------------------------------------------------------------+
|                             example banner                           |
+----------------------------------------------------------------------+
pyats.log.utils.get_file_length(file_name)

Get length details on specified file

Utility function, calculates length of file in bytes and lines.

If the file is still open, it is best to flush the file first before calling this API.

>>> with open('/path/to/file', 'w') as f:
...    f.write("First line

Second line Third line “)

>>> get_file_length(i'/path/to/file')
(34, 3)

f (str): Fully-specified pathname to file.

(length in bytes, length in lines)

An external subprocess call is made for speed, as the native Python equivalent suffers from performance issues.

pyats.log.utils.get_max_file_length(dir_name)

Get the maximum supported file length for the directory.

pyats.log.utils.str_shortener(text, limit=80, subst='...')

Use this util to shorten the text with the provided character limit. It is useful for reporting. If the text longer than the limit, it will truncate the string and add the given value for subst to the end of the string

Parameters:

  • (str) (subst) –

  • (int) (limit) – shorter than subst+1

  • (str) – if the text is longer than the limit.

Example:

print(str_shortener(“a long string will be truncated”, 9)) >>> a long…

pyats.log.utils.title(text, width=80, padding=2, margin='=', align='center')

Title api Create a title text.

Parameters:

  • (str) (margin) –

  • (int) (padding) –

  • (int) – and side

  • (str) – Must be of size 1

Example

import logging
from pyats.log.utils import title
testlog = logging.getLogger(__name__)
testlog.info(title("example title"))
Output:
==============================example title=============================
pyats.log.warnings.enable_deprecation_warnings(module='pyats\\..*|__main__')

This API enables the printing of DeprecationWarnings.

Parameters:

(str) (module) – warning for. Defaults to pyats.* and __main__ in regex.

pyats.log.warnings.enable_warnings_to_log()

This API overwrites warnings.showwarning() and replaces with a custom implementation that redirects warnings to logging (in addition to file)

Parameters:

None –