Docstrings in network from #1368

src/network/connectionpool.py

@@ -21,6 +21,7 @@ from udp import UDPSocket
 
 @Singleton
 class BMConnectionPool(object):
+    """Pool of all existing connections"""
     def __init__(self):
         asyncore.set_rates(
             BMConfigParser().safeGetInt(
@@ -38,9 +39,14 @@ class BMConnectionPool(object):
         self.bootstrapped = False
 
     def connectToStream(self, streamNumber):
+        """Connect to a bitmessage stream"""
         self.streams.append(streamNumber)
 
     def getConnectionByAddr(self, addr):
+        """
+        Return an (existing) connection object based on a `Peer` object
+        (IP and port)
+        """
         try:
             return self.inboundConnections[addr]
         except KeyError:
@@ -60,6 +66,7 @@ class BMConnectionPool(object):
         raise KeyError
 
     def isAlreadyConnected(self, nodeid):
+        """Check if we're already connected to this peer"""
         for i in (
             self.inboundConnections.values() +
             self.outboundConnections.values()
@@ -72,6 +79,7 @@ class BMConnectionPool(object):
         return False
 
     def addConnection(self, connection):
+        """Add a connection object to our internal dict"""
         if isinstance(connection, UDPSocket):
             return
         if connection.isOutbound:
@@ -84,6 +92,7 @@ class BMConnectionPool(object):
                     connection
 
     def removeConnection(self, connection):
+        """Remove a connection from our internal dict"""
         if isinstance(connection, UDPSocket):
             del self.udpSockets[connection.listening.host]
         elif isinstance(connection, TCPServer):
@@ -105,6 +114,7 @@ class BMConnectionPool(object):
         connection.handle_close()
 
     def getListeningIP(self):
+        """What IP are we supposed to be listening on?"""
         if BMConfigParser().safeGet(
                 "bitmessagesettings", "onionhostname").endswith(".onion"):
             host = BMConfigParser().safeGet(
@@ -121,6 +131,7 @@ class BMConnectionPool(object):
         return host
 
     def startListening(self, bind=None):
+        """Open a listening socket and start accepting connections on it"""
         if bind is None:
             bind = self.getListeningIP()
         port = BMConfigParser().safeGetInt("bitmessagesettings", "port")
@@ -129,6 +140,10 @@ class BMConnectionPool(object):
         self.listeningSockets[ls.destination] = ls
 
     def startUDPSocket(self, bind=None):
+        """
+        Open an UDP socket. Depending on settings, it can either only
+        accept incoming UDP packets, or also be able to send them.
+        """
         if bind is None:
             host = self.getListeningIP()
             udpSocket = UDPSocket(host=host, announcing=True)
@@ -140,6 +155,7 @@ class BMConnectionPool(object):
         self.udpSockets[udpSocket.listening.host] = udpSocket
 
     def loop(self):
+        """Main Connectionpool's loop"""
         # defaults to empty loop if outbound connections are maxed
         spawnConnections = False
         acceptConnections = True

src/network/proxy.py

@@ -9,6 +9,7 @@ from debug import logger
 
 
 class ProxyError(Exception):
+    """Base proxy exception class"""
     errorCodes = ("Unknown error",)
 
     def __init__(self, code=-1):
@@ -21,6 +22,7 @@ class ProxyError(Exception):
 
 
 class GeneralProxyError(ProxyError):
+    """General proxy error class (not specfic to an implementation)"""
     errorCodes = (
         "Success",
         "Invalid data",
@@ -36,6 +38,7 @@ class GeneralProxyError(ProxyError):
 
 
 class Proxy(AdvancedDispatcher):
+    """Base proxy class"""
     # these are global, and if you change config during runtime,
     # all active/new instances should change too
     _proxy = ("127.0.0.1", 9050)
@@ -46,10 +49,12 @@ class Proxy(AdvancedDispatcher):
 
     @property
     def proxy(self):
+        """Return proxy IP and port"""
         return self.__class__._proxy
 
     @proxy.setter
     def proxy(self, address):
+        """Set proxy IP and port"""
         if (not isinstance(address, tuple) or len(address) < 2 or
             not isinstance(address[0], str) or
                 not isinstance(address[1], int)):
@@ -58,18 +63,25 @@ class Proxy(AdvancedDispatcher):
 
     @property
     def auth(self):
+        """Return proxy authentication settings"""
         return self.__class__._auth
 
     @auth.setter
     def auth(self, authTuple):
+        """Set proxy authentication (username and password)"""
         self.__class__._auth = authTuple
 
     @property
     def onion_proxy(self):
+        """
+        Return separate proxy IP and port for use only with onion
+        addresses. Untested.
+        """
         return self.__class__._onion_proxy
 
     @onion_proxy.setter
     def onion_proxy(self, address):
+        """Set onion proxy address"""
         if address is not None and (
             not isinstance(address, tuple) or len(address) < 2 or
             not isinstance(address[0], str) or
@@ -79,10 +91,12 @@ class Proxy(AdvancedDispatcher):
 
     @property
     def onion_auth(self):
+        """Return proxy authentication settings for onion hosts only"""
         return self.__class__._onion_auth
 
     @onion_auth.setter
     def onion_auth(self, authTuple):
+        """Set proxy authentication for onion hosts only. Untested."""
         self.__class__._onion_auth = authTuple
 
     def __init__(self, address):
@@ -110,6 +124,7 @@ class Proxy(AdvancedDispatcher):
         )
 
     def handle_connect(self):
+        """Handle connection event (to the proxy)"""
         self.set_state("init")
         try:
             AdvancedDispatcher.handle_connect(self)
@@ -122,5 +137,6 @@ class Proxy(AdvancedDispatcher):
         self.state_init()
 
     def state_proxy_handshake_done(self):
+        """Handshake is complete at this point"""
         self.connectedAt = time.time()
         return False