
Server Descriptor
*****************

Parsing for Tor server descriptors, which contains the infrequently
changing information about a Tor relay (contact information, exit
policy, public keys, etc). This information is provided from a few
sources...

* The control port via 'GETINFO desc/*' queries.

* The 'cached-descriptors' file in Tor's data directory.

* Archived descriptors provided by CollecTor
  (https://collector.torproject.org/).

* Directory authorities and mirrors via their DirPort.

**Module Overview:**

   ServerDescriptor - Tor server descriptor.
     |- RelayDescriptor - Server descriptor for a relay.
     |
     |- BridgeDescriptor - Scrubbed server descriptor for a bridge.
     |  |- is_scrubbed - checks if our content has been properly scrubbed
     |  +- get_scrubbing_issues - description of issues with our scrubbing
     |
     |- digest - calculates the upper-case hex digest value for our content
     |- get_annotations - dictionary of content prior to the descriptor entry
     +- get_annotation_lines - lines that provided the annotations

class class stem.descriptor.server_descriptor.ServerDescriptor(raw_contents, validate=False, annotations=None)

   Bases: "stem.descriptor.Descriptor"

   Common parent for server descriptors.

   Variables:
      * **nickname** (*str*) -- ***** relay's nickname

      * **fingerprint** (*str*) -- identity key fingerprint

      * **published** (*datetime*) -- ***** time in UTC when this
        descriptor was made

      * **address** (*str*) -- ***** IPv4 address of the relay

      * **or_port** (*int*) -- ***** port used for relaying

      * **socks_port** (*int*) -- ***** port used as client
        (deprecated, always **None**)

      * **dir_port** (*int*) -- ***** port used for descriptor
        mirroring

      * **platform** (*bytes*) -- line with operating system and tor
        version

      * **tor_version** (*stem.version.Version*) -- version of tor

      * **operating_system** (*str*) -- operating system

      * **uptime** (*int*) -- uptime when published in seconds

      * **contact** (*bytes*) -- contact information

      * **exit_policy** (*stem.exit_policy.ExitPolicy*) -- *****
        stated exit policy

      * **exit_policy_v6** (*stem.exit_policy.MicroExitPolicy*) --
        ***** exit policy for IPv6

      * **family** (*set*) -- ***** nicknames or fingerprints of
        declared family

      * **average_bandwidth** (*int*) -- ***** average rate it's
        willing to relay in bytes/s

      * **burst_bandwidth** (*int*) -- ***** burst rate it's willing
        to relay in bytes/s

      * **observed_bandwidth** (*int*) -- ***** estimated capacity
        based on usage in bytes/s

      * **link_protocols** (*list*) -- link protocols supported by the
        relay

      * **circuit_protocols** (*list*) -- circuit protocols supported
        by the relay

      * **hibernating** (*bool*) -- ***** hibernating when published

      * **allow_single_hop_exits** (*bool*) -- ***** flag if single
        hop exiting is allowed

      * **extra_info_cache** (*bool*) -- ***** flag if a mirror for
        extra-info documents

      * **extra_info_digest** (*str*) -- upper-case hex encoded digest
        of our extra-info document

      * **eventdns** (*bool*) -- flag for evdns backend (deprecated,
        always unset)

      * **or_addresses** (*list*) -- ***** alternative for our
        address/or_port attributes, each entry is a tuple of the form
        (address (**str**), port (**int**), is_ipv6 (**bool**))

   Deprecated, moved to extra-info descriptor...

   Variables:
      * **read_history_end** (*datetime*) -- end of the sampling
        interval

      * **read_history_interval** (*int*) -- seconds per interval

      * **read_history_values** (*list*) -- bytes read during each
        interval

      * **write_history_end** (*datetime*) -- end of the sampling
        interval

      * **write_history_interval** (*int*) -- seconds per interval

      * **write_history_values** (*list*) -- bytes written during each
        interval

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

   digest()

      Provides the hex encoded sha1 of our content. This value is part
      of the network status entry for this relay.

      Returns:
         **unicode** with the upper-case hex digest value for this
         server descriptor

   get_annotations(*args, **kwds)

      Provides content that appeared prior to the descriptor. If this
      comes from the cached-descriptors file then this commonly
      contains content like...

         @downloaded-at 2012-03-18 21:18:29
         @source "173.254.216.66"

      Returns:
         **dict** with the key/value pairs in our annotations

   get_annotation_lines()

      Provides the lines of content that appeared prior to the
      descriptor. This is the same as the "get_annotations()" results,
      but with the unparsed lines and ordering retained.

      Returns:
         **list** with the lines of annotation that came before this
         descriptor

class class stem.descriptor.server_descriptor.RelayDescriptor(raw_contents, validate=False, annotations=None)

   Bases: "stem.descriptor.server_descriptor.ServerDescriptor"

   Server descriptor (descriptor specification)

   Variables:
      * **onion_key** (*str*) -- ***** key used to encrypt EXTEND
        cells

      * **ntor_onion_key** (*str*) -- base64 key used to encrypt
        EXTEND in the ntor protocol

      * **signing_key** (*str*) -- ***** relay's long-term identity
        key

      * **signature** (*str*) -- ***** signature for this descriptor

   ***** attribute is required when we're parsed with validation

   digest(*args, **kwds)

      Provides the digest of our descriptor's content.

      Returns:
         the digest string encoded in uppercase hex

      Raises :
         ValueError if the digest canot be calculated

class class stem.descriptor.server_descriptor.BridgeDescriptor(raw_contents, validate=False, annotations=None)

   Bases: "stem.descriptor.server_descriptor.ServerDescriptor"

   Bridge descriptor (bridge descriptor specification)

   digest()

   is_scrubbed()

      Checks if we've been properly scrubbed in accordance with the
      bridge descriptor specification. Validation is a moving target
      so this may not be fully up to date.

      Returns:
         **True** if we're scrubbed, **False** otherwise

   get_scrubbing_issues(*args, **kwds)

      Provides issues with our scrubbing.

      Returns:
         **list** of strings which describe issues we have with our
         scrubbing, this list is empty if we're properly scrubbed
