Add group_supernets helper function

[claytonsingh]

Adds a new helper function that groups a sequence of elements into supernets with groups of child subnet elements.

[jstasiak]

Hi @claytonsingh, thank you for the contribution.

I think at the very least we should have some simple but educating doctests in the function documentation (with and without key, ideally) – I had a pretty hard time understanding what the function does until I saw the tests, then it clicked for me.

I have no constructive suggestions for improving the function's description, I'll think about it.

May I ask is there a specific problem this function solves for you? The key parameter suggests you're doing something specific and I'd like to understand the need for it better.

[claytonsingh]

While I cant go into too much detail for NDA reasons.

I have been using this to summarize subnets across multiple device configurations and checking to see what ip's/routes/etc are assigned per subnet. In most cases I dont really care about the most specific networks but what IP space is assigned and what device/interface it is assigned to. Hopefully this gives you a better idea for my use cases.

interfaces = []
re_interface_ip_address = re.compile(r"^ *ip address (\d+\.\d+\.\d+\.\d+) (\d+\.\d+\.\d+\.\d+)")

for filename in glob.glob("./cpe_configs/*.txt"):
    config = ciscoconfparse2.CiscoConfParse(filename, syntax='ios')

    for obj in config.find_objects(re_interface_ip_address):
        if not obj.parent.is_intf: continue
        nwk = netaddr.IPNetwork("{0}/{1}".format(*re_interface_ip_address.match(obj.text).groups()))
        if nwk not in netblocks: continue
        interfaces.add(obj)

interface_networks = dict(group_supernets(interfaces, lambda x: netaddr.IPNetwork("{0}/{1}".format(*re_interface_ip_address.match(x.text).groups()))))

In the example above the returned data would look like.

{
    IPNetwork('10.0.0.2/30'): [<IOSCfgLine # 126>],
    ...
}

As for the description does it help to rephrase in terms of network overlap?

Organizes a series of overlapping elements into groups of non-overlapping networks, with each group containing child subnet elements. These elements may include overlapping IP addresses, subnets, or other objects. The key is a function computing an IPNetwork for each element. If the key is not specified or is set to None, the default action is to convert each element into an IPNetwork.

I honestly have no idea what a good minimal example would be to include in the docs.