{"id":7546,"library":"pyats-topology","title":"pyATS Topology","description":"pyATS Topology is a core component of the Cisco pyATS framework, providing robust objects and parsing capabilities for network testbed YAML definitions. It allows users to define network devices, links, and connections, enabling automated interaction with the network infrastructure for testing and operational tasks. The library is actively maintained and typically updated in sync with major pyATS framework releases, which occur quarterly or as needed.","status":"active","version":"26.3","language":"en","source_language":"en","source_url":"https://github.com/CiscoTestAutomation/pyats-topology","tags":["networking","testing","cisco","pyats","testbed","automation"],"install":[{"cmd":"pip install pyats-topology","lang":"bash","label":"Install pyats-topology"}],"dependencies":[{"reason":"Core pyATS framework functionality and context is required for full operation.","package":"pyats"},{"reason":"Required for parsing testbed YAML files.","package":"pyyaml"}],"imports":[{"symbol":"Testbed","correct":"from pyats.topology import Testbed"},{"note":"Commonly used for direct loading of testbed YAML files.","symbol":"loader","correct":"from pyats.topology import loader"}],"quickstart":{"code":"from pyats.topology import loader\nimport os\n\n# Create a dummy testbed YAML file for demonstration\ntestbed_yaml_content = \"\"\"\nname: MyTestbed\ndevices:\n  router1:\n    type: iosxe\n    os: iosxe\n    connections:\n      cli:\n        protocol: ssh\n        ip: 10.0.0.1\n        port: 22\n      rest:\n        protocol: rest\n        port: 443\n\"\"\"\n\ntestbed_file_path = 'my_testbed.yaml'\nwith open(testbed_file_path, 'w') as f:\n    f.write(testbed_yaml_content)\n\n# Load the testbed\ntestbed = loader.load(testbed_file_path)\n\n# Access devices and connections\ndevice = testbed.devices['router1']\nprint(f\"Testbed Name: {testbed.name}\")\nprint(f\"Device Name: {device.name}, Type: {device.type}, OS: {device.os}\")\nprint(f\"CLI Connection IP: {device.connections['cli'].ip}\")\n\n# Clean up the dummy file\nos.remove(testbed_file_path)\n","lang":"python","description":"Demonstrates loading a testbed YAML file and accessing a defined device and its connection details. This is the fundamental way to interact with network topology in pyATS."},"warnings":[{"fix":"Always review the official pyATS release notes and migration guides for your specific version upgrade. Update your testbed YAML files and Python scripts accordingly.","message":"Major pyATS framework upgrades (e.g., v20.x to v21.x) often introduce changes to the testbed YAML schema or object access patterns. For example, direct attribute access like `device.connections.cli` might require using dictionary-style access `device.connections['cli']` or vice-versa depending on the version.","severity":"breaking","affected_versions":"All major pyATS releases, typically quarterly."},{"fix":"Update your code to use `testbed.devices['device_name']` for accessing devices within a loaded testbed object.","message":"Older versions of pyATS Topology might have used methods like `testbed.find_device('name')` or `testbed.get_device_by_name('name')`. These methods are typically superseded by direct dictionary access `testbed.devices['name']` for consistency and performance.","severity":"deprecated","affected_versions":"Prior to pyATS v20.x, potentially earlier v21.x releases."},{"fix":"Always check for the existence of a connection protocol before attempting to access it, e.g., `if 'cli' in device.connections: ...` or use `.get('cli')` with a default value.","message":"The `connections` attribute of a `Device` object is a dictionary or an object that behaves like one. Accessing a non-existent connection (e.g., `device.connections['nonexistent_protocol']`) will raise a `KeyError`, which can be common during initial testbed development or debugging.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Verify the file path is absolutely correct, or ensure the file is in the expected relative location. Use `os.path.abspath()` for debugging if needed.","cause":"The specified testbed YAML file does not exist at the provided path, or the path is incorrect/relative and not found in the current working directory.","error":"pyats.topology.exceptions.TestbedError: Cannot find testbed file '/path/to/your_testbed.yaml'"},{"fix":"Double-check the `devices` section in your testbed YAML and ensure the device name matches exactly (case-sensitive). Use `print(testbed.devices.keys())` to see available device names.","cause":"You are trying to access a device `testbed.devices['my_device_name']` that is not defined in your testbed YAML file.","error":"KeyError: 'my_device_name'"},{"fix":"Ensure that the `connections` section for your device in the testbed YAML is correctly structured and contains the required protocol details (e.g., `cli` connection with `protocol`, `ip`, `port`). Also, confirm the pyATS runtime environment is set up to handle these connection types.","cause":"This usually happens when `device.connections['cli']` (or another connection) returns `None` because the connection object itself wasn't properly defined or loaded for the device, and you then try to call a method like `.connect()` on `None`.","error":"AttributeError: 'NoneType' object has no attribute 'connect'"}]}