commit 1731720fb8254fa27019f03c36f6701e8d8d62a6 Author: Damian Johnson <atagar@torproject.org> Date: Tue Aug 11 17:03:58 2020 -0700 Update microdescriptor pydocs This documentation dates back to the dawn of Stem. Thanks to Barkin for pointing out that it is no longer accurate... https://github.com/torproject/stem/issues/68 --- stem/descriptor/microdescriptor.py | 46 +++++++++++++++----------------------- 1 file changed, 18 insertions(+), 28 deletions(-) diff --git a/stem/descriptor/microdescriptor.py b/stem/descriptor/microdescriptor.py index 9b5b045d..4967d53e 100644 --- a/stem/descriptor/microdescriptor.py +++ b/stem/descriptor/microdescriptor.py @@ -2,25 +2,14 @@ # See LICENSE for licensing information """ -Parsing for Tor microdescriptors, which contain a distilled version of a -relay's server descriptor. As of Tor version 0.2.3.3-alpha Tor no longer -downloads server descriptors by default, opting for microdescriptors instead. +Microdescriptors are a distilled copy of a relay's server descriptor, +downloaded by Tor clients in lieu of server descriptors to reduce +bandwidth usage. -Unlike most descriptor documents these aren't available on the metrics site -(since they don't contain any information that the server descriptors don't). - -The limited information in microdescriptors make them rather clunky to use -compared with server descriptors. For instance microdescriptors lack the -relay's fingerprint, making it difficut to use them to look up the relay's -other descriptors. - -To do so you need to match the microdescriptor's digest against its -corresponding router status entry. For added fun as of this writing the -controller doesn't even surface those router status entries -(:trac:`7953`). - -For instance, here's an example that prints the nickname and fingerprints of -the exit relays. +Microdescriptors contain a subset of a server descriptor's information +and are rather clunky to use. For instance, microdescriptors lack a +relay's canonical identifier (its fingerprint). To get it you must +pair microdescriptors with the consensus from which they came... :: @@ -29,7 +18,7 @@ the exit relays. from stem.control import Controller from stem.descriptor import parse_file - with Controller.from_port(port = 9051) as controller: + with Controller.from_port() as controller: controller.authenticate() exit_digests = set() @@ -37,25 +26,26 @@ the exit relays. for desc in controller.get_microdescriptors(): if desc.exit_policy.is_exiting_allowed(): - exit_digests.add(desc.digest) + exit_digests.add(desc.digest()) - print 'Exit Relays:' + print('Exit Relays:') for desc in parse_file(os.path.join(data_dir, 'cached-microdesc-consensus')): - if desc.digest in exit_digests: - print ' %s (%s)' % (desc.nickname, desc.fingerprint) + if desc.microdescriptor_digest in exit_digests: + print(' %s (%s)' % (desc.nickname, desc.fingerprint)) Doing the same is trivial with server descriptors... :: - from stem.descriptor import parse_file + from stem.control import Controller - print 'Exit Relays:' + with Controller.from_port() as controller: + controller.authenticate() - for desc in parse_file('/home/atagar/.tor/cached-descriptors'): - if desc.exit_policy.is_exiting_allowed(): - print ' %s (%s)' % (desc.nickname, desc.fingerprint) + for desc in controller.get_server_descriptors(): + if desc.exit_policy.is_exiting_allowed(): + print(' %s (%s)' % (desc.nickname, desc.fingerprint)) **Module Overview:**