{"id":9205,"library":"pyats-kleenex","title":"pyATS Kleenex: Testbed Preparation, Clean & Finalization","description":"pyATS Kleenex is a crucial component of the larger pyATS ecosystem, specifically designed for testbed preparation, cleaning, and finalization tasks. It enables network engineers to restore network devices to a known good state before or after executing automated tests, ensuring consistent testing environments. As part of the pyATS framework, it maintains a regular release cadence, often monthly or bi-monthly, aligning with overall pyATS updates. The current version is 26.3.","status":"active","version":"26.3","language":"en","source_language":"en","source_url":"https://developer.cisco.com/docs/pyats/","tags":["pyats","network automation","test automation","network testing","device cleaning","testbed","cisco"],"install":[{"cmd":"pip install pyats.kleenex","lang":"bash","label":"Install only Kleenex"},{"cmd":"pip install 'pyats[kleenex]'","lang":"bash","label":"Install pyATS with Kleenex extra"}],"dependencies":[{"reason":"Kleenex is a sub-package and relies on the core pyATS framework for testbed management and execution.","package":"pyats","optional":false},{"reason":"Often used in conjunction with pyATS for advanced parsing and operations, though not a direct dependency of Kleenex itself, it's integral to a full pyATS testing environment.","package":"genie","optional":true}],"imports":[{"note":"Used programmatically to load and process clean YAML files.","symbol":"KleenexFileLoader","correct":"from pyats.clean.loader import KleenexFileLoader"}],"quickstart":{"code":"# Create a simple testbed.yaml file\n# devices:\n#   csr1:\n#     os: iosxe\n#     type: router\n#     connections:\n#       cli:\n#         protocol: ssh\n#         ip: 10.0.0.1\n#         credentials:\n#           default:\n#             username: cisco\n#             password: cisco\n\n# To run a clean operation using the pyats clean CLI command (recommended approach)\n# Assuming you have a testbed.yaml and a clean.yaml defining the clean stages\n# pyats clean <testbed.yaml> -clean_file <clean.yaml>\n\n# Example of a simple clean.yaml content:\n# clean:\n#   csr1:\n#     sections:\n#       - 'power_cycle'\n#       - 'install_image':\n#           image: \"/path/to/image.bin\"\n\n# Example Python snippet to initiate a clean operation (simplified conceptual view)\nimport os\nfrom pyats import topology\nfrom pyats.clean import clean_testbed\n\ntry:\n    # Load your testbed\n    testbed = topology.load(os.environ.get('TESTBED_YAML', 'testbed.yaml'))\n    device = testbed.devices['csr1']\n\n    # Example: Perform a clean operation on a device\n    # This typically requires a separate clean.yaml file to define the stages\n    # For a full execution, you would use pyats run job with a Python job file\n    # that orchestrates the clean operation, or the pyats clean CLI command.\n\n    # Programmatic invocation of clean (requires a clean_file argument in a real scenario)\n    # The clean_testbed function typically takes a testbed object and a clean file path.\n    print(f\"Attempting to clean device: {device.name}\")\n    # This is a conceptual example, actual clean invocation is more complex\n    # and often driven by EasyPy or the 'pyats clean' CLI.\n\n    # For demonstration, we'll simulate a successful clean stage\n    print(f\"Device {device.name} is ready for cleaning operations.\")\n    print(\"To execute a full clean, use the 'pyats clean <testbed.yaml> -clean_file <clean.yaml>' CLI command.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"The standalone `kleenex` CLI command is deprecated. Users should now use the `pyats clean` CLI command for testbed preparation, cleaning, and finalization tasks.","severity":"deprecated","affected_versions":"pyATS v20.9 and newer"},{"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.","message":"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.","severity":"breaking","affected_versions":"pyATS 20.x through 26.x (for Python 3.11+)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Update import statements from `import pyats.async` to `import pyats.async_` in any affected code.","message":"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.","severity":"deprecated","affected_versions":"pyATS v19.0 and newer when using Python 3.7+"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`.","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.","error":"ImportError: cannot import name 'Csr1000vPatterns'"},{"fix":"Install the `pyats.contrib` package: `pip install pyats.contrib`. This provides essential components for certain pyATS CLI commands.","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.","error":"pyats.topology.loader is a required dependency for this command. 'interactive' source cannot be found."}]}