[tor-commits] [stem/master] Adding remote descriptor sphinx docs to site
atagar at torproject.org
atagar at torproject.org
Mon Jul 22 03:10:17 UTC 2013
commit 713b04632e6ca1120c6d5c2661206fd84c01904b
Author: Damian Johnson <atagar at torproject.org>
Date: Sun Jul 21 18:37:48 2013 -0700
Adding remote descriptor sphinx docs to site
Tidying up our pydocs and including it in our site.
---
docs/api.rst | 5 +++-
docs/api/descriptor/remote.rst | 5 ++++
docs/contents.rst | 1 +
stem/descriptor/remote.py | 62 +++++++++++++++++++++-------------------
4 files changed, 43 insertions(+), 30 deletions(-)
diff --git a/docs/api.rst b/docs/api.rst
index 92eb200..b6a5d8f 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -22,7 +22,9 @@ Descriptors
To read descriptors from disk use :func:`~stem.descriptor.__init__.parse_file` for
individual files and `stem.descriptor.reader
-<api/descriptor/reader.html>`_ for batches.
+<api/descriptor/reader.html>`_ for batches. You can also use
+`stem.descriptor.remote <api/descriptor/remote.html>`_ to download descriptors
+remotely like tor does.
* **Classes**
@@ -34,6 +36,7 @@ individual files and `stem.descriptor.reader
* `stem.descriptor.router_status_entry <api/descriptor/router_status_entry.html>`_ - Relay entries within a network status document.
* `stem.descriptor.reader <api/descriptor/reader.html>`_ - Reads and parses descriptor files from disk.
+* `stem.descriptor.remote <api/descriptor/remote.html>`_ - Downloads descriptors from directory mirrors and authorities.
* `stem.descriptor.export <api/descriptor/export.html>`_ - Exports descriptors to other formats.
Utilities
diff --git a/docs/api/descriptor/remote.rst b/docs/api/descriptor/remote.rst
new file mode 100644
index 0000000..eb0d30a
--- /dev/null
+++ b/docs/api/descriptor/remote.rst
@@ -0,0 +1,5 @@
+Descriptor Remote
+=================
+
+.. automodule:: stem.descriptor.remote
+
diff --git a/docs/contents.rst b/docs/contents.rst
index 834ce0a..7c9720b 100644
--- a/docs/contents.rst
+++ b/docs/contents.rst
@@ -35,6 +35,7 @@ Contents
api/descriptor/export
api/descriptor/reader
+ api/descriptor/remote
api/util/conf
api/util/connection
diff --git a/stem/descriptor/remote.py b/stem/descriptor/remote.py
index 0aabd74..da1df63 100644
--- a/stem/descriptor/remote.py
+++ b/stem/descriptor/remote.py
@@ -13,8 +13,8 @@ content. For example...
from stem.descriptor.remote import DescriptorDownloader
downloader = DescriptorDownloader(
- cache = '/tmp/descriptor_cache',
use_mirrors = True,
+ timeout = 10,
)
query = downloader.get_server_descriptors()
@@ -48,19 +48,19 @@ itself...
DescriptorDownloader - Configurable class for issuing queries
|- use_directory_mirrors - use directory mirrors to download future descriptors
- |- get_server_descriptors - provides present :class:`~stem.descriptor.stem.descriptor.server_descriptor.ServerDescriptor`
- |- get_extrainfo_descriptors - provides present :class:`~stem.descriptor.extrainfo_descriptor.ExtraInfoDescriptor`
- |- get_microdescriptors - provides present :class:`~stem.descriptor.microdescriptor.Microdescriptor`
- |- get_consensus - provides present :class:`~stem.descriptor.router_status_entry.RouterStatusEntryV3`
- |- get_key_certificates - provides present :class:`~stem.descriptor.networkstatus.KeyCertificate`
+ |- get_server_descriptors - provides present server descriptors
+ |- get_extrainfo_descriptors - provides present extrainfo descriptors
+ |- get_microdescriptors - provides present microdescriptors
+ |- get_consensus - provides the present consensus or router status entries
+ |- get_key_certificates - provides present authority key certificates
+- query - request an arbitrary descriptor resource
-.. data:: MAX_DESCRIPTOR_BATCH_SIZE
+.. data:: MAX_FINGERPRINTS
- Maximum number of server or extrainfo descriptors that can requested at a
- time by their fingerprints.
+ Maximum number of descriptors that can requested at a time by their
+ fingerprints.
-.. data:: MAX_MICRODESCRIPTOR_BATCH_SIZE
+.. data:: MAX_MICRODESCRIPTOR_HASHES
Maximum number of microdescriptors that can requested at a time by their
hashes.
@@ -86,8 +86,8 @@ from stem.util import log
# Tor has a limited number of descriptors we can fetch explicitly by their
# fingerprint or hashes due to a limit on the url length by squid proxies.
-MAX_DESCRIPTOR_BATCH_SIZE = 96
-MAX_MICRODESCRIPTOR_BATCH_SIZE = 92
+MAX_FINGERPRINTS = 96
+MAX_MICRODESCRIPTOR_HASHES = 92
# Tor directory authorities as of commit f631b73 (7/4/13). This should only
# include authorities with 'v3ident':
@@ -134,7 +134,7 @@ class Query(object):
To block on the response and get results either call
:func:`~stem.descriptor.remote.Query.run` or iterate over the Query. The
- :func:`~stem.descriptor.remote.run` method pass along any errors that
+ :func:`~stem.descriptor.remote.Query.run` method pass along any errors that
arise...
::
@@ -143,7 +143,7 @@ class Query(object):
query = Query(
'/tor/server/all.z',
- 'server-descriptor 1.0',
+ descriptor_type = 'server-descriptor 1.0',
timeout = 30,
)
@@ -171,16 +171,18 @@ class Query(object):
<https://gitweb.torproject.org/torspec.git/blob/HEAD:/dir-spec.txt>`_).
Commonly useful ones include...
- ======== ===========
+ ===================================== ===========
Resource Description
- ======== ===========
+ ===================================== ===========
/tor/server/all.z all present server descriptors
/tor/server/fp/<fp1>+<fp2>+<fp3>.z server descriptors with the given fingerprints
/tor/extra/all.z all present extrainfo descriptors
/tor/extra/fp/<fp1>+<fp2>+<fp3>.z extrainfo descriptors with the given fingerprints
/tor/micro/d/<hash1>-<hash2>.z microdescriptors with the given hashes
/tor/status-vote/current/consensus.z present consensus
- ======== ===========
+ /tor/keys/all.z key certificates for the authorities
+ /tor/keys/fp/<v3ident1>+<v3ident2>.z key certificates for specific authorities
+ ===================================== ===========
The '.z' suffix can be excluded to get a plaintext rather than compressed
response. Compression is handled transparently, so this shouldn't matter to
@@ -211,7 +213,9 @@ class Query(object):
:var bool validate: checks the validity of the descriptor's content if
**True**, skips these checks otherwise
:var stem.descriptor.__init__.DocumentHandler document_handler: method in
- which to parse the :class:`~stem.descriptor.networkstatus.NetworkStatusDocument`
+ which to parse a :class:`~stem.descriptor.networkstatus.NetworkStatusDocument`
+
+ :param bool start: start making the request when constructed (default is **True**)
"""
def __init__(self, resource, descriptor_type = None, endpoints = None, retries = 2, fall_back_to_authority = True, timeout = None, start = True, validate = True, document_handler = stem.descriptor.DocumentHandler.ENTRIES):
@@ -432,8 +436,8 @@ class DescriptorDownloader(object):
fingerprints = [fingerprints]
if fingerprints:
- if len(fingerprints) > MAX_DESCRIPTOR_BATCH_SIZE:
- raise ValueError("Unable to request more than %i descriptors at a time by their fingerprints" % MAX_DESCRIPTOR_BATCH_SIZE)
+ if len(fingerprints) > MAX_FINGERPRINTS:
+ raise ValueError("Unable to request more than %i descriptors at a time by their fingerprints" % MAX_FINGERPRINTS)
resource = '/tor/server/fp/%s.z' % '+'.join(fingerprints)
@@ -462,8 +466,8 @@ class DescriptorDownloader(object):
fingerprints = [fingerprints]
if fingerprints:
- if len(fingerprints) > MAX_DESCRIPTOR_BATCH_SIZE:
- raise ValueError("Unable to request more than %i descriptors at a time by their fingerprints" % MAX_DESCRIPTOR_BATCH_SIZE)
+ if len(fingerprints) > MAX_FINGERPRINTS:
+ raise ValueError("Unable to request more than %i descriptors at a time by their fingerprints" % MAX_FINGERPRINTS)
resource = '/tor/extra/fp/%s.z' % '+'.join(fingerprints)
@@ -491,21 +495,21 @@ class DescriptorDownloader(object):
if isinstance(hashes, str):
hashes = [hashes]
- if len(hashes) > MAX_MICRODESCRIPTOR_BATCH_SIZE:
- raise ValueError("Unable to request more than %i microdescriptors at a time by their hashes" % MAX_MICRODESCRIPTOR_BATCH_SIZE)
+ if len(hashes) > MAX_MICRODESCRIPTOR_HASHES:
+ raise ValueError("Unable to request more than %i microdescriptors at a time by their hashes" % MAX_MICRODESCRIPTOR_HASHES)
return self.query('/tor/micro/d/%s.z' % '-'.join(hashes), **query_args)
- def get_consensus(self, document_handler = stem.descriptor.DocumentHandler.ENTRIES, authority_v3ident = None, **query_args):
+ def get_consensus(self, authority_v3ident = None, document_handler = stem.descriptor.DocumentHandler.ENTRIES, **query_args):
"""
Provides the present router status entries.
- :param stem.descriptor.__init__.DocumentHandler document_handler: method in
- which to parse the :class:`~stem.descriptor.networkstatus.NetworkStatusDocumentV3`
:param str authority_v3ident: fingerprint of the authority key for which
to get the consensus, see `'v3ident' in tor's config.c
<https://gitweb.torproject.org/tor.git/blob/f631b73:/src/or/config.c#l816>`_
for the values.
+ :param stem.descriptor.__init__.DocumentHandler document_handler: method in
+ which to parse the :class:`~stem.descriptor.networkstatus.NetworkStatusDocumentV3`
:param query_args: additional arguments for the
:class:`~stem.descriptor.remote.Query` constructor
@@ -546,8 +550,8 @@ class DescriptorDownloader(object):
authority_v3idents = [authority_v3idents]
if authority_v3idents:
- if len(authority_v3idents) > MAX_DESCRIPTOR_BATCH_SIZE:
- raise ValueError("Unable to request more than %i key certificates at a time by their identity fingerprints" % MAX_DESCRIPTOR_BATCH_SIZE)
+ if len(authority_v3idents) > MAX_FINGERPRINTS:
+ raise ValueError("Unable to request more than %i key certificates at a time by their identity fingerprints" % MAX_FINGERPRINTS)
resource = '/tor/keys/fp/%s.z' % '+'.join(authority_v3idents)
More information about the tor-commits
mailing list