[tor-commits] [stem/master] Update docstrings in stem/socket.py

[atagar@xxxxxxxxxxxxxx]

commit 152497ffaff55edc956f7423ab03e90697a252d3
Author: Illia Volochii <illia.volochii@xxxxxxxxx>
Date:   Sun May 17 18:29:57 2020 +0300

    Update docstrings in stem/socket.py
---
 stem/socket.py | 54 ++++++++++++++++++++++++++++--------------------------
 1 file changed, 28 insertions(+), 26 deletions(-)

diff --git a/stem/socket.py b/stem/socket.py
index e8ae492b..0feae831 100644
--- a/stem/socket.py
+++ b/stem/socket.py
@@ -15,31 +15,42 @@ Tor...
 
 ::
 
-  import stem
+  import asyncio
+  import sys
+
   import stem.connection
   import stem.socket
 
-  if __name__ == '__main__':
+  async def print_version() -> None:
     try:
       control_socket = stem.socket.ControlPort(port = 9051)
-      stem.connection.authenticate(control_socket)
+      await control_socket.connect()
+      await stem.connection.authenticate(control_socket)
     except stem.SocketError as exc:
-      print 'Unable to connect to tor on port 9051: %s' % exc
+      print(f'Unable to connect to tor on port 9051: {exc}')
       sys.exit(1)
     except stem.connection.AuthenticationFailure as exc:
-      print 'Unable to authenticate: %s' % exc
+      print(f'Unable to authenticate: {exc}')
       sys.exit(1)
 
-    print "Issuing 'GETINFO version' query...\\n"
-    control_socket.send('GETINFO version')
-    print control_socket.recv()
+    print("Issuing 'GETINFO version' query...\\n")
+    await control_socket.send('GETINFO version')
+    print(await control_socket.recv())
+
+
+  if __name__ == '__main__':
+    loop = asyncio.get_event_loop()
+    try:
+      loop.run_until_complete(print_version())
+    finally:
+      loop.close()
 
 ::
 
   % python example.py
   Issuing 'GETINFO version' query...
 
-  version=0.2.4.10-alpha-dev (git-8be6058d8f31e578)
+  version=0.4.3.5
   OK
 
 **Module Overview:**
@@ -66,6 +77,7 @@ Tor...
 
   send_message - Writes a message to a control socket.
   recv_message - Reads a ControlMessage from a control socket.
+  recv_message_from_bytes_io - Reads a ControlMessage from an I/O stream.
   send_formatting - Performs the formatting expected from sent messages.
 """
 
@@ -210,11 +222,7 @@ class BaseSocket(object):
 
   async def _send(self, message: Union[bytes, str], handler: Callable[[Union[socket.socket, ssl.SSLSocket], BinaryIO, Union[bytes, str]], None]) -> None:
     """
-    Send message in a thread safe manner. Handler is expected to be of the form...
-
-    ::
-
-      my_handler(socket, socket_file, message)
+    Send message in a thread safe manner.
     """
 
     with self._send_lock:
@@ -242,11 +250,7 @@ class BaseSocket(object):
 
   async def _recv(self, handler):
     """
-    Receives a message in a thread safe manner. Handler is expected to be of the form...
-
-    ::
-
-      my_handler(socket, socket_file)
+    Receives a message in a thread safe manner.
     """
 
     with self._recv_lock:
@@ -405,7 +409,7 @@ class ControlSocket(BaseSocket):
   receiving complete messages.
 
   Callers should not instantiate this class directly, but rather use subclasses
-  which are expected to implement the **_make_socket()** method.
+  which are expected to implement the **_open_connection()** method.
   """
 
   def __init__(self) -> None:
@@ -483,7 +487,7 @@ class ControlSocketFile(ControlSocket):
     """
     ControlSocketFile constructor.
 
-    :param socket_path: path where the control socket is located
+    :param path: path where the control socket is located
     """
 
     super(ControlSocketFile, self).__init__()
@@ -571,8 +575,7 @@ async def recv_message(reader: asyncio.StreamReader, arrived_at: Optional[float]
   Pulls from a control socket until we either have a complete message or
   encounter a problem.
 
-  :param control_file: file derived from the control socket (see the
-    socket's makefile() method for more information)
+  :param reader: reader object
 
   :returns: :class:`~stem.response.ControlMessage` read from the socket
 
@@ -692,11 +695,10 @@ async def recv_message(reader: asyncio.StreamReader, arrived_at: Optional[float]
 
 def recv_message_from_bytes_io(reader: asyncio.StreamReader, arrived_at: Optional[float] = None) -> 'stem.response.ControlMessage':
   """
-  Pulls from a control socket until we either have a complete message or
+  Pulls from an I/O stream until we either have a complete message or
   encounter a problem.
 
-  :param file control_file: file derived from the control socket (see the
-    socket's makefile() method for more information)
+  :param file reader: I/O stream
 
   :returns: :class:`~stem.response.ControlMessage` read from the socket
 



_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits