Stem Docs

Router Status Entries

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…

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 provided

Raises:
  • 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