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

New 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)¶

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