[tor-commits] [stem/master] Undeprecate stem.descriptor.remote's get_microdescriptors()
atagar at torproject.org
atagar at torproject.org
Wed Nov 21 20:29:36 UTC 2018
commit c606f44289408a63ea9ddfbe4dc3a18384b350cd
Author: Damian Johnson <atagar at 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,
More information about the tor-commits
mailing list