pyATS Connections

26.3 · active · verified Thu Apr 16

pyATS Connections is a sub-component of the pyATS end-to-end testing ecosystem, specializing in handling device connections to various network devices. It provides top-level abstractions and interfaces for creating connection classes, supporting CLI, REST, and NETCONF protocols. This library is crucial for enabling scripts to interact with network devices within the pyATS framework. The current version is 26.3, and it is actively maintained by Cisco Systems Inc. with frequent releases.

Common errors

```
pyats.aetest.loader.LoadError: Unable to load testbed file: <file_path>
```
cause The specified testbed YAML file is either missing, has incorrect path, or contains syntax errors.

fix Verify the file path and name. Check YAML syntax (indentation, colons, etc.) carefully. Use a YAML linter if necessary.
```
KeyError: 'devices' (when accessing testbed.devices)
```
cause The loaded testbed object does not contain a top-level 'devices' key, or it's empty.

fix Ensure your testbed YAML file defines a 'devices' block with at least one device. Example: `devices: my_device: ...`
```
An error occurred: connection to '...' timed out
```
cause The device is unreachable, network latency is too high, or the connection timeout is too short.

fix Verify network connectivity to the device (ping/SSH manually). Increase the `connection_timeout` parameter in your testbed or during `device.connect()` call. Check firewall rules.
```
An error occurred: Authentication failed.
```
cause Incorrect username or password provided for the device.

fix Double-check credentials in your testbed file or environment variables. Ensure the account is not locked on the device.

Warnings

breaking pyATS and its components, including pyats-connections, will cease support for Python 3.9 starting November 2025.
Fix: Upgrade your Python environment to 3.10 or newer (e.g., Python 3.12 or 3.13 are supported by version 26.3).
gotcha Incorrect YAML syntax in testbed files (e.g., mixing tabs and spaces, wrong indentation) is a very common cause of failures.
Fix: Always use spaces for indentation in YAML. Validate your testbed.yaml file thoroughly. Many issues stem from small formatting errors.
gotcha pyATS does not officially support Windows platforms.
Fix: Run pyATS on Linux or macOS systems, or use Windows Subsystem for Linux (WSL).
gotcha Hardcoding sensitive credentials (usernames, passwords) directly in testbed YAML files or scripts is a security risk.
Fix: Utilize environment variables (e.g., `%ENV{VAR_NAME}`) or dedicated secret management systems within your testbed files.

Install

pip install pyats.connections Install only pyATS Connections
pip install pyats[full] Install full pyATS package (recommended)

Imports

loader
```
from pyats.topology import loader
```
Used for loading testbed YAML files into a Python object.
load
```
from genie.testbed import load
```
An alternative import for loading testbed YAML files, often preferred when using Genie libraries.
BaseConnection
```
from pyats.connections.bases import BaseConnection
```
Base class for creating custom device connection types within pyATS.

Quickstart

This quickstart demonstrates how to load a testbed definition from a YAML file, retrieve a device object, and attempt to establish a connection using `device.connect()`. It uses environment variables for credentials as a best practice. Note that the connection to a dummy IP (127.0.0.1) will fail in a real-world scenario without a reachable network device or mock device setup, but the code illustrates the API usage.

import os
from pyats.topology import loader

# Create a dummy testbed.yaml file for demonstration
with open('testbed.yaml', 'w') as f:
    f.write("""
devices:
  CSR1:
    type: router
    os: iosxe
    credentials:
      default:
        username: '%ENV{PYATS_USER}'
        password: '%ENV{PYATS_PASSWORD}'
    connections:
      cli:
        protocol: ssh
        ip: 127.0.0.1 # Use a dummy IP for local execution
        port: 22
""")

# Set dummy environment variables for quickstart (replace with actual or secure method)
os.environ['PYATS_USER'] = os.environ.get('PYATS_USER', 'devnetuser')
os.environ['PYATS_PASSWORD'] = os.environ.get('PYATS_PASSWORD', 'Cisco123!')

try:
    # Load the testbed from the YAML file
    testbed = loader.load('testbed.yaml')

    # Get a specific device from the testbed
    device = testbed.devices['CSR1']

    # Connect to the device (connection will fail with dummy IP, but demonstrates API)
    print(f"Attempting to connect to {device.name} at {device.connections['cli'].ip}...")
    device.connect(init_exec_params={'timeout': 5})
    print(f"Successfully connected to {device.name}.")
    
    # Execute a command (will only reach here if connect succeeds)
    output = device.execute('show version')
    print("Show Version output:\n", output)

except Exception as e:
    print(f"An error occurred: {e}")
    print("Note: Connection to 127.0.0.1 will likely fail unless a mock device is running or IP is changed.")
finally:
    # Clean up the dummy testbed file
    os.remove('testbed.yaml')

view raw JSON →