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