0
# NTC Templates
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: ntc-templates
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install ntc-templates`
10
- **Template Count**: 932 TextFSM templates
11
- **Supported Platforms**: Multiple network device vendors (Cisco, Arista, Juniper, Alcatel, etc.)
12

13
## Core Imports
14

15
```python
16
from ntc_templates.parse import parse_output
17
```
18

19
Import the exception class for error handling:
20

21
```python
22
from ntc_templates.parse import parse_output, ParsingException
23
```
24

25
## Basic Usage
26

27
```python
28
from ntc_templates.parse import parse_output
29

30
# Example Cisco IOS "show vlan" output
31
vlan_output = """VLAN Name                             Status    Ports
32
---- -------------------------------- --------- -------------------------------
33
1    default                          active    Gi0/1
34
10   Management                       active    
35
50   VLan50                           active    Fa0/1, Fa0/2, Fa0/3, Fa0/4, Fa0/5,
36
                                                Fa0/6, Fa0/7, Fa0/8
37
"""
38

39
# Parse the output into structured data
40
result = parse_output(
41
    platform="cisco_ios",
42
    command="show vlan",
43
    data=vlan_output
44
)
45

46
print(result)
47
# Output:
48
# [
49
#     {
50
#         'vlan_id': '1',
51
#         'name': 'default',
52
#         'status': 'active',
53
#         'interfaces': ['Gi0/1']
54
#     },
55
#     {
56
#         'vlan_id': '10',
57
#         'name': 'Management',
58
#         'status': 'active',
59
#         'interfaces': []
60
#     },
61
#     {
62
#         'vlan_id': '50',
63
#         'name': 'VLan50',
64
#         'status': 'active',
65
#         'interfaces': ['Fa0/1', 'Fa0/2', 'Fa0/3', 'Fa0/4', 'Fa0/5', 'Fa0/6', 'Fa0/7', 'Fa0/8']
66
#     }
67
# ]
68
```
69

70
## Architecture
71

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

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

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

82
## Capabilities
83

84
### Primary Parsing Function
85

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

88
```python { .api }
89
def parse_output(
90
    platform=None,
91
    command=None,
92
    data=None,
93
    template_dir=None,
94
    try_fallback=False
95
):
96
    """
97
    Return the structured data based on the output from a network device.
98

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

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

113
    Raises:
114
        ParsingException: When TextFSM parsing fails or template cannot be found
115
        ImportError: When TextFSM library is not available (especially on Windows)
116
    """
117
```
118

119
### Error Handling
120

121
Exception class for parsing errors.
122

123
```python { .api }
124
class ParsingException(Exception):
125
    """
126
    Error that is raised when TextFSM hits an 'Error' state.
127
    
128
    This exception is raised when:
129
    - TextFSM parsing fails due to template errors
130
    - No matching template is found for the platform/command combination
131
    - Template parsing encounters an unexpected data format
132
    """
133
```
134

135
## Template System
136

137
### Built-in Templates
138

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

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

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

149
### Template Directory Structure
150

151
```
152
ntc_templates/
153
├── templates/
154
│   ├── index                    # Template index file
155
│   ├── cisco_ios_show_vlan.textfsm
156
│   ├── cisco_ios_show_interfaces.textfsm
157
│   ├── arista_eos_show_interfaces.textfsm
158
│   └── ... (932 template files)
159
```
160

161
### Custom Templates
162

163
You can use custom template directories:
164

165
```python
166
from ntc_templates.parse import parse_output
167

168
# Use custom template directory
169
result = parse_output(
170
    platform="custom_platform",
171
    command="show custom",
172
    data=raw_output,
173
    template_dir="/path/to/custom/templates"
174
)
175

176
# Try custom templates first, fallback to built-in if needed
177
result = parse_output(
178
    platform="cisco_ios",
179
    command="show version",
180
    data=raw_output,
181
    template_dir="/path/to/custom/templates",
182
    try_fallback=True
183
)
184
```
185

186
## Environment Configuration
187

188
### Template Directory Override
189

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

192
```bash
193
export NTC_TEMPLATES_DIR="/path/to/custom/templates"
194
```
195

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

198
## Platform Support
199

200
### Operating System Compatibility
201

202
- **Linux**: Fully supported
203
- **macOS**: Fully supported  
204
- **Windows**: Requires TextFSM patch (see error message for details)
205

206
### Python Version Support
207

208
- **Python 3.9+**: Fully supported
209
- **TextFSM Dependency**: Requires `textfsm>=1.1.0`
210

211
## Usage Examples
212

213
### Parsing Interface Status
214

215
```python
216
from ntc_templates.parse import parse_output
217

218
interface_output = """
219
Interface              Status         Protocol
220
GigabitEthernet0/1     up             up      
221
GigabitEthernet0/2     down           down    
222
Serial0/0/0            up             up      
223
"""
224

225
result = parse_output(
226
    platform="cisco_ios",
227
    command="show interfaces status",
228
    data=interface_output
229
)
230

231
for interface in result:
232
    print(f"Interface {interface['interface']} is {interface['status']}")
233
```
234

235
### Error Handling
236

237
```python
238
from ntc_templates.parse import parse_output, ParsingException
239

240
try:
241
    result = parse_output(
242
        platform="unknown_platform",
243
        command="show version",
244
        data=raw_output
245
    )
246
except ParsingException as e:
247
    print(f"Parsing failed: {e}")
248
except ImportError as e:
249
    print(f"TextFSM not available: {e}")
250
```
251

252
### Using Custom Templates
253

254
```python
255
import os
256
from ntc_templates.parse import parse_output
257

258
# Ensure custom template directory exists with proper index file
259
custom_dir = "/path/to/custom/templates"
260
if os.path.exists(custom_dir):
261
    result = parse_output(
262
        platform="custom_device",
263
        command="show custom command",
264
        data=raw_output,
265
        template_dir=custom_dir
266
    )
267
```