# Stem Docs

## 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).