docs: 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)