Descriptor
**********

Package for parsing and processing descriptor data.

**Module Overview:**

   parse_file - Parses the descriptors in a file.
   create_signing_key - Cretes a signing key that can be used for creating descriptors.

   Compression - method of descriptor decompression

   Descriptor - Common parent for all descriptor file types.
     | |- content - creates the text of a new descriptor
     | |- create - creates a new descriptor
     | +- from_str - provides a parsed descriptor for the given string
     |
     |- type_annotation - provides our @type annotation
     |- get_path - location of the descriptor on disk if it came from a file
     |- get_archive_path - location of the descriptor within the archive it came from
     |- get_bytes - similar to str(), but provides our original bytes content
     |- get_unrecognized_lines - unparsed descriptor content
     +- __str__ - string that the descriptor was made from

stem.descriptor.__init__.DigestHash(enum)

   Added in version 1.8.0.

   Hash function used by tor for descriptor digests.

   +-------------+-------------+
   | DigestHash  | Description |
   |=============|=============|
   | SHA1        | SHA1 hash   |
   +-------------+-------------+
   | SHA256      | SHA256 hash |
   +-------------+-------------+

stem.descriptor.__init__.DigestEncoding(enum)

   Added in version 1.8.0.

   Encoding of descriptor digests.

   +-------------------+------------------------------------------------------------------------------------------------------------------------+
   | DigestEncoding    | Description                                                                                                            |
   |===================|========================================================================================================================|
   | RAW               | hash object                                                                                                            |
   +-------------------+------------------------------------------------------------------------------------------------------------------------+
   | HEX               | uppercase hexidecimal encoding                                                                                         |
   +-------------------+------------------------------------------------------------------------------------------------------------------------+
   | BASE64            | base64 encoding without trailing ‘=’ padding                                                                           |
   +-------------------+------------------------------------------------------------------------------------------------------------------------+

stem.descriptor.__init__.DocumentHandler(enum)

   Ways in which we can parse a "NetworkStatusDocument".

   Both **ENTRIES** and **BARE_DOCUMENT** have a ‘thin’ document,
   which doesn’t have a populated **routers** attribute. This allows
   for lower memory usage and upfront runtime. However, if read time
   and memory aren’t a concern then **DOCUMENT** can provide you with
   a fully populated document.

   Handlers don’t change the fact that most methods that provide
   descriptors return an iterator. In the case of **DOCUMENT** and
   **BARE_DOCUMENT** that iterator would have just a single item - the
   document itself.

   Simple way to handle this is to call **next()** to get the
   iterator’s one and only value…

      import stem.descriptor.remote
      from stem.descriptor import DocumentHandler

      consensus = next(stem.descriptor.remote.get_consensus(
        document_handler = DocumentHandler.BARE_DOCUMENT,
      )

   +---------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | DocumentHandler     | Description                                                                                                                                                                               |
   |=====================|===========================================================================================================================================================================================|
   | **ENTRIES**         | Iterates over the contained "RouterStatusEntry". Each has a reference to the bare document it came from (through its **document** attribute).                                             |
   +---------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | **DOCUMENT**        | "NetworkStatusDocument" with the "RouterStatusEntry" it contains (through its **routers** attribute).                                                                                     |
   +---------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | **BARE_DOCUMENT**   | "NetworkStatusDocument" **without** a reference to its contents (the "RouterStatusEntry" are unread).                                                                                     |
   +---------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
