commit 152497ffaff55edc956f7423ab03e90697a252d3 Author: Illia Volochii illia.volochii@gmail.com 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