Router Status Entries¶
Parsing for router status entries, the information for individual routers within a network status document. This information is provided from a few sources…
- control port via ‘GETINFO ns/*’ and ‘GETINFO md/*’ queries
- router entries in a network status document, like the cached-consensus
Module Overview:
RouterStatusEntry - Common parent for router status entries
|- RouterStatusEntryV2 - Entry for a network status v2 document
| +- RouterStatusEntryBridgeV2 - Entry for a bridge flavored v2 document
|
|- RouterStatusEntryV3 - Entry for a network status v3 document
+- RouterStatusEntryMicroV3 - Entry for a microdescriptor flavored v3 document
-
class
stem.descriptor.router_status_entry.
RouterStatusEntry
(content, validate=False, document=None)[source]¶ Bases:
stem.descriptor.Descriptor
Information about an individual router stored within a network status document. This is the common parent for concrete status entry types.
Variables: - document (stem.descriptor.networkstatus.NetworkStatusDocument) – * document that this descriptor came from
- nickname (str) – * router’s nickname
- fingerprint (str) – * router’s fingerprint
- published (datetime) – * router’s publication
- address (str) – * router’s IP address
- or_port (int) – * router’s ORPort
- dir_port (int) – * router’s DirPort
- flags (list) – * list of
Flag
associated with the relay - version (stem.version.Version) – parsed version of tor, this is None if the relay’s using a new versioning scheme
- version_line (str) – versioning information reported by the relay
-
classmethod
from_str
(content, **kwargs)[source]¶ Provides a
Descriptor
for the given content.To parse a descriptor we must know its type. There are three ways to convey this…
# use a descriptor_type argument desc = Descriptor.from_str(content, descriptor_type = 'server-descriptor 1.0') # prefixing the content with a "@type" annotation desc = Descriptor.from_str('@type server-descriptor 1.0\n' + content) # use this method from a subclass desc = stem.descriptor.server_descriptor.RelayDescriptor.from_str(content)
New in version 1.8.0.
Parameters: - content (str,bytes) – string to construct the descriptor from
- multiple (bool) – if provided with True this provides a list of descriptors rather than a single one
- kwargs (dict) – additional arguments for
parse_file()
Returns: Descriptor
subclass for the given content, or a list of descriptors if multiple = True is providedRaises: - ValueError if the contents is malformed and validate is True
- TypeError if we can’t match the contents of the file to a descriptor type
- IOError if unable to read from the descriptor_file
-
class
stem.descriptor.router_status_entry.
RouterStatusEntryV2
(content, validate=False, document=None)[source]¶ Bases:
stem.descriptor.router_status_entry.RouterStatusEntry
Information about an individual router stored within a version 2 network status document.
Variables: digest (str) – * router’s upper-case hex digest * attribute is either required when we’re parsed with validation or has a default value, others are left as None if undefined
-
TYPE_ANNOTATION_NAME
= 'network-status-consensus-2'¶
-
classmethod
content
(attr=None, exclude=(), sign=False)[source]¶ Creates descriptor content with the given attributes. Mandatory fields are filled with dummy information unless data is supplied. This doesn’t yet create a valid signature.
New in version 1.6.0.
Parameters: - attr (dict) – keyword/value mappings to be included in the descriptor
- exclude (list) – mandatory keywords to exclude from the descriptor, this results in an invalid descriptor
- sign (bool) – includes cryptographic signatures and digests if True
Returns: str with the content of a descriptor
Raises: - ImportError if cryptography is unavailable and sign is True
- NotImplementedError if not implemented for this descriptor type
-
-
class
stem.descriptor.router_status_entry.
RouterStatusEntryBridgeV2
(content, validate=False, document=None)[source]¶ Bases:
stem.descriptor.router_status_entry.RouterStatusEntryV2
Information about an individual router stored within a bridge flavored version 2 network status document.
New in version 1.8.0.
-
TYPE_ANNOTATION_NAME
= 'bridge-network-status'¶
-
-
class
stem.descriptor.router_status_entry.
RouterStatusEntryV3
(content, validate=False, document=None)[source]¶ Bases:
stem.descriptor.router_status_entry.RouterStatusEntry
Information about an individual router stored within a version 3 network status document.
Variables: - or_addresses (list) – * relay’s OR addresses, this is a tuple listing of the form (address (str), port (int), is_ipv6 (bool))
- identifier_type (str) – identity digest key type
- identifier (str) – base64 encoded identity digest
- digest (str) – * router’s upper-case hex digest
- bandwidth (int) – bandwidth measured to be available by the relay, this is an arbitrary units (currently kilobytes per second) heuristic generated by the Bandwidth authoritites to weight relay selection
- measured (int) – bandwidth vote provided by a bandwidth authority
- is_unmeasured (bool) – bandwidth measurement isn’t based on three or more measurements
- unrecognized_bandwidth_entries (list) – * bandwidth weighting information that isn’t yet recognized
- exit_policy (stem.exit_policy.MicroExitPolicy) – router’s exit policy
- protocols (dict) – mapping of protocols to their supported versions
- microdescriptor_hashes (list) – * tuples of two values, the list of consensus methods for generating a set of digests and the ‘algorithm => digest’ mappings
* attribute is either required when we’re parsed with validation or has a default value, others are left as None if undefined
Changed in version 1.5.0: Added the identifier and identifier_type attributes.
Changed in version 1.6.0: Added the protocols attribute.
-
TYPE_ANNOTATION_NAME
= 'network-status-consensus-3'¶
-
classmethod
content
(attr=None, exclude=(), sign=False)[source]¶ Creates descriptor content with the given attributes. Mandatory fields are filled with dummy information unless data is supplied. This doesn’t yet create a valid signature.
New in version 1.6.0.
Parameters: - attr (dict) – keyword/value mappings to be included in the descriptor
- exclude (list) – mandatory keywords to exclude from the descriptor, this results in an invalid descriptor
- sign (bool) – includes cryptographic signatures and digests if True
Returns: str with the content of a descriptor
Raises: - ImportError if cryptography is unavailable and sign is True
- NotImplementedError if not implemented for this descriptor type
-
class
stem.descriptor.router_status_entry.
RouterStatusEntryMicroV3
(content, validate=False, document=None)[source]¶ Bases:
stem.descriptor.router_status_entry.RouterStatusEntry
Information about an individual router stored within a microdescriptor flavored network status document.
Variables: - or_addresses (list) – * relay’s OR addresses, this is a tuple listing of the form (address (str), port (int), is_ipv6 (bool))
- bandwidth (int) – bandwidth claimed by the relay (in kb/s)
- measured (int) – bandwidth measured to be available by the relay
- is_unmeasured (bool) – bandwidth measurement isn’t based on three or more measurements
- unrecognized_bandwidth_entries (list) – * bandwidth weighting information that isn’t yet recognized
- protocols (dict) – mapping of protocols to their supported versions
- digest (str) – * router’s hex encoded digest of our corresponding microdescriptor (deprecated, use microdescriptor_digest instead)
- microdescriptor_digest (str) – * router’s base64 encoded digest of our corresponding microdescriptor
Changed in version 1.6.0: Added the protocols attribute.
Changed in version 1.7.0: Added the or_addresses attribute.
Changed in version 1.7.0: Added the microdescriptor_digest attribute to replace our now deprecated digest attribute.
* attribute is either required when we’re parsed with validation or has a default value, others are left as None if undefined
-
TYPE_ANNOTATION_NAME
= 'network-status-microdesc-consensus-3'¶
-
classmethod
content
(attr=None, exclude=(), sign=False)[source]¶ Creates descriptor content with the given attributes. Mandatory fields are filled with dummy information unless data is supplied. This doesn’t yet create a valid signature.
New in version 1.6.0.
Parameters: - attr (dict) – keyword/value mappings to be included in the descriptor
- exclude (list) – mandatory keywords to exclude from the descriptor, this results in an invalid descriptor
- sign (bool) – includes cryptographic signatures and digests if True
Returns: str with the content of a descriptor
Raises: - ImportError if cryptography is unavailable and sign is True
- NotImplementedError if not implemented for this descriptor type