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
     |- 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

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

   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.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 a unit-less 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.

   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

   Changed in version 1.6.0: Added the protocols attribute.

   Changed in version 1.7.0: Added the or_addresses attribute.

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

   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
