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
```