Router Status Entries
*********************

Parsing for router status entries, the information for individual
routers within a network status document. This information is provided
from a few sources…

* control port via ‘GETINFO ns/*’ and ‘GETINFO md/*’ queries

* router entries in a network status document, like the cached-
  consensus

**Module Overview:**

   RouterStatusEntry - Common parent for router status entries
     |- RouterStatusEntryV2 - Entry for a network status v2 document
     |   +- RouterStatusEntryBridgeV2 - Entry for a bridge flavored v2 document
     |
     |- RouterStatusEntryV3 - Entry for a network status v3 document
     +- RouterStatusEntryMicroV3 - Entry for a microdescriptor flavored v3 document

class stem.descriptor.router_status_entry.RouterStatusEntry(content, validate=False, document=None)

   Bases: "stem.descriptor.Descriptor"

   Information about an individual router stored within a network
   status document. This is the common parent for concrete status
   entry types.

   Variables:
      * **document**
        (*stem.descriptor.networkstatus.NetworkStatusDocument*) –
        ***** document that this descriptor came from

      * **nickname** (*str*) – ***** router’s nickname

      * **fingerprint** (*str*) – ***** router’s fingerprint

      * **published** (*datetime*) – ***** router’s publication

      * **address** (*str*) – ***** router’s IP address

      * **or_port** (*int*) – ***** router’s ORPort

      * **dir_port** (*int*) – ***** router’s DirPort

      * **flags** (*list*) – ***** list of "Flag" associated with
        the relay

      * **version** (*stem.version.Version*) – parsed version of
        tor, this is **None** if the relay’s using a new versioning
        scheme

      * **version_line** (*str*) – versioning information reported
        by the relay

   classmethod from_str(content, **kwargs)

      Provides a "Descriptor" for the given content.

      To parse a descriptor we must know its type. There are three
      ways to convey this…

         # use a descriptor_type argument
         desc = Descriptor.from_str(content, descriptor_type = 'server-descriptor 1.0')

         # prefixing the content with a "@type" annotation
         desc = Descriptor.from_str('@type server-descriptor 1.0\n' + content)

         # use this method from a subclass
         desc = stem.descriptor.server_descriptor.RelayDescriptor.from_str(content)

      New in version 1.8.0.

      Parameters:
         * **content** (*str**,**bytes*) – string to construct the
           descriptor from

         * **multiple** (*bool*) – if provided with **True** this
           provides a list of descriptors rather than a single one

         * **kwargs** (*dict*) – additional arguments for
           "parse_file()"

      Returns:
         "Descriptor" subclass for the given content, or a **list** of
         descriptors if **multiple = True** is provided

      Raises:
         * **ValueError** if the contents is malformed and validate
           is True

         * **TypeError** if we can’t match the contents of the file
           to a descriptor type

         * **IOError** if unable to read from the descriptor_file

class stem.descriptor.router_status_entry.RouterStatusEntryV2(content, validate=False, document=None)

   Bases: "stem.descriptor.router_status_entry.RouterStatusEntry"

   Information about an individual router stored within a version 2
   network status document.

   Variables:
      **digest** (*str*) – ***** router’s upper-case hex digest

   ***** attribute is either required when we’re parsed with
   validation or has a default value, others are left as **None** if
   undefined

   TYPE_ANNOTATION_NAME = 'network-status-consensus-2'

   classmethod content(attr=None, exclude=(), sign=False)

      Creates descriptor content with the given attributes. Mandatory
      fields are filled with dummy information unless data is
      supplied. This doesn’t yet create a valid signature.

      New in version 1.6.0.

      Parameters:
         * **attr** (*dict*) – keyword/value mappings to be included
           in the descriptor

         * **exclude** (*list*) – mandatory keywords to exclude from
           the descriptor, this results in an invalid descriptor

         * **sign** (*bool*) – includes cryptographic signatures and
           digests if True

      Returns:
         **str** with the content of a descriptor

      Raises:
         * **ImportError** if cryptography is unavailable and sign
           is True

         * **NotImplementedError** if not implemented for this
           descriptor type

class stem.descriptor.router_status_entry.RouterStatusEntryBridgeV2(content, validate=False, document=None)

   Bases: "stem.descriptor.router_status_entry.RouterStatusEntryV2"

   Information about an individual router stored within a bridge
   flavored version 2 network status document.

   New in version 1.8.0.

   TYPE_ANNOTATION_NAME = 'bridge-network-status'

class stem.descriptor.router_status_entry.RouterStatusEntryV3(content, validate=False, document=None)

   Bases: "stem.descriptor.router_status_entry.RouterStatusEntry"

   Information about an individual router stored within a version 3
   network status document.

   Variables:
      * **or_addresses** (*list*) – ***** relay’s OR addresses, this
        is a tuple listing of the form (address (**str**), port
        (**int**), is_ipv6 (**bool**))

      * **identifier_type** (*str*) – identity digest key type

      * **identifier** (*str*) – base64 encoded identity digest

      * **digest** (*str*) – ***** router’s upper-case hex digest

      * **bandwidth** (*int*) – bandwidth measured to be available
        by the relay, this is an arbitrary units (currently kilobytes
        per second) heuristic generated by the Bandwidth authoritites
        to weight relay selection

      * **measured** (*int*) – *bandwidth* vote provided by a
        bandwidth authority

      * **is_unmeasured** (*bool*) – *bandwidth* measurement isn’t
        based on three or more measurements

      * **unrecognized_bandwidth_entries** (*list*) – *****
        bandwidth weighting information that isn’t yet recognized

      * **exit_policy** (*stem.exit_policy.MicroExitPolicy*) –
        router’s exit policy

      * **protocols** (*dict*) – mapping of protocols to their
        supported versions

      * **microdescriptor_hashes** (*list*) – ***** tuples of two
        values, the list of consensus methods for generating a set of
        digests and the ‘algorithm => digest’ mappings

   ***** attribute is either required when we’re parsed with
   validation or has a default value, others are left as **None** if
   undefined

   Changed in version 1.5.0: Added the identifier and identifier_type
   attributes.

   Changed in version 1.6.0: Added the protocols attribute.

   TYPE_ANNOTATION_NAME = 'network-status-consensus-3'

   classmethod content(attr=None, exclude=(), sign=False)

      Creates descriptor content with the given attributes. Mandatory
      fields are filled with dummy information unless data is
      supplied. This doesn’t yet create a valid signature.

      New in version 1.6.0.

      Parameters:
         * **attr** (*dict*) – keyword/value mappings to be included
           in the descriptor

         * **exclude** (*list*) – mandatory keywords to exclude from
           the descriptor, this results in an invalid descriptor

         * **sign** (*bool*) – includes cryptographic signatures and
           digests if True

      Returns:
         **str** with the content of a descriptor

      Raises:
         * **ImportError** if cryptography is unavailable and sign
           is True

         * **NotImplementedError** if not implemented for this
           descriptor type

class stem.descriptor.router_status_entry.RouterStatusEntryMicroV3(content, validate=False, document=None)

   Bases: "stem.descriptor.router_status_entry.RouterStatusEntry"

   Information about an individual router stored within a
   microdescriptor flavored network status document.

   Variables:
      * **or_addresses** (*list*) – ***** relay’s OR addresses, this
        is a tuple listing of the form (address (**str**), port
        (**int**), is_ipv6 (**bool**))

      * **bandwidth** (*int*) – bandwidth claimed by the relay (in
        kb/s)

      * **measured** (*int*) – bandwidth measured to be available by
        the relay

      * **is_unmeasured** (*bool*) – bandwidth measurement isn’t
        based on three or more measurements

      * **unrecognized_bandwidth_entries** (*list*) – *****
        bandwidth weighting information that isn’t yet recognized

      * **protocols** (*dict*) – mapping of protocols to their
        supported versions

      * **digest** (*str*) – ***** router’s hex encoded digest of
        our corresponding microdescriptor (**deprecated**, use
        microdescriptor_digest instead)

      * **microdescriptor_digest** (*str*) – ***** router’s base64
        encoded digest of our corresponding microdescriptor

   Changed in version 1.6.0: Added the protocols attribute.

   Changed in version 1.7.0: Added the or_addresses attribute.

   Changed in version 1.7.0: Added the microdescriptor_digest
   attribute to replace our now deprecated digest attribute.

   ***** attribute is either required when we’re parsed with
   validation or has a default value, others are left as **None** if
   undefined

   TYPE_ANNOTATION_NAME = 'network-status-microdesc-consensus-3'

   classmethod content(attr=None, exclude=(), sign=False)

      Creates descriptor content with the given attributes. Mandatory
      fields are filled with dummy information unless data is
      supplied. This doesn’t yet create a valid signature.

      New in version 1.6.0.

      Parameters:
         * **attr** (*dict*) – keyword/value mappings to be included
           in the descriptor

         * **exclude** (*list*) – mandatory keywords to exclude from
           the descriptor, this results in an invalid descriptor

         * **sign** (*bool*) – includes cryptographic signatures and
           digests if True

      Returns:
         **str** with the content of a descriptor

      Raises:
         * **ImportError** if cryptography is unavailable and sign
           is True

         * **NotImplementedError** if not implemented for this
           descriptor type
