Descriptor Remote
*****************

Module for remotely retrieving descriptors from directory authorities
and mirrors. This is the simplest method for getting current tor
descriptor information…

   import stem.descriptor.remote

   for desc in stem.descriptor.remote.get_server_descriptors():
     if desc.exit_policy.is_exiting_allowed():
       print('  %s (%s)' % (desc.nickname, desc.fingerprint))

More custom downloading behavior can be done through the
"DescriptorDownloader" class, which issues "Query" instances to get
you descriptor content. For example…

   from stem.descriptor.remote import DescriptorDownloader

   downloader = DescriptorDownloader(
     use_mirrors = True,
     timeout = 10,
   )

   query = downloader.get_server_descriptors()

   print('Exit Relays:')

   try:
     for desc in query.run():
       if desc.exit_policy.is_exiting_allowed():
         print('  %s (%s)' % (desc.nickname, desc.fingerprint))

     print
     print('Query took %0.2f seconds' % query.runtime)
   except Exception as exc:
     print('Unable to retrieve the server descriptors: %s' % exc)

   get_instance - Provides a singleton DescriptorDownloader used for...
     |- their_server_descriptor - provides the server descriptor of the relay we download from
     |- get_server_descriptors - provides present server descriptors
     |- get_extrainfo_descriptors - provides present extrainfo descriptors
     |- get_microdescriptors - provides present microdescriptors with the given digests
     |- get_consensus - provides the present consensus or router status entries
     |- get_bandwidth_file - provides bandwidth heuristics used to make the next consensus
     +- get_detached_signatures - authority signatures used to make the next consensus

   Query - Asynchronous request to download tor descriptors
     |- start - issues the query if it isn't already running
     +- run - blocks until the request is finished and provides the results

   DescriptorDownloader - Configurable class for issuing queries
     |- use_directory_mirrors - use directory mirrors to download future descriptors
     |- their_server_descriptor - provides the server descriptor of the relay we download from
     |- get_server_descriptors - provides present server descriptors
     |- get_extrainfo_descriptors - provides present extrainfo descriptors
     |- get_microdescriptors - provides present microdescriptors with the given digests
     |- get_consensus - provides the present consensus or router status entries
     |- get_vote - provides an authority's vote for the next consensus
     |- get_key_certificates - provides present authority key certificates
     |- get_bandwidth_file - provides bandwidth heuristics used to make the next consensus
     |- get_detached_signatures - authority signatures used to make the next consensus
     +- query - request an arbitrary descriptor resource

New in version 1.1.0.

stem.descriptor.remote.MAX_FINGERPRINTS

   Maximum number of descriptors that can requested at a time by their
   fingerprints.

stem.descriptor.remote.MAX_MICRODESCRIPTOR_HASHES

   Maximum number of microdescriptors that can requested at a time by
   their hashes.

stem.descriptor.remote.Compression(enum)

   Compression when downloading descriptors.

   New in version 1.7.0.

   +-----------------+-------------------------------------------------------------------------------------------------------------------------------------------+
   | Compression     | Description                                                                                                                               |
   |=================|===========================================================================================================================================|
   | **PLAINTEXT**   | Uncompressed data.                                                                                                                        |
   +-----------------+-------------------------------------------------------------------------------------------------------------------------------------------+
   | **GZIP**        | GZip compression.                                                                                                                         |
   +-----------------+-------------------------------------------------------------------------------------------------------------------------------------------+
   | **ZSTD**        | Zstandard compression, this requires the zstandard module.                                                                                |
   +-----------------+-------------------------------------------------------------------------------------------------------------------------------------------+
   | **LZMA**        | LZMA compression, this requires the ‘lzma module <https://docs.python.org/3/library/lzma.html>`_.                                         |
   +-----------------+-------------------------------------------------------------------------------------------------------------------------------------------+
