commit 8b3e9ed828070b2da9010220e989017668cb994d Author: Damian Johnson <atagar@torproject.org> Date: Fri Jan 18 00:04:30 2013 -0800 Table providing desctriptor_type to class mappings --- .gitignore | 2 -- docs/api.rst | 4 ++++ stem/descriptor/__init__.py | 30 ++++++++++++++++++++++++++---- stem/descriptor/networkstatus.py | 3 ++- 4 files changed, 32 insertions(+), 7 deletions(-) diff --git a/.gitignore b/.gitignore index c05eb6d..f74e628 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,4 @@ *.swp test/data/ docs/_build/ -docs/stem.* -docs/modules.rst diff --git a/docs/api.rst b/docs/api.rst index c876778..3f9d770 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -20,6 +20,10 @@ Controller 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. + * **Classes** * `stem.descriptor <api/descriptor/descriptor.html>`_ - Base class for descriptors. diff --git a/stem/descriptor/__init__.py b/stem/descriptor/__init__.py index 12a3a3e..aec8632 100644 --- a/stem/descriptor/__init__.py +++ b/stem/descriptor/__init__.py @@ -43,7 +43,7 @@ PGP_BLOCK_END = "-----END %s-----" def parse_file(descriptor_file, descriptor_type = None, path = None): """ Simple function to read the descriptor contents from a file, providing an - iterator for its :class:`~stem.descriptor.Descriptor` contents. + iterator for its :class:`~stem.descriptor.__init__.Descriptor` contents. If you don't provide a **descriptor_type** argument then this automatically tries to determine the descriptor type based on the following... @@ -52,17 +52,39 @@ def parse_file(descriptor_file, descriptor_type = None, path = None): instance, tor's 'cached-descriptors' contains server descriptors. * The @type annotation on the first line. These are generally only found in - the descriptor archives from 'https://metrics.torproject.org'. + the `descriptor archives <https://metrics.torproject.org>`_. This is a handy function for simple usage, but if you're reading multiple descriptor files you might want to consider the :class:`~stem.descriptor.reader.DescriptorReader`. + Descriptor types include the following, including further minor versions (ie. + if we support 1.0 then we also support 1.1 and above)... + + ===================================== ===== + Descriptor Type Class + ===================================== ===== + server-descriptor 1.0 :class:`~stem.descriptor.server_descriptor.RelayDescriptor` + extra-info 1.0 :class:`~stem.descriptor.extrainfo_descriptor.RelayExtraInfoDescriptor` + directory 1.0 **unsupported** + network-status-2 1.0 :class:`~stem.descriptor.router_status_entry.RouterStatusEntryV2` (with a :class:`~stem.descriptor.networkstatus.NetworkStatusDocumentV2`) + dir-key-certificate-3 1.0 **unsupported** + network-status-consensus-3 1.0 :class:`~stem.descriptor.router_status_entry.RouterStatusEntryV3` (with a :class:`~stem.descriptor.networkstatus.NetworkStatusDocumentV3`) + network-status-vote-3 1.0 :class:`~stem.descriptor.router_status_entry.RouterStatusEntryV3` (with a :class:`~stem.descriptor.networkstatus.NetworkStatusDocumentV3`) + network-status-microdesc-consensus-3 :class:`~stem.descriptor.router_status_entry.RouterStatusEntryMicroV3` (with a :class:`~stem.descriptor.networkstatus.NetworkStatusDocumentV3`) + bridge-network-status 1.0 :class:`~stem.descriptor.router_status_entry.RouterStatusEntryV3` (with a :class:`~stem.descriptor.networkstatus.BridgeNetworkStatusDocument`) + bridge-server-descriptor 1.0 :class:`~stem.descriptor.server_descriptor.BridgeDescriptor` + bridge-extra-info 1.0 :class:`~stem.descriptor.extrainfo_descriptor.BridgeExtraInfoDescriptor` + torperf 1.0 **unsupported** + bridge-pool-assignment 1.0 **unsupported** + tordnsel 1.0 **unsupported** + ===================================== ===== + :param file descriptor_file: opened file with the descriptor contents - :param str descriptor_type: `descriptor type <https://metrics.torproject.org/formats.html#descriptortypes>`_ + :param str descriptor_type: `descriptor type <https://metrics.torproject.org/formats.html#descriptortypes>`_, this is guessed if not provided :param str path: absolute path to the file's location on disk - :returns: iterator for :class:`stem.descriptor.Descriptor` instances in the file + :returns: iterator for :class:`~stem.descriptor.__init__.Descriptor` instances in the file :raises: * **TypeError** if we can't match the contents of the file to a descriptor type diff --git a/stem/descriptor/networkstatus.py b/stem/descriptor/networkstatus.py index fc46fa0..1ae412e 100644 --- a/stem/descriptor/networkstatus.py +++ b/stem/descriptor/networkstatus.py @@ -60,7 +60,8 @@ and upfront runtime. NetworkStatusDocument - Network status document |- NetworkStatusDocumentV2 - Version 2 network status document - +- NetworkStatusDocumentV3 - Version 3 network status document + |- NetworkStatusDocumentV3 - Version 3 network status document + +- BridgeNetworkStatusDocument - Version 3 network status document for bridges DocumentSignature - Signature of a document by a directory authority DirectoryAuthority - Directory authority as defined in a v3 network status document