def _parse_version_line(descriptor, entries):
  value = _value('version', entries)

  if value.isdigit():
    descriptor.version = int(value)
  else:
    raise ValueError('version line must have a positive integer value: %s' % value)

def _parse_geoip_to_count_line(keyword, attribute, descriptor, entries):
  # "<keyword>" CC=N,CC=N,...
  #
  # The maxmind geoip (https://www.maxmind.com/app/iso3166) has numeric
  # locale codes for some special values, for instance...
  #   A1,"Anonymous Proxy"
  #   A2,"Satellite Provider"
  #   ??,"Unknown"

  value, locale_usage = _value(keyword, entries), {}
  error_msg = 'Entries in %s line should only be CC=N entries: %s %s' % (keyword, keyword, value)

  if value:
    for entry in value.split(','):
      if '=' not in entry:
        raise ValueError(error_msg)

      locale, count = entry.split('=', 1)

      if _locale_re.match(locale) and count.isdigit():
        locale_usage[locale] = int(count)
      else:
        raise ValueError(error_msg)

  setattr(descriptor, attribute, locale_usage)

def _parse_hs_stats(keyword, stat_attribute, extra_attribute, descriptor, entries):
  # "<keyword>" num key=val key=val...

  value, stat, extra = _value(keyword, entries), None, {}

  if value is not None:
    value_comp = value.split()

    if not value_comp:
      raise ValueError("'%s' line was blank" % keyword)

    try:
      stat = int(value_comp[0])
    except ValueError:
      raise ValueError("'%s' stat was non-numeric (%s): %s %s" % (keyword, value_comp[0], keyword, value))

    for entry in value_comp[1:]:
      if '=' not in entry:
        raise ValueError('Entries after the stat in %s lines should only be key=val entries: %s %s' % (keyword, keyword, value))

      key, val = entry.split('=', 1)
      extra[key] = val

  setattr(descriptor, stat_attribute, stat)
  setattr(descriptor, extra_attribute, extra)

def _parse_w_line(descriptor, entries):
  # "w" "Bandwidth=" INT ["Measured=" INT] ["Unmeasured=1"]
  # example: w Bandwidth=7980

  value = _value('w', entries)
  w_comp = value.split(' ')

  if len(w_comp) < 1:
    raise ValueError("%s 'w' line is blank: w %s" % (descriptor._name(), value))
  elif not w_comp[0].startswith('Bandwidth='):
    raise ValueError("%s 'w' line needs to start with a 'Bandwidth=' entry: w %s" % (descriptor._name(), value))

  for w_entry in w_comp:
    if '=' in w_entry:
      w_key, w_value = w_entry.split('=', 1)
    else:
      w_key, w_value = w_entry, None

    if w_key == 'Bandwidth':
      if not (w_value and w_value.isdigit()):
        raise ValueError("%s 'Bandwidth=' entry needs to have a numeric value: w %s" % (descriptor._name(), value))

      descriptor.bandwidth = int(w_value)
    elif w_key == 'Measured':
      if not (w_value and w_value.isdigit()):
        raise ValueError("%s 'Measured=' entry needs to have a numeric value: w %s" % (descriptor._name(), value))

      descriptor.measured = int(w_value)
    elif w_key == 'Unmeasured':
      if w_value != '1':
        raise ValueError("%s 'Unmeasured=' should only have the value of '1': w %s" % (descriptor._name(), value))

      descriptor.is_unmeasured = True
    else:
      descriptor.unrecognized_bandwidth_entries.append(w_entry)

def _parse_hidden_service_dir_line(descriptor, entries):
  value = _value('hidden-service-dir', entries)

  if value:
    descriptor.hidden_service_dir = value.split(' ')
  else:
    descriptor.hidden_service_dir = ['2']

def _parse_dirreq_line(keyword, recognized_counts_attr, unrecognized_counts_attr, descriptor, entries):
  value = _value(keyword, entries)

  recognized_counts = {}
  unrecognized_counts = {}

  is_response_stats = keyword in ('dirreq-v2-resp', 'dirreq-v3-resp')
  key_set = DirResponse if is_response_stats else DirStat

  key_type = 'STATUS' if is_response_stats else 'STAT'
  error_msg = '%s lines should contain %s=COUNT mappings: %s %s' % (keyword, key_type, keyword, value)

  if value:
    for entry in value.split(','):
      if '=' not in entry:
        raise ValueError(error_msg)

      status, count = entry.split('=', 1)

      if count.isdigit():
        if status in key_set:
          recognized_counts[status] = int(count)
        else:
          unrecognized_counts[status] = int(count)
      else:
        raise ValueError(error_msg)

  setattr(descriptor, recognized_counts_attr, recognized_counts)
  setattr(descriptor, unrecognized_counts_attr, unrecognized_counts)

def _parse_extrainfo_digest_line(descriptor, entries):
  value = _value('extra-info-digest', entries)
  value = value.split(' ')[0]  # lines have additional content from propsal 228, waiting for it to be documented: #16227

  if not stem.util.tor_tools.is_hex_digits(value, 40):
    raise ValueError('extra-info-digest should be 40 hex characters: %s' % value)

  descriptor.extra_info_digest = value

def _parse_hibernating_line(descriptor, entries):
  # "hibernating" 0|1 (in practice only set if one)

  value = _value('hibernating', entries)

  if value not in ('0', '1'):
    raise ValueError('Hibernating line had an invalid value, must be zero or one: %s' % value)

  descriptor.hibernating = value == '1'

def _parse_id_line(descriptor, entries):
  value = _value('id', entries)
  value_comp = value.split()

  if len(value_comp) >= 2:
    descriptor.identifier_type = value_comp[0]
    descriptor.identifier = value_comp[1]
  else:
    raise ValueError("'id' lines should contain both the key type and digest: id %s" % value)

def _parse_extrainfo_digest_line(descriptor, entries):
  value = _value('extra-info-digest', entries)
  digest_comp = value.split(' ')

  if not stem.util.tor_tools.is_hex_digits(digest_comp[0], 40):
    raise ValueError('extra-info-digest should be 40 hex characters: %s' % digest_comp[0])

  descriptor.extra_info_digest = digest_comp[0]
  descriptor.extra_info_sha256_digest = digest_comp[1] if len(digest_comp) >= 2 else None

def _parse_protocols_line(descriptor, entries):
  value = _value('protocols', entries)
  protocols_match = re.match('^Link (.*) Circuit (.*)$', value)

  if not protocols_match:
    raise ValueError('Protocols line did not match the expected pattern: protocols %s' % value)

  link_versions, circuit_versions = protocols_match.groups()
  descriptor.link_protocols = link_versions.split(' ')
  descriptor.circuit_protocols = circuit_versions.split(' ')

def _parse_p_line(descriptor, entries):
  # "p" ("accept" / "reject") PortList
  # p reject 1-65535
  # example: p accept 80,110,143,443,993,995,6660-6669,6697,7000-7001

  value = _value('p', entries)

  try:
    descriptor.exit_policy = stem.exit_policy.MicroExitPolicy(value)
  except ValueError as exc:
    raise ValueError('%s exit policy is malformed (%s): p %s' % (descriptor._name(), exc, value))

def _parse_dirreq_share_line(keyword, attribute, descriptor, entries):
  value = _value(keyword, entries)

  if not value.endswith('%'):
    raise ValueError('%s lines should be a percentage: %s %s' % (keyword, keyword, value))
  elif float(value[:-1]) < 0:
    raise ValueError('Negative percentage value: %s %s' % (keyword, value))

  # bug means it might be above 100%: https://lists.torproject.org/pipermail/tor-dev/2012-June/003679.html

  setattr(descriptor, attribute, float(value[:-1]) / 100)

def _parse_cell_circuits_per_decline_line(descriptor, entries):
  # "cell-circuits-per-decile" num

  value = _value('cell-circuits-per-decile', entries)

  if not value.isdigit():
    raise ValueError('Non-numeric cell-circuits-per-decile value: %s' % value)
  elif int(value) < 0:
    raise ValueError('Negative cell-circuits-per-decile value: %s' % value)

  descriptor.cell_circuits_per_decile = int(value)

def _parse_protocol_versions_line(descriptor, entries):
  value = _value('protocol-versions', entries)

  try:
    versions = [int(entry) for entry in value.split(',')]
  except ValueError:
    raise ValueError('protocol-versions line has non-numeric versoins: protocol-versions %s' % value)

  for v in versions:
    if v <= 0:
      raise ValueError('protocol-versions must be positive integers: %s' % value)

  descriptor.protocol_versions = versions

def _parse_s_line(descriptor, entries):
  # "s" Flags
  # example: s Named Running Stable Valid

  value = _value('s', entries)
  flags = [] if value == '' else value.split(' ')
  descriptor.flags = flags

  for flag in flags:
    if flags.count(flag) > 1:
      raise ValueError('%s had duplicate flags: s %s' % (descriptor._name(), value))
    elif flag == '':
      raise ValueError("%s had extra whitespace on its 's' line: s %s" % (descriptor._name(), value))

def _parse_w_line(descriptor, entries):
    # "w" "Bandwidth=" INT ["Measured=" INT] ["Unmeasured=1"]
    # example: w Bandwidth=7980

    value = _value("w", entries)
    w_comp = value.split(" ")

    if len(w_comp) < 1:
        raise ValueError("%s 'w' line is blank: w %s" % (descriptor._name(), value))
    elif not w_comp[0].startswith("Bandwidth="):
        raise ValueError("%s 'w' line needs to start with a 'Bandwidth=' entry: w %s" % (descriptor._name(), value))

    bandwidth = None
    measured = None
    is_unmeasured = False
    unrecognized_bandwidth_entries = []

    for w_entry in w_comp:
        if "=" in w_entry:
            w_key, w_value = w_entry.split("=", 1)
        else:
            w_key, w_value = w_entry, None

        if w_key == "Bandwidth":
            if not (w_value and w_value.isdigit()):
                raise ValueError(
                    "%s 'Bandwidth=' entry needs to have a numeric value: w %s" % (descriptor._name(), value)
                )

            bandwidth = int(w_value)
        elif w_key == "Measured":
            if not (w_value and w_value.isdigit()):
                raise ValueError(
                    "%s 'Measured=' entry needs to have a numeric value: w %s" % (descriptor._name(), value)
                )

            measured = int(w_value)
        elif w_key == "Unmeasured":
            if w_value != "1":
                raise ValueError(
                    "%s 'Unmeasured=' should only have the value of '1': w %s" % (descriptor._name(), value)
                )

            is_unmeasured = True
        else:
            unrecognized_bandwidth_entries.append(w_entry)

    descriptor.bandwidth = bandwidth
    descriptor.measured = measured
    descriptor.is_unmeasured = is_unmeasured
    descriptor.unrecognized_bandwidth_entries = unrecognized_bandwidth_entries

def _parse_r_line(descriptor, entries):
  # Parses a RouterStatusEntry's 'r' line. They're very nearly identical for
  # all current entry types (v2, v3, and microdescriptor v3) with one little
  # wrinkle: only the microdescriptor flavor excludes a 'digest' field.
  #
  # For v2 and v3 router status entries:
  #   "r" nickname identity digest publication IP ORPort DirPort
  #   example: r mauer BD7xbfsCFku3+tgybEZsg8Yjhvw itcuKQ6PuPLJ7m/Oi928WjO2j8g 2012-06-22 13:19:32 80.101.105.103 9001 0
  #
  # For v3 microdescriptor router status entries:
  #   "r" nickname identity publication IP ORPort DirPort
  #   example: r Konata ARIJF2zbqirB9IwsW0mQznccWww 2012-09-24 13:40:40 69.64.48.168 9001 9030

  value = _value('r', entries)
  include_digest = not isinstance(descriptor, RouterStatusEntryMicroV3)

  r_comp = value.split(' ')

  # inject a None for the digest to normalize the field positioning
  if not include_digest:
    r_comp.insert(2, None)

  if len(r_comp) < 8:
    expected_field_count = 'eight' if include_digest else 'seven'
    raise ValueError("%s 'r' line must have %s values: r %s" % (descriptor._name(), expected_field_count, value))

  if not stem.util.tor_tools.is_valid_nickname(r_comp[0]):
    raise ValueError("%s nickname isn't valid: %s" % (descriptor._name(), r_comp[0]))
  elif not stem.util.connection.is_valid_ipv4_address(r_comp[5]):
    raise ValueError("%s address isn't a valid IPv4 address: %s" % (descriptor._name(), r_comp[5]))
  elif not stem.util.connection.is_valid_port(r_comp[6]):
    raise ValueError('%s ORPort is invalid: %s' % (descriptor._name(), r_comp[6]))
  elif not stem.util.connection.is_valid_port(r_comp[7], allow_zero = True):
    raise ValueError('%s DirPort is invalid: %s' % (descriptor._name(), r_comp[7]))

  descriptor.nickname = r_comp[0]
  descriptor.fingerprint = _base64_to_hex(r_comp[1])

  if include_digest:
    descriptor.digest = _base64_to_hex(r_comp[2])

  descriptor.address = r_comp[5]
  descriptor.or_port = int(r_comp[6])
  descriptor.dir_port = None if r_comp[7] == '0' else int(r_comp[7])

  try:
    published = '%s %s' % (r_comp[3], r_comp[4])
    descriptor.published = stem.util.str_tools._parse_timestamp(published)
  except ValueError:
    raise ValueError("Publication time time wasn't parsable: r %s" % value)

def _parse_extra_info_line(descriptor, entries):
  # "extra-info" Nickname Fingerprint

  value = _value('extra-info', entries)
  extra_info_comp = value.split()

  if len(extra_info_comp) < 2:
    raise ValueError('Extra-info line must have two values: extra-info %s' % value)
  elif not stem.util.tor_tools.is_valid_nickname(extra_info_comp[0]):
    raise ValueError("Extra-info line entry isn't a valid nickname: %s" % extra_info_comp[0])
  elif not stem.util.tor_tools.is_valid_fingerprint(extra_info_comp[1]):
    raise ValueError('Tor relay fingerprints consist of forty hex digits: %s' % extra_info_comp[1])

  descriptor.nickname = extra_info_comp[0]
  descriptor.fingerprint = extra_info_comp[1]

def _parse_history_line(keyword, history_end_attribute, history_interval_attribute, history_values_attribute, descriptor, entries):
  value = _value(keyword, entries)
  timestamp, interval, remainder = stem.descriptor.extrainfo_descriptor._parse_timestamp_and_interval(keyword, value)

  try:
    if remainder:
      history_values = [int(entry) for entry in remainder.split(',')]
    else:
      history_values = []
  except ValueError:
    raise ValueError('%s line has non-numeric values: %s %s' % (keyword, keyword, value))

  setattr(descriptor, history_end_attribute, timestamp)
  setattr(descriptor, history_interval_attribute, interval)
  setattr(descriptor, history_values_attribute, history_values)