Search for BGP neighbors details in the mines of the ``bgp.neighbors`` function.

    Arguments:

    asns
        A list of AS numbers to search for.
        The runner will return only the neighbors of these AS numbers.

    device
        Filter by device name (minion ID).

    ip
        Search BGP neighbor using the IP address.
        In multi-VRF environments, the same IP address could be used by
        more than one neighbors, in different routing tables.

    network
        Search neighbors within a certain IP network.

    title
        Custom title.

    display: ``True``
        Display on the screen or return structured object? Default: ``True`` (return on the CLI).

    outputter: ``table``
        Specify the outputter name when displaying on the CLI. Default: :mod:`table <salt.output.table_out>`.

    In addition, any field from the output of the ``neighbors`` function
    from the :mod:`NAPALM BGP module <salt.modules.napalm_bgp.neighbors>` can be used as a filter.

    CLI Example:

    .. code-block:: bash

        salt-run bgp.neighbors 13335 15169
        salt-run bgp.neighbors 13335 ip=172.17.19.1
        salt-run bgp.neighbors multipath=True
        salt-run bgp.neighbors up=False export_policy=my-export-policy multihop=False
        salt-run bgp.neighbors network=192.168.0.0/16

    Output example:

    .. code-block:: text

        BGP Neighbors for 13335, 15169
        ________________________________________________________________________________________________________________________________________________________________
        |    Device    | AS Number |         Neighbor Address        | State|#Active/Received/Accepted/Damped |         Policy IN         |         Policy OUT         |
        ________________________________________________________________________________________________________________________________________________________________
        | edge01.bjm01 |   13335   |          172.17.109.11          |        Established 0/398/398/0         |       import-policy       |        export-policy       |
        ________________________________________________________________________________________________________________________________________________________________
        | edge01.bjm01 |   13335   |          172.17.109.12          |       Established 397/398/398/0        |       import-policy       |        export-policy       |
        ________________________________________________________________________________________________________________________________________________________________
        | edge01.flw01 |   13335   |          192.168.172.11         |        Established 1/398/398/0         |       import-policy       |        export-policy       |
        ________________________________________________________________________________________________________________________________________________________________
        | edge01.oua01 |   13335   |          172.17.109.17          |          Established 0/0/0/0           |       import-policy       |        export-policy       |
        ________________________________________________________________________________________________________________________________________________________________
        | edge01.bjm01 |   15169   |             2001::1             |       Established 102/102/102/0        |       import-policy       |        export-policy       |
        ________________________________________________________________________________________________________________________________________________________________
        | edge01.bjm01 |   15169   |             2001::2             |       Established 102/102/102/0        |       import-policy       |        export-policy       |
        ________________________________________________________________________________________________________________________________________________________________
        | edge01.tbg01 |   13335   |          192.168.172.17         |          Established 0/1/1/0           |       import-policy       |        export-policy       |
        ________________________________________________________________________________________________________________________________________________________________

def neighbors(*asns, **kwargs):
    '''
    Search for BGP neighbors details in the mines of the ``bgp.neighbors`` function.

    Arguments:

    asns
        A list of AS numbers to search for.
        The runner will return only the neighbors of these AS numbers.

    device
        Filter by device name (minion ID).

    ip
        Search BGP neighbor using the IP address.
        In multi-VRF environments, the same IP address could be used by
        more than one neighbors, in different routing tables.

    network
        Search neighbors within a certain IP network.

    title
        Custom title.

    display: ``True``
        Display on the screen or return structured object? Default: ``True`` (return on the CLI).

    outputter: ``table``
        Specify the outputter name when displaying on the CLI. Default: :mod:`table <salt.output.table_out>`.

    In addition, any field from the output of the ``neighbors`` function
    from the :mod:`NAPALM BGP module <salt.modules.napalm_bgp.neighbors>` can be used as a filter.

    CLI Example:

    .. code-block:: bash

        salt-run bgp.neighbors 13335 15169
        salt-run bgp.neighbors 13335 ip=172.17.19.1
        salt-run bgp.neighbors multipath=True
        salt-run bgp.neighbors up=False export_policy=my-export-policy multihop=False
        salt-run bgp.neighbors network=192.168.0.0/16

    Output example:

    .. code-block:: text

        BGP Neighbors for 13335, 15169
        ________________________________________________________________________________________________________________________________________________________________
        |    Device    | AS Number |         Neighbor Address        | State|#Active/Received/Accepted/Damped |         Policy IN         |         Policy OUT         |
        ________________________________________________________________________________________________________________________________________________________________
        | edge01.bjm01 |   13335   |          172.17.109.11          |        Established 0/398/398/0         |       import-policy       |        export-policy       |
        ________________________________________________________________________________________________________________________________________________________________
        | edge01.bjm01 |   13335   |          172.17.109.12          |       Established 397/398/398/0        |       import-policy       |        export-policy       |
        ________________________________________________________________________________________________________________________________________________________________
        | edge01.flw01 |   13335   |          192.168.172.11         |        Established 1/398/398/0         |       import-policy       |        export-policy       |
        ________________________________________________________________________________________________________________________________________________________________
        | edge01.oua01 |   13335   |          172.17.109.17          |          Established 0/0/0/0           |       import-policy       |        export-policy       |
        ________________________________________________________________________________________________________________________________________________________________
        | edge01.bjm01 |   15169   |             2001::1             |       Established 102/102/102/0        |       import-policy       |        export-policy       |
        ________________________________________________________________________________________________________________________________________________________________
        | edge01.bjm01 |   15169   |             2001::2             |       Established 102/102/102/0        |       import-policy       |        export-policy       |
        ________________________________________________________________________________________________________________________________________________________________
        | edge01.tbg01 |   13335   |          192.168.172.17         |          Established 0/1/1/0           |       import-policy       |        export-policy       |
        ________________________________________________________________________________________________________________________________________________________________
    '''
    opts = _get_bgp_runner_opts()
    title = kwargs.pop('title', None)
    display = kwargs.pop('display', opts['display'])
    outputter = kwargs.pop('outputter', opts['outputter'])

    # cleaning up the kwargs
    # __pub args not used in this runner (yet)
    kwargs_copy = {}
    kwargs_copy.update(kwargs)
    for karg, _ in six.iteritems(kwargs_copy):
        if karg.startswith('__pub'):
            kwargs.pop(karg)
    if not asns and not kwargs:
        if display:
            print('Please specify at least an AS Number or an output filter')
        return []
    device = kwargs.pop('device', None)
    neighbor_ip = kwargs.pop('ip', None)
    ipnet = kwargs.pop('network', None)
    ipnet_obj = IPNetwork(ipnet) if ipnet else None
    # any other key passed on the CLI can be used as a filter

    rows = []
    # building the labels
    labels = {}
    for field in opts['return_fields']:
        if field in _DEFAULT_LABELS_MAPPING:
            labels[field] = _DEFAULT_LABELS_MAPPING[field]
        else:
            # transform from 'previous_connection_state' to 'Previous Connection State'
            labels[field] = ' '.join(map(lambda word: word.title(), field.split('_')))
    display_fields = list(set(opts['return_fields']) - set(_DEFAULT_INCLUDED_FIELDS))
    get_bgp_neighbors_all = _get_mine(opts=opts)

    if not title:
        title_parts = []
        if asns:
            title_parts.append('BGP Neighbors for {asns}'.format(
                asns=', '.join([six.text_type(asn) for asn in asns])
            ))
        if neighbor_ip:
            title_parts.append('Selecting neighbors having the remote IP address: {ipaddr}'.format(ipaddr=neighbor_ip))
        if ipnet:
            title_parts.append('Selecting neighbors within the IP network: {ipnet}'.format(ipnet=ipnet))
        if kwargs:
            title_parts.append('Searching for BGP neighbors having the attributes: {attrmap}'.format(
                attrmap=', '.join(map(lambda key: '{key}={value}'.format(key=key, value=kwargs[key]), kwargs))
            ))
        title = '\n'.join(title_parts)
    for minion, get_bgp_neighbors_minion in six.iteritems(get_bgp_neighbors_all):  # pylint: disable=too-many-nested-blocks
        if not get_bgp_neighbors_minion.get('result'):
            continue  # ignore empty or failed mines
        if device and minion != device:
            # when requested to display only the neighbors on a certain device
            continue
        get_bgp_neighbors_minion_out = get_bgp_neighbors_minion.get('out', {})
        for vrf, vrf_bgp_neighbors in six.iteritems(get_bgp_neighbors_minion_out):  # pylint: disable=unused-variable
            for asn, get_bgp_neighbors_minion_asn in six.iteritems(vrf_bgp_neighbors):
                if asns and asn not in asns:
                    # if filtering by AS number(s),
                    # will ignore if this AS number key not in that list
                    # and continue the search
                    continue
                for neighbor in get_bgp_neighbors_minion_asn:
                    if kwargs and not _compare_match(kwargs, neighbor):
                        # requested filtering by neighbors stats
                        # but this one does not correspond
                        continue
                    if neighbor_ip and neighbor_ip != neighbor.get('remote_address'):
                        # requested filtering by neighbors IP addr
                        continue
                    if ipnet_obj and neighbor.get('remote_address'):
                        neighbor_ip_obj = IPAddress(neighbor.get('remote_address'))
                        if neighbor_ip_obj not in ipnet_obj:
                            # Neighbor not in this network
                            continue
                    row = {
                        'device': minion,
                        'neighbor_address': neighbor.get('remote_address'),
                        'as_number': asn
                    }
                    if 'vrf' in display_fields:
                        row['vrf'] = vrf
                    if 'connection_stats' in display_fields:
                        connection_stats = '{state} {active}/{received}/{accepted}/{damped}'.format(
                            state=neighbor.get('connection_state', -1),
                            active=neighbor.get('active_prefix_count', -1),
                            received=neighbor.get('received_prefix_count', -1),
                            accepted=neighbor.get('accepted_prefix_count', -1),
                            damped=neighbor.get('suppressed_prefix_count', -1),
                        )
                        row['connection_stats'] = connection_stats
                    if 'interface_description' in display_fields or 'interface_name' in display_fields:
                        net_find = __salt__['net.interfaces'](device=minion,
                                                              ipnet=neighbor.get('remote_address'),
                                                              display=False)
                        if net_find:
                            if 'interface_description' in display_fields:
                                row['interface_description'] = net_find[0]['interface_description']
                            if 'interface_name' in display_fields:
                                row['interface_name'] = net_find[0]['interface']
                        else:
                            # if unable to find anything, leave blank
                            if 'interface_description' in display_fields:
                                row['interface_description'] = ''
                            if 'interface_name' in display_fields:
                                row['interface_name'] = ''
                    for field in display_fields:
                        if field in neighbor:
                            row[field] = neighbor[field]
                    rows.append(row)
    return _display_runner(rows, labels, title, display=display, outputter=outputter)