{"id":7547,"library":"pyats-utils","title":"pyATS Utilities Module","description":"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.","status":"active","version":"26.3","language":"en","source_language":"en","source_url":"https://github.com/CiscoTestAutomation/pyats-utils","tags":["pyats","cisco","network-automation","testing","utilities","schema-validation","file-utils"],"install":[{"cmd":"pip install pyats-utils","lang":"bash","label":"Install stable version"},{"cmd":"pip install pyats","lang":"bash","label":"Recommended: Install full pyATS framework (includes pyats-utils)"}],"dependencies":[{"reason":"Most functionalities are designed to integrate with or enhance the pyATS framework. While some utilities can be used standalone, full functionality often requires pyATS.","package":"pyats","optional":false},{"reason":"Many parsing and device interaction utilities in pyATS/pyats-utils leverage Genie for platform abstraction.","package":"genie","optional":true}],"imports":[{"note":"The 'api' module is a higher-level interface, but 'base' is where the core Schema class resides for direct use.","wrong":"from pyats_utils.schema.api import Schema","symbol":"Schema","correct":"from pyats_utils.schema.base import Schema"},{"note":"The 'validate' function for easy schema validation is exposed directly via the 'api' module.","wrong":"from pyats_utils.schema.base import validate","symbol":"validate","correct":"from pyats_utils.schema.api import validate"},{"note":"The 'File' utility class is nested within the 'file' submodule of 'fileutils'.","wrong":"from pyats_utils.fileutils import File","symbol":"File","correct":"from pyats_utils.fileutils.file import File"}],"quickstart":{"code":"from pyats_utils.schema.api import validate\nfrom pyats_utils.schema.base import Schema, Any, Optional\n\n# Define a simple schema\nmy_schema = Schema({\n 'name': str,\n 'age': int,\n Optional('city'): str,\n 'active': bool\n})\n\n# Data to validate\nvalid_data = {\n 'name': 'Alice',\n 'age': 30,\n 'active': True\n}\n\ninvalid_data = {\n 'name': 'Bob',\n 'age': 'twenty five', # Incorrect type\n 'active': False\n}\n\n# Validate data\nprint(\"Validating valid_data...\")\ntry:\n validated = validate(data=valid_data, schema=my_schema)\n print(f\"Validation successful: {validated}\")\nexcept Exception as e:\n print(f\"Validation failed: {e}\")\n\nprint(\"\\nValidating invalid_data...\")\ntry:\n validated = validate(data=invalid_data, schema=my_schema)\n print(f\"Validation successful: {validated}\")\nexcept Exception as e:\n print(f\"Validation failed: {e}\")","lang":"python","description":"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."},"warnings":[{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"Versions prior to 25.0 when upgrading to 25.0+, or prior to 26.0 when upgrading to 26.0+"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `pyats-utils` is installed by running `pip install pyats-utils`. If you are in a virtual environment, ensure it's activated.","cause":"The `pyats-utils` package is not installed or is installed incorrectly.","error":"ModuleNotFoundError: No module named 'pyats_utils.schema.api'"},{"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`).","cause":"The data being validated against a `pyats_utils.schema.base.Schema` is missing a required key that is defined in the schema.","error":"pyats_utils.schema.exceptions.SchemaError: Key 'X' missing from dictionary"},{"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.","cause":"The data being validated against a `pyats_utils.schema.base.Schema` has a value with an incorrect type for a key.","error":"pyats_utils.schema.exceptions.SchemaError: Value 'X' of type is not of type "}]}