[tor-commits] [stem/master] Revising descriptor pydocs
atagar at torproject.org
atagar at torproject.org
Mon May 14 00:14:27 UTC 2012
commit bff56e18ecde250eb9ad2eba7db5e29d1817bd8f
Author: Damian Johnson <atagar at 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()
More information about the tor-commits
mailing list