Parsergen Module

class genie.parsergen._parsergen.CmdCache

Bases: object

This class holds the CLI command cache and associated cache update logic.

cache = {}
refresh_cache(obj, show_command)

Refresh the cache

Parameters

  • obj (parsergen.oper_check or parsergen.oper_fill_tabular object) – Object that is asking for a cache refresh.

  • show_command (str or tuple) – The show command to execute.

class genie.parsergen._parsergen.Device(name, *args, **kwargs)

Bases: object

Defining a device class to eliminate parsergen dependency on a device object

execute(*args, **kwargs)
is_connected(alias, *args, **kwargs)
genie.parsergen._parsergen.extend(regex_ext=None, show_cmds=None, regex_tags=None)

Allows an external module to extend parsergen’s dictionary of regular expressions, known show commands and regex tags.

parsergen keeps its master regular expression dictionary in the member parsergen._glb_regex, its master show command dictionary in the member parsergen._glb_show_commands and its master regex tag dictionary in the member parsergen._glb_regex_tags.

It is possible to register CLI show commands without specifying any regular expressions, since oper_fill_tabular also uses this CLI tag/command repository to format its CLI commands.

Parameters

  • regex_ext (A dict of dictionaries of regular expressions keyed by OS type and regex tag) – A series of tags (keys) and their corresponding regexes (values). Any regex in this dictionary may also be expressed as a list (this feature allows the same regex tag to match multiple patterns, and is intended on enabling parsers to work correctly across multiple releases across which CLI text may have changed).

  • show_cmds (A dict of dictionaries of str keyed by OS type and generic CLI command tag) – A series of generic CLI command tags (keys) and their corresponding CLI command equivalents (values). The values may contain string formatting characters, including equal signs, as documented in How To Specify Show Commands.

  • regex_tags (A dict of lists of regex tags keyed by OS type) – A series of tags (keys). This allows parsergen to store the original order order the tags were declared. This parameter must be specified in order to make use of the regex_tag_fill_pattern parameter of oper_fill and in order to enable the auto-attrvalpair-reordering feature offered by oper_check.

genie.parsergen._parsergen.extend_markup(marked_up_input)

Allows an external module to extend parsergen’s dictionary of regular expressions , regex tags and known show commands by specifying marked-up show command text (see Core documentation)

This input text is transformed, and then automatically passed to extend.

Parameters

marked_up_input (str) – Marked-up show command input

genie.parsergen._parsergen.get_os_type(device, alias=None)

Get the OS of the given router

genie.parsergen._parsergen.isstr(s)
class genie.parsergen._parsergen.oper_check(device=None, show_command=None, attrvalpairs=None, refresh_cache=False, negate=False, device_conn_alias=None, device_output=None, device_os=None)

Bases: genie.predcore._predcore.Predicate

Optionally run a show command on a device, parse user-requested fields, and compare these fields against expected values.

Create an object to parse and check CLI command output.

Parameters

  • device (Device()) – The device to run the show command on.

  • show_command (str or tuple of (str, list of positional formatting args, dict of keyword formatting args)) – The key into the show command dictionary previously passed to extend or the actual show command to issue. If the corresponding show command dictionary string contains formatting fields, specify these arguments using a tuple. Remember to use None as a placeholder if you are combining default and non-default fields(see How To Specify Show Commands).

  • attrvalpairs (list of tuples (str, str or tuple)) – An ordered list of (attribute/value) pairs. Parsergen must have been taught the relationship between attributes and regular expressions, which is done via the extend API. If a value is expressed as a tuple, then each member of the tuple is considered as a potential match. These pairs are reordered on behalf of the user if all attributes are present in parsergen._glb_regex_tag (which is automatically populated via extend_markup and optionally populated via extend).

  • refresh_cache (bool) – If True, refresh the cache by running the indicated show command on the device, and then parse this output. If False, parse the previously cached show command output for this device. Defaults to True.

  • negate (bool) – If True, negate the result (ie. treat a failure like a success). Defaults to False.

  • device_conn_alias (str) – If specified, assume the device was connected to under the indicated alias. Otherwise, the default alias is assumed. For details, please see http://wwwin-pyats.cisco.com/documentation/latest/connections/manager.html#connection-manager

dump()

Dump the predicate’s internal state for debugging and logging purposes.

error(msg, line=9223372036854775807)
parse()

Perform the parsing and retrieve results.

Returns

Returns True if the parsing was successful. The values passed in as None will be filled in parsergen.ext_dictio[device_name]. Returns False if the parsing failed. The user may obtain a failure analysis by calling python:str on the parsing object.

Return type

bool

process_attrvalpairs(attrvalpairs, os, reorder=True)

Process a list of tuples of attr/value pairs into a form that parsercare can use.

result(result)
test()

Override this method to actually perform the predicate test.

class genie.parsergen._parsergen.oper_fill(device=None, show_command=None, attrvalpairs=None, refresh_cache=False, regex_tag_fill_pattern='', skip=False, device_conn_alias=None, device_output=None, device_os=None)

Bases: genie.parsergen._parsergen.oper_check

Optionally run a show command on a device and parse user-requested fields.

Create an object to parse CLI command output.

Parameters

  • device (Device()) – The device to run the show command on.

  • show_command (str or tuple of (str, list of positional formatting args, dict of keyword formatting args)) – The key into the show command dictionary previously passed to extend or the actual show command to issue. If the corresponding show command dictionary string contains formatting fields, specify these arguments using a tuple. Remember to use None as a placeholder if you are combining default and non-default fields(see How To Specify Show Commands).

  • attrvalpairs (list of tuples (str, str or tuple)) – An ordered list of attribute/value pairs. A value of None requests a fill for that attribute. The very first value cannot be None. Parsergen must have been taught the relationship between attributes and regular expressions, which is done via the extend API. If a value is expressed as a tuple, then each member of the tuple is considered as a potential match.

  • refresh_cache (bool) – If True, refresh the cache by running the indicated show command on the device, and then parse this output. If False, parse the previously cached show command output for this device. Defaults to True.

  • regex_tag_fill_pattern (regular expression) – Regular expression to use to select a group of regex tags to fill. The tags will be added to the attrvalpairs list as (tag, None) in the same order as found in parsergen._glb_regex_tag (which is automatically populated via extend_markup and optionally populated via extend).

  • skip (bool) – Whether or not to ignore unmatched attributes (regex tags). If True, then ignore any attributes (regex tags) whose associated regexes do not match the text to parse. One reason to specify this option could be when the text to parse could contain optional content lines. Defaults to False.

  • device_conn_alias (str) – If specified, assume the device was connected to under the indicated alias. Otherwise, the default alias is assumed. For details, please see http://wwwin-pyats.cisco.com/documentation/latest/connections/manager.html#connection-manager

Warning

If you specify a non-None regex_tag_fill_pattern then ensure none of your (attr, value) pairs have a value of None, otherwise parser failure can result.

Example use to obtain interface state values:

parsergen.oper_fill(R1, 'show interfaces',
            [ ('im.intf-name',       'GigabitEthernet0/0/0/1'),
              ('im.intf-status',      None),
              ('im.intf-line-status', None),
              ('im.intf-mtu',         None),
              ('im.intf-bw',          None),
              ('im.intf-arptype',     None)
            ],
            refresh_cache=True)

The values passed in as None will be filled in parsergen.ext_dictio[device_name].

Note that, in case of output with multiple entries, eg datalist, oper_fill needs a hook in the code in order to target the desired values. For instance, in the above example, it’s using the name of the interfaces to hook into that section of the output.

This class may not be the best choice to parse tabular data.

Note

Please consider using the oper_fill_tabular class for parsing tabular results as it is generally far easier. For output that contains both tabular and non-tabular data, it is also possible to use both mechanisms to parse different parts of the output.

Example of accessing the filled in values:

>>> parsergen.ext_dictio[R1.name]['im.intf-line-status'] 
'Up'
>>> parsergen.ext_dictio[R1.name]['im.intf-mtu']         
'1500'
class genie.parsergen._parsergen.oper_fill_tabular(device=None, show_command=None, refresh_cache=True, header_fields=None, table_terminal_pattern=None, index=0, skip_header=None, table_title_pattern=None, right_justified=False, label_fields=None, is_run_command=False, skip_line=None, device_conn_alias=None, device_output=None, device_os=None, delimiter='')

Bases: genie.parsergen.core.column_table_result_core_t

Class that parses tabular “show” command output.

Example:

show_command_output_example = '''
    RP/0/0/CPU0:one#show rib clients
    Thu Sep 17 11:41:18.164 EDT
    Process              Location         Client ID  Redist   Proto
    bcdl_agent           node0_0_CPU0     0          insync   no
'''

from genie.parsergen import oper_fill_tabular
res = oper_fill_tabular(
    device=device1,
    show_command="show rib clients",
    header_fields =
        ["Process", "Location", "Client ID", "Redist", "Proto"])
print res.entries['bcdl_agent']['Location']

will print node0_0_CPU0

set second_show_command_output_example '''
RP/0/0/CPU0:one#show isis topology level 1
Sat Sep 19 14:46:33.902 EDT

IS-IS ring paths to IPv4 Unicast (Level-1) routers
System Id       Metric  Next-Hop        Interface       SNPA
one             --
two             10      two             Gi0/0/0/0       *PtoP*
two             10      two             Gi0/0/0/1       02db.ebba.ecc4
three           20      two             Gi0/0/0/0       *PtoP*
three           20      two             Gi0/0/0/1       02db.ebba.ecc4
'''

res = oper_fill_tabular ( device=device1,
                          show_command="show isis topology level 1",
                          header_fields=
                              ["System Id", "Metric", "Next-Hop",
                               "Interface", "SNPA"],
                             index=[0,3])
print res.entries['three']['Gi0/0/0/1']['SNPA']

will print 02db.ebba.ecc4

print res.entries['one']['']['Metric']

will print --

Note

The tabular parsing behavior may be customized via subclassing. Please refer to Use of Subclassing with the Tabular Parser and tabular_parser_subclass.py for examples.

Creates a results object that parses tabular “show” command output.

Returns

Parsed results are obtained by using the column positions of the header field. The entry starts with the column of the first header character and ends just prior to the next header column.

The object returned has a dictionary named entries which is keyed by the entry value corresponding to the header at index. Each key in entries is indexed by the corresponding header_fields name (or label_fields name if specified).

Parameters

  • device (Device()) – The device to run the show command on.

  • device_conn_alias (str) – If specified, assume the device was connected to under the indicated alias. Otherwise, the default alias is assumed. For details, please see https://developer.cisco.com/docs/pyats/ ConnectionMeta - > Connection Manager

  • show_command (str or tuple of (str, list of positional formatting args, dict of keyword formatting args)) – The key into the show command dictionary previously passed to extend or the actual show command to issue. If the corresponding show command dictionary string contains formatting fields, specify these arguments using a tuple.

  • refresh_cache (bool) – If True, refresh the cache by running the indicated show command on the device again, and then parse this output. If False, parse the previously cached show command output. Defaults to True.

  • header_fields (list of str) – List of column headings to parse. If not specified, it must be provided via a subclass via get_init_info.

  • table_terminal_pattern (str) – If specified, this is the pattern to terminate the search for results.

  • index (int or list of int) – Defaults to the first field (0). If more fields are required to guarantee uniqueness pass a list of indices in index and that many dictionaries will be returned keyed by the given field values at those indices.

  • skip_header (str) – If specified, then the input between the header fields and this pattern are skipped before entries are looked for.

  • table_title_pattern (str) – If specified, this pattern allows multiple tables to be identified. Results will be a dictionary of matches keyed on group('Title') of the regex. (e.g., a pattern like r'(?P<Title>Port (\w+))' would match "Port GigabitEthernet_0_0_0_0 ..." and the key would be 'GigabitEthernet_0_0_0_0').

  • right_justified (bool) – If True, then the header labels are considered right justified. Defaults to False.

  • label_fields (list of str) – If specified, then the entries object will contain these keys instead of those specified in header_fields. There must be a corresponding entry in label_fields for each entry in header_fields.

  • skip_line (str) – If specified, then any line matching this pattern will be skipped.

  • delimiter (str) – Table delimiter pattern that allows for columns’ borders identification.