pyATS Topology

26.3 · active · verified Thu Apr 16

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.

Common errors

```
pyats.topology.exceptions.TestbedError: Cannot find testbed file '/path/to/your_testbed.yaml'
```
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.

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.
```
KeyError: 'my_device_name'
```
cause You are trying to access a device `testbed.devices['my_device_name']` that is not defined in your testbed YAML file.

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.
```
AttributeError: 'NoneType' object has no attribute 'connect'
```
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`.

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.

Warnings

breaking 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.
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.
deprecated 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.
Fix: Update your code to use `testbed.devices['device_name']` for accessing devices within a loaded testbed object.
gotcha 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.
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.

Install

pip install pyats-topology Install pyats-topology

Imports

Testbed
```
from pyats.topology import Testbed
```
loader
```
from pyats.topology import loader
```
Commonly used for direct loading of testbed YAML files.

Quickstart

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.

from pyats.topology import loader
import os

# Create a dummy testbed YAML file for demonstration
testbed_yaml_content = """
name: MyTestbed
devices:
  router1:
    type: iosxe
    os: iosxe
    connections:
      cli:
        protocol: ssh
        ip: 10.0.0.1
        port: 22
      rest:
        protocol: rest
        port: 443
"""

testbed_file_path = 'my_testbed.yaml'
with open(testbed_file_path, 'w') as f:
    f.write(testbed_yaml_content)

# Load the testbed
testbed = loader.load(testbed_file_path)

# Access devices and connections
device = testbed.devices['router1']
print(f"Testbed Name: {testbed.name}")
print(f"Device Name: {device.name}, Type: {device.type}, OS: {device.os}")
print(f"CLI Connection IP: {device.connections['cli'].ip}")

# Clean up the dummy file
os.remove(testbed_file_path)

view raw JSON →