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)[source]¶ Converts a
ControlMessage
into a particular kind of tor response. This does an in-place conversion of the message from being aControlMessage
to a subclass for its response type. Recognized types include…response_type
Class
ADD_ONION
AUTHCHALLENGE
EVENT
stem.response.events.Event
subclassGETCONF
GETINFO
MAPADDRESS
PROTOCOLINFO
SINGLELINE
- 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 typestem.InvalidArguments
the arguments given as input are invalid, this is can only be raised if the response_type is: GETINFO, GETCONFstem.InvalidRequest
the arguments given as input are invalid, this is can only be raised if the response_type is: MAPADDRESSstem.OperationFailed
if the action the event represents failed, this is can only be raised if the response_type is: MAPADDRESSTypeError if argument isn’t a
ControlMessage
or response_type isn’t supported
-
class
stem.response.
ControlMessage
(parsed_content, raw_content, arrived_at=None)[source]¶ 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)[source]¶ 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
()[source]¶ 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)[source]¶ 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
-
class
stem.response.
ControlLine
(value)[source]¶ 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
()[source]¶ Provides our unparsed content. This is an empty string after we’ve popped all entries.
- Returns
str of the unparsed content
-
is_empty
()[source]¶ Checks if we have further content to pop or not.
- Returns
True if we have additional content, False otherwise
-
is_next_quoted
(escaped=False)[source]¶ 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)[source]¶ 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
()[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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 requeststem.InvalidRequest
if the addresses provided were invalid
-
class
stem.response.protocolinfo.
ProtocolInfoResponse
(parsed_content, raw_content, arrived_at=None)[source]¶ 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 acceptunknown_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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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 builtpurpose (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)[source]¶ 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 builtpurpose (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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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