or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/pypi-ntc-templates

TextFSM Templates for Network Devices, and Python wrapper for TextFSM's CliTable.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/ntc-templates@8.0.x

To install, run

npx @tessl/cli install tessl/pypi-ntc-templates@8.0.0

index.mddocs/

NTC Templates

A comprehensive Python library providing TextFSM templates for parsing CLI output from network devices. The library includes hundreds of pre-built templates for various network device vendors and commands, along with a Python wrapper for TextFSM's CliTable functionality that converts unstructured CLI output into structured data formats.

Package Information

  • Package Name: ntc-templates
  • Package Type: pypi
  • Language: Python
  • Installation: pip install ntc-templates
  • Template Count: 932 TextFSM templates
  • Supported Platforms: Multiple network device vendors (Cisco, Arista, Juniper, Alcatel, etc.)

Core Imports

from ntc_templates.parse import parse_output

Import the exception class for error handling:

from ntc_templates.parse import parse_output, ParsingException

Basic Usage

from ntc_templates.parse import parse_output

# Example Cisco IOS "show vlan" output
vlan_output = """VLAN Name                             Status    Ports
---- -------------------------------- --------- -------------------------------
1    default                          active    Gi0/1
10   Management                       active    
50   VLan50                           active    Fa0/1, Fa0/2, Fa0/3, Fa0/4, Fa0/5,
                                                Fa0/6, Fa0/7, Fa0/8
"""

# Parse the output into structured data
result = parse_output(
    platform="cisco_ios",
    command="show vlan",
    data=vlan_output
)

print(result)
# Output:
# [
#     {
#         'vlan_id': '1',
#         'name': 'default',
#         'status': 'active',
#         'interfaces': ['Gi0/1']
#     },
#     {
#         'vlan_id': '10',
#         'name': 'Management',
#         'status': 'active',
#         'interfaces': []
#     },
#     {
#         'vlan_id': '50',
#         'name': 'VLan50',
#         'status': 'active',
#         'interfaces': ['Fa0/1', 'Fa0/2', 'Fa0/3', 'Fa0/4', 'Fa0/5', 'Fa0/6', 'Fa0/7', 'Fa0/8']
#     }
# ]

Architecture

The library operates as a bridge between raw CLI output and structured data:

  • Templates: Collection of 932 TextFSM template files (.textfsm) that define parsing rules for specific platform/command combinations
  • Index File: Maps platform and command patterns to appropriate template files using regex matching
  • Parser Function: parse_output() function that automatically selects and applies the correct template
  • CliTable Integration: Uses TextFSM's CliTable for template matching and data extraction
  • Data Transformation: Converts TextFSM table results into Python dictionaries with lowercase field names

The template-driven approach enables consistent parsing across hundreds of different network device commands without requiring custom parsing logic for each command.

Capabilities

Primary Parsing Function

Core functionality for parsing network device CLI output using TextFSM templates.

def parse_output(
    platform=None,
    command=None,
    data=None,
    template_dir=None,
    try_fallback=False
):
    """
    Return the structured data based on the output from a network device.

    Args:
        platform (str, optional): The platform the command was run on (e.g., 'cisco_ios')
        command (str, optional): The command run on the platform (e.g., 'show int status')
        data (str, optional): The output from running the command
        template_dir (str, optional): The directory to look for TextFSM templates.
            Defaults to setting of environment variable or default ntc-templates dir.
            The specified directory must have a properly configured index file.
        try_fallback (bool, optional): Whether to fallback to using the default template
            directory upon failure with template_dir. Defaults to False.

    Returns:
        list: The TextFSM table entries as dictionaries with lowercase field names.
            Each dictionary represents one row of parsed data.

    Raises:
        ParsingException: When TextFSM parsing fails or template cannot be found
        ImportError: When TextFSM library is not available (especially on Windows)
    """

Error Handling

Exception class for parsing errors.

class ParsingException(Exception):
    """
    Error that is raised when TextFSM hits an 'Error' state.
    
    This exception is raised when:
    - TextFSM parsing fails due to template errors
    - No matching template is found for the platform/command combination
    - Template parsing encounters an unexpected data format
    """

Template System

Built-in Templates

The library includes pre-built templates for common network device commands:

  • Cisco IOS/IOS-XE: show commands for interfaces, VLANs, routing, OSPF, BGP, etc.
  • Cisco NXOS: show commands for data center networking features
  • Arista EOS: show commands for Arista network devices
  • Juniper JUNOS: show commands for Juniper routers and switches
  • Many others: Alcatel, HP, F5, Fortinet, Palo Alto, and more

Templates are automatically selected based on platform and command matching using the index file.

Template Directory Structure

ntc_templates/
├── templates/
│   ├── index                    # Template index file
│   ├── cisco_ios_show_vlan.textfsm
│   ├── cisco_ios_show_interfaces.textfsm
│   ├── arista_eos_show_interfaces.textfsm
│   └── ... (932 template files)

Custom Templates

You can use custom template directories:

from ntc_templates.parse import parse_output

# Use custom template directory
result = parse_output(
    platform="custom_platform",
    command="show custom",
    data=raw_output,
    template_dir="/path/to/custom/templates"
)

# Try custom templates first, fallback to built-in if needed
result = parse_output(
    platform="cisco_ios",
    command="show version",
    data=raw_output,
    template_dir="/path/to/custom/templates",
    try_fallback=True
)

Environment Configuration

Template Directory Override

Set the NTC_TEMPLATES_DIR environment variable to use a custom template directory globally:

export NTC_TEMPLATES_DIR="/path/to/custom/templates"

When set, this becomes the default template directory for all parsing operations.

Platform Support

Operating System Compatibility

  • Linux: Fully supported
  • macOS: Fully supported
  • Windows: Requires TextFSM patch (see error message for details)

Python Version Support

  • Python 3.9+: Fully supported
  • TextFSM Dependency: Requires textfsm>=1.1.0

Usage Examples

Parsing Interface Status

from ntc_templates.parse import parse_output

interface_output = """
Interface              Status         Protocol
GigabitEthernet0/1     up             up      
GigabitEthernet0/2     down           down    
Serial0/0/0            up             up      
"""

result = parse_output(
    platform="cisco_ios",
    command="show interfaces status",
    data=interface_output
)

for interface in result:
    print(f"Interface {interface['interface']} is {interface['status']}")

Error Handling

from ntc_templates.parse import parse_output, ParsingException

try:
    result = parse_output(
        platform="unknown_platform",
        command="show version",
        data=raw_output
    )
except ParsingException as e:
    print(f"Parsing failed: {e}")
except ImportError as e:
    print(f"TextFSM not available: {e}")

Using Custom Templates

import os
from ntc_templates.parse import parse_output

# Ensure custom template directory exists with proper index file
custom_dir = "/path/to/custom/templates"
if os.path.exists(custom_dir):
    result = parse_output(
        platform="custom_device",
        command="show custom command",
        data=raw_output,
        template_dir=custom_dir
    )