
Controller Responses
********************

Parses replies from the control socket.

**Module Overview:**

   convert - translates a ControlMessage into a particular response subclass

   ControlMessage - Message that's read from the control socket.
     |- SingleLineResponse - Simple tor response only including a single line of information.
     |
     |- from_str - provides a ControlMessage for the given string
     |- is_ok - response had a 250 status
     |- content - provides the parsed message content
     |- raw_content - unparsed socket data
     |- __str__ - content stripped of protocol formatting
     +- __iter__ - ControlLine entries for the content of the message

   ControlLine - String subclass with methods for parsing controller responses.
     |- remainder - provides the unparsed content
     |- is_empty - checks if the remaining content is empty
     |- is_next_quoted - checks if the next entry is a quoted value
     |- is_next_mapping - checks if the next entry is a KEY=VALUE mapping
     |- peek_key - provides the key of the next entry
     |- pop - removes and returns the next entry
     +- pop_mapping - removes and returns the next entry as a KEY=VALUE mapping

stem.response.convert(response_type, message, **kwargs)

   Converts a "ControlMessage" into a particular kind of tor response.
   This does an in-place conversion of the message from being a
   "ControlMessage" to a subclass for its response type. Recognized
   types include...

   +---------------------+------------------------------------------------------------+
   | response_type       | Class                                                      |
   +=====================+============================================================+
   | **GETINFO**         | "stem.response.getinfo.GetInfoResponse"                    |
   +---------------------+------------------------------------------------------------+
   | **GETCONF**         | "stem.response.getconf.GetConfResponse"                    |
   +---------------------+------------------------------------------------------------+
   | **MAPADDRESS**      | "stem.response.mapaddress.MapAddressResponse"              |
   +---------------------+------------------------------------------------------------+
   | **EVENT**           | "stem.response.events.Event" subclass                      |
   +---------------------+------------------------------------------------------------+
   | **PROTOCOLINFO**    | "stem.response.protocolinfo.ProtocolInfoResponse"          |
   +---------------------+------------------------------------------------------------+
   | **AUTHCHALLENGE**   | "stem.response.authchallenge.AuthChallengeResponse"        |
   +---------------------+------------------------------------------------------------+
   | **SINGLELINE**      | "stem.response.SingleLineResponse"                         |
   +---------------------+------------------------------------------------------------+

   Parameters:
      * **response_type** (*str*) -- type of tor response to convert
        to

      * **message** (*stem.response.ControlMessage*) -- message to be
        converted

      * **kwargs** -- optional keyword arguments to be passed to the
        parser method

   Raises :
      * "stem.ProtocolError" the message isn't a proper response of
        that type

      * "stem.InvalidArguments" the arguments given as input are
        invalid, this is can only be raised if the response_type is:
        **GETINFO**, **GETCONF**

      * "stem.InvalidRequest" the arguments given as input are
        invalid, this is can only be raised if the response_type is:
        **MAPADDRESS**

      * "stem.OperationFailed" if the action the event represents
        failed, this is can only be raised if the response_type is:
        **MAPADDRESS**

      * **TypeError** if argument isn't a "ControlMessage" or
        response_type isn't supported

class class stem.response.ControlMessage(parsed_content, raw_content)

   Bases: "object"

   Message from the control socket. This is iterable and can be
   stringified for individual message components stripped of protocol
   formatting. Messages are never empty.

   static from_str(content, msg_type=None, **kwargs)

      Provides a ControlMessage for the given content.

      New in version 1.1.0.

      Parameters:
         * **content** (*str*) -- message to construct the message
           from

         * **msg_type** (*str*) -- type of tor reply to parse the
           content as

         * **kwargs** -- optional keyword arguments to be passed to
           the parser method

      Returns:
         stem.response.ControlMessage instance

   is_ok()

      Checks if any of our lines have a 250 response.

      Returns:
         **True** if any lines have a 250 response code, **False**
         otherwise

   content(get_bytes=False)

      Provides the parsed message content. These are entries of the
      form...

         (status_code, divider, content)

      **status_code**
         Three character code for the type of response (defined in
         section 4 of the control-spec).

      **divider**
         Single character to indicate if this is mid-reply, data, or
         an end to the message (defined in section 2.3 of the control-
         spec).

      **content**
         The following content is the actual payload of the line.

      For data entries the content is the full multi-line payload with
      newline linebreaks and leading periods unescaped.

      The **status_code** and **divider** are both strings (**bytes**
      in python 2.x and **unicode** in python 3.x). The **content**
      however is **bytes** if **get_bytes** is **True**.

      Changed in version 1.1.0: Added the get_bytes argument.

      Parameters:
         **get_bytes** (*bool*) -- provides **bytes** for the
         **content** rather than a **str**

      Returns:
         **list** of (str, str, str) tuples for the components of this
         message

   raw_content(get_bytes=False)

      Provides the unparsed content read from the control socket.

      Changed in version 1.1.0: Added the get_bytes argument.

      Parameters:
         **get_bytes** (*bool*) -- if **True** then this provides
         **bytes** rather than a **str**

      Returns:
         **str** of the socket data used to generate this message

class class stem.response.ControlLine(value)

   Bases: "str"

   String subclass that represents a line of controller output. This
   behaves as a normal string with additional methods for parsing and
   popping entries from a space delimited series of elements like a
   stack.

   None of these additional methods effect ourselves as a string
   (which is still immutable). All methods are thread safe.

   remainder()

      Provides our unparsed content. This is an empty string after
      we've popped all entries.

      Returns:
         **str** of the unparsed content

   is_empty()

      Checks if we have further content to pop or not.

      Returns:
         **True** if we have additional content, **False** otherwise

   is_next_quoted(escaped=False)

      Checks if our next entry is a quoted value or not.

      Parameters:
         **escaped** (*bool*) -- unescapes the CONTROL_ESCAPES escape
         sequences

      Returns:
         **True** if the next entry can be parsed as a quoted value,
         **False** otherwise

   is_next_mapping(key=None, quoted=False, escaped=False)

      Checks if our next entry is a KEY=VALUE mapping or not.

      Parameters:
         * **key** (*str*) -- checks that the key matches this value,
           skipping the check if **None**

         * **quoted** (*bool*) -- checks that the mapping is to a
           quoted value

         * **escaped** (*bool*) -- unescapes the CONTROL_ESCAPES
           escape sequences

      Returns:
         **True** if the next entry can be parsed as a key=value
         mapping, **False** otherwise

   peek_key()

      Provides the key of the next entry, providing **None** if it
      isn't a key/value mapping.

      Returns:
         **str** with the next entry's key

   pop(quoted=False, escaped=False)

      Parses the next space separated entry, removing it and the space
      from our remaining content. Examples...

         >>> line = ControlLine("\"We're all mad here.\" says the grinning cat.")
         >>> print line.pop(True)
           "We're all mad here."
         >>> print line.pop()
           "says"
         >>> print line.remainder()
           "the grinning cat."

         >>> line = ControlLine("\"this has a \\\" and \\\\ in it\" foo=bar more_data")
         >>> print line.pop(True, True)
           "this has a \" and \\ in it"

      Parameters:
         * **quoted** (*bool*) -- parses the next entry as a quoted
           value, removing the quotes

         * **escaped** (*bool*) -- unescapes the CONTROL_ESCAPES
           escape sequences

      Returns:
         **str** of the next space separated entry

      Raises :
         * **ValueError** if quoted is True without the value being
           quoted

         * **IndexError** if we don't have any remaining content left
           to parse

   pop_mapping(quoted=False, escaped=False)

      Parses the next space separated entry as a KEY=VALUE mapping,
      removing it and the space from our remaining content.

      Parameters:
         * **quoted** (*bool*) -- parses the value as being quoted,
           removing the quotes

         * **escaped** (*bool*) -- unescapes the CONTROL_ESCAPES
           escape sequences

      Returns:
         **tuple** of the form (key, value)

      Raises :
         **ValueError** if this isn't a KEY=VALUE mapping or if quoted
         is **True** without the value being quoted

      Raises :
         **IndexError** if there's nothing to parse from the line

class class stem.response.SingleLineResponse(parsed_content, raw_content)

   Bases: "stem.response.ControlMessage"

   Reply to a request that performs an action rather than querying
   data. These requests only contain a single line, which is 'OK' if
   successful, and a description of the problem if not.

   Variables:
      * **code** (*str*) -- status code for our line

      * **message** (*str*) -- content of the line

   is_ok(strict=False)

      Checks if the response code is "250". If strict is **True** then
      this checks if the response is "250 OK"

      Parameters:
         **strict** (*bool*) -- checks for a "250 OK" message if
         **True**

      Returns:
         * If strict is **False**: **True** if the response code is
           "250", **False** otherwise

         * If strict is **True**: **True** if the response is "250
           OK", **False** otherwise


Responses
=========

class class stem.response.add_onion.AddOnionResponse(parsed_content, raw_content)

   Bases: "stem.response.ControlMessage"

   ADD_ONION response.

   Variables:
      * **service_id** (*str*) -- hidden service address without the
        '.onion' suffix

      * **private_key** (*str*) -- base64 encoded hidden service
        private key

      * **private_key_type** (*str*) -- crypto used to generate the
        hidden service private key (such as RSA1024)

class class stem.response.authchallenge.AuthChallengeResponse(parsed_content, raw_content)

   Bases: "stem.response.ControlMessage"

   AUTHCHALLENGE query response.

   Variables:
      * **server_hash** (*str*) -- server hash provided by tor

      * **server_nonce** (*str*) -- server nonce provided by tor

class class stem.response.getconf.GetConfResponse(parsed_content, raw_content)

   Bases: "stem.response.ControlMessage"

   Reply for a GETCONF query.

   Note that configuration parameters won't match what we queried for
   if it's one of the special mapping options (ex.
   'HiddenServiceOptions').

   Variables:
      **entries** (*dict*) -- mapping between the config parameter
      (**str**) and their values (**list** of **str**)

class class stem.response.getinfo.GetInfoResponse(parsed_content, raw_content)

   Bases: "stem.response.ControlMessage"

   Reply for a GETINFO query.

   Variables:
      **entries** (*dict*) -- mapping between the queried options and
      their bytes values

class class stem.response.mapaddress.MapAddressResponse(parsed_content, raw_content)

   Bases: "stem.response.ControlMessage"

   Reply for a MAPADDRESS query. Doesn't raise an exception unless no
   addresses were mapped successfully.

   Variables:
      **entries** (*dict*) -- mapping between the original and
      replacement addresses

   Raises :
      * "stem.OperationFailed" if Tor was unable to satisfy the
        request

      * "stem.InvalidRequest" if the addresses provided were invalid

class class stem.response.protocolinfo.ProtocolInfoResponse(parsed_content, raw_content)

   Bases: "stem.response.ControlMessage"

   Version one PROTOCOLINFO query response.

   The protocol_version is the only mandatory data for a valid
   PROTOCOLINFO response, so all other values are None if undefined or
   empty if a collection.

   Variables:
      * **protocol_version** (*int*) -- protocol version of the
        response

      * **tor_version** (*stem.version.Version*) -- version of the tor
        process

      * **auth_methods** (*tuple*) -- "stem.connection.AuthMethod"
        types that tor will accept

      * **unknown_auth_methods** (*tuple*) -- strings of unrecognized
        auth methods

      * **cookie_path** (*str*) -- path of tor's authentication cookie


Events
======

class class stem.response.events.Event(parsed_content, raw_content)

   Bases: "stem.response.ControlMessage"

   Base for events we receive asynchronously, as described in section
   4.1 of the control-spec.

   Variables:
      * **type** (*str*) -- event type

      * **arrived_at** (*int*) -- unix timestamp for when the message
        arrived

      * **positional_args** (*list*) -- positional arguments of the
        event

      * **keyword_args** (*dict*) -- key/value arguments of the event

class class stem.response.events.AddrMapEvent(parsed_content, raw_content)

   Bases: "stem.response.events.Event"

   Event that indicates a new address mapping.

   The ADDRMAP event was one of the first Control Protocol V1 events
   and was introduced in tor version 0.1.1.1-alpha.

   Changed in version 1.1.0: Added the cached attribute.

   Variables:
      * **hostname** (*str*) -- address being resolved

      * **destination** (*str*) -- destionation of the resolution,
        this is usually an ip, but could be a hostname if
        TrackHostExits is enabled or **NONE** if the resolution failed

      * **expiry** (*datetime*) -- expiration time of the resolution
        in local time

      * **error** (*str*) -- error code if the resolution failed

      * **utc_expiry** (*datetime*) -- expiration time of the
        resolution in UTC

      * **cached** (*bool*) -- **True** if the resolution will be kept
        until it expires, **False** otherwise or **None** if undefined

class class stem.response.events.AuthDirNewDescEvent(parsed_content, raw_content)

   Bases: "stem.response.events.Event"

   Event specific to directory authorities, indicating that we just
   received new descriptors. The descriptor type contained within this
   event is unspecified so the descriptor contents are left unparsed.

   The AUTHDIR_NEWDESCS event was introduced in tor version
   0.1.1.10-alpha.

   Variables:
      * **action** (*stem.AuthDescriptorAction*) -- what is being done
        with the descriptor

      * **message** (*str*) -- explanation of why we chose this action

      * **descriptor** (*str*) -- content of the descriptor

class class stem.response.events.BandwidthEvent(parsed_content, raw_content)

   Bases: "stem.response.events.Event"

   Event emitted every second with the bytes sent and received by tor.

   The BW event was one of the first Control Protocol V1 events and
   was introduced in tor version 0.1.1.1-alpha.

   Variables:
      * **read** (*long*) -- bytes received by tor that second

      * **written** (*long*) -- bytes sent by tor that second

class class stem.response.events.BuildTimeoutSetEvent(parsed_content, raw_content)

   Bases: "stem.response.events.Event"

   Event indicating that the timeout value for a circuit has changed.
   This was first added in tor version 0.2.2.7.

   The BUILDTIMEOUT_SET event was introduced in tor version
   0.2.2.7-alpha.

   Variables:
      * **set_type** (*stem.TimeoutSetType*) -- way in which the
        timeout is changing

      * **total_times** (*int*) -- circuit build times tor used to
        determine the timeout

      * **timeout** (*int*) -- circuit timeout value in milliseconds

      * **xm** (*int*) -- Pareto parameter Xm in milliseconds

      * **alpha** (*float*) -- Pareto parameter alpha

      * **quantile** (*float*) -- CDF quantile cutoff point

      * **timeout_rate** (*float*) -- ratio of circuits that have time
        out

      * **close_timeout** (*int*) -- duration to keep measurement
        circuits in milliseconds

      * **close_rate** (*float*) -- ratio of measurement circuits that
        are closed

class class stem.response.events.CircuitEvent(parsed_content, raw_content)

   Bases: "stem.response.events.Event"

   Event that indicates that a circuit has changed.

   The fingerprint or nickname values in our 'path' may be **None** if
   the VERBOSE_NAMES feature isn't enabled. The option was first
   introduced in tor version 0.1.2.2, and on by default after 0.2.2.1.

   The CIRC event was one of the first Control Protocol V1 events and
   was introduced in tor version 0.1.1.1-alpha.

   Changed in version 1.4.0: Added the socks_username and
   socks_password attributes which is used for stream isolation.

   Variables:
      * **id** (*str*) -- circuit identifier

      * **status** (*stem.CircStatus*) -- reported status for the
        circuit

      * **path** (*tuple*) -- relays involved in the circuit, these
        are **(fingerprint, nickname)** tuples

      * **build_flags** (*tuple*) -- "CircBuildFlag" attributes
        governing how the circuit is built

      * **purpose** (*stem.CircPurpose*) -- purpose that the circuit
        is intended for

      * **hs_state** (*stem.HiddenServiceState*) -- status if this is
        a hidden service circuit

      * **rend_query** (*str*) -- circuit's rendezvous-point if this
        is hidden service related

      * **created** (*datetime*) -- time when the circuit was created
        or cannibalized

      * **reason** (*stem.CircClosureReason*) -- reason for the
        circuit to be closed

      * **remote_reason** (*stem.CircClosureReason*) -- remote side's
        reason for the circuit to be closed

      * **socks_username** (*str*) -- username for using this circuit

      * **socks_password** (*str*) -- password for using this circuit

class class stem.response.events.CircMinorEvent(parsed_content, raw_content)

   Bases: "stem.response.events.Event"

   Event providing information about minor changes in our circuits.
   This was first added in tor version 0.2.3.11.

   The CIRC_MINOR event was introduced in tor version 0.2.3.11-alpha.

   Variables:
      * **id** (*str*) -- circuit identifier

      * **event** (*stem.CircEvent*) -- type of change in the circuit

      * **path** (*tuple*) -- relays involved in the circuit, these
        are **(fingerprint, nickname)** tuples

      * **build_flags** (*tuple*) -- "CircBuildFlag" attributes
        governing how the circuit is built

      * **purpose** (*stem.CircPurpose*) -- purpose that the circuit
        is intended for

      * **hs_state** (*stem.HiddenServiceState*) -- status if this is
        a hidden service circuit

      * **rend_query** (*str*) -- circuit's rendezvous-point if this
        is hidden service related

      * **created** (*datetime*) -- time when the circuit was created
        or cannibalized

      * **old_purpose** (*stem.CircPurpose*) -- prior purpose for the
        circuit

      * **old_hs_state** (*stem.HiddenServiceState*) -- prior status
        as a hidden service circuit

class class stem.response.events.ClientsSeenEvent(parsed_content, raw_content)

   Bases: "stem.response.events.Event"

   Periodic event on bridge relays that provides a summary of our
   users.

   The CLIENTS_SEEN event was introduced in tor version
   0.2.1.10-alpha.

   Variables:
      * **start_time** (*datetime*) -- time in UTC that we started
        collecting these stats

      * **locales** (*dict*) -- mapping of country codes to a rounded
        count for the number of users

      * **ip_versions** (*dict*) -- mapping of ip protocols to a
        rounded count for the number of users

class class stem.response.events.ConfChangedEvent(parsed_content, raw_content)

   Bases: "stem.response.events.Event"

   Event that indicates that our configuration changed, either in
   response to a SETCONF or RELOAD signal.

   The CONF_CHANGED event was introduced in tor version 0.2.3.3-alpha.

   Variables:
      **config** (*dict*) -- mapping of configuration options to their
      new values (**None** if the option is being unset)

class class stem.response.events.DescChangedEvent(parsed_content, raw_content)

   Bases: "stem.response.events.Event"

   Event that indicates that our descriptor has changed.

   The DESCCHANGED event was introduced in tor version 0.1.2.2-alpha.

class class stem.response.events.GuardEvent(parsed_content, raw_content)

   Bases: "stem.response.events.Event"

   Event that indicates that our guard relays have changed. The
   'endpoint' could be either a...

   * fingerprint

   * 'fingerprint=nickname' pair

   The derived 'endpoint_*' attributes are generally more useful.

   The GUARD event was introduced in tor version 0.1.2.5-alpha.

   Variables:
      * **guard_type** (*stem.GuardType*) -- purpose the guard relay
        is for

      * **endpoint** (*str*) -- relay that the event concerns

      * **endpoint_fingerprint** (*str*) -- endpoint's finterprint

      * **endpoint_nickname** (*str*) -- endpoint's nickname if it was
        provided

      * **status** (*stem.GuardStatus*) -- status of the guard relay

class class stem.response.events.HSDescEvent(parsed_content, raw_content)

   Bases: "stem.response.events.Event"

   Event triggered when we fetch a hidden service descriptor that
   currently isn't in our cache.

   The HS_DESC event was introduced in tor version 0.2.5.2-alpha.

   New in version 1.2.0.

   Changed in version 1.3.0: Added the reason attribute.

   Variables:
      * **action** (*stem.HSDescAction*) -- what is happening with the
        descriptor

      * **address** (*str*) -- hidden service address

      * **authentication** (*stem.HSAuth*) -- service's authentication
        method

      * **directory** (*str*) -- hidden service directory servicing
        the request

      * **directory_fingerprint** (*str*) -- hidden service
        directory's finterprint

      * **directory_nickname** (*str*) -- hidden service directory's
        nickname if it was provided

      * **descriptor_id** (*str*) -- descriptor identifier

      * **reason** (*stem.HSDescReason*) -- reason the descriptor
        failed to be fetched

class class stem.response.events.HSDescContentEvent(parsed_content, raw_content)

   Bases: "stem.response.events.Event"

   Provides the content of hidden service descriptors we fetch.

   The HS_DESC_CONTENT event was introduced in tor version
   0.2.7.1-alpha.

   New in version 1.4.0.

   Variables:
      * **address** (*str*) -- hidden service address

      * **descriptor_id** (*str*) -- descriptor identifier

      * **directory** (*str*) -- hidden service directory servicing
        the request

      * **directory_fingerprint** (*str*) -- hidden service
        directory's finterprint

      * **directory_nickname** (*str*) -- hidden service directory's
        nickname if it was provided

      * **descriptor** (*stem.descriptor.hidden_service_descriptor.Hid
        denServiceDescriptor*) -- descriptor that was retrieved

class class stem.response.events.LogEvent(parsed_content, raw_content)

   Bases: "stem.response.events.Event"

   Tor logging event. These are the most visible kind of event since,
   by default, tor logs at the NOTICE "Runlevel" to stdout.

   The logging events were some of the first Control Protocol V1
   events and were introduced in tor version 0.1.1.1-alpha.

   Variables:
      * **runlevel** (*stem.Runlevel*) -- runlevel of the logged
        message

      * **message** (*str*) -- logged message

class class stem.response.events.NetworkStatusEvent(parsed_content, raw_content)

   Bases: "stem.response.events.Event"

   Event for when our copy of the consensus has changed. This was
   introduced in tor version 0.1.2.3.

   The NS event was introduced in tor version 0.1.2.3-alpha.

   Variables:
      **desc** (*list*) -- "RouterStatusEntryV3" for the changed
      descriptors

class class stem.response.events.NewConsensusEvent(parsed_content, raw_content)

   Bases: "stem.response.events.Event"

   Event for when we have a new consensus. This is similar to
   "NetworkStatusEvent", except that it contains the whole consensus
   so anything not listed is implicitly no longer recommended.

   The NEWCONSENSUS event was introduced in tor version
   0.2.1.13-alpha.

   Variables:
      **desc** (*list*) -- "RouterStatusEntryV3" for the changed
      descriptors

class class stem.response.events.NewDescEvent(parsed_content, raw_content)

   Bases: "stem.response.events.Event"

   Event that indicates that a new descriptor is available.

   The fingerprint or nickname values in our 'relays' may be **None**
   if the VERBOSE_NAMES feature isn't enabled. The option was first
   introduced in tor version 0.1.2.2, and on by default after 0.2.2.1.

   The NEWDESC event was one of the first Control Protocol V1 events
   and was introduced in tor version 0.1.1.1-alpha.

   Variables:
      **relays** (*tuple*) -- **(fingerprint, nickname)** tuples for
      the relays with new descriptors

class class stem.response.events.ORConnEvent(parsed_content, raw_content)

   Bases: "stem.response.events.Event"

   Event that indicates a change in a relay connection. The 'endpoint'
   could be any of several things including a...

   * fingerprint

   * nickname

   * 'fingerprint=nickname' pair

   * address:port

   The derived 'endpoint_*' attributes are generally more useful.

   The ORCONN event was one of the first Control Protocol V1 events
   and was introduced in tor version 0.1.1.1-alpha. Its id attribute
   was added in version 0.2.5.2-alpha.

   Changed in version 1.2.0: Added the id attribute.

   Variables:
      * **id** (*str*) -- connection identifier

      * **endpoint** (*str*) -- relay that the event concerns

      * **endpoint_fingerprint** (*str*) -- endpoint's finterprint if
        it was provided

      * **endpoint_nickname** (*str*) -- endpoint's nickname if it was
        provided

      * **endpoint_address** (*str*) -- endpoint's address if it was
        provided

      * **endpoint_port** (*int*) -- endpoint's port if it was
        provided

      * **status** (*stem.ORStatus*) -- state of the connection

      * **reason** (*stem.ORClosureReason*) -- reason for the
        connection to be closed

      * **circ_count** (*int*) -- number of established and pending
        circuits

class class stem.response.events.SignalEvent(parsed_content, raw_content)

   Bases: "stem.response.events.Event"

   Event that indicates that tor has received and acted upon a signal
   being sent to the process. As of tor version 0.2.4.6 the only
   signals conveyed by this event are...

   * RELOAD

   * DUMP

   * DEBUG

   * NEWNYM

   * CLEARDNSCACHE

   The SIGNAL event was introduced in tor version 0.2.3.1-alpha.

   Variables:
      **signal** (*stem.Signal*) -- signal that tor received

class class stem.response.events.StatusEvent(parsed_content, raw_content)

   Bases: "stem.response.events.Event"

   Notification of a change in tor's state. These are generally
   triggered for the same sort of things as log messages of the NOTICE
   level or higher. However, unlike "LogEvent" these contain well
   formed data.

   The STATUS_GENERAL, STATUS_CLIENT, STATUS_SERVER events were
   introduced in tor version 0.1.2.3-alpha.

   Variables:
      * **status_type** (*stem.StatusType*) -- category of the status
        event

      * **runlevel** (*stem.Runlevel*) -- runlevel of the logged
        message

      * **action** (*str*) -- activity that caused this message

      * **arguments** (*dict*) -- attributes about the event

class class stem.response.events.StreamEvent(parsed_content, raw_content)

   Bases: "stem.response.events.Event"

   Event that indicates that a stream has changed.

   The STREAM event was one of the first Control Protocol V1 events
   and was introduced in tor version 0.1.1.1-alpha.

   Variables:
      * **id** (*str*) -- stream identifier

      * **status** (*stem.StreamStatus*) -- reported status for the
        stream

      * **circ_id** (*str*) -- circuit that the stream is attached to,
        this is **None** of the stream is unattached

      * **target** (*str*) -- destination of the stream

      * **target_address** (*str*) -- destination address (ip,
        hostname, or '(Tor_internal)')

      * **target_port** (*int*) -- destination port

      * **reason** (*stem.StreamClosureReason*) -- reason for the
        stream to be closed

      * **remote_reason** (*stem.StreamClosureReason*) -- remote
        side's reason for the stream to be closed

      * **source** (*stem.StreamSource*) -- origin of the REMAP
        request

      * **source_addr** (*str*) -- requester of the connection

      * **source_address** (*str*) -- requester address (ip or
        hostname)

      * **source_port** (*int*) -- requester port

      * **purpose** (*stem.StreamPurpose*) -- purpose for the stream

class class stem.response.events.StreamBwEvent(parsed_content, raw_content)

   Bases: "stem.response.events.Event"

   Event (emitted approximately every second) with the bytes sent and
   received by the application since the last such event on this
   stream.

   The STREAM_BW event was introduced in tor version 0.1.2.8-beta.

   Variables:
      * **id** (*str*) -- stream identifier

      * **written** (*long*) -- bytes sent by the application

      * **read** (*long*) -- bytes received by the application

class class stem.response.events.TransportLaunchedEvent(parsed_content, raw_content)

   Bases: "stem.response.events.Event"

   Event triggered when a pluggable transport is launched.

   The TRANSPORT_LAUNCHED event was introduced in tor version
   0.2.5.0-alpha.

   New in version 1.1.0.

   Variables:
      * **type** (*str*) -- 'server' or 'client'

      * **name** (*str*) -- name of the pluggable transport

      * **address** (*str*) -- IPv4 or IPv6 address where the
        transport is listening for connections

      * **port** (*int*) -- port where the transport is listening for
        connections

class class stem.response.events.ConnectionBandwidthEvent(parsed_content, raw_content)

   Bases: "stem.response.events.Event"

   Event emitted every second with the bytes sent and received by tor
   on a per-connection basis.

   The CONN_BW event was introduced in tor version 0.2.5.2-alpha.

   New in version 1.2.0.

   Variables:
      * **id** (*str*) -- connection identifier

      * **type** (*stem.ConnectionType*) -- connection type

      * **read** (*long*) -- bytes received by tor that second

      * **written** (*long*) -- bytes sent by tor that second

class class stem.response.events.CircuitBandwidthEvent(parsed_content, raw_content)

   Bases: "stem.response.events.Event"

   Event emitted every second with the bytes sent and received by tor
   on a per-circuit basis.

   The CIRC_BW event was introduced in tor version 0.2.5.2-alpha.

   New in version 1.2.0.

   Variables:
      * **id** (*str*) -- circuit identifier

      * **read** (*long*) -- bytes received by tor that second

      * **written** (*long*) -- bytes sent by tor that second

class class stem.response.events.CellStatsEvent(parsed_content, raw_content)

   Bases: "stem.response.events.Event"

   Event emitted every second with a count of the number of cells
   types broken down by the circuit. **These events are only emitted
   if TestingTorNetwork is set.**

   The CELL_STATS event was introduced in tor version 0.2.5.2-alpha.

   New in version 1.2.0.

   Variables:
      * **id** (*str*) -- circuit identifier

      * **inbound_queue** (*str*) -- inbound queue identifier

      * **inbound_connection** (*str*) -- inbound connection
        identifier

      * **inbound_added** (*dict*) -- mapping of added inbound cell
        types to their count

      * **inbound_removed** (*dict*) -- mapping of removed inbound
        cell types to their count

      * **inbound_time** (*dict*) -- mapping of inbound cell types to
        the time they took to write in milliseconds

      * **outbound_queue** (*str*) -- outbound queue identifier

      * **outbound_connection** (*str*) -- outbound connection
        identifier

      * **outbound_added** (*dict*) -- mapping of added outbound cell
        types to their count

      * **outbound_removed** (*dict*) -- mapping of removed outbound
        cell types to their count

      * **outbound_time** (*dict*) -- mapping of outbound cell types
        to the time they took to write in milliseconds

class class stem.response.events.TokenBucketEmptyEvent(parsed_content, raw_content)

   Bases: "stem.response.events.Event"

   Event emitted when refilling an empty token bucket. **These events
   are only emitted if TestingTorNetwork is set.**

   The TB_EMPTY event was introduced in tor version 0.2.5.2-alpha.

   New in version 1.2.0.

   Variables:
      * **bucket** (*stem.TokenBucket*) -- bucket being refilled

      * **id** (*str*) -- connection identifier

      * **read** (*int*) -- time in milliseconds since the read bucket
        was last refilled

      * **written** (*int*) -- time in milliseconds since the write
        bucket was last refilled

      * **last_refill** (*int*) -- time in milliseconds the bucket has
        been empty since last refilled
