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

   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                                                      |
   +=====================+============================================================+
   | **ADD_ONION**       | "stem.response.add_onion.AddOnionResponse"                 |
   +---------------------+------------------------------------------------------------+
   | **AUTHCHALLENGE**   | "stem.response.authchallenge.AuthChallengeResponse"        |
   +---------------------+------------------------------------------------------------+
   | **EVENT**           | "stem.response.events.Event" subclass                      |
   +---------------------+------------------------------------------------------------+
   | **GETCONF**         | "stem.response.getconf.GetConfResponse"                    |
   +---------------------+------------------------------------------------------------+
   | **GETINFO**         | "stem.response.getinfo.GetInfoResponse"                    |
   +---------------------+------------------------------------------------------------+
   | **MAPADDRESS**      | "stem.response.mapaddress.MapAddressResponse"              |
   +---------------------+------------------------------------------------------------+
   | **PROTOCOLINFO**    | "stem.response.protocolinfo.ProtocolInfoResponse"          |
   +---------------------+------------------------------------------------------------+
   | **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 stem.response.ControlMessage(parsed_content, raw_content, arrived_at=None)

   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.

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

   Changed in version 1.7.0: Implemented equality and hashing.

   Changed in version 1.8.0: Moved **arrived_at** from the Event class
   up to this base ControlMessage.

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

      Provides a ControlMessage for the given content.

      New in version 1.1.0.

      Changed in version 1.6.0: Added the normalize argument.

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

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

         * **normalize** (*bool*) -- ensures expected carriage
           return and ending newline are present

         * **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 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 string

      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 string

      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 string

      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, get_bytes=False)

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

      Changed in version 1.6.0: Added the get_bytes argument.

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

         * **escaped** (*bool*) -- unescapes the string

         * **get_bytes** (*bool*) -- provides **bytes** for the
           **value** rather than a **str**

      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 stem.response.SingleLineResponse(parsed_content, raw_content, arrived_at=None)

   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 stem.response.add_onion.AddOnionResponse(parsed_content, raw_content, arrived_at=None)

   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)

      * **client_auth** (*dict*) -- newly generated client
        credentials the service accepts

class stem.response.authchallenge.AuthChallengeResponse(parsed_content, raw_content, arrived_at=None)

   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 stem.response.getconf.GetConfResponse(parsed_content, raw_content, arrived_at=None)

   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 stem.response.getinfo.GetInfoResponse(parsed_content, raw_content, arrived_at=None)

   Bases: "stem.response.ControlMessage"

   Reply for a GETINFO query.

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

class stem.response.mapaddress.MapAddressResponse(parsed_content, raw_content, arrived_at=None)

   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 stem.response.protocolinfo.ProtocolInfoResponse(parsed_content, raw_content, arrived_at=None)

   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 stem.response.events.Event(parsed_content, raw_content, arrived_at=None)

   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

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

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

class stem.response.events.AddrMapEvent(parsed_content, raw_content, arrived_at=None)

   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*) -- destination 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 stem.response.events.AuthDirNewDescEvent(parsed_content, raw_content, arrived_at=None)

   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 and removed in 0.3.2.1-alpha. (spec)

   Deprecated since version 1.6.0: Tor dropped this event as of
   version 0.3.2.1. (spec)

   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 stem.response.events.BandwidthEvent(parsed_content, raw_content, arrived_at=None)

   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** (*int*) -- bytes received by tor that second

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

class stem.response.events.BuildTimeoutSetEvent(parsed_content, raw_content, arrived_at=None)

   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 stem.response.events.CircuitEvent(parsed_content, raw_content, arrived_at=None)

   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 stem.response.events.CircMinorEvent(parsed_content, raw_content, arrived_at=None)

   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 stem.response.events.ClientsSeenEvent(parsed_content, raw_content, arrived_at=None)

   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 stem.response.events.ConfChangedEvent(parsed_content, raw_content, arrived_at=None)

   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.

   Deprecated since version 1.7.0: Deprecated the *config* attribute.
   Some tor configuration options (like ExitPolicy) can have multiple
   values, so a simple 'str => str' mapping meant that we only
   provided the last.

   Changed in version 1.7.0: Added the changed and unset attributes.

   Variables:
      * **changed** (*dict*) -- mapping of configuration options to
        a list of their new values

      * **unset** (*list*) -- configuration options that have been
        unset

class stem.response.events.DescChangedEvent(parsed_content, raw_content, arrived_at=None)

   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 stem.response.events.GuardEvent(parsed_content, raw_content, arrived_at=None)

   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 stem.response.events.HSDescEvent(parsed_content, raw_content, arrived_at=None)

   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.

   Changed in version 1.5.0: Added the replica attribute.

   Changed in version 1.7.0: Added the index 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

      * **replica** (*int*) -- replica number the descriptor
        involves

      * **index** (*str*) -- computed index of the HSDir the
        descriptor was uploaded to or fetched from

class stem.response.events.HSDescContentEvent(parsed_content, raw_content, arrived_at=None)

   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.HiddenServiceDescriptorV2*)
        -- descriptor that was retrieved

class stem.response.events.LogEvent(parsed_content, raw_content, arrived_at=None)

   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 stem.response.events.NetworkStatusEvent(parsed_content, raw_content, arrived_at=None)

   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 stem.response.events.NetworkLivenessEvent(parsed_content, raw_content, arrived_at=None)

   Bases: "stem.response.events.Event"

   Event for when the network becomes reachable or unreachable.

   The NETWORK_LIVENESS event was introduced in tor version
   0.2.7.2-alpha.

   New in version 1.5.0.

   Variables:
      **status** (*str*) -- status of the network ('UP', 'DOWN', or
      possibly other statuses in the future)

class stem.response.events.NewConsensusEvent(parsed_content, raw_content, arrived_at=None)

   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.

   Changed in version 1.6.0: Added the consensus_content attribute.

   Deprecated since version 1.6.0: In Stem 2.0 we'll remove the desc
   attribute, so this event only provides the unparsed consensus.
   Callers can then parse it if they'd like. To drop parsing before
   then you can set...

      stem.response.events.PARSE_NEWCONSENSUS_EVENTS = False

   Variables:
      * **consensus_content** (*str*) -- consensus content

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

class stem.response.events.NewDescEvent(parsed_content, raw_content, arrived_at=None)

   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 stem.response.events.ORConnEvent(parsed_content, raw_content, arrived_at=None)

   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 stem.response.events.SignalEvent(parsed_content, raw_content, arrived_at=None)

   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 stem.response.events.StatusEvent(parsed_content, raw_content, arrived_at=None)

   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 stem.response.events.StreamEvent(parsed_content, raw_content, arrived_at=None)

   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 stem.response.events.StreamBwEvent(parsed_content, raw_content, arrived_at=None)

   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.

   Changed in version 1.6.0: Added the time attribute.

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

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

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

      * **time** (*datetime*) -- time when the measurement was
        recorded

class stem.response.events.TransportLaunchedEvent(parsed_content, raw_content, arrived_at=None)

   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 stem.response.events.ConnectionBandwidthEvent(parsed_content, raw_content, arrived_at=None)

   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.

   Changed in version 1.6.0: Renamed 'type' attribute to 'conn_type'
   so it wouldn't be override parent class attribute with the same
   name.

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

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

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

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

class stem.response.events.CircuitBandwidthEvent(parsed_content, raw_content, arrived_at=None)

   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.

   Changed in version 1.6.0: Added the time attribute.

   Changed in version 1.7.0: Added the delivered_read,
   delivered_written, overhead_read, and overhead_written attributes.

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

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

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

      * **delivered_read** (*int*) -- user payload received by tor
        that second

      * **delivered_written** (*int*) -- user payload sent by tor
        that second

      * **overhead_read** (*int*) -- padding so read cells will have
        a fixed length

      * **overhead_written** (*int*) -- padding so written cells
        will have a fixed length

      * **time** (*datetime*) -- time when the measurement was
        recorded

class stem.response.events.CellStatsEvent(parsed_content, raw_content, arrived_at=None)

   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 stem.response.events.TokenBucketEmptyEvent(parsed_content, raw_content, arrived_at=None)

   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
