Genie Libs Clean

26.3 · active · verified Thu Apr 16

Genie Libs Clean (version 26.3) is a component of the CiscoTestAutomation's Genie framework, providing functionalities for cleaning network devices. It automates tasks such as removing configurations, upgrading/downgrading OS, and reloading devices to prepare them for new test runs or restore them to a known state. It is actively maintained as part of the broader Genie/pyATS ecosystem, with a release cadence tied to the pyATS framework.

Common errors

```
ImportError: cannot import name 'Clean' from 'genie.libs.clean'
```
cause The `Clean` class is located in a submodule `clean.py`, not directly under `genie.libs.clean`.

fix Change the import statement to `from genie.libs.clean.clean import Clean`.
```
pyats.exceptions.SchemaError: Key 'clean' must be of type 'dict'
```
cause The YAML structure provided to the `Clean` object (via `clean_info`) is incorrect or malformed, often due to improper indentation or invalid top-level keys.

fix Review your `clean_info` YAML. The top-level key should typically be `clean`, and its value should be a dictionary defining the clean process. Ensure correct YAML syntax and indentation.
```
Error: 'reload' stage failed for device dut1
```
cause A specific stage in the clean process failed, often due to underlying device connectivity issues, incorrect commands executed by Genie, or unexpected device state.

fix Inspect the pyATS run logs for detailed output from the failing stage. This often reveals the exact command that failed, network errors, or device-specific error messages. Verify device connectivity and the validity of the clean stage for the target device.

Warnings

breaking Version compatibility between `pyATS`, `genie`, and `genie-libs-clean` is critical. Mismatched major versions can lead to `ImportError`s, `AttributeError`s, or unexpected behavior.
Fix: Always install `pyats` and `genie` packages from the same release train (e.g., `pip install pyats==<X> genie==<X> genie.libs.clean==<X>`). Refer to Cisco's official pyATS/Genie documentation for version compatibility matrices.
gotcha The `Clean` process relies heavily on specific device configurations, parsers, and operating system support within the pyATS testbed and Genie libraries. Misconfigured devices, unsupported OS versions, or missing custom parsers will lead to clean stage failures.
Fix: Thoroughly review your pyATS testbed file, ensure the device OS is correctly specified, and verify that the required Genie parsers and device-specific functionalities are available for your device and OS version. Check detailed logs for underlying errors during clean execution.
gotcha The `clean_info` YAML structure is highly schema-driven. Incorrect indentation, misspelled stage names, or invalid arguments within the YAML definition will cause the `Clean` object to fail during initialization or execution.
Fix: Always validate your clean YAML against the expected schema provided in the Genie documentation. Pay close attention to stage names (e.g., `install_os`, `apply_configuration`, `reload`) and their required arguments.

Install

pip install genie-libs-clean Install latest version

Imports

Clean
wrong:
```
from genie.libs.clean import Clean
```
correct:
```
from genie.libs.clean.clean import Clean
```
The `Clean` class resides in the `clean.py` submodule, not directly under `genie.libs.clean`.

Quickstart

This quickstart demonstrates how to instantiate and prepare a `Clean` object with a device and a basic clean YAML process. It shows the correct import and initialization. Note that `clean_obj.go()` is commented out to prevent actual device interaction in a basic runnable example; in a real environment, it would execute the defined clean stages on the device.

import os
import yaml
from pyats.topology import Device
from genie.libs.clean.clean import Clean

# --- This example uses a mock device for demonstration ---
# In a real scenario, `device` would come from a pyATS testbed file
# and `device.connect()` would establish a connection.

device = Device(name="dut1", os="iosxe", connections={'cli': {'protocol': 'ssh'}})
print(f"Created mock device: {device.name}")

# Define a simple clean YAML process. In a real test, this
# would often be loaded from a file or generated dynamically.
clean_yaml_process = """
clean:
    order:
        - stage: clear_logging
        - stage: reload
"""

# Instantiate the Clean object with the device and the clean definition
try:
    clean_obj = Clean(device=device, clean_info=yaml.safe_load(clean_yaml_process))
    print("Clean object instantiated successfully.")

    # Execute the clean process.
    # IMPORTANT: clean_obj.go() would execute actual commands on the device.
    # For this quickstart, we are simulating its call.
    # To run for real, ensure device is connected and testbed setup correctly.
    print("Simulating clean process execution (clean_obj.go() is commented out).")
    # clean_obj.go()

    print("Quickstart demonstration completed.")

except Exception as e:
    print(f"An error occurred during quickstart: {e}")
    print("Ensure all dependencies (pyATS, genie) are installed and versions are compatible.")

view raw JSON →