From 391b5ded870b66f5039d3e4d011cc9301ab2c5f0 Mon Sep 17 00:00:00 2001 From: Dmitri Bogomolov <4glitch@gmail.com> Date: Mon, 8 Jul 2019 17:20:29 +0300 Subject: [PATCH] Docstrings in network from #1368 --- src/network/connectionpool.py | 16 ++++++++++++++++ src/network/proxy.py | 16 ++++++++++++++++ 2 files changed, 32 insertions(+) diff --git a/src/network/connectionpool.py b/src/network/connectionpool.py index 9a51f513..077f44a5 100644 --- a/src/network/connectionpool.py +++ b/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 diff --git a/src/network/proxy.py b/src/network/proxy.py index e2d03446..04f0ac13 100644 --- a/src/network/proxy.py +++ b/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