Genie Libs SDK: Triggers and Verifications

Common errors

• ImportError: cannot import name 'SomePatternClass' from 'unicon.plugins.iosxe.csr1000v.patterns'

  cause A mismatch in versions between pyATS/Genie core packages and specific Unicon plugins, or a refactoring/renaming of internal pattern classes in newer releases.
  fix Ensure all `pyats`, `genie`, and `unicon` packages and their respective plugins (`genie.libs.*`, `unicon.plugins.*`) are at compatible versions. A complete upgrade via `pip install --upgrade pyats genie --no-cache-dir` can often resolve this.

• TypeError: 'NoneType' object is not iterable

  cause This generic Python error can occur when a `testbed.parse()` or a similar operation within Genie fails to retrieve data (e.g., device not connected, command failed) and returns `None`, which is then attempted to be iterated over or accessed like a dictionary.
  fix Implement robust error handling around device interactions. Verify device connectivity (`device.is_connected()`) and check the return values of parsing/learning APIs before proceeding with data manipulation.

• Exception: Terminal server information is not provided in the testbed YAML file for device '<device_name>'\nUnable to clear the console port line

  cause Attempting to use a utility like `execute_clear_line` which requires `terminal_server` details in the testbed YAML, but these details are missing for the specified device.
  fix Add the `peripherals.terminal_server` section to your device entry in the testbed YAML, specifying the terminal server details (e.g., `terminal_server: { my_term_server: [ 2001 ] }`).

Warnings

• breaking Python 3.6 support has been deprecated and removed in recent pyATS/Genie versions (e.g., v22.4). Users on Python 3.6 will encounter errors and must upgrade to Python 3.7+.
  Fix: Upgrade your Python environment to version 3.7 or newer.
• gotcha When upgrading pyATS/Genie, users might encounter `ImportError` for specific patterns (e.g., `cannot import name 'Csr1000vPatterns'`). This often indicates a version mismatch between core pyATS/Genie and its plugins (like Unicon) or internal refactoring.
  Fix: Perform a clean reinstallation or upgrade all `pyats` and `genie` related packages simultaneously: `pip install --upgrade pyats genie genie.libs.sdk genie.libs.parser genie.libs.ops unicon` (and other specific plugins you use). Consider using a virtual environment.
• gotcha Using `genie.libs.sdk` (and the broader Genie/pyATS framework) with multi-threaded applications like certain Nornir versions (e.g., Nornir 2.20 with >1 worker) has historically led to issues, particularly with the abstraction library loading layer.
  Fix: Ensure you are on the latest versions of `genie.libs.sdk` and `pyATS`, as these issues have reportedly been fixed. If problems persist, consider reducing worker count or investigating process-based parallelism if supported by the integrating library.

Install

• pip install genie Install Genie (includes genie.libs.sdk)
• pip install --upgrade genie.libs.sdk Upgrade genie.libs.sdk directly

Imports

• TriggerReload

  from genie.libs.sdk.triggers.template.trigger_reload import TriggerReload

• TriggerShutNoShut

  from genie.libs.sdk.triggers.interface import TriggerShutNoShut

• gRun

  from genie.harness.main import gRun

  gRun is part of genie.harness, used to execute triggers and verifications with a testbed.
• load

  from genie.testbed import load

  Used to load pyATS testbed YAML files.

Quickstart

This quickstart demonstrates how to load a testbed and execute a pre-built 'Trigger' from `genie.libs.sdk` using the `gRun` function from `genie.harness.main`. It includes a minimal `testbed.yaml` example and uses `TriggerReload` as a representative trigger. For actual execution, ensure a reachable network device configured in the testbed and necessary environment variables for credentials.

import os
from genie.testbed import load
from genie.harness.main import gRun
from genie.libs.sdk.triggers.template.trigger_reload import TriggerReload

# Create a dummy testbed.yaml for demonstration purposes
# In a real scenario, this would be a network device testbed file.
# Ensure your environment variables are set for device credentials.
# E.g., export PYATS_USERNAME=admin, export PYATS_PASSWORD=Cisco123
testbed_content = '''
devices:
  R1:
    os: iosxe
    type: router
    connections:
      cli:
        protocol: ssh
        ip: 127.0.0.1
        port: 2222 # Use a mock SSH server or a reachable device
    credentials:
      default:
        username: ${PYATS_USERNAME}
        password: ${PYATS_PASSWORD}
'''

with open('testbed.yaml', 'w') as f:
    f.write(testbed_content)

# Set dummy environment variables if not already set
os.environ.setdefault('PYATS_USERNAME', 'mockuser')
os.environ.setdefault('PYATS_PASSWORD', 'mockpass')

def main():
    # Load the testbed from the YAML file
    testbed = load('testbed.yaml')

    # Define the trigger to run
    # In a real scenario, this would target a specific device and its OS
    # For this example, we assume R1 is the 'uut' (unit under test) by default for TriggerReload
    # A custom datafile might be needed for specific trigger parameters or device mappings
    
    # Execute the trigger using gRun. 
    # The TriggerReload acts as a placeholder for demonstration.
    # For a true reload, 'R1' would need to be a real device and reachable.
    try:
        print("\n--- Running TriggerReload on R1 ---")
        gRun(testbed=testbed, trigger_uids=["TriggerReload"], trigger_datafile="""
extends: "%CALLABLE{genie.libs.sdk.genie_yamls.datafile(trigger)}"
TriggerReload:
  devices:
    R1:
      command: 'reload'
        """
        )
        print("TriggerReload completed (or skipped if no real device was found).")
    except Exception as e:
        print(f"An error occurred during gRun: {e}")

if __name__ == '__main__':
    main()