[tor-commits] [stem/master] Revised API docs for stem.util.connection

[atagar at torproject.org]

commit 15ff02a5d2d654fb6afd6791d635ee2421f1b604
Author: Damian Johnson <atagar at torproject.org>
Date:   Sat Oct 27 15:14:26 2012 -0700

    Revised API docs for stem.util.connection
---
 docs/api.rst             |    3 +++
 docs/contents.rst        |    1 +
 docs/util/connection.rst |    5 +++++
 stem/util/connection.py  |   26 +++++++++++++-------------
 4 files changed, 22 insertions(+), 13 deletions(-)

diff --git a/docs/api.rst b/docs/api.rst
index f92a84a..01c929d 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -11,11 +11,13 @@ Descriptors
 -----------
 
 * **Classes**
+
  * `stem.descriptor <descriptor/descriptor.html>`_ - Base class for descriptors.
  * `stem.descriptor.server_descriptor <descriptor/server_descriptor.html>`_ - Relay and bridge server descriptors.
  * `stem.descriptor.extrainfo_descriptor <descriptor/extrainfo_descriptor.html>`_ - Relay and bridge extrainfo descriptors.
  * `stem.descriptor.networkstatus <descriptor/networkstatus.html>`_ - Network status documents which make up the Tor consensus.
  * `stem.descriptor.router_status_entry <descriptor/router_status_entry.html>`_ - Relay entries within a network status document.
+
 * `stem.descriptor.reader <descriptor/reader.html>`_ - Reads and parses descriptor files from disk.
 * `stem.descriptor.export <descriptor/export.html>`_ - Exports descriptors to other formats.
 
@@ -23,5 +25,6 @@ Utilities
 ---------
 
 * `stem.util.conf <util/conf.html>`_ - Configuration file handling.
+* `stem.util.connection <util/connection.html>`_ - Connection and IP related utilities.
 * `stem.util.enum <util/enum.html>`_ - Enumeration class.
 
diff --git a/docs/contents.rst b/docs/contents.rst
index 90b1af6..4cfbe21 100644
--- a/docs/contents.rst
+++ b/docs/contents.rst
@@ -21,5 +21,6 @@ Contents
    types/version
 
    util/conf
+   util/connection
    util/enum
 
diff --git a/docs/util/connection.rst b/docs/util/connection.rst
new file mode 100644
index 0000000..63e3b96
--- /dev/null
+++ b/docs/util/connection.rst
@@ -0,0 +1,5 @@
+Connection Utilities
+====================
+
+.. automodule:: stem.util.connection
+
diff --git a/stem/util/connection.py b/stem/util/connection.py
index 02201bb..104ad5c 100644
--- a/stem/util/connection.py
+++ b/stem/util/connection.py
@@ -36,7 +36,7 @@ def is_valid_ip_address(address):
   
   :param str address: string to be checked
   
-  :returns: True if input is a valid IPv4 address, False otherwise
+  :returns: **True** if input is a valid IPv4 address, **False** otherwise
   """
   
   if not isinstance(address, str): return False
@@ -60,7 +60,7 @@ def is_valid_ipv6_address(address, allow_brackets = False):
   :param str address: string to be checked
   :param bool allow_brackets: ignore brackets which form '[address]'
   
-  :returns: True if input is a valid IPv6 address, False otherwise
+  :returns: **True** if input is a valid IPv6 address, **False** otherwise
   """
   
   if allow_brackets:
@@ -93,7 +93,7 @@ def is_valid_port(entry, allow_zero = False):
   :param list,str,int entry: string, integer or list to be checked
   :param bool allow_zero: accept port number of zero (reserved by defintion)
   
-  :returns: True if input is an integer and within the valid port range, False otherwise
+  :returns: **True** if input is an integer and within the valid port range, **False** otherwise
   """
   
   if isinstance(entry, list):
@@ -129,7 +129,7 @@ def expand_ipv6_address(address):
   
   :param str address: IPv6 address to be expanded
   
-  :raises: ValueError if the address can't be expanded due to being malformed
+  :raises: **ValueError** if the address can't be expanded due to being malformed
   """
   
   if not is_valid_ipv6_address(address):
@@ -158,9 +158,9 @@ def get_mask(bits):
   
   :param int bits: number of bits to be converted
   
-  :returns: str with the subnet mask representation for this many bits
+  :returns: **str** with the subnet mask representation for this many bits
   
-  :raises: ValueError if given a number of bits outside the range of 0-32
+  :raises: **ValueError** if given a number of bits outside the range of 0-32
   """
   
   if bits > 32 or bits < 0:
@@ -182,9 +182,9 @@ def get_masked_bits(mask):
   
   :param str mask: mask to be converted
   
-  :returns: int with the number of bits represented by the mask
+  :returns: **int** with the number of bits represented by the mask
   
-  :raises: ValueError if the mask is invalid or can't be converted
+  :raises: **ValueError** if the mask is invalid or can't be converted
   """
   
   if not is_valid_ip_address(mask):
@@ -206,9 +206,9 @@ def get_mask_ipv6(bits):
   
   :param int bits: number of bits to be converted
   
-  :returns: str with the subnet mask representation for this many bits
+  :returns: **str** with the subnet mask representation for this many bits
   
-  :raises: ValueError if given a number of bits outside the range of 0-128
+  :raises: **ValueError** if given a number of bits outside the range of 0-128
   """
   
   if bits > 128 or bits < 0:
@@ -239,9 +239,9 @@ def get_address_binary(address):
   """
   Provides the binary value for an IPv4 or IPv6 address.
   
-  :returns: str with the binary prepresentation of this address
+  :returns: **str** with the binary prepresentation of this address
   
-  :raises: ValueError if address is neither an IPv4 nor IPv6 address
+  :raises: **ValueError** if address is neither an IPv4 nor IPv6 address
   """
   
   if is_valid_ip_address(address):
@@ -271,7 +271,7 @@ def cryptovariables_equal(x, y):
   :param str x: string to be compared.
   :param str y: the other string to be compared.
   
-  :returns: True if both strings are equal, False otherwise.
+  :returns: **True** if both strings are equal, **False** otherwise.
   """
   
   return (hmac_sha256(CRYPTOVARIABLE_EQUALITY_COMPARISON_NONCE, x) ==