Control Socket
**************

Supports communication with sockets speaking Tor protocols. This
allows us to send messages as basic strings, and receive responses as
"ControlMessage" instances.

**This module only consists of low level components, and is not
intended for users.** See our tutorials and Control Module if you’re
new to Stem and looking to get started.

With that aside, these can still be used for raw socket communication
with Tor…

   import stem
   import stem.connection
   import stem.socket

   if __name__ == '__main__':
     try:
       control_socket = stem.socket.ControlPort(port = 9051)
       stem.connection.authenticate(control_socket)
     except stem.SocketError as exc:
       print 'Unable to connect to tor on port 9051: %s' % exc
       sys.exit(1)
     except stem.connection.AuthenticationFailure as exc:
       print 'Unable to authenticate: %s' % exc
       sys.exit(1)

     print "Issuing 'GETINFO version' query...\n"
     control_socket.send('GETINFO version')
     print control_socket.recv()

   % python example.py
   Issuing 'GETINFO version' query...

   version=0.2.4.10-alpha-dev (git-8be6058d8f31e578)
   OK

**Module Overview:**

   BaseSocket - Thread safe socket.
     |- RelaySocket - Socket for a relay's ORPort.
     |  |- send - sends a message to the socket
     |  +- recv - receives a response from the socket
     |
     |- ControlSocket - Socket wrapper that speaks the tor control protocol.
     |  |- ControlPort - Control connection via a port.
     |  |- ControlSocketFile - Control connection via a local file socket.
     |  |
     |  |- send - sends a message to the socket
     |  +- recv - receives a ControlMessage from the socket
     |
     |- is_alive - reports if the socket is known to be closed
     |- is_localhost - returns if the socket is for the local system or not
     |- connection_time - timestamp when socket last connected or disconnected
     |- connect - connects a new socket
     |- close - shuts down the socket
     +- __enter__ / __exit__ - manages socket connection

   send_message - Writes a message to a control socket.
   recv_message - Reads a ControlMessage from a control socket.
   send_formatting - Performs the formatting expected from sent messages.

class stem.socket.BaseSocket

   Bases: "object"

   Thread safe socket, providing common socket functionality.

   is_alive()

      Checks if the socket is known to be closed. We won’t be aware if
      it is until we either use it or have explicitily shut it down.

      In practice a socket derived from a port knows about its
      disconnection after failing to receive data, whereas socket file
      derived connections know after either sending or receiving data.

      This means that to have reliable detection for when we’re
      disconnected you need to continually pull from the socket (which
      is part of what the "BaseController" does).

      Returns:
         **bool** that’s **True** if our socket is connected and
         **False** otherwise

   is_localhost()

      Returns if the connection is for the local system or not.

      Returns:
         **bool** that’s **True** if the connection is for the local
         host and **False** otherwise

   connection_time()

      Provides the unix timestamp for when our socket was either
      connected or disconnected. That is to say, the time we connected
      if we’re currently connected and the time we disconnected if
      we’re not connected.

      New in version 1.3.0.

      Returns:
         **float** for when we last connected or disconnected, zero if
         we’ve never connected

   connect()

      Connects to a new socket, closing our previous one if we’re
      already attached.

      Raises:
         "stem.SocketError" if unable to make a socket

   close()

      Shuts down the socket. If it’s already closed then this is a no-
      op.

class stem.socket.RelaySocket(address='127.0.0.1', port=9050, connect=True)

   Bases: "stem.socket.BaseSocket"

   Link-level connection to a Tor relay.

   New in version 1.7.0.

   Variables:
      * **address** (*str*) – address our socket connects to

      * **port** (*int*) – ORPort our socket connects to

   send(message)

      Sends a message to the relay’s ORPort.

      Parameters:
         **message** (*str*) – message to be formatted and sent to the
         socket

      Raises:
         * "stem.SocketError" if a problem arises in using the
           socket

         * "stem.SocketClosed" if the socket is known to be shut
           down

   recv(timeout=None)

      Receives a message from the relay.

      Parameters:
         **timeout** (*float*) – maxiumum number of seconds to await a
         response, this blocks indefinitely if **None**

      Returns:
         bytes for the message received

      Raises:
         * "stem.ProtocolError" the content from the socket is
           malformed

         * "stem.SocketClosed" if the socket closes before we
           receive a complete message

   is_localhost()

      Returns if the connection is for the local system or not.

      Returns:
         **bool** that’s **True** if the connection is for the local
         host and **False** otherwise

class stem.socket.ControlSocket

   Bases: "stem.socket.BaseSocket"

   Wrapper for a socket connection that speaks the Tor control
   protocol. To the better part this transparently handles the
   formatting for sending and receiving complete messages.

   Callers should not instantiate this class directly, but rather use
   subclasses which are expected to implement the **_make_socket()**
   method.

   send(message)

      Formats and sends a message to the control socket. For more
      information see the "send_message()" function.

      Deprecated since version 1.7.0: The **raw** argument was
      unhelpful and be removed. Use "stem.socket.send_message()" if
      you need this level of control instead.

      Parameters:
         **message** (*str*) – message to be formatted and sent to the
         socket

      Raises:
         * "stem.SocketError" if a problem arises in using the
           socket

         * "stem.SocketClosed" if the socket is known to be shut
           down

   recv()

      Receives a message from the control socket, blocking until we’ve
      received one. For more information see the "recv_message()"
      function.

      Returns:
         "ControlMessage" for the message received

      Raises:
         * "stem.ProtocolError" the content from the socket is
           malformed

         * "stem.SocketClosed" if the socket closes before we
           receive a complete message

class stem.socket.ControlPort(address='127.0.0.1', port=9051, connect=True)

   Bases: "stem.socket.ControlSocket"

   Control connection to tor. For more information see tor’s
   ControlPort torrc option.

   Variables:
      * **address** (*str*) – address our socket connects to

      * **port** (*int*) – ControlPort our socket connects to

   get_address()

      Provides the ip address our socket connects to.

      Deprecated since version 1.7.0: Use the **address** attribute
      instead.

      Returns:
         str with the ip address of our socket

   get_port()

      Provides the port our socket connects to.

      Deprecated since version 1.7.0: Use the **port** attribute
      instead.

      Returns:
         int with the port of our socket

   is_localhost()

      Returns if the connection is for the local system or not.

      Returns:
         **bool** that’s **True** if the connection is for the local
         host and **False** otherwise

class stem.socket.ControlSocketFile(path='/var/run/tor/control', connect=True)

   Bases: "stem.socket.ControlSocket"

   Control connection to tor. For more information see tor’s
   ControlSocket torrc option.

   Variables:
      **path** (*str*) – filesystem path of the socket we connect to

   get_socket_path()

      Provides the path our socket connects to.

      Deprecated since version 1.7.0: Use the **path** attribute
      instead.

      Returns:
         str with the path for our control socket

   is_localhost()

      Returns if the connection is for the local system or not.

      Returns:
         **bool** that’s **True** if the connection is for the local
         host and **False** otherwise

stem.socket.send_message(control_file, message, raw=False)

   Sends a message to the control socket, adding the expected
   formatting for single verses multi-line messages. Neither message
   type should contain an ending newline (if so it’ll be treated as a
   multi-line message with a blank line at the end). If the message
   doesn’t contain a newline then it’s sent as…

      <message>\r\n

   and if it does contain newlines then it’s split on "\n" and sent
   as…

      +<line 1>\r\n
      <line 2>\r\n
      <line 3>\r\n
      .\r\n

   Parameters:
      * **control_file** (*file*) – file derived from the control
        socket (see the socket’s makefile() method for more
        information)

      * **message** (*str*) – message to be sent on the control
        socket

      * **raw** (*bool*) – leaves the message formatting untouched,
        passing it to the socket as-is

   Raises:
      * "stem.SocketError" if a problem arises in using the socket

      * "stem.SocketClosed" if the socket is known to be shut down

stem.socket.recv_message(control_file, arrived_at=None)

   Pulls from a control socket until we either have a complete message
   or encounter a problem.

   Parameters:
      **control_file** (*file*) – file derived from the control socket
      (see the socket’s makefile() method for more information)

   Returns:
      "ControlMessage" read from the socket

   Raises:
      * "stem.ProtocolError" the content from the socket is
        malformed

      * "stem.SocketClosed" if the socket closes before we receive a
        complete message

stem.socket.send_formatting(message)

   Performs the formatting expected from sent control messages. For
   more information see the "send_message()" function.

   Parameters:
      **message** (*str*) – message to be formatted

   Returns:
      **str** of the message wrapped by the formatting expected from
      controllers
