tessl/pypi-textfsm

Python module for parsing semi-structured text into python tables.

Overview

Eval results

Files

Core Parser Engine

Name: tessl/pypi-textfsm
Author: tessl

The TextFSM core parser provides the fundamental template-based state machine functionality for extracting structured data from semi-formatted text. This is the primary interface for creating parsers and processing text input.

Core Imports

import textfsm
from textfsm.parser import TextFSM, TextFSMValue, TextFSMRule
from textfsm.parser import TextFSMError, TextFSMTemplateError

Capabilities

TextFSM Parser

The main parser class that processes TextFSM templates and applies them to text input to extract structured records.

class TextFSM:
    def __init__(self, template, options_class=None):
        """
        Initialize TextFSM parser with template.
        
        Args:
            template: File-like object containing TextFSM template
            options_class: Custom options class (default: TextFSMOptions)
        """
    
    def ParseText(self, text, eof=True):
        """
        Parse input text using the template.
        
        Args:
            text (str): Input text to parse
            eof (bool): Whether to process end-of-file transitions (default: True)
            
        Returns:
            list: List of records, each record is a list of extracted values
        """
    
    def ParseTextToDicts(self, text, eof=True):
        """
        Parse input text using the template, returning dictionary records.
        
        Args:
            text (str): Input text to parse
            eof (bool): Whether to process end-of-file transitions (default: True)
            
        Returns:
            list: List of records, each record is a dict with column names as keys
        """
    
    def Reset(self):
        """Reset parser state to initial conditions."""
    
    def GetValuesByAttrib(self, attribute):
        """
        Get values that have a specific attribute.
        
        Args:
            attribute (str): Attribute name to search for
            
        Returns:
            list: List of value names with the attribute
        """
    
    @property
    def header(self):
        """List of column headers from Value definitions."""
    
    @property
    def values(self):
        """List of TextFSMValue objects."""
    
    @property
    def states(self):
        """Dict of FSM states and their rules."""
    
    @property
    def value_map(self):
        """Dict mapping value names to TextFSMValue objects."""
    
    @property
    def state_list(self):
        """List of state names in order."""

TextFSM Value Definitions

Represents template value definitions with regex patterns and processing options.

class TextFSMValue:
    def __init__(self, fsm=None, max_name_len=48, options_class=None):
        """
        Initialize value definition.
        
        Args:
            fsm: Parent TextFSM object
            max_name_len (int): Maximum allowed name length (default: 48)
            options_class: Custom options class for value processing
        """
    
    def Parse(self, value):
        """
        Parse a Value line from template.
        
        Args:
            value (str): Value definition line from template
        """
    
    def AssignVar(self, value):
        """
        Assign a value to this variable.
        
        Args:
            value: Value to assign
        """
    
    def ClearVar(self):
        """
        Clear this variable's value.
        """
    
    def ClearAllVar(self):
        """
        Clear this variable's value (part of ClearAll operation).
        """
    
    def Header(self):
        """
        Get header name for this value.
        
        Returns:
            str: Header name string
        """
    
    def OnCreateOptions(self):
        """Called after all options have been parsed."""
    
    def OnClearVar(self):
        """Called when value is cleared."""
    
    def OnClearAllVar(self):
        """Called when value is cleared with ClearAll."""
    
    def OnSaveRecord(self):
        """Called when record is saved."""
    
    def OptionNames(self):
        """
        Get list of option names for this value.
        
        Returns:
            list: List of option name strings
        """
    
    @property
    def name(self):
        """Value name string."""
    
    @property
    def regex(self):
        """Original regex pattern."""
    
    @property
    def template(self):
        """Compiled regex template with named groups."""
    
    @property
    def value(self):
        """Current extracted value."""
    
    @property
    def options(self):
        """List of option objects."""
    
    @property
    def compiled_regex(self):
        """Compiled regex object for matching."""
    
    @property
    def max_name_len(self):
        """Maximum allowed name length."""

TextFSM Rule Processing

Represents parsing rules that define state transitions and actions within the FSM.

class TextFSMRule:
    def __init__(self, line, line_num=0, var_map=None, options_class=None):
        """
        Initialize parsing rule.
        
        Args:
            line (str): Rule line from template
            line_num (int): Line number in template (default: 0)
            var_map (dict): Variable name to regex mapping
            options_class: Options class for processing
        """
    
    
    @property
    def match(self):
        """Regex match pattern for this rule."""
    
    @property
    def line_op(self):
        """Line operation (Continue, Next, Error, etc.)."""
    
    @property
    def new_state(self):
        """Next state to transition to."""
    
    @property
    def record_op(self):
        """Record operation (NoRecord, Record, Clear, etc.)."""
    
    @property
    def regex(self):
        """Original regex pattern string."""
    
    @property
    def regex_obj(self):
        """Compiled regex object."""
    
    @property
    def line_num(self):
        """Line number in template."""

Value Options System

Container and base classes for TextFSM value processing options like Filldown and Required.

class TextFSMOptions:
    """Container for all valid TextFSMValue options."""
    
    @classmethod
    def ValidOptions(cls):
        """
        Get list of valid option names.
        
        Returns:
            list: List of valid option name strings
        """
    
    @classmethod
    def GetOption(cls, name):
        """
        Get option class by name.
        
        Args:
            name (str): Option name
            
        Returns:
            class: Option class
        """
    
    class OptionBase:
        def __init__(self, value):
            """
            Base class for value options.
            
            Args:
                value: Parent TextFSMValue instance
            """
        
        def OnCreateOptions(self):
            """Called after all options have been parsed."""
        
        def OnClearVar(self):
            """Called when value has been cleared."""
        
        def OnClearAllVar(self):
            """Called when value has been cleared with ClearAll."""
        
        def OnAssignVar(self, value):
            """
            Called when value is assigned.
            
            Args:
                value: Assigned value
            """
        
        def OnGetValue(self):
            """
            Called when value is retrieved.
            
            Returns:
                Value to return
            """
        
        def OnSaveRecord(self):
            """Called when record is saved."""
        
        @property
        def name(self):
            """Option name without 'option' prefix."""
    
    class optionFilldown(OptionBase):
        """Maintains value across records until explicitly changed."""
    
    class optionFillup(OptionBase):
        """Fills empty values from subsequent records."""
    
    class optionRequired(OptionBase):
        """Requires value to be set before record can be saved."""
    
    class optionList(OptionBase):
        """Collects multiple values into a list."""
    
    class optionKey(OptionBase):
        """Marks value as a key field for record identification."""

Helper Classes

class CopyableRegexObject:
    def __init__(self, pattern):
        """
        Wrapper for regex objects to enable deep copying.
        
        Args:
            pattern: Regular expression pattern or compiled regex
        """
    
    def search(self, *args, **kwargs):
        """Search for pattern in text."""
    
    def match(self, *args, **kwargs):
        """Match pattern at start of text."""
    
    def sub(self, *args, **kwargs):
        """Substitute pattern matches in text."""
    
    def __copy__(self):
        """Create shallow copy."""
    
    def __deepcopy__(self, unused_memo):
        """Create deep copy."""

Module Functions

def main(argv=None):
    """
    Command-line interface for TextFSM parsing.
    
    Args:
        argv (list): Command line arguments (default: sys.argv)
        
    Returns:
        int: Exit code (0 for success)
    """

Core Exceptions

class Error(Exception):
    """Base exception class for TextFSM."""

class UsageError(Exception):
    """Command line execution error."""

class TextFSMTemplateError(Error):
    """Error in template parsing or validation."""

class FSMAction(Exception):
    """Base class for FSM action indicators."""

class SkipRecord(FSMAction):
    """Indicates current record should be skipped."""

class SkipValue(FSMAction):
    """Indicates current value should be skipped."""

Usage Examples

Basic Template Processing

import io
import textfsm

# Define template
template = """
Value HOSTNAME (\S+)
Value UPTIME (.+)
Value VERSION (\S+)

Start
  ^${HOSTNAME} uptime is ${UPTIME}
  ^Software version ${VERSION} -> Record
"""

# Parse text
text = """
router1 uptime is 5 days, 14 hours, 23 minutes
Software version 15.1(4)M5
router2 uptime is 2 days, 8 hours, 15 minutes  
Software version 15.2(2)T1
"""

fsm = textfsm.TextFSM(io.StringIO(template))
results = fsm.ParseText(text)
# [['router1', '5 days, 14 hours, 23 minutes', '15.1(4)M5'],
#  ['router2', '2 days, 8 hours, 15 minutes', '15.2(2)T1']]

Using Value Options

template_with_options = """
Value Required INTERFACE (\S+)
Value Filldown DEVICE (\S+)
Value List IP_ADDR (\d+\.\d+\.\d+\.\d+)

Start
  ^Device: ${DEVICE}
  ^Interface ${INTERFACE}
  ^  IP: ${IP_ADDR} -> Record
"""

text = """
Device: switch1
Interface GigE0/1  
  IP: 192.168.1.1
  IP: 10.0.0.1
Interface GigE0/2
  IP: 172.16.1.1
"""

fsm = textfsm.TextFSM(io.StringIO(template_with_options))
results = fsm.ParseText(text)
# [['GigE0/1', 'switch1', ['192.168.1.1', '10.0.0.1']],
#  ['GigE0/2', 'switch1', ['172.16.1.1']]]

Install with Tessl CLI