commit bff56e18ecde250eb9ad2eba7db5e29d1817bd8f Author: Damian Johnson atagar@torproject.org Date: Sat May 12 13:57:53 2012 -0700

Revising descriptor pydocs

Revisited the ordering, defaults, and descriptions of descriptor attributes to be shorter and more user friendly. --- stem/descriptor/extrainfo_descriptor.py | 74 ++++++++++----------- stem/descriptor/server_descriptor.py | 96 +++++++++++++++------------- test/integ/descriptor/server_descriptor.py | 2 +- 3 files changed, 87 insertions(+), 85 deletions(-)

diff --git a/stem/descriptor/extrainfo_descriptor.py b/stem/descriptor/extrainfo_descriptor.py index a9bbfec..93b438c 100644 --- a/stem/descriptor/extrainfo_descriptor.py +++ b/stem/descriptor/extrainfo_descriptor.py @@ -139,47 +139,43 @@ class ExtraInfoDescriptor(stem.descriptor.Descriptor): Extra-info descriptor document.

Attributes: - nickname (str) - relay's nickname (*) - fingerprint (str) - fourty hex digits that make up the relay's fingerprint (*) - published (datetime.datetime) - time in GMT when the descriptor was generated (*) - geoip_db_digest (str) - sha1 of geoIP database file - signature (str) - signature for this extrainfo descriptor (*) + nickname (str) - relay's nickname (*) + fingerprint (str) - identity key fingerprint (*) + published (datetime) - time in GMT when this descriptor was made (*) + geoip_db_digest (str) - sha1 of geoIP database file + signature (str) - signature for this extrainfo descriptor (*)

Bytes read/written for relayed traffic - read_history_end (datetime.datetime) - end of the sampling interval + read_history_end (datetime) - end of the sampling interval read_history_interval (int) - seconds per interval - read_history_values (list) - bytes read during each interval (*) + read_history_values (list) - bytes read during each interval

- write_history_end (datetime.datetime) - end of the sampling interval + write_history_end (datetime) - end of the sampling interval write_history_interval (int) - seconds per interval - write_history_values (list) - bytes written during each interval (*) - - Directory Mirror Attributes: - dirreq_stats_end (datetime.datetime) - end of the period where directory - mirroring stats were gathered - dirreq_stats_interval (int) - length in seconds of the interval where - directory stats were gathered + write_history_values (list) - bytes written during each interval

- Bytes read/written for directory mirroring - dir_read_history_end (datetime.datetime) - end of the sampling interval - dir_read_history_interval (int) - seconds per interval - dir_read_history_values (list) - bytes read during each interval (*) + Directory Mirror Attributes: + dirreq_stats_end (datetime) - end of the period when stats were gathered + dirreq_stats_interval (int) - length in seconds of the interval

- dir_write_history_end (datetime.datetime) - end of the sampling interval - dir_write_history_interval (int) - seconds per interval - dir_write_history_values (list) - bytes read during each interval (*) - - Bridge Attributes: - bridge_stats_end (datetime.datetime) - end of the period when geoip - statistics were gathered - bridge_stats_interval (int) - length in seconds of the interval where - stats were gathered - bridge_ips (dict) - mapping of country codes to a rounded number of unique - ips from that region - geoip_start_time (datetime.datetime) - replaced by bridge_stats_end - geoip_client_origins (dict) - replaced by bridge_ips + Bytes read/written for directory mirroring + dir_read_history_end (datetime) - end of the sampling interval + dir_read_history_interval (int) - seconds per interval + dir_read_history_values (list) - bytes read during each interval + + dir_write_history_end (datetime) - end of the sampling interval + dir_write_history_interval (int) - seconds per interval + dir_write_history_values (list) - bytes read during each interval + + Bridge Attributes: + bridge_stats_end (datetime) - end of the period when stats were gathered + bridge_stats_interval (int) - length in seconds of the interval + bridge_ips (dict) - mapping of locales to rounded count of unique user ips + geoip_start_time (datetime) - (deprecated) replaced by bridge_stats_end + geoip_client_origins (dict) - (deprecated) replaced by bridge_ips

- (*) required fields, others are left as None if undefined + (*) attribute is either required when we're parsed with validation or has a + default value, others are left as None if undefined """

def __init__(self, raw_contents, validate = True, annotations = None): @@ -211,22 +207,22 @@ class ExtraInfoDescriptor(stem.descriptor.Descriptor):

self.read_history_end = None self.read_history_interval = None - self.read_history_values = [] + self.read_history_values = None

self.write_history_end = None self.write_history_interval = None - self.write_history_values = [] + self.write_history_values = None

self.dirreq_stats_end = None self.dirreq_stats_interval = None

self.dir_read_history_end = None self.dir_read_history_interval = None - self.dir_read_history_values = [] + self.dir_read_history_values = None

self.dir_write_history_end = None self.dir_write_history_interval = None - self.dir_write_history_values = [] + self.dir_write_history_values = None

self.bridge_stats_end = None self.bridge_stats_interval = None diff --git a/stem/descriptor/server_descriptor.py b/stem/descriptor/server_descriptor.py index 7e16c77..d347b15 100644 --- a/stem/descriptor/server_descriptor.py +++ b/stem/descriptor/server_descriptor.py @@ -141,42 +141,47 @@ class ServerDescriptor(stem.descriptor.Descriptor): Common parent for server descriptors.

Attributes: - nickname (str) - relay's nickname (*) - fingerprint (str) - fourty hex digits that make up the relay's fingerprint - address (str) - IPv4 address of the relay (*) - or_port (int) - port used for relaying (*) - socks_port (int) - (deprecated) always zero (*) - dir_port (int) - port used for descriptor mirroring (*) - platform (str) - operating system and tor version + nickname (str) - relay's nickname (*) + fingerprint (str) - identity key fingerprint + published (datetime) - time in GMT when this descriptor was made (*) + + address (str) - IPv4 address of the relay (*) + or_port (int) - port used for relaying (*) + socks_port (int) - (deprecated, always zero) port used as client (*) + dir_port (int) - port used for descriptor mirroring (*) + + platform (str) - line with operating system and tor version tor_version (stem.version.Version) - version of tor - operating_system (str) - relay's operating system - uptime (int) - relay's uptime when published in seconds - published (datetime.datetime) - time in GMT when the descriptor was generated (*) - contact (str) - relay's contact information - link_protocols (list) - link protocols supported by the relay - circuit_protocols (list) - circuit protocols supported by the relay - hibernating (bool) - flag to indicate if the relay was hibernating when published (*) - allow_single_hop_exits (bool) - flag to indicate if single hop exiting is allowed from it (*) - extra_info_cache (bool) - flag to indicate if it's a mirror for extra-info documents (*) - extra_info_digest (str) - hex encoded digest of our extra-info document - hidden_service_dir (list) - hidden service descriptor versions that it stores - exit_policy (stem.exit_policy.ExitPolicy) - relay's stated exit policy - family (list) - nicknames or fingerprints of relays it has a declared family with (*) - average_bandwidth (int) - rate of traffic relay is willing to relay in bytes/s (*) - burst_bandwidth (int) - rate of traffic relay is willing to burst to in bytes/s (*) - observed_bandwidth (int) - estimated capacity of the relay based on usage in bytes/s (*) - eventdns (bool) - (deprecated) always unset (*) + operating_system (str) - operating system + uptime (int) - uptime when published in seconds + contact (str) - contact information + exit_policy (stem.exit_policy.ExitPolicy) - stated exit policy (*) + family (list) - nicknames or fingerprints of declared family (*) + + average_bandwidth (int) - averate rate it's willing to relay in bytes/s (*) + burst_bandwidth (int) - burst rate it's willing to relay in bytes/s (*) + observed_bandwidth (int) - estimated capacity based on usage in bytes/s (*) + + link_protocols (list) - link protocols supported by the relay + circuit_protocols (list) - circuit protocols supported by the relay + hibernating (bool) - hibernating when published (*) + allow_single_hop_exits (bool) - flag if single hop exiting is allowed (*) + extra_info_cache (bool) - flag if a mirror for extra-info documents (*) + extra_info_digest (str) - hex encoded digest of our extra-info document + hidden_service_dir (list) - hidden service descriptor versions it stores + eventdns (bool) - (deprecated, always unset) flag for evdns backend

Deprecated, moved to extra-info descriptor... - read_history_end (datetime.datetime) - end of the sampling interval + read_history_end (datetime) - end of the sampling interval read_history_interval (int) - seconds per interval - read_history_values (list) - bytes read during each interval (*) + read_history_values (list) - bytes read during each interval

- write_history_end (datetime.datetime) - end of the sampling interval + write_history_end (datetime) - end of the sampling interval write_history_interval (int) - seconds per interval - write_history_values (list) - bytes written during each interval (*) - - (*) required fields, others are left as None if undefined + write_history_values (list) - bytes written during each interval + + (*) attribute is either required when we're parsed with validation or has a + default value, others are left as None if undefined """

def __init__(self, raw_contents, validate = True, annotations = None): @@ -203,16 +208,25 @@ class ServerDescriptor(stem.descriptor.Descriptor):

self.nickname = None self.fingerprint = None + self.published = None + self.address = None self.or_port = None self.socks_port = None self.dir_port = None + self.platform = None self.tor_version = None self.operating_system = None self.uptime = None - self.published = None self.contact = None + self.exit_policy = [] # should be an ExitPolicy instance when we have the class... + self.family = [] + + self.average_bandwidth = None + self.burst_bandwidth = None + self.observed_bandwidth = None + self.link_protocols = None self.circuit_protocols = None self.hibernating = False @@ -220,30 +234,21 @@ class ServerDescriptor(stem.descriptor.Descriptor): self.extra_info_cache = False self.extra_info_digest = None self.hidden_service_dir = None - self.family = [] - self.average_bandwidth = None - self.burst_bandwidth = None - self.observed_bandwidth = None - self.eventdns = True + self.eventdns = None

self.read_history_end = None self.read_history_interval = None - self.read_history_values = [] + self.read_history_values = None

self.write_history_end = None self.write_history_interval = None - self.write_history_values = [] + self.write_history_values = None

self._unrecognized_lines = []

self._annotation_lines = annotations if annotations else [] self._annotation_dict = None # cached breakdown of key/value mappings

- # TODO: Until we have a proper ExitPolicy class this is just a list of the - # exit policy strings... - - self.exit_policy = [] - # A descriptor contains a series of 'keyword lines' which are simply a # keyword followed by an optional value. Lines can also be followed by a # signature block. @@ -551,8 +556,9 @@ class RelayDescriptor(ServerDescriptor): onion_key (str) - key used to encrypt EXTEND cells (*) signing_key (str) - relay's long-term identity key (*) signature (str) - signature for this descriptor (*) - - (*) required fields, others are left as None if undefined + + (*) attribute is either required when we're parsed with validation or has a + default value, others are left as None if undefined """

def __init__(self, raw_contents, validate = True, annotations = None): diff --git a/test/integ/descriptor/server_descriptor.py b/test/integ/descriptor/server_descriptor.py index d7b5c14..3c07364 100644 --- a/test/integ/descriptor/server_descriptor.py +++ b/test/integ/descriptor/server_descriptor.py @@ -160,7 +160,7 @@ Qlx9HNCqCY877ztFRC624ja2ql6A2hBcuoYMbkHjcQ4= # the following attributes should be deprecated, and not appear in the wild self.assertEquals(None, desc.read_history_end) self.assertEquals(None, desc.write_history_end) - self.assertEquals(True, desc.eventdns) + self.assertEquals(None, desc.eventdns) self.assertEquals(0, desc.socks_port)

unrecognized_lines = desc.get_unrecognized_lines()