pyATS

https://github.com/suhaibqr/salrabee-pts
Admin
pyATS is a free Python-based test framework by Cisco designed for network test automation,...
Tokens:420,485
Snippets:3,270
Trust Score:2.9
License:Apache-2.0
Update:10 months ago
Show doc for...
Tokens:
Raw
### Install pyATS Framework

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/getting_started/index.md

Installs the pyATS core framework and various optional packages for enhanced functionality. The recommended installation includes the pyATS Library/Genie for network automation.

```bash
pip install pyats
pip install pyats[library]
pip install pyats[robot]
pip install pyats[template]
pip install pyats[full]
```

--------------------------------

### Installing pyATS Examples and Templates Packages via pip

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/changelog/2015/june.md

Shows how to install the 'ats.examples' and 'ats.templates' PyPI packages using pip. These packages provide examples and templates for pyATS, installed under the root instance folder as 'examples/' and 'templates/'.

```bash
bash$ pip install ats.examples
bash$ pip install ats.templates
```

--------------------------------

### Load Testbed and Execute Commands with pyATS

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/getting_started/index.md

Demonstrates loading a YAML testbed file, accessing devices, establishing connections, and executing operational and configuration commands using pyATS Python APIs. It showcases handling multiple connections to a single device.

```python
# loader our newly minted testbed file
from pyats.topology import loader
testbed = loader.load('ios_testbed.yaml')

# access the devices
print(testbed.devices)
ios_1 = testbed.devices['ios-1']
ios_2 = testbed.devices['ios-2']

# find links from one device to another
for link in ios_1.find_links(ios_2):
    print(repr(link))

# establish basic connectivity
ios_1.connect()

# issue commands
print(ios_1.execute('show version'))
ios_1.configure('''
    interface GigabitEthernet0/0
        ip address 10.10.10.1 255.255.255.0
''')

# establish multiple, simultaneous connections
ios_2.connect(alias = 'console', via = 'a')
ios_2.connect(alias = 'vty_1', via = 'vty')

# issue commands through each connection separately
print(ios_2.vty_1.execute('show running'))
ios_2.console.execute('reload')
```

--------------------------------

### Python: Start Common Setup Section in Test Script

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/apidoc/aereport/index.md

Initiates a common setup section within a test script context. It requires parameters like log file path and optionally accepts client host and process ID. If the mode is strict, it raises an exception on issues; otherwise, it returns None.

```python
def start_commonsetup(kwargs):
    # Make sure the current context is a testscript (TestScript).
    # If yes, add a section to the list commonsetup
    # And push this section to the context stack.
    pass

# Example usage:
aerunner.start_commonsetup(logfilepath='/tmp/logfile.log',
                            xref={'file':'/init/info/file',
                                     'line':'30'})

```

--------------------------------

### YAML Configuration: PyATS Plugin Setup

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/easypy/plugins.md

This YAML snippet demonstrates how to configure the Hello World plugin within a PyATS environment. It specifies the plugin name and can include custom arguments if needed, though this example is a placeholder.

```yaml
# Example
# -------
#
# plugins:
#   HelloWorld:
#     # custom arguments can be passed here
#     # e.g. my_arg: 'some_value'

```

--------------------------------

### pyATS AEtest Structured Testscript Example

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/getting_started/index.md

An example of a pyATS AEtest testscript demonstrating structured testing. It includes common setup for device connection and topology checks, a parameterized ping testcase with looping and error handling, and common cleanup for disconnecting devices. It also shows how to parse testbed files using argparse.

```Python
from pyats import aetest
import re
import logging

logger = logging.getLogger(__name__)

class CommonSetup(aetest.CommonSetup):

    @aetest.subsection
    def check_topology(self,
                       testbed,
                       ios1_name = 'ios-1',
                       ios2_name = 'ios-2'):
        ios1 = testbed.devices[ios1_name]
        ios2 = testbed.devices[ios2_name]

        self.parent.parameters.update(ios1 = ios1, ios2 = ios2)

        links = ios1.find_links(ios2)

        assert len(links) >= 1, 'require one link between ios1 and ios2'


    @aetest.subsection
    def establish_connections(self, steps, ios1, ios2):
        with steps.start('Connecting to %s' % ios1.name):
            ios1.connect()

        with steps.start('Connecting to %s' % ios2.name):
            ios2.connect()

@aetest.loop(device=('ios1', 'ios2'))
class PingTestcase(aetest.Testcase):

    @aetest.test.loop(destination=('10.10.10.1', '10.10.10.2'))
    def ping(self, device, destination):
        try:
            result = self.parameters[device].ping(destination)

        except Exception as e:
            self.failed('Ping {} from device {} failed with error: {}'.format(
                                destination,
                                device,
                                str(e),
                            ),
                        goto = ['exit'])
        else:
            match = re.search(r'Success rate is (?P<rate>\d+) percent', result)
            success_rate = match.group('rate')

            logger.info('Ping {} with success rate of {}%'.format(
                                        destination,
                                        success_rate,
                                    )
                               )

class CommonCleanup(aetest.CommonCleanup):

    @aetest.subsection
    def disconnect(self, steps, ios1, ios2):
        with steps.start('Disconnecting from %s' % ios1.name):
            ios1.disconnect()

        with steps.start('Disconnecting from %s' % ios2.name):
            ios2.disconnect()

if __name__ == '__main__':
    import argparse
    from pyats.topology import loader

    parser = argparse.ArgumentParser()
    parser.add_argument('--testbed', dest = 'testbed',
                        type = loader.load)

    args, unknown = parser.parse_known_args()

    aetest.main(**vars(args))
```

--------------------------------

### Configure and Start Test Execution with salrabee-pts

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/aereport/index.md

This snippet shows how to configure the client with paths and versions, then initiate a job execution. It also demonstrates starting and stopping test scripts and common setup procedures, including logging.

```python
clt.set_ats(path= '/aPath/',
                 versions= '5.3.0',
                 packages=[('aPackage','1.0')])
clt.start_jobexecution()
clt.start_testscript(logfilepath='/tmp/logfile.log')
clt.start_commonsetup(logfilepath='/tmp/logfile.log')
clt.stop_commonsetup()
```

--------------------------------

### Pre Service Method Example - Python

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/connections/wrapper.md

Shows the `pre_service` method, executed before `call_service`. This method is intended for any setup or preparatory actions required before the main service logic runs. The example logs informational messages including the service name and any arguments passed.

```python
def pre_service(self, *args, **kwargs) -> None:
  logger.info(f"Running pre_service on {self.service_name}")
  logger.info(f"{self.service_name} args: {args} kwargs: {kwargs}")
```

--------------------------------

### Complete PyATS Test Execution Example (Python)

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/aereport/index.md

A comprehensive example showcasing the initialization and interaction with AEClient and AERunner for a test execution. It includes starting the server, connecting the client, and setting various parameters for a test suite.

```python
import time
import subprocess
from pyats.aereport.aerunner import AERunner
from pyats.aereport.client import AEClient svrpid, svrport, servername = AERunner.start_server(logsdir='/tmp/ttt/',
                                             logfilename='logfile.log')
clt = AEClient(port=svrport,servername=servername)
clt.connect()
clt.start_testsuite(**{'jobname':'job1',
                           'submitter':'anUser'})
clt.add_ats_packages(packages=[('Csccon', '1.1'), ('aetest', '1.2')])
args = {'dnsname':'aDnsName',
'post':{'status':'aStatus',
'cmd':'aCmd'},
        'bgPost':False,
        'attributes':[{'name':'aName',
'value':'aSuperValue'},
                      {'name':'secondName',
'value':'superValue2'}]}
clt.set_tims(**args)
clt.start_clean()
time.sleep(0.4)
clt.set_initinfo(script='aScript',
                      pargs='pargs')
clt.set_runinfo(comment='aComment')
clt.stop_clean()
clt.set_initinfo(host='aHost',
                        params={'cli':'aCli',
'errors':'10',
'reason':'aReason',
'type':'aReportType',
'sem':{'alignment':True,
'traceback':False},
                           )

```

--------------------------------

### SampleClass Example Usage

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/apidoc/aereport/index.md

Demonstrates the instantiation of AEReport and TestSuite classes, which are based on AEReportElement. This provides a basic example of how to use these components.

```python
class SampleClass(AEReportElement):
    """
    Bases: [`AEReportElement`](pyats.aereport.toplevel.md#pyats.aereport.toplevel.aereportelement.AEReportElement)

    AEReportElement is the base class for all schema elements.
    It implements a default functionality for generating xml.
    It also defines common attributes and default values.

    ```default
    Class based on the following schema definition
    <some xml>
    ```

    ### Examples

    ```pycon
    >>> aer = AEReport()
    >>> ts1 = TestSuite()
    ```
    """
    pass
```

--------------------------------

### Install pyATS Test Framework

Source: https://context7.com/suhaibqr/salrabee-pts/llms.txt

Installs the pyATS framework and its individual components using pip. Includes commands for full installation, specific modules, and upgrading existing installations.

```bash
# Install full pyATS package
pip install pyats[full]

# Install individual components
pip install pyats.aetest
pip install pyats.topology
pip install pyats.easypy

# Upgrade existing installation
pip install pyats.aetest --upgrade
```

--------------------------------

### Remove pyATS Templates and Examples Folders

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/changelog/2015/june.md

Before upgrading pyATS, it is recommended to remove the existing 'examples' and 'templates' folders. This ensures that new templates and examples, which will be installed via pip, are properly integrated. Back up any custom modifications before deletion.

```bash
bash$ cd $VIRTUAL_ENV
# note - this will delete it. If you modified examples/templates, 
# make sure to make local backups
bash$ rm -rf templates examples
```

--------------------------------

### AEtest Testcase Parameter Propagation Example

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/changelog/2015/june.md

Demonstrates how updates to the 'parameters' dictionary within the setup phase of an AEtest Testcase are reflected in the TestScript's parameters. This ensures that data defined in setup is accessible in test methods.

```python
# Example
# -------
#
#   parameter dict updates reflects in TestScript

from ats import aetest

parameters = {}

class Testcase(aetest.Testcase):

    @aetest.setup
    def setup(self):
        # add new stuff to parameters
        parameters['new'] = 1

        # propagates to parameters
        assert 'new' in self.parameters

    @aetest.test
    def test(self, new):
        # and useable
        assert new == 1
```

--------------------------------

### Start Job Execution in Python

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/apidoc/aereport/index.md

Starts a JobExecution context within a TestSuite context. This function takes clienthost and pid as parameters. It does not return any value.

```python
>>> # Be inside testsuite context
>>> aerunner.start_jobexecution()
```

--------------------------------

### Pcall Class Initialization and Execution Example

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/async/pcall.md

Illustrates how to instantiate and use the Pcall class to execute a function (`add`) in parallel across multiple processes. It demonstrates starting the processes, waiting for their completion using `join()`, and accessing the collected results.

```python
from pyats.async_ import Pcall

# define a function to be called in
def add(x, y):
    return x + y

# create a Pcall object
p = Pcall(add, x = (1, 2, 3), y = (4, 5, 6))

# start all child processes
p.start()

# wait for everything to finish
p.join()

# collect results
results = p.results
```

--------------------------------

### PyATS AEtest SetupSection Class

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/apidoc/aetest/index.md

Represents a setup section within a Testcase. It wraps a function/method marked with @setup.

```APIDOC
## class pyats.aetest.sections.SetupSection

### Description
SetupSection class. Testcase setup section. Wrapper class for @setup marked Testcase function/method. Normally not seen/used directly by the user.

### Bases
[`TestcaseSection`](#pyats.aetest.sections.TestcaseSection)

### `__init__`
Initializes the TestFunction by storing the given function (obj method).

### Parameters
- **function** (function)
- **uid** (str)
- **args/kwargs** (arguments passed to parent TestItem._init_)
```

--------------------------------

### Start XML RPC Server

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/apidoc/aereport/index.md

Starts the XML RPC server, ensuring a logs directory exists and obtaining a free port. It polls for a 'ready' signal from the server process and returns its connection information (pid, hostname, port). Returns 0, 0, 0 if the server fails to start.

```python
# Example usage (assuming aerunner is imported and configured)
# server_info = aerunner.start_server(logsdir='/path/to/logs', logfilename='report.log')
```

--------------------------------

### Create and Configure Device Objects in Python

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/topology/concept.md

Demonstrates the creation and configuration of Device objects, including setting aliases, operating systems, and adding interfaces. It also shows how to associate devices with a testbed and iterate through a device's interfaces.

```python
# Example
# ------- 
# 
#   creating device objects

from pyats.topology import Testbed, Device, Interface

# create some interfaces for adding to devices
intf_a = Interface('Eth1/1', 'ethernet')
intf_b = Interface('Eth2/1', 'ethernet')

# creating a testbed for demonstration's sake
testbed = Testbed('exampleTestbed')

# creating an empty device
device_a = Device('emptyDevice')

# giving device a different alias
device_a.alias = 'newAlias'

# set device os
device_a.os = 'iosxe'

# creating a device with connection parameters
device_b = Device('deviceThatCanBeConnected',
                  os='iosxe',
                  connections={
                      'mgmt': {
                          'protocol': 'telnet',
                          'ip': '1.1.1.1'
                      },
                  })

# adding interface to device objects
device_b.add_interface(intf_a)

# creating device with interfaces
device_c = Device('deviceCreatedWithIntfs',
                  os='iosxe',
                  interfaces = [intf_b])

# associating a device to a testbed can be done either by performing
# a testbed.add_device() call, or directly by setting a device's testbed
# attribute, which automatically performs the parent add_device() call
device_c.testbed = testbed

# checking if an intf object belongs to a device can be done
# using the in operator
assert intf_b in device_c

# loop through interfaces on a device
for intf in device_c:
    print(intf.name)

```

--------------------------------

### Create and Manipulate Testbed Objects (Python)

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/topology/concept.md

Demonstrates the creation of Testbed objects, including empty testbeds, testbeds with aliases, and testbeds initialized with devices. It also shows how to add and remove devices, squeeze the testbed, and initiate connections.

```python
from pyats.topology import Testbed, Device

# create some device objects for demonstration's sake
device_a = Device('A')
device_b = Device('B')
device_c = Device('C')
device_d = Device('D')

# creating an empty testbed
testbed_a = Testbed(name = 'emptyTestbed')

# creating a testbed with an alias
testbed_b = Testbed(name = 'myTestbed',
                    alias = 'yetAnotherTestbed')

# creating a testbed with devices
testbed_c = Testbed(name = 'testbedWithDevicesFromStart',
                    devices = [device_a, device_b])

# adding devices into testbeds
testbed_d = Testbed(name = 'testbedToReceiveDevices')
testbed_d.add_device(device_c)

# removing devices from a testbed
testbed_e = Testbed(name = 'testbedToRemoveDevices',
                    devices = [device_d])
testbed_e.remove_device(device_d)

# squeezing a testbed to keep only wanted devices
testbed_e = Testbed(name = 'testbedToSqueeze',
                    devices = [device_a, device_b, device_c])
testbed_e.squeeze(device_b.name, device_c.name)

# connect to all devices in this testbed in parallel
testbed_e.connect()

# connect to specific devices in this testbed in parallel

```

--------------------------------

### Python pyATS Job File Example

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/getting_started/index.md

A simple Python job file for pyATS that uses the 'run' API to execute a specified test script. The 'main' function is the entry point for the job. When 'run()' is called, the script is executed as a child process.

```python
from pyats.easypy import run

def main():

    # run api launches a testscript as an individual task.
    run('connectivity_check.py')

```

--------------------------------

### Create and Use Connection Pool with Multiprocessing

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/getting_started/index.md

This snippet shows how to initialize a connection pool with a specified size and then use it within a multiprocessing context. Each process is allocated a connection from the pool, and the `sleep` function demonstrates executing a command through the pool.

```Python
ios_2.start_pool(alias = 'pool', size = 2)

def sleep(seconds):
    ios_2.pool.execute('sleep %s' % seconds)

import multiprocessing
p1 = multiprocessing.Process(target=sleep, args = (10, ))
p2 = multiprocessing.Process(target=sleep, args = (10, ))
p3 = multiprocessing.Process(target=sleep, args = (10, ))
p1.start(); p2.start(); p3.start()
p1.join(); p2.join(); p3.join()
```

--------------------------------

### Define Network Testbed in YAML

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/getting_started/index.md

Describes a network topology using YAML format, including device details, credentials, connection protocols, IP addresses, and interface configurations. This file serves as the blueprint for pyATS test execution.

```yaml
testbed:
    name: IOS_Testbed
    credentials:
        default:
            username: admin
            password: cisco
        enable:
            password: cisco

devices:
    ios-1: # <----- must match to your device hostname in the prompt
        os: ios
        type: ios
        connections:
            a:
                protocol: telnet
                ip: 1.1.1.1
                port: 11023
    ios-2:
        os: ios
        type: ios
        connections:
            a:
                protocol: telnet
                ip: 1.1.1.2
                port: 11024
            vty:
                protocol: ssh
                ip: 5.5.5.5
topology:
    ios-1:
        interfaces:
            GigabitEthernet0/0:
                ipv4: 10.10.10.1/24
                ipv6: '10:10:10::1/64'
                link: link-1
                type: ethernet
            Loopback0:
                ipv4: 192.168.0.1/32
                ipv6: '192::1/128'
                link: ios1_Loopback0
                type: loopback
    ios-2:
        interfaces:
            GigabitEthernet0/0:
                ipv4: 10.10.10.2/24
                ipv6: '10:10:10::2/64'
                link: link-1
                type: ethernet
            Loopback0:
                ipv4: 192.168.0.2/32
                ipv6: '192::2/128'
                link: ios2_Loopback0
                type: loopback
```

--------------------------------

### Start AERunner Setuphandler

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/apidoc/aereport/index.md

Starts a setuphandler section within a testsuite. It requires parameters like clienthost, pid, and name, with an optional logfilepath. Returns an Exception if an issue is encountered in strict mode, otherwise returns None.

```python
>>>  # Make sure current context is testsuite
>>>  aerunner.start_setuphandler('firstsetuphandler')
```

--------------------------------

### Run pyATS Job from Command Line

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/getting_started/index.md

Launches a pyATS job using the 'pyats run job' command. This command accepts arguments for specifying the testbed file and enabling HTML log generation. The '--testbed-file' argument automatically loads and parses the testbed configuration.

```bash
bash$ pyats run job ios_job.py --testbed-file ios_testbed.yaml --html-logs
```

--------------------------------

### Python Job File Structure

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/getting_started/index.md

Demonstrates the basic structure of a Python job file, which serves as an entry point for executing testscripts within AEtest's job management system. A job file must define a 'main()' method, which is the designated starting point for the job's execution. Job files allow for standardized runtime environments and plugin utilization for tasks like loading testbed configurations.

```python
# Example: ios_job.py
# -------------------
#

```

--------------------------------

### Python: Device Connection and Command Execution Example

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/connections/integration.md

Demonstrates the integration of connection manager with a Device object. It shows how to connect to a device, execute commands, configure settings, and perform network operations like ping and reload. Assumes a testbed environment is set up.

```python
# Example
# -------
#
#   device & connection integration

# when given a device object
device = testbed.devices['some-uut-device']

# users should be able to directly interface with it, eg:
# connect to it
device.connect()

# send commands
output = device.execute('show version')
device.configure(''
    interface Ethernet1/1
        ip address 192.5.10.1 255.255.255.0
        no shutdown
'')

# and more ...
assert device.connected
device.ping('192.5.10.2')
device.reload()
device.disconnect()
```

--------------------------------

### Start Common Subsection

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/apidoc/aereport/index.md

Starts a common subsection within a specified context. This function is used to group related test or setup operations.

```APIDOC
## start_commonsubsection

### Description
Starts a common subsection within a specified context. This function is used to group related test or setup operations.

### Method
Not applicable (Python function call)

### Endpoint
Not applicable (Python function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **name** (str) - Required - The name of the subsection to start.

### Request Example
```pycon
>>> clt.start_commonsubsection(name='comsubsec1')
```

### Response
#### Success Response (200)
None

#### Response Example
```json
null
```

### Error Handling
* If mode is strict and an issue is seen, an Exception will be raised. Else None in all other cases.
* **Return type:** Exception or None
```

--------------------------------

### Copying Latest Examples and Templates to pyATS Instance

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/changelog/2015/june.md

Demonstrates how to copy the latest examples and templates into your pyATS instance. This involves backing up existing directories and then copying new ones from a specified path.

```bash
bash$ cd $VIRTUAL_ENV
bash$ mv examples examples_bak
bash$ mv templates templates_bak
bash$ cp -r /auto/pyats/examples .
bash$ cp -r /auto/pyats/templates .
```

--------------------------------

### Run Python Testscript from Command Line

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/getting_started/index.md

Executes a Python testscript named 'connectivity_check.py' using the 'python' interpreter and passes 'ios_testbed.yaml' as an argument. This command assumes the testscript is designed to be run from the command line, often leveraging an 'if __name__ == "__main__":' block to initiate AEtest for execution and result reporting.

```bash
bash$ python connectivity_check.py --testbed ios_testbed.yaml
```

--------------------------------

### YAML Testbed Format Example

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/topology/introduction.md

Demonstrates the structure of a YAML file used to define testbed topology and device metadata. This format is human-readable and machine-parseable, mapping directly to Python data structures.

```yaml
devices:
    jarvis:
        type: "Artificial Intelligence Computer"
        alias: "J.A.R.V.I.S"
        connections:
            voice:
                protocol: english
        role: "Tony Stark's housekeeper"
        custom:
            appeared_in:
                - Iron Man
                - Iron Man 2
                - The Avengers
                - Iron Man 3
                - Avengers - Age of Ultron
```

--------------------------------

### Testbed YAML Extension Example

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/utilities/yaml_markup.md

Demonstrates how to extend a base testbed YAML file (tb1.yaml) with additional device configurations in another file (tb2.yaml). The 'extends' keyword allows merging configurations, enabling modular testbed definitions.

```yaml
devices:
  xr-1:
    connections:
      cli:
        ip: 10.1.1.1
        protocol: ssh
    credentials:
      default:
        password: cisco
        username: cisco
      enable:
        password: cisco
    os: iosxr
    type: iosxr
```

```yaml
extends: tb1.yaml
devices:
  xr-2:
    connections:
      cli:
        ip: 10.2.2.2
        protocol: ssh
    credentials:
      default:
        password: cisco
        username: cisco
      enable:
        password: cisco
    os: iosxr
    type: iosxr
```

--------------------------------

### Instantiating and Using ConnectionManager APIs

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/connections/manager.md

This example demonstrates how to access and utilize the ConnectionManager associated with a device object. It shows how to connect, access the manager, verify its parent device, and inspect the managed connections.

```python
# Example
# -------
#
#   behind-the-scene integration & apis

# assume we had a device object
device
# <Device phoenix at 0xf7714c0c>

# it always features its own connection manager
device.connectionmgr
# <pyats.connections.ConnectionManager object at 0xf76f1c4c>

# if we make the default connection
device.connect()

# and dice things further
# eg, single out the connection manager
manager = device.connectionmgr

# notice that each manager is unique to its parent device
manager.device
# <Device phoenix at 0xf7714c0c>

# and contains a dictionary of connections it currently knows
# stored as alias: object mapping
# note how the default connection is assigned with alias "default"
manager.connections
# AttrDict({'default': <Connection phoenix at 0xf76c3d08>})
```

--------------------------------

### Device Class Instantiation with Interfaces (Python)

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/apidoc/topology/index.md

Shows how to create a Device object, which is a fundamental component in a testbed topology. This example demonstrates initializing a device with a name, alias, and associating it with interfaces and a testbed object. It highlights the composition of a network device within the pyats framework.

```python
>>> device = Device('myDevice')
>>> from pyats.topology import Testbed, Interface
>>> testbed = Testbed('myTestbed')
>>> interface = Interface('Ethernet1/1', 'ethernet')
>>> device = Device('myNewDevice',
...                 alias = 'myAlias',
...                 interfaces = [interface,],
...                 testbed = testbed)
```

--------------------------------

### Create and Add a Device to a Testbed Object in Python

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/apidoc/topology/index.md

Illustrates the process of creating a Testbed object and adding a Device object to it. The Testbed serves as the top-level container for network topology elements, and devices are key components within it. This example shows the basic steps for initializing a testbed and populating it with devices.

```python
>>> testbed = Testbed('myTestbed')
>>> from pyats.topology import Device
>>> device = Device('myDevice')
>>> testbed.add_device(device)
```

--------------------------------

### pyATS Configuration File Example

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/configuration/index.md

An example of a pyATS configuration file in INI format. This file demonstrates how to set parameters for different sections like 'email'. pyATS uses standard INI syntax with sections in '[]', key/value pairs separated by '=', and comments starting with '#'.

```ini
# Example
# -------
#
#   pyATS configuration file

[email]
smtp.host = mail.google.com
smtp.port = 25
default_domain = gmail.com

```

--------------------------------

### Iterate Over Testbed Devices

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/topology/concept.md

Demonstrates how to loop through all devices within a testbed. This allows for individual processing or inspection of each device's properties, such as its name.

```python
for device in testbed_c:
    print(device.name)

```

--------------------------------

### TopologyObject Initialization Example (Python)

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/apidoc/topology/index.md

Illustrates the basic instantiation of the TopologyObject class, showing how to create objects with just a name, and also with both a name and an alias. This is fundamental for defining topology components in pyats.

```python
>>> obja = TopologyObject(name = 'obja')
>>> objb = TopologyObject(name = 'objb', alias = 'alias_objb')
```

--------------------------------

### Set Testbed, Device, and Connection Credentials in pyATS

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/topology/concept.md

Demonstrates setting credentials at the testbed, device, and connection levels. It shows how to access these credentials using dot notation and verifies their presence. Includes an example of converting encoded passwords back to plaintext.

```python
testbed.credentials['default'] = dict(username='defaultuser', password='defaultpw')
assert testbed.credentials.default.username == 'defaultuser'

testbed.credentials['tbcreds'] = dict(username='tbuser', password='tbpw')
device_c.credentials['devcreds'] = dict(username='devuser', password='devpw')
assert 'tbcreds' in device_c.credentials
assert 'devcreds' in device_c.credentials

# Missing credentials fall back to default credential if present
assert testbed.credentials.unknowncred.username == 'defaultuser'

from pyats.utils.secret_strings import to_plaintext
assert to_plaintext(device_c.credentials.devcreds.password) == 'devpw'


con = device_b.connections.mgmt
device_b.testbed = testbed
con.credentials['concreds'] = dict(username='connuser', password='conpw')
assert 'tbcreds' in con.credentials
assert 'concreds' in con.credentials

# Provide a connection-level default credential
con.credentials['default'] = dict(username='condefun', password='condefpw')
```

--------------------------------

### Setting and Getting Tcl Doubles with pyats

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/tcl/variables.md

This example demonstrates setting a double-precision floating-point number in Tcl using `set_double` and retrieving it with `get_int`. It highlights pyats' ability to handle and cast double values.

```python
from pyats import tcl

# Tcl Doubles
# ----------- 
tcl.set_double('myDouble', 3.1415926)
print(tcl.vars['myDouble'])
doubleVar = tcl.get_double('myDouble')
print(doubleVar)
```

--------------------------------

### Python: Multiple Device Connection Instances with Aliases

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/connections/integration.md

Explains how to manage multiple connection instances to a device, requiring a unique alias for each. Demonstrates connecting, accessing services via aliases, and disconnecting individual or all instances. Includes an inline testbed setup for multiple connection points.

```text
Syntax
------

    # [] denotes optional arguments
    # *args, **kwargs denotes all other possible arguments

    # connect to alias and disconnect from alias
    device.connect(alias = "alias", [via = "path"], [**kwargs])
    device.<alias>.disconnect()

    # calling services of an alias
    device.<alias>.<services>([*args], [**kwargs])
```

```python
# Example
# -------
#
#   multiple connection instance example

# following the example above, let's make the testbed
# connection description slightly more complicated
# (edit this to whatever your testbed looks like)
testbed = topology.loader.load('''
testbed:
    name: my-inline-testbed

devices:
    tplana-hath:
        type: iosxe
        os: iosxe
        connections:
            a:
                protocol: telnet
                ip: 10.1.1.1
                port: 10000
            mgmt:
                protocol: telnet
                ip: 10.1.1.1
                port: 20000
''')

# pick the device
device = testbed.devices['tplana-hath']

# make multiple connections to mgmt port (which accepts multi sessions)
# each should be provided a unique alias and the exact path eg:
device.connect(alias = 'vty_1', via = 'mgmt')
device.connect(alias = 'vty_2', via = 'mgmt')
device.connect(alias = 'vty_3', via = 'mgmt')

# now we can use each instance independent of the others
assert device.vty_1.connected
assert device.vty_2.connected
assert device.vty_3.connected

# each instance has its own services
# eg, configure different terminal width for each session
device.vty_1.configure('terminal width 100')
device.vty_2.configure('terminal width 200')
device.vty_2.configure('terminal width 300')

# disconnect each independently
device.vty_1.disconnect()
device.vty_2.disconnect()
device.vty_3.disconnect()

# or disconnect everything altogether
device.disconnect_all()
```

--------------------------------

### Validate Jinja2 Configuration - Example

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/cli/pyats_validate.md

An example of using the 'pyats validate jinja2_config' command to render configurations for specific devices and sequences. It demonstrates how to provide the configuration datafile, testbed file, and sequence number to obtain the rendered output.

```bash
$ pyats validate jinja2_config data/config_datafile.yaml --testbed-file data/testbed.yaml --sequence 1

Device R1 sequence 1:
interface Loopback0
no shutdown
ip address 1.1.1.1 255.255.255.255


Device R2 sequence 1:
interface Loopback0
no shutdown
ip address 2.2.2.2 255.255.255.255
```

--------------------------------

### Setting and Getting Tcl Lists with pyats

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/tcl/variables.md

This example demonstrates setting a Tcl list with multiple elements using `set_list` and retrieving it as a tuple using `get_list`. It showcases pyats' handling of Tcl list structures.

```python
from pyats import tcl

# Tcl Lists
# ----------
tcl.set_list('myList', [1, 2, 3, 4, 5])
print(tcl.vars['myList'])
listVar = tcl.get_list('myList')
print(listVar)
```

--------------------------------

### Configure Embedded PyATS File Transfer Server

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/changelog/2020/dec.md

Example configuration in a testbed YAML file to enable the embedded PyATS File Transfer Server. This feature allows for dynamic FTP server setup within the testbed.

```yaml
testbed:
  servers:
    myftpserver:
      dynamic: true
      protocol: ftp
      subnet: 10.0.0.0/8
      path: /path/to/root/dir
```

--------------------------------

### Device Connection Example with 'via' Argument (Python)

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/changelog/2015/march.md

Demonstrates how to connect to a device using the `connect` method with the `via` argument. This snippet shows the updated syntax where the `connections.` prefix is no longer required for the `via` parameter, simplifying the connection configuration. It requires the `ats.connections` module.

```python
from ats.connections import Connection

# Assume 'device' is an initialized device object

# Before:
# device.connect(via = 'connections.alt')

# Now:
device.connect(via = 'alt')
```

--------------------------------

### PyATS Testcase Definition and Execution

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/aetest/structure.md

Demonstrates how to define simple and more complex testcases using PyATS's aetest module. It includes examples of testcase setup, cleanup, and basic assertions. This approach is fundamental for structuring automated tests.

```python
# import the aetest module
from pyats import aetest

# define a simple testcase by inheriting aetest.Testcase
# this testcase's uid is defaulted to "SimpleTestcase"
class SimpleTestcase(aetest.Testcase):

    @aetest.test
    def trivial_test(self):
        assert 1 + 1 == 2

# testcases could also have its own setup/cleanups
class SlightlyMoreComplexTestcase(aetest.Testcase):

    # providing this testcase a user-defined uid
    uid = 'id_of_this_testcase'

    @aetest.setup
    def setup(self):
        self.value = 1

    @aetest.test
    def another_trivial_test(self):
        self.value += -1
        assert self.value == 0

    @aetest.cleanup
    def cleanup(self):
        del self.value
```

--------------------------------

### Automatic Genie Testbed Conversion in pyats

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/changelog/2021/february.md

Demonstrates how pyats automatically converts a testbed file to support Genie APIs when Genie libraries are installed. The example shows loading a testbed and interacting with devices using Genie-specific types.

```python
>>> from pyats.topology.loader import load
>>> testbed = load('testbed.yaml')
-------------------------------------------------------------------------------
In [1]: type(testbed)
Out[1]: genie.libs.conf.testbed.Testbed

In [2]: dev=testbed.devices.R1

In [3]: type(dev)
Out[3]: genie.libs.conf.device.iosxe.device.Device
```

--------------------------------

### Find Devices in Testbed

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/utilities/helper_functions.md

This example demonstrates how to use the `find` API to retrieve all `Device` objects from a testbed's device list. It's a basic usage scenario where minimal arguments are provided, returning all matching objects.

```python
from pyats.utils.objects import find

# Assuming testbed is a pre-configured testbed object
# find(from_ = testbed.devices.values(), type_ = Device)
# This would return a list of Device objects like:
# [<Device iol-one at 0xf6a7008c>, <Device iol-three at 0xf6a05b4c>, <Device iol-two at 0xf6a708cc>]
```

--------------------------------

### POST /run_server

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/apidoc/aereport/index.md

Starts an XMLRPC server on localhost and registers AERunner methods.

```APIDOC
## POST /run_server

### Description
Starts a simple XMLRPC server on the localhost and registers the methods in AERunner class. It uses the current assigned port, or gets a new port if not assigned.

### Method
POST

### Endpoint
/run_server

### Response
#### Success Response (200)
- **status** (str) - Indicates the status of the server startup.

#### Response Example
```json
{
  "status": "server started on port 8080"
}
```
```

--------------------------------

### Setting and Getting Tcl Keyed Lists with pyats

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/tcl/variables.md

This example demonstrates setting a Tcl keyed list using `set_keyed_list` with pyats' `tcl.KeyedList` object and retrieving it. It showcases the handling of Tcl's specific keyed list data structure.

```python
from pyats import tcl

# Tcl Keyed Lists
# -----------------
tcl.set_keyed_list('myKlist', tcl.KeyedList(a = 1, b = 2, c = 3))
print(tcl.vars['myKlist'])

# reading tcl arrays by name and typecasting
klist = tcl.get_keyed_list('myKlist')
print(klist)
```

--------------------------------

### pyats.aetest.reporter.default.SACommonSetupReporter

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/apidoc/aetest/pyats.aetest.reporter.md

Reporter for common setup sections in test execution.

```APIDOC
## SACommonSetupReporter Class

### Description
Reporter for common setup sections in test execution.

### Method
Class

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "section": "Section object",
  "parent": "BaseSectionReporter object (optional)"
}
```

### Response
#### Success Response (200)
- **N/A** (N/A) - N/A

#### Response Example
```json
{
  "example": "Instantiation does not return a specific value."
}
```

## child(section)

### Description
Creates a child reporter for a given section within the common setup.

### Method
Instance Method

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "section": "Section object"
}
```

### Response
#### Success Response (200)
- **ChildReporter** (object) - The newly created child reporter.

#### Response Example
```json
{
  "example": "Returns an instance of a child reporter for a section."
}
```

## processor(section)

### Description
Processes a given section within the common setup.

### Method
Instance Method

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "section": "Section object"
}
```

### Response
#### Success Response (200)
- **N/A** (N/A) - N/A

#### Response Example
```json
{
  "example": "Processes the section."
}
```

## start()

### Description
Starts the reporting process for the common setup section.

### Method
Instance Method

### Endpoint
N/A

### Parameters
None

### Request Example
```json
{
  "example": "Calling the start method."
}
```

### Response
#### Success Response (200)
- **N/A** (N/A) - N/A

#### Response Example
```json
{
  "example": "Starts the common setup reporting."
}
```

## stop(exc_type=None, exc_value=None, traceback=None)

### Description
Stops the reporting process for the common setup section, optionally handling exceptions.

### Method
Instance Method

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "exc_type": "Exception type (optional)",
  "exc_value": "Exception value (optional)",
  "traceback": "Traceback object (optional)"
}
```

### Response
#### Success Response (200)
- **N/A** (N/A) - N/A

#### Response Example
```json
{
  "example": "Stops the common setup reporting and handles any exceptions."
}
```
```

--------------------------------

### Set Different Common Discovery Classes per Common Section in PyATS

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/aetest/control.md

This example demonstrates assigning specific `discoverer` classes to common setup or cleanup sections, overriding the default common discoverer. This allows for tailored discovery logic for different common execution points.

```python
from pyats import aetest
from pyats.aetest import runtime

runtime.discoverer.common = MyDefaultDiscovery

class common_setup(aetest.CommonSetup):
    pass

class common_cleanup(aetest.CommonCleanup):
    discoverer = MyCommonDiscovery1
```

--------------------------------

### PyATS aetest Result Counting Example

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/aetest/results.md

This Python code demonstrates result counting in PyATS aetest. It defines common setup, testcase, and testcase components, illustrating how different structures (like CommonSetup, Testcase) contribute to the overall summary result numbers, while subsections do not.

```python
# Example
# -------
#
#   example testscript and number counting

from pyats import aetest

class CommonSetup(aetest.CommonSetup):

    @aetest.subsection
    def subsection_one(self): pass

    @aetest.subsection
    def subsection_two(self): pass

class TestcaseOne(aetest.Testcase):

    @aetest.setup
    def setup(self): pass

    @aetest.test
    def test_one(self): pass

    @aetest.test
    def test_two(self):
        self.failed()

    @aetest.cleanup
    def cleanup(self): pass


# +------------------------------------------------------------------------+
# |                                Summary                                 |
# +------------------------------------------------------------------------+
#  Number of ABORTED                                                      0
#  Number of BLOCKED                                                      0
#  Number of ERRORED                                                      0
#  Number of FAILED                                                       1
#  Number of PASSED                                                       1
#  Number of PASSX                                                        0
#  Number of SKIPPED                                                      0
# --------------------------------------------------------------------------

```

--------------------------------

### Define Testbed Server and Device Configurations (YAML)

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/kleenex/inputs.md

This YAML snippet defines the testbed structure, including server details with authentication credentials and device configurations with connection protocols, IP addresses, and ports. It serves as a blueprint for setting up network environments.

```yaml
testbed:
    servers:
        golden_img_svr.domain.com:
            credentials:
                default:
                    username: jdoe
                    password: my_pw

        img_svr.domain.com:
            credentials:
                default:
                    username: jdoe
                    password: my_pw

devices:
    example-device:
        type: example-type
        connections:
            default:
                protocol: telnet
                ip: 1.1.1.10
                port: 500

    another-example-device:
        type: example-type
        connections:
            default:
                protocol: telnet
                ip: 1.1.1.10
                port: 501
...
```

--------------------------------

### Basic Python Logging Setup and Usage

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/log/introduction.md

Demonstrates how to import, set up, and use the native Python `logging` module in a script. This includes getting a logger instance, configuring it (implicitly handled by pyATS for consistent formatting), and emitting log messages of different severity levels (info, error, debug).

```python
import logging

# always use your module name as the logger name.
# this enables logger hierarchy
logger = logging.getLogger(__name__)

# use logger:
logger.info('an info message')
logger.error('an error message')
logger.debug('a debug message')
```

--------------------------------

### NX-OS Device Pre-Clean Script (YAML)

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/topology/example.md

This snippet shows the pre-clean configuration commands for NX-OS devices within the testbed. It configures the switch name, grace period for licenses, enables telnet, sets the management interface IP address, and configures VRF routes. The `%{self}` and `%{self.connections.vty.ip}` variables are placeholders specific to the testbed framework.

```yaml
pre_clean: |
            switchname %{self}
            license grace-period
            feature telnet
            interface mgmt0
                ip addr %{self.connections.vty.ip}/24
            no shut
            vrf context management
                ip route 101.0.0.0/24 5.19.27.251
                ip route 102.0.0.0/24 5.19.27.251
```

--------------------------------

### Start XMLRPC Server (Python)

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/apidoc/aereport/index.md

Initializes and starts a simple XMLRPC server on localhost. This server registers the methods available within the AERunner class, allowing remote procedure calls. It uses the currently assigned port or acquires a new one if none is set.

```python
def run_server():
    """Starts a simple XMLRPC server on the localhost and registers
    the methods in AERunner class.
    It uses the current assigned port, or gets a new
    port if not assigned.
    """
    pass
```

--------------------------------

### Configure Devices in Parallel on Testbed

Source: https://github.com/suhaibqr/salrabee-pts/blob/main/docs/topology/concept.md

Applies a configuration command to all devices within the testbed concurrently. This is useful for deploying consistent settings across an entire lab environment.

```python
testbed.configure('no logging console')

```
Tokens:
Raw