[tor-commits] [stem/master] Replace get_authorities() with DirectoryAuthority.from_cache()
atagar at torproject.org
atagar at torproject.org
Tue May 8 20:20:09 UTC 2018
commit fa26e4aad86b5d52a0cb4002afd302cfccebf768
Author: Damian Johnson <atagar at torproject.org>
Date: Fri May 4 12:48:35 2018 -0700
Replace get_authorities() with DirectoryAuthority.from_cache()
Replacing our function for vending directory authority data. Simplifies our API
by making us more consistant across our Directory subclasses.
---
docs/change_log.rst | 1 +
stem/descriptor/remote.py | 143 +++++++++++++++++++++++-----------------------
2 files changed, 71 insertions(+), 73 deletions(-)
diff --git a/docs/change_log.rst b/docs/change_log.rst
index d10597ea..d5505821 100644
--- a/docs/change_log.rst
+++ b/docs/change_log.rst
@@ -57,6 +57,7 @@ The following are only available within Stem's `git repository
* `stem.descriptor.remote <api/descriptor/remote.html>`_ can now download from relay ORPorts
* Zstd and lzma compression support (:spec:`1cb56af`)
+ * Added :func:`~stem.descriptor.remote.Directory.from_cache` and :func:`~stem.descriptor.remote.Directory.from_remote` to the :class:`~stem.descriptor.remote.DirectoryAuthority` subclass.
* `Fallback directory v2 support <https://lists.torproject.org/pipermail/tor-dev/2017-December/012721.html>`_, which adds *nickname* and *extrainfo*
* Added server descriptor's new is_hidden_service_dir attribute
* Don't retry downloading descriptors when we've timed out
diff --git a/stem/descriptor/remote.py b/stem/descriptor/remote.py
index a656e354..e0b4c21d 100644
--- a/stem/descriptor/remote.py
+++ b/stem/descriptor/remote.py
@@ -50,13 +50,12 @@ content. For example...
|- get_extrainfo_descriptors - provides present extrainfo descriptors
+- get_consensus - provides the present consensus or router status entries
- get_authorities - Provides tor directory information.
-
Directory - Relay we can retrieve directory information from
+ | |- from_cache - Provides fallback directories cached with Stem.
+ | +- from_remote - Retrieves fallback directories remotely from tor's latest commit.
+ |
|- DirectoryAuthority - Information about a tor directory authority
+- FallbackDirectory - Directory mirror tor uses when authories are unavailable
- |- from_cache - Provides fallback directories cached with Stem.
- +- from_remote - Retrieves fallback directories remotely from tor's latest commit.
Query - Asynchronous request to download tor descriptors
|- start - issues the query if it isn't already running
@@ -1022,9 +1021,18 @@ class DescriptorDownloader(object):
class Directory(object):
"""
- Relay we can contact for directory information
+ Relay we can contact for directory information.
- .. versionadded:: 1.5.0
+ Our :func:`~stem.descriptor.remote.Directory.from_cache` and
+ :func:`~stem.descriptor.remote.Directory.from_remote` functions key off a
+ different identifier based on our subclass...
+
+ * **DirectoryAuthority** keys off the nickname.
+ * **FallbackDirectory** keys off fingerprints.
+
+ This is because authorities are highly static and canonically known by their
+ names, whereas fallbacks vary more and don't necessarily have a nickname to
+ key off of.
.. versionchanged:: 1.3.0
Moved nickname from subclasses to this base class.
@@ -1043,6 +1051,53 @@ class Directory(object):
self.fingerprint = fingerprint
self.nickname = nickname
+ @staticmethod
+ def from_cache():
+ """
+ Provides cached Tor directory information. This information is hardcoded
+ into Tor and occasionally changes, so the information this provides might
+ not necessarily match your version of tor.
+
+ .. versionadded:: 1.5.0
+
+ .. versionchanged:: 1.7.0
+ Support added to the :class:`~stem.descriptor.remote.DirectoryAuthority` class.
+
+ :returns: **dict** of **str** identifiers to
+ :class:`~stem.descriptor.remote.Directory` instances
+ """
+
+ raise NotImplementedError('Unsupported Operation: this should be implemented by the Directory subclass')
+
+ @staticmethod
+ def from_remote(timeout = 60):
+ """
+ Reads and parses tor's directory data `from gitweb.torproject.org <https://gitweb.torproject.org/>`_.
+ Note that while convenient, this reliance on GitWeb means you should alway
+ call with a fallback, such as...
+
+ ::
+
+ try:
+ authorities = DirectoryAuthority.from_remote()
+ except IOError:
+ authorities = DirectoryAuthority.from_cache()
+
+ .. versionadded:: 1.5.0
+
+ .. versionchanged:: 1.7.0
+ Support added to the :class:`~stem.descriptor.remote.DirectoryAuthority` class.
+
+ :param int timeout: seconds to wait before timing out the request
+
+ :returns: **dict** of **str** identifiers to their
+ :class:`~stem.descriptor.remote.Directory`
+
+ :raises: **IOError** if unable to retrieve the fallback directories
+ """
+
+ raise NotImplementedError('Unsupported Operation: this should be implemented by the Directory subclass')
+
def __hash__(self):
return _hash_attr(self, 'address', 'or_port', 'dir_port', 'fingerprint')
@@ -1056,7 +1111,7 @@ class Directory(object):
class DirectoryAuthority(Directory):
"""
Tor directory authority, a special type of relay `hardcoded into tor
- <https://gitweb.torproject.org/tor.git/tree/src/or/config.c#n819>`_
+ <https://gitweb.torproject.org/tor.git/plain/src/or/auth_dirs.inc>`_
that enumerates the other relays within the network.
At a very high level tor works as follows...
@@ -1095,34 +1150,11 @@ class DirectoryAuthority(Directory):
self.is_bandwidth_authority = is_bandwidth_authority
@staticmethod
- def from_remote(timeout = 60):
- """
- Reads and parses tor's latest directory authority data `from
- gitweb.torproject.org
- <https://gitweb.torproject.org/tor.git/plain/src/or/auth_dirs.inc>`_.
- Note that while convenient, this reliance on GitWeb means you should alway
- call with a fallback, such as...
-
- ::
-
- try:
- fallback_directories = DirectoryAuthority.from_remote()
- except IOError:
- fallback_directories = get_authorities()
-
- Authorities provided through this method will not have a
- **is_bandwidth_authority** value set.
-
- .. versionadded:: 1.7.0
-
- :param int timeout: seconds to wait before timing out the request
-
- :returns: **dict** of **str** nicknames to their
- :class:`~stem.descriptor.remote.DirectoryAuthority`
-
- :raises: **IOError** if unable to retrieve the directory authorities
- """
+ def from_cache():
+ return dict(DIRECTORY_AUTHORITIES)
+ @staticmethod
+ def from_remote(timeout = 60):
try:
lines = str_tools._to_unicode(urllib.urlopen(GITWEB_AUTHORITY_URL, timeout = timeout).read()).splitlines()
except:
@@ -1341,10 +1373,13 @@ def get_authorities():
information hardcoded into Tor and occasionally changes, so the information
this provides might not necessarily match your version of tor.
+ .. deprecated:: 1.7.0
+ Use stem.descriptor.remote.DirectoryAuthority.from_cache() instead.
+
:returns: **dict** of **str** nicknames to :class:`~stem.descriptor.remote.DirectoryAuthority` instances
"""
- return dict(DIRECTORY_AUTHORITIES)
+ return DirectoryAuthority.from_cache()
class FallbackDirectory(Directory):
@@ -1398,22 +1433,6 @@ class FallbackDirectory(Directory):
@staticmethod
def from_cache(path = CACHE_PATH):
- """
- Provides fallback directory information cached with Stem. Unlike
- :func:`~stem.descriptor.remote.FallbackDirectory.from_remote` this doesn't
- have any system requirements, and is faster too. Only drawback is that
- these fallback directories are only as up to date as the Stem release we're
- using.
-
- .. versionchanged:: 1.7.0
- Added the path argument.
-
- :param str path: cache file to load from
-
- :returns: **dict** of **str** fingerprints to their
- :class:`~stem.descriptor.remote.FallbackDirectory`
- """
-
conf = stem.util.conf.Config()
conf.load(path)
headers = OrderedDict([(k.split('.', 1)[1], conf.get(k)) for k in conf.keys() if k.startswith('header.')])
@@ -1466,28 +1485,6 @@ class FallbackDirectory(Directory):
@staticmethod
def from_remote(timeout = 60):
- """
- Reads and parses tor's latest fallback directories `from
- gitweb.torproject.org
- <https://gitweb.torproject.org/tor.git/plain/src/or/fallback_dirs.inc>`_.
- Note that while convenient, this reliance on GitWeb means you should alway
- call with a fallback, such as...
-
- ::
-
- try:
- fallback_directories = FallbackDirectory.from_remote()
- except IOError:
- fallback_directories = FallbackDirectory.from_cache()
-
- :param int timeout: seconds to wait before timing out the request
-
- :returns: **dict** of **str** fingerprints to their
- :class:`~stem.descriptor.remote.FallbackDirectory`
-
- :raises: **IOError** if unable to retrieve the fallback directories
- """
-
try:
lines = str_tools._to_unicode(urllib.urlopen(GITWEB_FALLBACK_URL, timeout = timeout).read()).splitlines()
except:
More information about the tor-commits
mailing list