Stem Docs

Controller Responses

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)[source]

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)[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.

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
raw_content(get_bytes=False)[source]

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)[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)[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)[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)[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)[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)[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)[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 :
class stem.response.protocolinfo.ProtocolInfoResponse(parsed_content, raw_content)[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 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)[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
  • 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 stem.response.events.AddrMapEvent(parsed_content, raw_content)[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)[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.

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)[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 (long) -- bytes received by tor that second
  • written (long) -- bytes sent by tor that second
class stem.response.events.BuildTimeoutSetEvent(parsed_content, raw_content)[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)[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 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)[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 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)[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)[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.

Variables:config (dict) -- mapping of configuration options to their new values (None if the option is being unset)
class stem.response.events.DescChangedEvent(parsed_content, raw_content)[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)[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)[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.

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
class stem.response.events.HSDescContentEvent(parsed_content, raw_content)[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_descriptor.HiddenServiceDescriptor) -- descriptor that was retrieved
class stem.response.events.LogEvent(parsed_content, raw_content)[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)[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)[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)[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.

Variables:desc (list) -- RouterStatusEntryV3 for the changed descriptors
class stem.response.events.NewDescEvent(parsed_content, raw_content)[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)[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)[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)[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)[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)[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 (long) -- bytes sent by the application
  • read (long) -- bytes received by the application
  • time (datetime) -- time when the measurement was recorded
class stem.response.events.TransportLaunchedEvent(parsed_content, raw_content)[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)[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 (long) -- bytes received by tor that second
  • written (long) -- bytes sent by tor that second
class stem.response.events.CircuitBandwidthEvent(parsed_content, raw_content)[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.

Variables:
  • id (str) -- circuit identifier
  • read (long) -- bytes received by tor that second
  • written (long) -- bytes sent by tor that second
  • time (datetime) -- time when the measurement was recorded
class stem.response.events.CellStatsEvent(parsed_content, raw_content)[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)[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