pyATS Kleenex: Testbed Preparation, Clean & Finalization

Common errors

• ImportError: cannot import name 'Csr1000vPatterns'

  cause This error typically indicates that necessary Genie libraries or plugins, which pyATS components often rely on for device interaction and parsing, are missing or incorrectly installed after an upgrade.
  fix Ensure `genie` and its related `genie.libs.*` packages are correctly installed and up-to-date. A common fix is to reinstall or upgrade `pyats` and `genie` together: `pip install --upgrade pyats genie`.

• pyats.topology.loader is a required dependency for this command. 'interactive' source cannot be found.

  cause When using `pyats create testbed interactive` or other testbed generation tools, this error often occurs because the `pyats.contrib` package, which provides additional utilities and plugins, is not installed.
  fix Install the `pyats.contrib` package: `pip install pyats.contrib`. This provides essential components for certain pyATS CLI commands.

Warnings

• deprecated The standalone `kleenex` CLI command is deprecated. Users should now use the `pyats clean` CLI command for testbed preparation, cleaning, and finalization tasks.
  Fix: Migrate any scripts or workflows using `kleenex` to `pyats clean`. Refer to the pyATS documentation for the updated `pyats clean` command syntax and options.
• breaking pyATS and its components, including Kleenex, have specific Python version requirements. While PyPI lists `>=3.8`, current stable releases (e.g., 26.x) are typically incompatible with Python 3.11 and newer due to underlying dependencies.
  Fix: Ensure your environment uses a compatible Python version, typically Python 3.8 to 3.10. Always check the official pyATS documentation or release notes for the exact supported Python versions for your specific pyATS release.
• gotcha pyATS does not officially support Windows platforms without the use of Windows Subsystem for Linux (WSL). Running pyATS components directly on Windows may lead to unexpected behavior or errors.
  Fix: Develop and run pyATS applications on Linux, macOS, or within a WSL environment on Windows. Alternatively, use official pyATS Docker images which provide a pre-configured Linux environment.
• deprecated The `pyats.async` module was renamed to `pyats.async_` in pyATS v19.0 due to `async` becoming a reserved keyword in Python 3.7. Code written for older Python versions or pyATS releases may break.
  Fix: Update import statements from `import pyats.async` to `import pyats.async_` in any affected code.

Install

• pip install pyats.kleenex Install only Kleenex
• pip install 'pyats[kleenex]' Install pyATS with Kleenex extra

Imports

• KleenexFileLoader

  from pyats.clean.loader import KleenexFileLoader

  Used programmatically to load and process clean YAML files.

Quickstart

The quickstart demonstrates the general approach to using pyATS Kleenex functionality. While `pyats.kleenex` is the package, the primary interaction for cleaning devices is through the `pyats clean` command-line interface. This example shows how to conceptually set up a testbed and points to the CLI for execution.

# Create a simple testbed.yaml file
# devices:
#   csr1:
#     os: iosxe
#     type: router
#     connections:
#       cli:
#         protocol: ssh
#         ip: 10.0.0.1
#         credentials:
#           default:
#             username: cisco
#             password: cisco

# To run a clean operation using the pyats clean CLI command (recommended approach)
# Assuming you have a testbed.yaml and a clean.yaml defining the clean stages
# pyats clean <testbed.yaml> -clean_file <clean.yaml>

# Example of a simple clean.yaml content:
# clean:
#   csr1:
#     sections:
#       - 'power_cycle'
#       - 'install_image':
#           image: "/path/to/image.bin"

# Example Python snippet to initiate a clean operation (simplified conceptual view)
import os
from pyats import topology
from pyats.clean import clean_testbed

try:
    # Load your testbed
    testbed = topology.load(os.environ.get('TESTBED_YAML', 'testbed.yaml'))
    device = testbed.devices['csr1']

    # Example: Perform a clean operation on a device
    # This typically requires a separate clean.yaml file to define the stages
    # For a full execution, you would use pyats run job with a Python job file
    # that orchestrates the clean operation, or the pyats clean CLI command.

    # Programmatic invocation of clean (requires a clean_file argument in a real scenario)
    # The clean_testbed function typically takes a testbed object and a clean file path.
    print(f"Attempting to clean device: {device.name}")
    # This is a conceptual example, actual clean invocation is more complex
    # and often driven by EasyPy or the 'pyats clean' CLI.

    # For demonstration, we'll simulate a successful clean stage
    print(f"Device {device.name} is ready for cleaning operations.")
    print("To execute a full clean, use the 'pyats clean <testbed.yaml> -clean_file <clean.yaml>' CLI command.")

except Exception as e:
    print(f"An error occurred: {e}")