{"id":7539,"library":"pyats-connections","title":"pyATS Connections","description":"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.","status":"active","version":"26.3","language":"en","source_language":"en","source_url":"https://developer.cisco.com/site/pyats/","tags":["networking","Cisco","automation","testing","network automation","pyATS","connection","Unicon","Genie"],"install":[{"cmd":"pip install pyats.connections","lang":"bash","label":"Install only pyATS Connections"},{"cmd":"pip install pyats[full]","lang":"bash","label":"Install full pyATS package (recommended)"}],"dependencies":[{"reason":"pyats.connections is a core sub-component of the pyATS framework.","package":"pyats"},{"reason":"This package automatically installs Unicon, which provides unified CLI connection capabilities for pyATS.","package":"unicon"},{"reason":"Requires Python version 3.8 or higher.","package":"Python","optional":false}],"imports":[{"note":"Used for loading testbed YAML files into a Python object.","symbol":"loader","correct":"from pyats.topology import loader"},{"note":"An alternative import for loading testbed YAML files, often preferred when using Genie libraries.","symbol":"load","correct":"from genie.testbed import load"},{"note":"Base class for creating custom device connection types within pyATS.","symbol":"BaseConnection","correct":"from pyats.connections.bases import BaseConnection"}],"quickstart":{"code":"import os\nfrom pyats.topology import loader\n\n# Create a dummy testbed.yaml file for demonstration\nwith open('testbed.yaml', 'w') as f:\n    f.write(\"\"\"\ndevices:\n  CSR1:\n    type: router\n    os: iosxe\n    credentials:\n      default:\n        username: '%ENV{PYATS_USER}'\n        password: '%ENV{PYATS_PASSWORD}'\n    connections:\n      cli:\n        protocol: ssh\n        ip: 127.0.0.1 # Use a dummy IP for local execution\n        port: 22\n\"\"\")\n\n# Set dummy environment variables for quickstart (replace with actual or secure method)\nos.environ['PYATS_USER'] = os.environ.get('PYATS_USER', 'devnetuser')\nos.environ['PYATS_PASSWORD'] = os.environ.get('PYATS_PASSWORD', 'Cisco123!')\n\ntry:\n    # Load the testbed from the YAML file\n    testbed = loader.load('testbed.yaml')\n\n    # Get a specific device from the testbed\n    device = testbed.devices['CSR1']\n\n    # Connect to the device (connection will fail with dummy IP, but demonstrates API)\n    print(f\"Attempting to connect to {device.name} at {device.connections['cli'].ip}...\")\n    device.connect(init_exec_params={'timeout': 5})\n    print(f\"Successfully connected to {device.name}.\")\n    \n    # Execute a command (will only reach here if connect succeeds)\n    output = device.execute('show version')\n    print(\"Show Version output:\\n\", output)\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Note: Connection to 127.0.0.1 will likely fail unless a mock device is running or IP is changed.\")\nfinally:\n    # Clean up the dummy testbed file\n    os.remove('testbed.yaml')","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or newer (e.g., Python 3.12 or 3.13 are supported by version 26.3).","message":"pyATS and its components, including pyats-connections, will cease support for Python 3.9 starting November 2025.","severity":"breaking","affected_versions":"<=25.7"},{"fix":"Always use spaces for indentation in YAML. Validate your testbed.yaml file thoroughly. Many issues stem from small formatting errors.","message":"Incorrect YAML syntax in testbed files (e.g., mixing tabs and spaces, wrong indentation) is a very common cause of failures.","severity":"gotcha","affected_versions":"All"},{"fix":"Run pyATS on Linux or macOS systems, or use Windows Subsystem for Linux (WSL).","message":"pyATS does not officially support Windows platforms.","severity":"gotcha","affected_versions":"All"},{"fix":"Utilize environment variables (e.g., `%ENV{VAR_NAME}`) or dedicated secret management systems within your testbed files.","message":"Hardcoding sensitive credentials (usernames, passwords) directly in testbed YAML files or scripts is a security risk.","severity":"gotcha","affected_versions":"All"}],"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 and name. Check YAML syntax (indentation, colons, etc.) carefully. Use a YAML linter if necessary.","cause":"The specified testbed YAML file is either missing, has incorrect path, or contains syntax errors.","error":"pyats.aetest.loader.LoadError: Unable to load testbed file: <file_path>"},{"fix":"Ensure your testbed YAML file defines a 'devices' block with at least one device. Example: `devices:\n  my_device:\n    ...`","cause":"The loaded testbed object does not contain a top-level 'devices' key, or it's empty.","error":"KeyError: 'devices' (when accessing testbed.devices)"},{"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.","cause":"The device is unreachable, network latency is too high, or the connection timeout is too short.","error":"An error occurred: connection to '...' timed out"},{"fix":"Double-check credentials in your testbed file or environment variables. Ensure the account is not locked on the device.","cause":"Incorrect username or password provided for the device.","error":"An error occurred: Authentication failed."}]}