{"id":8191,"library":"genie-libs-sdk","title":"Genie Libs SDK: Triggers and Verifications","description":"Genie.libs.sdk is a sub-component of the Cisco pyATS and Genie framework, providing a rich library of pre-built 'Triggers' and 'Verifications'. These are reusable test cases and automation actions designed to facilitate rapid development, simplify test automation, and validate network device states. The library is actively maintained by Cisco Systems Inc., with frequent releases aligning with the broader pyATS/Genie ecosystem (typically monthly or bi-monthly major versions, currently at 26.3).","status":"active","version":"26.3","language":"en","source_language":"en","source_url":"https://github.com/CiscoTestAutomation/genielibs","tags":["network automation","pyats","genie","cisco","testing","triggers","verifications"],"install":[{"cmd":"pip install genie","lang":"bash","label":"Install Genie (includes genie.libs.sdk)"},{"cmd":"pip install --upgrade genie.libs.sdk","lang":"bash","label":"Upgrade genie.libs.sdk directly"}],"dependencies":[{"reason":"Genie.libs.sdk is a sub-component of the Genie framework and requires the core 'genie' package for full functionality and the pyATS test harness.","package":"genie"},{"reason":"Genie is built on top of the pyATS framework, which provides the core test automation infrastructure (testbed management, connections, logging).","package":"pyats"},{"reason":"Used by pyATS and Genie for device connectivity, interaction, and state machine handling.","package":"unicon","optional":true},{"reason":"Required for parsing YAML testbed and data files.","package":"ruamel.yaml","optional":true}],"imports":[{"symbol":"TriggerReload","correct":"from genie.libs.sdk.triggers.template.trigger_reload import TriggerReload"},{"symbol":"TriggerShutNoShut","correct":"from genie.libs.sdk.triggers.interface import TriggerShutNoShut"},{"note":"gRun is part of genie.harness, used to execute triggers and verifications with a testbed.","symbol":"gRun","correct":"from genie.harness.main import gRun"},{"note":"Used to load pyATS testbed YAML files.","symbol":"load","correct":"from genie.testbed import load"}],"quickstart":{"code":"import os\nfrom genie.testbed import load\nfrom genie.harness.main import gRun\nfrom genie.libs.sdk.triggers.template.trigger_reload import TriggerReload\n\n# Create a dummy testbed.yaml for demonstration purposes\n# In a real scenario, this would be a network device testbed file.\n# Ensure your environment variables are set for device credentials.\n# E.g., export PYATS_USERNAME=admin, export PYATS_PASSWORD=Cisco123\ntestbed_content = '''\ndevices:\n  R1:\n    os: iosxe\n    type: router\n    connections:\n      cli:\n        protocol: ssh\n        ip: 127.0.0.1\n        port: 2222 # Use a mock SSH server or a reachable device\n    credentials:\n      default:\n        username: ${PYATS_USERNAME}\n        password: ${PYATS_PASSWORD}\n'''\n\nwith open('testbed.yaml', 'w') as f:\n    f.write(testbed_content)\n\n# Set dummy environment variables if not already set\nos.environ.setdefault('PYATS_USERNAME', 'mockuser')\nos.environ.setdefault('PYATS_PASSWORD', 'mockpass')\n\ndef main():\n    # Load the testbed from the YAML file\n    testbed = load('testbed.yaml')\n\n    # Define the trigger to run\n    # In a real scenario, this would target a specific device and its OS\n    # For this example, we assume R1 is the 'uut' (unit under test) by default for TriggerReload\n    # A custom datafile might be needed for specific trigger parameters or device mappings\n    \n    # Execute the trigger using gRun. \n    # The TriggerReload acts as a placeholder for demonstration.\n    # For a true reload, 'R1' would need to be a real device and reachable.\n    try:\n        print(\"\\n--- Running TriggerReload on R1 ---\")\n        gRun(testbed=testbed, trigger_uids=[\"TriggerReload\"], trigger_datafile=\"\"\"\nextends: \"%CALLABLE{genie.libs.sdk.genie_yamls.datafile(trigger)}\"\nTriggerReload:\n  devices:\n    R1:\n      command: 'reload'\n        \"\"\"\n        )\n        print(\"TriggerReload completed (or skipped if no real device was found).\")\n    except Exception as e:\n        print(f\"An error occurred during gRun: {e}\")\n\nif __name__ == '__main__':\n    main()","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to version 3.7 or newer.","message":"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+.","severity":"breaking","affected_versions":"<= 22.3 (support ends), >= 22.4 (unsupported)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions during upgrades"},{"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.","message":"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.","severity":"gotcha","affected_versions":"Older versions when used with multi-threaded runners"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"ImportError: cannot import name 'SomePatternClass' from 'unicon.plugins.iosxe.csr1000v.patterns'"},{"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.","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.","error":"TypeError: 'NoneType' object is not iterable"},{"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 ] }`).","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.","error":"Exception: Terminal server information is not provided in the testbed YAML file for device '<device_name>'\\nUnable to clear the console port line"}]}