commit c606f44289408a63ea9ddfbe4dc3a18384b350cd Author: Damian Johnson atagar@torproject.org Date: Wed Nov 21 11:52:50 2018 -0800
Undeprecate stem.descriptor.remote's get_microdescriptors()
We deprecated get_microdescriptors() because tor hadn't implemented it on DirPorts but now it has. Not only that but our existing method just works (neat!). Undeprecating get_microdescriptors(), expanding its pydocs, adding a test, and adding an alias to the base module to match other descriptor types. --- docs/change_log.rst | 1 + stem/descriptor/remote.py | 46 ++++++++++++++++++++++++++++++++++++---------- test/unit/doctest.py | 30 ++++++++++++++++++++++++++++++ 3 files changed, 67 insertions(+), 10 deletions(-)
diff --git a/docs/change_log.rst b/docs/change_log.rst index 7b99f8f0..396ec105 100644 --- a/docs/change_log.rst +++ b/docs/change_log.rst @@ -51,6 +51,7 @@ The following are only available within Stem's `git repository
* **Descriptors**
+ * Added :func:`stem.descriptor.remote.get_microdescriptors` * Added :func:`~stem.descriptor.__init__.Descriptor.from_str` method (:trac:`28450`) * Added :func:`~stem.descriptor.__init__.Descriptor.type_annotation` method (:trac:`28397`) * Added the **hash_type** and **encoding** arguments to `ServerDescriptor <api/descriptor/server_descriptor.html#stem.descriptor.server_descriptor.ServerDescriptor.digest>`_ and `ExtraInfo's <api/descriptor/extrainfo_descriptor.html#stem.descriptor.extrainfo_descriptor.ExtraInfoDescriptor.digest>`_ digest methods (:trac:`28398`) diff --git a/stem/descriptor/remote.py b/stem/descriptor/remote.py index 91a3bad2..78dd8367 100644 --- a/stem/descriptor/remote.py +++ b/stem/descriptor/remote.py @@ -59,6 +59,7 @@ content. For example... |- 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_key_certificates - provides present authority key certificates +- query - request an arbitrary descriptor resource @@ -191,6 +192,18 @@ def get_extrainfo_descriptors(fingerprints = None, **query_args): return get_instance().get_extrainfo_descriptors(fingerprints, **query_args)
+def get_microdescriptors(hashes, **query_args): + """ + Shorthand for + :func:`~stem.descriptor.remote.DescriptorDownloader.get_microdescriptors` + on our singleton instance. + + .. versionadded:: 1.8.0 + """ + + return get_instance().get_microdescriptors(hashes, **query_args) + + def get_consensus(authority_v3ident = None, microdescriptor = False, **query_args): """ Shorthand for @@ -662,19 +675,32 @@ class DescriptorDownloader(object):
return self.query(resource, **query_args)
- # TODO: drop in stem 2.x - def get_microdescriptors(self, hashes, **query_args): """ Provides the microdescriptors with the given hashes. To get these see the - 'microdescriptor_hashes' attribute of - :class:`~stem.descriptor.router_status_entry.RouterStatusEntryV3`. Note - that these are only provided via a microdescriptor consensus (such as - 'cached-microdesc-consensus' in your data directory). - - .. deprecated:: 1.5.0 - This function has never worked, as it was never implemented in tor - (:trac:`9271`). + **microdescriptor_digest** attribute of + :class:`~stem.descriptor.router_status_entry.RouterStatusEntryMicroV3`. + Note that these are only provided via the **microdescriptor consensus**. + For exampe... + + :: + + >>> import stem.descriptor.remote + >>> consensus = stem.descriptor.remote.get_consensus(microdescriptor = True).run() + >>> my_router_status_entry = filter(lambda desc: desc.nickname == 'caersidi', consensus)[0] + >>> print(my_router_status_entry.microdescriptor_digest) + IQI5X2A5p0WVN/MgwncqOaHF2f0HEGFEaxSON+uKRhU + + >>> my_microdescriptor = stem.descriptor.remote.get_microdescriptors([my_router_status_entry.microdescriptor_digest]).run()[0] + >>> print(my_microdescriptor) + onion-key + -----BEGIN RSA PUBLIC KEY----- + MIGJAoGBAOJo9yyVgG8ksEHQibqPIEbLieI6rh1EACRPiDiV21YObb+9QEHaR3Cf + FNAzDbGhbvADLBB7EzuViL8w+eXQUOaIsJRdymh/wuUJ78bv5oEIJhthKq/Uqa4P + wKHXSZixwAHfy8NASTX3kxu9dAHWU3Owb+4W4lR2hYM0ZpoYYkThAgMBAAE= + -----END RSA PUBLIC KEY----- + ntor-onion-key kWOHNd+2uBlMpcIUbbpFLiq/rry66Ep6MlwmNpwzcBg= + id ed25519 xE/GeYImYAIB0RbzJXFL8kDLpDrj/ydCuCdvOgC4F/4
:param str,list hashes: microdescriptor hash or list of hashes to be retrieved diff --git a/test/unit/doctest.py b/test/unit/doctest.py index 7e40e873..28eef0cf 100644 --- a/test/unit/doctest.py +++ b/test/unit/doctest.py @@ -34,6 +34,26 @@ ADD_ONION_RESPONSE = """\ 250 OK """
+CONSENSUS_ENTRY = """\ +r caersidi O7NMYwctnRDoNu5ClocT97kyX2Y 2018-11-21 05:25:24 208.113.135.162 1443 1444 +m IQI5X2A5p0WVN/MgwncqOaHF2f0HEGFEaxSON+uKRhU +s Fast Guard HSDir Running Stable V2Dir Valid +v Tor 0.3.4.0-alpha-dev +pr Cons=1-2 Desc=1-2 DirCache=1-2 HSDir=1-2 HSIntro=3-4 HSRend=1-2 Link=1-5 LinkAuth=1,3 Microdesc=1-2 Relay=1-2 +w Bandwidth=8360 +""" + +MICRODESCRIPTOR_ENTRY = """\ +onion-key +-----BEGIN RSA PUBLIC KEY----- +MIGJAoGBAOJo9yyVgG8ksEHQibqPIEbLieI6rh1EACRPiDiV21YObb+9QEHaR3Cf +FNAzDbGhbvADLBB7EzuViL8w+eXQUOaIsJRdymh/wuUJ78bv5oEIJhthKq/Uqa4P +wKHXSZixwAHfy8NASTX3kxu9dAHWU3Owb+4W4lR2hYM0ZpoYYkThAgMBAAE= +-----END RSA PUBLIC KEY----- +ntor-onion-key kWOHNd+2uBlMpcIUbbpFLiq/rry66Ep6MlwmNpwzcBg= +id ed25519 xE/GeYImYAIB0RbzJXFL8kDLpDrj/ydCuCdvOgC4F/4 +""".rstrip() +
class TestDocumentation(unittest.TestCase): def test_examples(self): @@ -51,6 +71,16 @@ class TestDocumentation(unittest.TestCase): get_config_mock.return_value = config
test_run = doctest.testfile(path, **args) + elif path.endswith('/stem/descriptor/remote.py'): + consensus_query = Mock() + consensus_query.run.return_value = [stem.descriptor.router_status_entry.RouterStatusEntryMicroV3.from_str(CONSENSUS_ENTRY)] + + microdescriptor_query = Mock() + microdescriptor_query.run.return_value = [stem.descriptor.microdescriptor.Microdescriptor.from_str(MICRODESCRIPTOR_ENTRY)] + + with patch('stem.descriptor.remote.get_consensus', Mock(return_value = consensus_query)): + with patch('stem.descriptor.remote.get_microdescriptors', Mock(return_value = microdescriptor_query)): + test_run = doctest.testfile(path, **args) elif path.endswith('/stem/descriptor/router_status_entry.py'): args['globs'] = { '_base64_to_hex': stem.descriptor.router_status_entry._base64_to_hex,