[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