Exceptions and Attribute Enums¶

Library for working with the tor process.

Module Overview:

Endpoint - Networking endpoint.
  |- ORPort - Tor relay endpoint.
  +- DirPort - Descriptor mirror.

ControllerError - Base exception raised when using the controller.
  |- ProtocolError - Malformed socket data.
  |
  |- OperationFailed - Tor was unable to successfully complete the operation.
  |  |- UnsatisfiableRequest - Tor was unable to satisfy a valid request.
  |  |  |- CircuitExtensionFailed - Attempt to make or extend a circuit failed.
  |  |  |- DescriptorUnavailable - The given relay descriptor is unavailable.
  |  |  +- Timeout - Caller requested timeout was reached.
  |  |
  |  |
  |  +- InvalidRequest - Invalid request.
  |     +- InvalidArguments - Invalid request parameters.
  |
  +- SocketError - Communication with the socket failed.
     +- SocketClosed - Socket has been shut down.

DownloadFailed - Inability to download a resource.
  +- DownloadTimeout - Download timeout reached.

stem.Runlevel(enum)¶

Rating of importance used for event logging.

Runlevel	Description
ERR	critical issues that impair tor's ability to function
WARN	non-critical issues the user should be aware of
NOTICE	information that may be helpful to the user
INFO	high level runtime information
DEBUG	low level runtime information

stem.Signal(enum)¶

Signals that the tor process will accept.

Changed in version 1.3.0: Added the HEARTBEAT signal.

Changed in version 1.8.0: Added the ACTIVE and DORMANT signals. You can check for Tor support for these signals with the DORMANT_MODE Requirement

Signal	Description
RELOAD or HUP	reloads our torrc
SHUTDOWN or INT	shut down, waiting ShutdownWaitLength first if we're a relay
DUMP or USR1	dumps information about open connections and circuits to our log
DEBUG or USR2	switch our logging to the DEBUG runlevel
HALT or TERM	exit tor immediately
NEWNYM	switch to new circuits, so new application requests don't share any circuits with old ones (this also clears our DNS cache)
CLEARDNSCACHE	clears cached DNS results
HEARTBEAT	trigger a heartbeat log message
DORMANT	enables dormant mode, during which tor will avoid cpu and network usage
ACTIVE	disables dormant mode

stem.Flag(enum)¶

Flag assigned to tor relays by the authorities to indicate various characteristics.

Note: The BADDIRECTORY flag was removed from tor.

Changed in version 1.5.0: Added the NO_ED_CONSENSUS flag.

Changed in version 1.8.0: Added the STALE_DESC flag.

Flag	Description
AUTHORITY	relay is a directory authority
BADEXIT	relay shouldn't be used as an exit due to being either problematic or malicious
BADDIRECTORY	relay shouldn't be used for directory information
EXIT	relay's exit policy makes it more useful as an exit rather than middle hop
FAST	relay's suitable for high-bandwidth circuits
GUARD	relay's suitable for being an entry guard (first hop)
HSDIR	relay is being used as a v2 hidden service directory
NAMED	relay can be referred to by its nickname
NO_ED_CONSENSUS	relay's Ed25519 doesn't reflrect the consensus
RUNNING	relay is currently usable
STABLE	relay's suitable for long-lived circuits
STALE_DESC	relay descriptor is outdated and should be re-uploaded
UNNAMED	relay isn't currently bound to a nickname
V2DIR	relay supports the v2 directory protocol
VALID	relay has been validated

stem.CircStatus(enum)¶

Statuses that a circuit can be in. Tor may provide statuses not in this enum.

Changed in version 1.6.0: Added the GUARD_WAIT signal.

CircStatus	Description
LAUNCHED	new circuit was created
BUILT	circuit finished being created and can accept traffic
GUARD_WAIT	waiting to see if there's a circuit with a better guard before using
EXTENDED	circuit has been extended by a hop
FAILED	circuit construction failed
CLOSED	circuit has been closed

stem.CircBuildFlag(enum)¶

Attributes about how a circuit is built. These were introduced in tor version 0.2.3.11. Tor may provide flags not in this enum.

CircBuildFlag	Description
ONEHOP_TUNNEL	single hop circuit to fetch directory information
IS_INTERNAL	circuit that won't be used for client traffic
NEED_CAPACITY	circuit only includes high capacity relays
NEED_UPTIME	circuit only includes relays with a high uptime

stem.CircPurpose(enum)¶

Description of what a circuit is intended for. These were introduced in tor version 0.2.1.6. Tor may provide purposes not in this enum.

CircPurpose	Description
GENERAL	client traffic or fetching directory information
HS_CLIENT_INTRO	client side introduction point for a hidden service circuit
HS_CLIENT_REND	client side hidden service rendezvous circuit
HS_SERVICE_INTRO	server side introduction point for a hidden service circuit
HS_SERVICE_REND	server side hidden service rendezvous circuit
TESTING	testing to see if we're reachable, so we can be used as a relay
CONTROLLER	circuit that was built by a controller
MEASURE_TIMEOUT	circuit being kept around to see how long it takes

stem.CircClosureReason(enum)¶

Reason that a circuit is being closed or failed to be established. Tor may provide reasons not in this enum.

CircClosureReason	Description
NONE	no reason given
TORPROTOCOL	violation in the tor protocol
INTERNAL	internal error
REQUESTED	requested by the client via a TRUNCATE command
HIBERNATING	relay is currently hibernating
RESOURCELIMIT	relay is out of memory, sockets, or circuit IDs
CONNECTFAILED	unable to contact the relay
OR_IDENTITY	relay had the wrong OR identification
OR_CONN_CLOSED	connection failed after being established
FINISHED	circuit has expired (see tor's MaxCircuitDirtiness config option)
TIMEOUT	circuit construction timed out
DESTROYED	circuit unexpectedly closed
NOPATH	not enough relays to make a circuit
NOSUCHSERVICE	requested hidden service does not exist
MEASUREMENT_EXPIRED	same as TIMEOUT except that it was left open for measurement purposes

stem.CircEvent(enum)¶

Type of change reflected in a circuit by a CIRC_MINOR event. Tor may provide event types not in this enum.

CircEvent	Description
PURPOSE_CHANGED	circuit purpose or hidden service state has changed
CANNIBALIZED	circuit connections are being reused for a different circuit

stem.HiddenServiceState(enum)¶

State that a hidden service circuit can have. These were introduced in tor version 0.2.3.11. Tor may provide states not in this enum.

Enumerations fall into four groups based on their prefix...

Prefix	Description
HSCI_*	client-side introduction-point
HSCR_*	client-side rendezvous-point
HSSI_*	service-side introduction-point
HSSR_*	service-side rendezvous-point

HiddenServiceState	Description
HSCI_CONNECTING	connecting to the introductory point
HSCI_INTRO_SENT	sent INTRODUCE1 and awaiting a reply
HSCI_DONE	received a reply, circuit is closing
HSCR_CONNECTING	connecting to the introductory point
HSCR_ESTABLISHED_IDLE	rendezvous-point established, awaiting an introduction
HSCR_ESTABLISHED_WAITING	introduction received, awaiting a rend
HSCR_JOINED	connected to the hidden service
HSSI_CONNECTING	connecting to the introductory point
HSSI_ESTABLISHED	established introductory point
HSSR_CONNECTING	connecting to the introductory point
HSSR_JOINED	connected to the rendezvous-point

stem.RelayEndReason(enum)¶

Reasons why the stream is to be closed.

RelayEndReason	Description
MISC	none of the following reasons
RESOLVEFAILED	unable to resolve the hostname
CONNECTREFUSED	remote host refused the connection
EXITPOLICY	OR refuses to connect to the destination
DESTROY	circuit is being shut down
DONE	connection has been closed
TIMEOUT	connection timed out
NOROUTE	routing error while contacting the destination
HIBERNATING	relay is temporarily hibernating
INTERNAL	internal error at the relay
RESOURCELIMIT	relay has insufficient resources to service the request
CONNRESET	connection was unexpectedly reset
TORPROTOCOL	violation in the tor protocol
NOTDIRECTORY	directory information requested from a relay that isn't mirroring it

stem.StreamStatus(enum)¶

State that a stream going through tor can have. Tor may provide states not in this enum.

StreamStatus	Description
NEW	request for a new connection
NEWRESOLVE	request to resolve an address
REMAP	address is being re-mapped to another
SENTCONNECT	sent a connect cell along a circuit
SENTRESOLVE	sent a resolve cell along a circuit
SUCCEEDED	stream has been established
FAILED	stream is detached, and won't be re-established
DETACHED	stream is detached, but might be re-established
CLOSED	stream has closed

stem.StreamClosureReason(enum)¶

Reason that a stream is being closed or failed to be established. This includes all values in the RelayEndReason enumeration as well as the following. Tor may provide reasons not in this enum.

StreamClosureReason	Description
END	endpoint has sent a RELAY_END cell
PRIVATE_ADDR	endpoint was a private address (127.0.0.1, 10.0.0.1, etc)

stem.StreamSource(enum)¶

Cause of a stream being remapped to another address. Tor may provide sources not in this enum.

StreamSource	Description
CACHE	tor is remapping because of a cached answer
EXIT	exit relay requested the remap

stem.StreamPurpose(enum)¶

Purpsoe of the stream. This is only provided with new streams and tor may provide purposes not in this enum.

StreamPurpose	Description
DIR_FETCH	fetching directory information (descriptors, consensus, etc)
DIR_UPLOAD	uploading our descriptor to an authority
DNS_REQUEST	user initiated DNS request
DIRPORT_TEST	checking that our directory port is reachable externally
USER	either relaying user traffic or not one of the above categories

stem.ORStatus(enum)¶

State that an OR connection can have. Tor may provide states not in this enum.

ORStatus	Description
NEW	received OR connection, starting server-side handshake
LAUNCHED	launched outbound OR connection, starting client-side handshake
CONNECTED	OR connection has been established
FAILED	attempt to establish OR connection failed
CLOSED	OR connection has been closed

stem.ORClosureReason(enum)¶

Reason that an OR connection is being closed or failed to be established. Tor may provide reasons not in this enum.

ORClosureReason	Description
DONE	OR connection shut down cleanly
CONNECTREFUSED	got a ECONNREFUSED when connecting to the relay
IDENTITY	identity of the relay wasn't what we expected
CONNECTRESET	got a ECONNRESET or similar error from relay
TIMEOUT	got a ETIMEOUT or similar error from relay
NOROUTE	got a ENOTCONN, ENETUNREACH, ENETDOWN, EHOSTUNREACH, or similar error from relay
IOERROR	got a different kind of error from relay
RESOURCELIMIT	relay has insufficient resources to service the request
MISC	connection refused for another reason
PT_MISSING	no pluggable transport was available

stem.AuthDescriptorAction(enum)¶

Actions that directory authorities might take with relay descriptors. Tor may provide reasons not in this enum.

AuthDescriptorAction	Description
ACCEPTED	accepting the descriptor as the newest version
DROPPED	descriptor rejected without notifying the relay
REJECTED	relay notified that its descriptor has been rejected

stem.StatusType(enum)¶

Sources for tor status events. Tor may provide types not in this enum.

StatusType	Description
GENERAL	general tor activity, not specifically as a client or relay
CLIENT	related to our activity as a tor client
SERVER	related to our activity as a tor relay

stem.GuardType(enum)¶

Use a guard relay can be for. Tor may provide types not in this enum.

GuardType	Description
ENTRY	used to connect to the tor network

stem.GuardStatus(enum)¶

Status a guard relay can have. Tor may provide types not in this enum.

GuardStatus	Description
NEW	new guard that we weren't previously using
DROPPED	removed from use as one of our guards
UP	guard is now reachable
DOWN	guard is now unreachable
BAD	consensus or relay considers this relay to be unusable as a guard
GOOD	consensus or relay considers this relay to be usable as a guard

stem.TimeoutSetType(enum)¶

Way in which the timeout value of a circuit is changing. Tor may provide types not in this enum.

TimeoutSetType	Description
COMPUTED	tor has computed a new timeout based on prior circuits
RESET	timeout reverted to its default
SUSPENDED	timeout reverted to its default until network connectivity has recovered
DISCARD	throwing out timeout value from when the network was down
RESUME	resumed calculations to determine the proper timeout

stem.ConnectionType(enum)¶

Purpose for a tor connection. Tor may provide types not in this enum.

The meaning behind these values is a bit unclear, pending ticket 10086.

New in version 1.2.0.

ConnectionType	Description
OR	carrying traffic within the tor network
DIR	fetching or sending tor descriptor data
EXIT	carrying traffic between the tor network and an external destination

stem.TokenBucket(enum)¶

Bucket categories of TB_EMPTY events.

New in version 1.2.0.

TokenBucket	Description
GLOBAL	global token bucket
RELAY	relay token bucket
ORCONN	bucket used for OR connections

stem.HSDescAction(enum)¶

Action beeing taken in a HS_DESC event.

New in version 1.2.0.

Changed in version 1.4.0: Added the UPLOAD and UPLOADED actions.

Changed in version 1.5.0: Added the CREATED action.

HSDescAction	Description
REQUESTED	uncached hidden service descriptor is being requested
UPLOAD	descriptor is being uploaded with HSPOST
RECEIVED	hidden service descriptor has been retrieved
UPLOADED	descriptor was uploaded with HSPOST
IGNORE	fetched descriptor was ignored because we already have its v0 descriptor
FAILED	we were unable to retrieve the descriptor
CREATED	hidden service descriptor was just created

stem.HSDescReason(enum)¶

Reason for the hidden service descriptor to fail to be fetched.

New in version 1.3.0.

Changed in version 1.4.0: Added the UPLOAD_REJECTED reason.

Changed in version 1.6.0: Added the QUERY_NO_HSDIR reason.

Changed in version 1.8.0: Added the QUERY_RATE_LIMITED reason.

HSDescReason	Description
BAD_DESC	descriptor was unparseable
QUERY_REJECTED	hidden service directory refused to provide the descriptor
UPLOAD_REJECTED	descriptor was rejected by the hidden service directory
NOT_FOUND	descriptor with the given identifier wasn't found
QUERY_NO_HSDIR	no hidden service directory was found
QUERY_RATE_LIMITED	request was throttled
UNEXPECTED	failure type is unknown

stem.HSAuth(enum)¶

Type of authentication being used for a HS_DESC event.

New in version 1.2.0.

HSAuth	Description
NO_AUTH	no authentication
BASIC_AUTH	general hidden service authentication
STEALTH_AUTH	authentication method that hides service activity from unauthorized clients
UNKNOWN	unrecognized method of authentication

exception stem.ControllerError[source]¶

Bases: exceptions.Exception

Base error for controller communication issues.

exception stem.ProtocolError[source]¶

Bases: stem.ControllerError

Malformed content from the control socket.

exception stem.OperationFailed(code=None, message=None)[source]¶

Bases: stem.ControllerError

Base exception class for failed operations that return an error code

Variables:	code (str) -- error code returned by Tor message (str) -- error message returned by Tor or a human readable error message

exception stem.UnsatisfiableRequest(code=None, message=None)[source]¶

Bases: stem.OperationFailed

Exception raised if Tor was unable to process our request.

exception stem.CircuitExtensionFailed(message, circ=None)[source]¶

Bases: stem.UnsatisfiableRequest

An attempt to create or extend a circuit failed.

Variables:	circ (stem.response.CircuitEvent) -- response notifying us of the failure

exception stem.DescriptorUnavailable(message)[source]¶

Bases: stem.UnsatisfiableRequest

Tor was unable to provide a descriptor for the given relay.

Changed in version 1.7.0: Subclassed under UnsatisfiableRequest rather than OperationFailed.

exception stem.Timeout(message)[source]¶

Bases: stem.UnsatisfiableRequest

Timeout requested by the caller was reached.

New in version 1.7.0.

exception stem.InvalidRequest(code=None, message=None)[source]¶

Bases: stem.OperationFailed

Exception raised when the request was invalid or malformed.

exception stem.InvalidArguments(code=None, message=None, arguments=None)[source]¶

Bases: stem.InvalidRequest

Exception class for requests which had invalid arguments.

Variables:	code (str) -- error code returned by Tor message (str) -- error message returned by Tor or a human readable error message arguments (list) -- a list of arguments which were invalid

exception stem.SocketError[source]¶

Bases: stem.ControllerError

Error arose while communicating with the control socket.

exception stem.SocketClosed[source]¶

Bases: stem.SocketError

Control socket was closed before completing the message.

exception stem.DownloadFailed(url, error, stacktrace, message=None)[source]¶

Bases: exceptions.IOError

Inability to download a resource. Python's urllib module raises a wide variety of undocumented exceptions (urllib2.URLError, socket.timeout, and others).

This wraps lower level failures in a common exception type that retains their exception and stacktrace.

New in version 1.8.0.

Variables:	url (str) -- url we failed to download from error (Exception) -- original urllib exception stacktrace (traceback) -- original stacktrace stacktrace_str (str) -- string representation of the stacktrace

exception stem.DownloadTimeout(url, error, stacktrace, timeout)[source]¶

Bases: stem.DownloadFailed

Timeout reached while downloading this resource.

New in version 1.8.0.