{"id":4279,"library":"textfsm","title":"TextFSM","description":"TextFSM is a Python module that implements a template-based state machine for parsing semi-structured text into Python tables. Originally developed by Google, it's widely used for extracting structured data from command-line interface (CLI) output of network devices. The library is currently at version 2.1.0 and has a sporadic but active release cadence, focusing on fixes and improvements.","status":"active","version":"2.1.0","language":"en","source_language":"en","source_url":"https://github.com/google/textfsm","tags":["parsing","text-processing","network-automation","cli-output","state-machine","regex"],"install":[{"cmd":"pip install textfsm","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"TextFSM","correct":"import textfsm"}],"quickstart":{"code":"import textfsm\nimport io\n\n# Example template string (equivalent to a .textfsm file)\ntemplate_string = '''\nValue Interface (\\S+)\nValue IP_Address (\\S+)\nValue Status (\\S+)\nValue Protocol (\\S+)\n\nStart\n  ^Interface\\s+IP-Address\\s+Status\\s+Protocol\\s*$$\n  ^${Interface}\\s+${IP_Address}\\s+${Status}\\s+${Protocol} -> Record\n'''\n\n# Example raw text output to parse\nraw_text_data = '''\nInterface        IP-Address   Status     Protocol\nGigabitEthernet0/1 192.168.1.1  up         up\nGigabitEthernet0/2 10.0.0.1     up         up\nLoopback0          unassigned   up         down\n'''\n\n# Open the template (using io.StringIO for a string, normally a file path)\nwith io.StringIO(template_string) as template_file:\n    # Create a TextFSM object\n    fsm = textfsm.TextFSM(template_file)\n\n    # Parse the raw text data\n    parsed_data = fsm.ParseText(raw_text_data)\n\n    # Print headers and data\n    print(fsm.header)\n    for row in parsed_data:\n        print(row)\n\n# Expected output:\n# ['Interface', 'IP_Address', 'Status', 'Protocol']\n# ['GigabitEthernet0/1', '192.168.1.1', 'up', 'up']\n# ['GigabitEthernet0/2', '10.0.0.1', 'up', 'up']\n# ['Loopback0', 'unassigned', 'up', 'down']","lang":"python","description":"This example demonstrates parsing a simple 'show ip interface brief' style output using an in-memory TextFSM template. It defines values to capture, a 'Start' state to match the header, and a rule to capture data lines into records."},"warnings":[{"fix":"Carefully review TextFSM template syntax documentation, especially for `Value` options (`Required`, `List`, `Filldown`, `Fillup`) and state transitions. Ensure regex patterns are correctly formatted and include capture groups.","message":"TextFSM templates use a strict Domain Specific Language (DSL). Incorrect `Value` definitions (e.g., missing regex capture groups, invalid options like `Filldown` without a match), improper `Start` state definitions, or incorrect indentation/blank lines can lead to parsing failures or `textfsm.TextFSMError` exceptions. An empty line after `Value` definitions signals the end of that section.","severity":"gotcha","affected_versions":"All"},{"fix":"Choose the appropriate `Value` option based on your data structure. Use `List` for collecting multiple occurrences of a field within a single record, otherwise, subsequent matches for a `Value` will overwrite previous ones.","message":"Misunderstanding the `Required` option vs. `Filldown`/`Fillup` can lead to unexpected output. `Required` ensures a record is only emitted if the value is present. `Filldown` propagates the last matched value downwards, while `Fillup` propagates the first matched value upwards to fill preceding empty fields.","severity":"gotcha","affected_versions":"All"},{"fix":"Migrate any Python 2 TextFSM usage to Python 3. For new projects, always use Python 3.","message":"While PyPI tags list `Python 2, Python 3` compatibility, modern development and usage of TextFSM (and its ecosystem like `ntc-templates`) strongly recommend Python 3. Older versions like `textfsm==0.4.1` explicitly supported Python 2.x and Python 3.x, but ongoing maintenance primarily targets Python 3 environments.","severity":"deprecated","affected_versions":"<= 2.1.0 (Python 2 compatibility)"},{"fix":"Ensure you are using the correct import path, typically `from textfsm import clitable` (or directly `textfsm.clitable.CliTable`). Review the official TextFSM GitHub repository for the most up-to-date usage of `CliTable`.","message":"The `clitable` module, which provides the `CliTable` utility for loading TextFSM templates from directories, might have had changes in its import path or internal workings in the past. This could lead to `ImportError: cannot import name 'clitable' from 'textfsm'` in projects that directly accessed it.","severity":"breaking","affected_versions":"Prior to 2.x (approx.)"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}