pyATS Utilities Module

26.3 · active · verified Thu Apr 16

pyATS Utils is a core component of Cisco's pyATS framework, providing a collection of reusable utility functions for test automation, data manipulation, schema validation, and file operations. It's designed to support and extend the capabilities of pyATS and Genie, streamlining common tasks in network automation and testing. The current version is 26.3, and it follows a rapid release cadence, typically aligning with the broader pyATS ecosystem.

Common errors

```
ModuleNotFoundError: No module named 'pyats_utils.schema.api'
```
cause The `pyats-utils` package is not installed or is installed incorrectly.

fix Ensure `pyats-utils` is installed by running `pip install pyats-utils`. If you are in a virtual environment, ensure it's activated.
```
pyats_utils.schema.exceptions.SchemaError: Key 'X' missing from dictionary
```
cause The data being validated against a `pyats_utils.schema.base.Schema` is missing a required key that is defined in the schema.

fix Review the schema definition and the input data. Either add the missing key to the data, or mark the key as `Optional` in the schema (e.g., `Optional('key'): str`).
```
pyats_utils.schema.exceptions.SchemaError: Value 'X' of type <class 'Y'> is not of type <class 'Z'>
```
cause The data being validated against a `pyats_utils.schema.base.Schema` has a value with an incorrect type for a key.

fix Ensure the data's types match those specified in the schema. For example, if the schema expects `int`, provide an integer, not a string.

Warnings

gotcha pyATS Utils is part of a larger ecosystem. Mismatched versions between `pyats-utils`, `pyats`, and `genie` packages can lead to unexpected errors or runtime issues. It's best practice to keep all pyATS-related packages updated together.
Fix: Always install/upgrade all pyATS components together, ideally using `pip install --upgrade pyats` which often pulls in compatible versions of dependencies. Verify versions with `pyats version`.
breaking The internal structure and API of `pyats-utils` modules can change between major `pyats` releases (e.g., from 23.x to 24.x, or 24.x to 25.x). While efforts are made for backward compatibility, direct imports from deep sub-modules might break.
Fix: Refer to the official pyATS release notes for detailed breaking changes. Prefer importing from documented top-level APIs (e.g., `pyats_utils.schema.api`) rather than internal modules when available.
gotcha Some utilities in `pyats-utils` assume the context of a pyATS testbed or run-time environment. Using them in isolation without proper setup might lead to `AttributeError` or `KeyError` if they try to access non-existent testbed attributes.
Fix: Ensure that the necessary pyATS environment or objects are initialized when using utilities that rely on them. For standalone use, ensure you understand the utility's dependencies and provide mock objects or necessary configurations if required.

Install

pip install pyats-utils Install stable version
pip install pyats Recommended: Install full pyATS framework (includes pyats-utils)

Imports

Schema
wrong:
```
from pyats_utils.schema.api import Schema
```
correct:
```
from pyats_utils.schema.base import Schema
```
The 'api' module is a higher-level interface, but 'base' is where the core Schema class resides for direct use.
validate
wrong:
```
from pyats_utils.schema.base import validate
```
correct:
```
from pyats_utils.schema.api import validate
```
The 'validate' function for easy schema validation is exposed directly via the 'api' module.
File
wrong:
```
from pyats_utils.fileutils import File
```
correct:
```
from pyats_utils.fileutils.file import File
```
The 'File' utility class is nested within the 'file' submodule of 'fileutils'.

Quickstart

This quickstart demonstrates how to define and use a simple schema for data validation using `pyats_utils.schema`. It shows how to import `Schema` and `validate`, define data structures with types and optional fields, and then validate sample data against the defined schema.

from pyats_utils.schema.api import validate
from pyats_utils.schema.base import Schema, Any, Optional

# Define a simple schema
my_schema = Schema({
    'name': str,
    'age': int,
    Optional('city'): str,
    'active': bool
})

# Data to validate
valid_data = {
    'name': 'Alice',
    'age': 30,
    'active': True
}

invalid_data = {
    'name': 'Bob',
    'age': 'twenty five', # Incorrect type
    'active': False
}

# Validate data
print("Validating valid_data...")
try:
    validated = validate(data=valid_data, schema=my_schema)
    print(f"Validation successful: {validated}")
except Exception as e:
    print(f"Validation failed: {e}")

print("\nValidating invalid_data...")
try:
    validated = validate(data=invalid_data, schema=my_schema)
    print(f"Validation successful: {validated}")
except Exception as e:
    print(f"Validation failed: {e}")

view raw JSON →