pyats.kleenex package




Myles Dear(mdear), CSG Test - Ottawa Siming Yuan (siyuan), CSG Test - Ottawa


This module provides a framework that allows users to:

  • plug in own orchestrators that bring up dynamic device topologies on a variety of different backends.

  • plug in their own cleaners that prepare a physical device for testing.



class pyats.kleenex.engine.KleenexEngine(reporter, debug_=False, **clean_mappings)

Bases: object

KleenexEngine effectively allows users to clean multiple devices at the same time, using various clean implementations for each device, without having to worry about about forks, processes & etc.

Internally this class is just about the same as async_.pcall, however, as clean definitions are designed to be mostly reused, there are some overlaps in code…

clean(devices, timeout=None, task=None, lcl_logger=<Logger pyats.kleenex.engine (WARNING)>)

Clean one or more sets of devices. Devices within each set are cleaned in parallel (if not running in debug mode).

Each set is cleaned sequentially.

clean_testbed(testbed, *, timeout=None, task=None, lcl_logger=<Logger pyats.kleenex.engine (WARNING)>)

Performs best-attempt cleaning of the testbed, assuming there is clean definition for each device in this testbed. If none is found - that device is skipped

classmethod from_cleandefs(*cleandefs, reporter, debug_=False)

Test whether KleenexEngine has clean definitions for a given device.


device (device object or device name string) –

Return type

True or False

static update_testbed(testbed, **cleaninfo)
exception pyats.kleenex.exceptions.CleanException(tb)

Bases: Exception

class pyats.kleenex.exceptions.CleanExceptionWithTraceback(exc, device_name)

Bases: ExceptionWithTraceback

exception pyats.kleenex.exceptions.CleanWorkerException

Bases: Exception

A decoupled tool to perform bringup and/or clean. If bringup is selected, launch the topology, optionally clean the topology, wait for the user to press <Ctrl><C>, then tear down the topology.

  • Returns a Linux exit code of 0 if all actions succeeded.

  • Otherwise, returns a Linux exit code if 1 if one or more actions failed.

class pyats.kleenex.kleenex_main.KleenexMain(testbed_file=None, clean_files=None, clean_devices=None, loglevel=20, logdir=None, no_logdir=None, orchestrator=None, debug=False, no_mail=False, commandline=False, device_image_deprecated=None, os_image_deprecated=None, clean_separator=':', device_image=None, os_image=None, group_image=None, platform_image=None, legacy=True, parser=None, no_upload=False, runinfo_dir=None, archive_dir=None, no_archive_subdir=False, skip_teardown=False, **kwargs)

Bases: object

This class implements bringup/clean behavior.

Bringup describes how a logical topology is converted into an actual topology consisting of physical and/or software-based routers.

Clean describes how one or more physical devices are prepared for testing by placing user-specified images on them. It may also include such steps as netbooting, bringing up a device from rommon mode or power cycling a device in order to recover it.

Create an instance of a bringup/clean orchestrator.

If an exception is thrown or a CLI argument fails validation, sys.exit(1) is called. This allows proper integration with test runners such as Jenkins.

  • testbed_file (str) – A YAML-formatted file describing the devices in the topology and how they are interconnected.

  • clean_files (list) – YAML-formatted files describing how the devices in the topology are to be brought up and / or cleaned.

  • clean_devices (list) – A list of devices to clean. If not specified, all devices in the topology are cleaned.

  • loglevel (str) – The Kleenex log level. One of the following : DEBUG, INFO, WARNING, ERROR, CRITICAL.

  • runinfo_dir (str) – The directory to store Kleenex logs and console output to. If not specified, defaults to a time-stamped directory under runinfo directory in the current environment, with a prefix of “Kleenex”.

  • archive_dir (str) – The directory to store Kleenex archive logs (zip). If not specified, defaults to a date-stamped directory under archive directory in the current environment.

  • no_archive_subdir (bool) – When True, does not create a date-stamped subdirectory under the specified archive directory. The Kleenex archive will be saved to the archive directory directly.

  • no_logdir (bool) – If True, no log directory is produced and all output goes to the console. If False, a log directory is produced as described by the logdir parameter. Defaults to False.

  • orchestrator (pyats.kleenex.bases.BringUpWorkerBase) – The bringup orchestrator to use. If not specified, then bringup is skipped.

  • skip_teardown (bool) – If True, topology is not torn down at the end of the run If False , topology is torn down at the end. Defaults to False.

  • no_mail (bool) – If True, no email is sent on failure. If False, an email is sent on failure Defaults to False.

  • commandline (bool) –

    If True, the object is being instantiated as part of a standalone tool and all arguments appear in the -help display.

    If False, the object is being instantiated programmatically and the user is expected to pass arguments to the constructor instead of via the command line. Defaults to False.

  • legacy (bool) –

    If True, the commandLine arguments use the legacy version such as -testbed_file

    If False, the commandLine arguments use the current version such as --testbed-file

  • parser (obj) – Provide a custom parser object

  • no_upload (bool) – If True, log archive uploading is disabled. If False, log archives are uploaded to TaaS Defaults to False.


CLI parser that does help processing and contains help/usage details from other CLI parsers contained by the module.




CLI parser for local module-scope arguments.




Bringup instance containing usage and help text.




Set to True then this class has been instantiated in commandline mode and the user has specified -h on the command line. Otherwise, defaults to False.



configure_local_parser(commandline, legacy)

Create parser for all local module-scope arguments except help.


configure logging Configure logging level based on the values from CLI args parsing and values passed to the method.



configure_parser(commandline, legacy)

Create a parser integrating help content with contained parsers.


Generate archive file for clean


Produce zipfile content for all results.

Return type

Binary representation of the zipfile content.


Lauch a dynamic topology if logical devices have been specified.


Execute bringup and / or clean behavior as required.

send_detailed_clean_email_report_to_user(resp=None, msg=None)

In case of error, send email to user with details.


Consolidate a parser’s usage and help text from contained objs.

Updates the help output of a provided parser. Automatically aggregates its current help information with those of the plugins. this allows an orchestrator’s xxxbringup -help to show all available arguments from every class along the chain.

class pyats.kleenex.worker.KleenexSteps(parent=None)

Bases: Steps

built-in __init__

instantiates the Steps class by creating an internal list that houses number of steps currently taken.


step index is the same as the list index of current step.


Creates a new Step instance and return it to the user scope. This is the main API called within the user realm to create and start new steps within the current scope.

Offset is used primarily with parallel call implementation. If specifying manually, ensure offset is large enough to enable additional steps per chid process.

  • (int) (offset) –

  • args (all arguments to this api propagates directly to Step) –

  • kwargs (all arguments to this api propagates directly to Step) –

Return type

new Step() instance.

class pyats.kleenex.worker.KleenexWorker(cleaner, device, reporter, logfile, queue, timeout, debug_=False)

Bases: ForkProcess

property result

Method to be run in sub-process; can be overridden in sub-class