<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Controller — Stem 1.1.0 documentation</title>
<link rel="stylesheet" href="../_static/haiku.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../_static/print.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.1.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/theme_extras.js"></script>
<link rel="shortcut icon" href="../_static/favicon.png"/>
<link rel="top" title="Stem 1.1.0 documentation" href="../index.html" />
<link rel="up" title="Contents" href="../contents.html" />
<link rel="next" title="Controller Connection" href="connection.html" />
<link rel="prev" title="API" href="../api.html" />
</head>
<body>
<div class="header"><img class="rightlogo" src="../_static/logo.png" alt="Logo"/><h1 class="heading"><a href="../index.html">
<span>Stem Docs</span></a></h1>
<h2 class="heading"><span>Controller</span></h2>
</div>
<div class="topnav">
<p>
<ul id="navbar">
<li><a href="../index.html">Home</a></li>
<li><a href="../tutorials.html">Tutorials</a>
<ul>
<li><a href="../tutorials/the_little_relay_that_could.html">Hello World</a></li>
<li><a href="../tutorials/to_russia_with_love.html">Client Usage</a></li>
<li><a href="../tutorials/tortoise_and_the_hare.html">Event Listening</a></li>
<li><a href="../tutorials/mirror_mirror_on_the_wall.html">Tor Descriptors</a></li>
<li><a href="../tutorials/east_of_the_sun.html">Utilities</a></li>
<li><a href="../tutorials/double_double_toil_and_trouble.html">Examples</a></li>
</ul>
</li>
<li><a href="../api.html">API</a>
<ul>
<li><a href="#">stem.control</a></li>
<li><a href="connection.html">stem.connection</a></li>
<li><a href="socket.html">stem.socket</a></li>
<li><a href="process.html">stem.process</a></li>
<li><a href="response.html">stem.response</a></li>
<li><a href="exit_policy.html">stem.exit_policy</a></li>
<li><a href="version.html">stem.version</a></li>
<li><a href="../api.html#descriptors">Descriptors</a></li>
<li><a href="../api.html#utilities">Utilities</a></li>
</ul>
</li>
<li><a href="https://trac.torproject.org/projects/tor/wiki/doc/stem">Development</a>
<ul>
<li><a href="../faq.html">FAQ</a></li>
<li><a href="../change_log.html">Change Log</a></li>
<li><a href="https://trac.torproject.org/projects/tor/wiki/doc/stem/bugs">Bug Tracker</a></li>
<li><a href="../download.html">Download</a></li>
</ul>
</li>
</ul>
</p>
</div>
<div class="content">
<div class="section" id="module-stem.control">
<span id="controller"></span><h1>Controller<a class="headerlink" href="#module-stem.control" title="Permalink to this headline">¶</a></h1>
<p>Classes for interacting with the tor control socket.</p>
<p>Controllers are a wrapper around a <a class="reference internal" href="socket.html#stem.socket.ControlSocket" title="stem.socket.ControlSocket"><tt class="xref py py-class docutils literal"><span class="pre">ControlSocket</span></tt></a>,
retaining many of its methods (connect, close, is_alive, etc) in addition to
providing its own for interacting at a higher level.</p>
<p><strong>Module Overview:</strong></p>
<div class="highlight-python"><pre>Controller - General controller class intended for direct use
| |- from_port - Provides a Controller based on a port connection.
| +- from_socket_file - Provides a Controller based on a socket file connection.
|
|- authenticate - authenticates this controller with tor
|
|- get_info - issues a GETINFO query for a parameter
|- get_version - provides our tor version
|- get_exit_policy - provides our exit policy
|- get_socks_listeners - provides where tor is listening for SOCKS connections
|- get_protocolinfo - information about the controller interface
|- get_user - provides the user tor is running as
|- get_pid - provides the pid of our tor process
|
|- get_microdescriptor - querying the microdescriptor for a relay
|- get_microdescriptors - provides all presently available microdescriptors
|- get_server_descriptor - querying the server descriptor for a relay
|- get_server_descriptors - provides all presently available server descriptors
|- get_network_status - querying the router status entry for a relay
|- get_network_statuses - provides all preently available router status entries
|
|- get_conf - gets the value of a configuration option
|- get_conf_map - gets the values of multiple configuration options
|- set_conf - sets the value of a configuration option
|- reset_conf - reverts configuration options to their default values
|- set_options - sets or resets the values of multiple configuration options
|
|- add_event_listener - attaches an event listener to be notified of tor events
|- remove_event_listener - removes a listener so it isn't notified of further events
|
|- is_caching_enabled - true if the controller has enabled caching
|- set_caching - enables or disables caching
|- clear_cache - clears any cached results
|
|- load_conf - loads configuration information as if it was in the torrc
|- save_conf - saves configuration information to the torrc
|
|- is_feature_enabled - checks if a given controller feature is enabled
|- enable_feature - enables a controller feature that has been disabled by default
|
|- get_circuit - provides an active circuit
|- get_circuits - provides a list of active circuits
|- new_circuit - create new circuits
|- extend_circuit - create new circuits and extend existing ones
|- repurpose_circuit - change a circuit's purpose
|- close_circuit - close a circuit
|
|- get_streams - provides a list of active streams
|- attach_stream - attach a stream to a circuit
|- close_stream - close a stream
|
|- signal - sends a signal to the tor client
|- is_geoip_unavailable - true if we've discovered our geoip db to be unavailable
+- map_address - maps one address to another such that connections to the original are replaced with the other
BaseController - Base controller class asynchronous message handling
|- msg - communicates with the tor process
|- is_alive - reports if our connection to tor is open or closed
|- is_authenticated - checks if we're authenticated to tor
|- connect - connects or reconnects to tor
|- close - shuts down our connection to the tor process
|- get_socket - provides the socket used for control communication
|- get_latest_heartbeat - timestamp for when we last heard from tor
|- add_status_listener - notifies a callback of changes in our status
|- remove_status_listener - prevents further notification of status changes
+- __enter__ / __exit__ - manages socket connection</pre>
</div>
<dl class="data">
<dt id="stem.control.State">
<tt class="descclassname">stem.control.</tt><tt class="descname">State</tt><big>(</big><em>enum</em><big>)</big><a class="headerlink" href="#stem.control.State" title="Permalink to this definition">¶</a></dt>
<dd><p>Enumeration for states that a controller can have.</p>
<table border="1" class="docutils">
<colgroup>
<col width="25%" />
<col width="75%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">State</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><strong>INIT</strong></td>
<td>new control connection</td>
</tr>
<tr class="row-odd"><td><strong>RESET</strong></td>
<td>received a reset/sighup signal</td>
</tr>
<tr class="row-even"><td><strong>CLOSED</strong></td>
<td>control connection closed</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="data">
<dt id="stem.control.EventType">
<tt class="descclassname">stem.control.</tt><tt class="descname">EventType</tt><big>(</big><em>enum</em><big>)</big><a class="headerlink" href="#stem.control.EventType" title="Permalink to this definition">¶</a></dt>
<dd><p>Known types of events that the
<a class="reference internal" href="#stem.control.Controller.add_event_listener" title="stem.control.Controller.add_event_listener"><tt class="xref py py-func docutils literal"><span class="pre">add_event_listener()</span></tt></a> method of the
<a class="reference internal" href="#stem.control.Controller" title="stem.control.Controller"><tt class="xref py py-class docutils literal"><span class="pre">Controller</span></tt></a> can listen for.</p>
<p>The most frequently listened for event types tend to be the logging events
(<strong>DEBUG</strong>, <strong>INFO</strong>, <strong>NOTICE</strong>, <strong>WARN</strong>, and <strong>ERR</strong>), bandwidth usage
(<strong>BW</strong>), and circuit or stream changes (<strong>CIRC</strong> and <strong>STREAM</strong>).</p>
<p>Enums are mapped to <a class="reference internal" href="response.html#stem.response.events.Event" title="stem.response.events.Event"><tt class="xref py py-class docutils literal"><span class="pre">Event</span></tt></a> subclasses as
follows...</p>
<table border="1" class="docutils">
<colgroup>
<col width="30%" />
<col width="70%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">EventType</th>
<th class="head">Event Class</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><strong>ADDRMAP</strong></td>
<td><a class="reference internal" href="response.html#stem.response.events.AddrMapEvent" title="stem.response.events.AddrMapEvent"><tt class="xref py py-class docutils literal"><span class="pre">stem.response.events.AddrMapEvent</span></tt></a></td>
</tr>
<tr class="row-odd"><td><strong>AUTHDIR_NEWDESCS</strong></td>
<td><a class="reference internal" href="response.html#stem.response.events.AuthDirNewDescEvent" title="stem.response.events.AuthDirNewDescEvent"><tt class="xref py py-class docutils literal"><span class="pre">stem.response.events.AuthDirNewDescEvent</span></tt></a></td>
</tr>
<tr class="row-even"><td><strong>BUILDTIMEOUT_SET</strong></td>
<td><a class="reference internal" href="response.html#stem.response.events.BuildTimeoutSetEvent" title="stem.response.events.BuildTimeoutSetEvent"><tt class="xref py py-class docutils literal"><span class="pre">stem.response.events.BuildTimeoutSetEvent</span></tt></a></td>
</tr>
<tr class="row-odd"><td><strong>BW</strong></td>
<td><a class="reference internal" href="response.html#stem.response.events.BandwidthEvent" title="stem.response.events.BandwidthEvent"><tt class="xref py py-class docutils literal"><span class="pre">stem.response.events.BandwidthEvent</span></tt></a></td>
</tr>
<tr class="row-even"><td><strong>CIRC</strong></td>
<td><a class="reference internal" href="response.html#stem.response.events.CircuitEvent" title="stem.response.events.CircuitEvent"><tt class="xref py py-class docutils literal"><span class="pre">stem.response.events.CircuitEvent</span></tt></a></td>
</tr>
<tr class="row-odd"><td><strong>CIRC_MINOR</strong></td>
<td><a class="reference internal" href="response.html#stem.response.events.CircMinorEvent" title="stem.response.events.CircMinorEvent"><tt class="xref py py-class docutils literal"><span class="pre">stem.response.events.CircMinorEvent</span></tt></a></td>
</tr>
<tr class="row-even"><td><strong>CLIENTS_SEEN</strong></td>
<td><a class="reference internal" href="response.html#stem.response.events.ClientsSeenEvent" title="stem.response.events.ClientsSeenEvent"><tt class="xref py py-class docutils literal"><span class="pre">stem.response.events.ClientsSeenEvent</span></tt></a></td>
</tr>
<tr class="row-odd"><td><strong>CONF_CHANGED</strong></td>
<td><a class="reference internal" href="response.html#stem.response.events.ConfChangedEvent" title="stem.response.events.ConfChangedEvent"><tt class="xref py py-class docutils literal"><span class="pre">stem.response.events.ConfChangedEvent</span></tt></a></td>
</tr>
<tr class="row-even"><td><strong>DEBUG</strong></td>
<td><a class="reference internal" href="response.html#stem.response.events.LogEvent" title="stem.response.events.LogEvent"><tt class="xref py py-class docutils literal"><span class="pre">stem.response.events.LogEvent</span></tt></a></td>
</tr>
<tr class="row-odd"><td><strong>DESCCHANGED</strong></td>
<td><a class="reference internal" href="response.html#stem.response.events.DescChangedEvent" title="stem.response.events.DescChangedEvent"><tt class="xref py py-class docutils literal"><span class="pre">stem.response.events.DescChangedEvent</span></tt></a></td>
</tr>
<tr class="row-even"><td><strong>ERR</strong></td>
<td><a class="reference internal" href="response.html#stem.response.events.LogEvent" title="stem.response.events.LogEvent"><tt class="xref py py-class docutils literal"><span class="pre">stem.response.events.LogEvent</span></tt></a></td>
</tr>
<tr class="row-odd"><td><strong>GUARD</strong></td>
<td><a class="reference internal" href="response.html#stem.response.events.GuardEvent" title="stem.response.events.GuardEvent"><tt class="xref py py-class docutils literal"><span class="pre">stem.response.events.GuardEvent</span></tt></a></td>
</tr>
<tr class="row-even"><td><strong>INFO</strong></td>
<td><a class="reference internal" href="response.html#stem.response.events.LogEvent" title="stem.response.events.LogEvent"><tt class="xref py py-class docutils literal"><span class="pre">stem.response.events.LogEvent</span></tt></a></td>
</tr>
<tr class="row-odd"><td><strong>NEWCONSENSUS</strong></td>
<td><a class="reference internal" href="response.html#stem.response.events.NewConsensusEvent" title="stem.response.events.NewConsensusEvent"><tt class="xref py py-class docutils literal"><span class="pre">stem.response.events.NewConsensusEvent</span></tt></a></td>
</tr>
<tr class="row-even"><td><strong>NEWDESC</strong></td>
<td><a class="reference internal" href="response.html#stem.response.events.NewDescEvent" title="stem.response.events.NewDescEvent"><tt class="xref py py-class docutils literal"><span class="pre">stem.response.events.NewDescEvent</span></tt></a></td>
</tr>
<tr class="row-odd"><td><strong>NOTICE</strong></td>
<td><a class="reference internal" href="response.html#stem.response.events.LogEvent" title="stem.response.events.LogEvent"><tt class="xref py py-class docutils literal"><span class="pre">stem.response.events.LogEvent</span></tt></a></td>
</tr>
<tr class="row-even"><td><strong>NS</strong></td>
<td><a class="reference internal" href="response.html#stem.response.events.NetworkStatusEvent" title="stem.response.events.NetworkStatusEvent"><tt class="xref py py-class docutils literal"><span class="pre">stem.response.events.NetworkStatusEvent</span></tt></a></td>
</tr>
<tr class="row-odd"><td><strong>ORCONN</strong></td>
<td><a class="reference internal" href="response.html#stem.response.events.ORConnEvent" title="stem.response.events.ORConnEvent"><tt class="xref py py-class docutils literal"><span class="pre">stem.response.events.ORConnEvent</span></tt></a></td>
</tr>
<tr class="row-even"><td><strong>SIGNAL</strong></td>
<td><a class="reference internal" href="response.html#stem.response.events.SignalEvent" title="stem.response.events.SignalEvent"><tt class="xref py py-class docutils literal"><span class="pre">stem.response.events.SignalEvent</span></tt></a></td>
</tr>
<tr class="row-odd"><td><strong>STATUS_CLIENT</strong></td>
<td><a class="reference internal" href="response.html#stem.response.events.StatusEvent" title="stem.response.events.StatusEvent"><tt class="xref py py-class docutils literal"><span class="pre">stem.response.events.StatusEvent</span></tt></a></td>
</tr>
<tr class="row-even"><td><strong>STATUS_GENERAL</strong></td>
<td><a class="reference internal" href="response.html#stem.response.events.StatusEvent" title="stem.response.events.StatusEvent"><tt class="xref py py-class docutils literal"><span class="pre">stem.response.events.StatusEvent</span></tt></a></td>
</tr>
<tr class="row-odd"><td><strong>STATUS_SERVER</strong></td>
<td><a class="reference internal" href="response.html#stem.response.events.StatusEvent" title="stem.response.events.StatusEvent"><tt class="xref py py-class docutils literal"><span class="pre">stem.response.events.StatusEvent</span></tt></a></td>
</tr>
<tr class="row-even"><td><strong>STREAM</strong></td>
<td><a class="reference internal" href="response.html#stem.response.events.StreamEvent" title="stem.response.events.StreamEvent"><tt class="xref py py-class docutils literal"><span class="pre">stem.response.events.StreamEvent</span></tt></a></td>
</tr>
<tr class="row-odd"><td><strong>STREAM_BW</strong></td>
<td><a class="reference internal" href="response.html#stem.response.events.StreamBwEvent" title="stem.response.events.StreamBwEvent"><tt class="xref py py-class docutils literal"><span class="pre">stem.response.events.StreamBwEvent</span></tt></a></td>
</tr>
<tr class="row-even"><td><strong>WARN</strong></td>
<td><a class="reference internal" href="response.html#stem.response.events.LogEvent" title="stem.response.events.LogEvent"><tt class="xref py py-class docutils literal"><span class="pre">stem.response.events.LogEvent</span></tt></a></td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="class">
<dt id="stem.control.BaseController">
<em class="property">class </em><tt class="descclassname">stem.control.</tt><tt class="descname">BaseController</tt><big>(</big><em>control_socket</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#BaseController"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.BaseController" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">object</span></tt></p>
<p>Controller for the tor process. This is a minimal base class for other
controllers, providing basic process communication and event listing. Don’t
use this directly - subclasses like the <a class="reference internal" href="#stem.control.Controller" title="stem.control.Controller"><tt class="xref py py-class docutils literal"><span class="pre">Controller</span></tt></a>
provide higher level functionality.</p>
<p>It’s highly suggested that you don’t interact directly with the
<a class="reference internal" href="socket.html#stem.socket.ControlSocket" title="stem.socket.ControlSocket"><tt class="xref py py-class docutils literal"><span class="pre">ControlSocket</span></tt></a> that we’re constructed from - use our
wrapper methods instead.</p>
<dl class="method">
<dt id="stem.control.BaseController.msg">
<tt class="descname">msg</tt><big>(</big><em>message</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#BaseController.msg"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.BaseController.msg" title="Permalink to this definition">¶</a></dt>
<dd><p>Sends a message to our control socket and provides back its reply.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><p class="first"><strong>message</strong> (<em>str</em>) – message to be formatted and sent to tor</p>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first"><a class="reference internal" href="response.html#stem.response.ControlMessage" title="stem.response.ControlMessage"><tt class="xref py py-class docutils literal"><span class="pre">ControlMessage</span></tt></a> with the response</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><ul class="first last simple">
<li><a class="reference internal" href="#stem.ProtocolError" title="stem.ProtocolError"><tt class="xref py py-class docutils literal"><span class="pre">stem.ProtocolError</span></tt></a> the content from the socket is
malformed</li>
<li><a class="reference internal" href="#stem.SocketError" title="stem.SocketError"><tt class="xref py py-class docutils literal"><span class="pre">stem.SocketError</span></tt></a> if a problem arises in using the
socket</li>
<li><a class="reference internal" href="#stem.SocketClosed" title="stem.SocketClosed"><tt class="xref py py-class docutils literal"><span class="pre">stem.SocketClosed</span></tt></a> if the socket is shut down</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.BaseController.is_alive">
<tt class="descname">is_alive</tt><big>(</big><big>)</big><a class="reference internal" href="../_modules/stem/control.html#BaseController.is_alive"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.BaseController.is_alive" title="Permalink to this definition">¶</a></dt>
<dd><p>Checks if our socket is currently connected. This is a pass-through for our
socket’s <a class="reference internal" href="socket.html#stem.socket.ControlSocket.is_alive" title="stem.socket.ControlSocket.is_alive"><tt class="xref py py-func docutils literal"><span class="pre">is_alive()</span></tt></a> method.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body"><strong>bool</strong> that’s <strong>True</strong> if our socket is connected and <strong>False</strong> otherwise</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.BaseController.is_authenticated">
<tt class="descname">is_authenticated</tt><big>(</big><big>)</big><a class="reference internal" href="../_modules/stem/control.html#BaseController.is_authenticated"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.BaseController.is_authenticated" title="Permalink to this definition">¶</a></dt>
<dd><p>Checks if our socket is both connected and authenticated.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body"><strong>bool</strong> that’s <strong>True</strong> if our socket is authenticated to tor
and <strong>False</strong> otherwise</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.BaseController.connect">
<tt class="descname">connect</tt><big>(</big><big>)</big><a class="reference internal" href="../_modules/stem/control.html#BaseController.connect"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.BaseController.connect" title="Permalink to this definition">¶</a></dt>
<dd><p>Reconnects our control socket. This is a pass-through for our socket’s
<a class="reference internal" href="socket.html#stem.socket.ControlSocket.connect" title="stem.socket.ControlSocket.connect"><tt class="xref py py-func docutils literal"><span class="pre">connect()</span></tt></a> method.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><a class="reference internal" href="#stem.SocketError" title="stem.SocketError"><tt class="xref py py-class docutils literal"><span class="pre">stem.SocketError</span></tt></a> if unable to make a socket</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.BaseController.close">
<tt class="descname">close</tt><big>(</big><big>)</big><a class="reference internal" href="../_modules/stem/control.html#BaseController.close"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.BaseController.close" title="Permalink to this definition">¶</a></dt>
<dd><p>Closes our socket connection. This is a pass-through for our socket’s
<a class="reference internal" href="socket.html#stem.socket.ControlSocket.close" title="stem.socket.ControlSocket.close"><tt class="xref py py-func docutils literal"><span class="pre">close()</span></tt></a> method.</p>
</dd></dl>
<dl class="method">
<dt id="stem.control.BaseController.get_socket">
<tt class="descname">get_socket</tt><big>(</big><big>)</big><a class="reference internal" href="../_modules/stem/control.html#BaseController.get_socket"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.BaseController.get_socket" title="Permalink to this definition">¶</a></dt>
<dd><p>Provides the socket used to speak with the tor process. Communicating with
the socket directly isn’t advised since it may confuse this controller.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body"><a class="reference internal" href="socket.html#stem.socket.ControlSocket" title="stem.socket.ControlSocket"><tt class="xref py py-class docutils literal"><span class="pre">ControlSocket</span></tt></a> we’re communicating with</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.BaseController.get_latest_heartbeat">
<tt class="descname">get_latest_heartbeat</tt><big>(</big><big>)</big><a class="reference internal" href="../_modules/stem/control.html#BaseController.get_latest_heartbeat"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.BaseController.get_latest_heartbeat" title="Permalink to this definition">¶</a></dt>
<dd><p>Provides the unix timestamp for when we last heard from tor. This is zero
if we’ve never received a message.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body">float for the unix timestamp of when we last heard from tor</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.BaseController.add_status_listener">
<tt class="descname">add_status_listener</tt><big>(</big><em>callback</em>, <em>spawn=True</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#BaseController.add_status_listener"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.BaseController.add_status_listener" title="Permalink to this definition">¶</a></dt>
<dd><p>Notifies a given function when the state of our socket changes. Functions
are expected to be of the form...</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">my_function</span><span class="p">(</span><span class="n">controller</span><span class="p">,</span> <span class="n">state</span><span class="p">,</span> <span class="n">timestamp</span><span class="p">)</span>
</pre></div>
</div>
<p>The state is a value from the <a class="reference internal" href="#stem.control.State" title="stem.control.State"><tt class="xref py py-data docutils literal"><span class="pre">stem.control.State</span></tt></a> enum. Functions
<strong>must</strong> allow for new values. The timestamp is a float for the unix time
when the change occurred.</p>
<p>This class only provides <strong>State.INIT</strong> and <strong>State.CLOSED</strong> notifications.
Subclasses may provide others.</p>
<p>If spawn is <strong>True</strong> then the callback is notified via a new daemon thread.
If <strong>False</strong> then the notice is under our locks, within the thread where
the change occurred. In general this isn’t advised, especially if your
callback could block for a while.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>callback</strong> (<em>function</em>) – function to be notified when our state changes</li>
<li><strong>spawn</strong> (<em>bool</em>) – calls function via a new thread if <strong>True</strong>, otherwise
it’s part of the connect/close method call</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.BaseController.remove_status_listener">
<tt class="descname">remove_status_listener</tt><big>(</big><em>callback</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#BaseController.remove_status_listener"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.BaseController.remove_status_listener" title="Permalink to this definition">¶</a></dt>
<dd><p>Stops listener from being notified of further events.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>callback</strong> (<em>function</em>) – function to be removed from our listeners</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><strong>bool</strong> that’s <strong>True</strong> if we removed one or more occurrences of
the callback, <strong>False</strong> otherwise</td>
</tr>
</tbody>
</table>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="stem.control.Controller">
<em class="property">class </em><tt class="descclassname">stem.control.</tt><tt class="descname">Controller</tt><big>(</big><em>control_socket</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#stem.control.BaseController" title="stem.control.BaseController"><tt class="xref py py-class docutils literal"><span class="pre">stem.control.BaseController</span></tt></a></p>
<p>Communicates with a control socket. This is built on top of the
BaseController and provides a more user friendly API for library users.</p>
<dl class="staticmethod">
<dt id="stem.control.Controller.from_port">
<em class="property">static </em><tt class="descname">from_port</tt><big>(</big><em>address='127.0.0.1'</em>, <em>port=9051</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.from_port"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.from_port" title="Permalink to this definition">¶</a></dt>
<dd><p>Constructs a <a class="reference internal" href="socket.html#stem.socket.ControlPort" title="stem.socket.ControlPort"><tt class="xref py py-class docutils literal"><span class="pre">ControlPort</span></tt></a> based Controller.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>address</strong> (<em>str</em>) – ip address of the controller</li>
<li><strong>port</strong> (<em>int</em>) – port number of the controller</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first"><a class="reference internal" href="#stem.control.Controller" title="stem.control.Controller"><tt class="xref py py-class docutils literal"><span class="pre">Controller</span></tt></a> attached to the given port</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><p class="first last"><a class="reference internal" href="#stem.SocketError" title="stem.SocketError"><tt class="xref py py-class docutils literal"><span class="pre">stem.SocketError</span></tt></a> if we’re unable to establish a connection</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="staticmethod">
<dt id="stem.control.Controller.from_socket_file">
<em class="property">static </em><tt class="descname">from_socket_file</tt><big>(</big><em>path='/var/run/tor/control'</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.from_socket_file"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.from_socket_file" title="Permalink to this definition">¶</a></dt>
<dd><p>Constructs a <a class="reference internal" href="socket.html#stem.socket.ControlSocketFile" title="stem.socket.ControlSocketFile"><tt class="xref py py-class docutils literal"><span class="pre">ControlSocketFile</span></tt></a> based Controller.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>path</strong> (<em>str</em>) – path where the control socket is located</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><a class="reference internal" href="#stem.control.Controller" title="stem.control.Controller"><tt class="xref py py-class docutils literal"><span class="pre">Controller</span></tt></a> attached to the given socket file</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><a class="reference internal" href="#stem.SocketError" title="stem.SocketError"><tt class="xref py py-class docutils literal"><span class="pre">stem.SocketError</span></tt></a> if we’re unable to establish a connection</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.connect">
<tt class="descname">connect</tt><big>(</big><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.connect"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.connect" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="stem.control.Controller.close">
<tt class="descname">close</tt><big>(</big><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.close"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.close" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
<dt id="stem.control.Controller.authenticate">
<tt class="descname">authenticate</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.authenticate"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.authenticate" title="Permalink to this definition">¶</a></dt>
<dd><p>A convenience method to authenticate the controller. This is just a
pass-through to <a class="reference internal" href="connection.html#stem.connection.authenticate" title="stem.connection.authenticate"><tt class="xref py py-func docutils literal"><span class="pre">stem.connection.authenticate()</span></tt></a>.</p>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.get_info">
<tt class="descname">get_info</tt><big>(</big><em>params</em>, <em>default='<Undefined_ >'</em>, <em>get_bytes=False</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.get_info"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.get_info" title="Permalink to this definition">¶</a></dt>
<dd><p>Queries the control socket for the given GETINFO option. If provided a
default then that’s returned if the GETINFO option is undefined or the
call fails for any reason (error response, control port closed, initiated,
etc).</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>params</strong> (<em>str,list</em>) – GETINFO option or options to be queried</li>
<li><strong>default</strong> (<em>object</em>) – response if the query fails</li>
<li><strong>get_bytes</strong> (<em>bool</em>) – provides <strong>bytes</strong> values rather than a <strong>str</strong> under python 3.x</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first"><p>Response depends upon how we were called as follows...</p>
<ul class="simple">
<li><strong>str</strong> with the response if our param was a <strong>str</strong></li>
<li><strong>dict</strong> with the ‘param => response’ mapping if our param was a <strong>list</strong></li>
<li>default if one was provided and our call failed</li>
</ul>
</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><ul class="first last simple">
<li><a class="reference internal" href="#stem.ControllerError" title="stem.ControllerError"><tt class="xref py py-class docutils literal"><span class="pre">stem.ControllerError</span></tt></a> if the call fails and we weren’t
provided a default response</li>
<li><a class="reference internal" href="#stem.InvalidArguments" title="stem.InvalidArguments"><tt class="xref py py-class docutils literal"><span class="pre">stem.InvalidArguments</span></tt></a> if the ‘params’ requested was
invalid</li>
<li><a class="reference internal" href="#stem.ProtocolError" title="stem.ProtocolError"><tt class="xref py py-class docutils literal"><span class="pre">stem.ProtocolError</span></tt></a> if the geoip database is known to be
unavailable</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.get_version">
<tt class="descname">get_version</tt><big>(</big><em>default='<Undefined_ >'</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.get_version"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.get_version" title="Permalink to this definition">¶</a></dt>
<dd><p>A convenience method to get tor version that current controller is
connected to.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><p class="first"><strong>default</strong> (<em>object</em>) – response if the query fails</p>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first"><a class="reference internal" href="version.html#stem.version.Version" title="stem.version.Version"><tt class="xref py py-class docutils literal"><span class="pre">Version</span></tt></a> of the tor instance that we’re
connected to</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><ul class="first simple">
<li><a class="reference internal" href="#stem.ControllerError" title="stem.ControllerError"><tt class="xref py py-class docutils literal"><span class="pre">stem.ControllerError</span></tt></a> if unable to query the version</li>
<li><strong>ValueError</strong> if unable to parse the version</li>
</ul>
<p class="last">An exception is only raised if we weren’t provided a default response.</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.get_exit_policy">
<tt class="descname">get_exit_policy</tt><big>(</big><em>default='<Undefined_ >'</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.get_exit_policy"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.get_exit_policy" title="Permalink to this definition">¶</a></dt>
<dd><p>Effective ExitPolicy for our relay. This accounts for
ExitPolicyRejectPrivate and default policies.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><p class="first"><strong>default</strong> (<em>object</em>) – response if the query fails</p>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first"><a class="reference internal" href="exit_policy.html#stem.exit_policy.ExitPolicy" title="stem.exit_policy.ExitPolicy"><tt class="xref py py-class docutils literal"><span class="pre">ExitPolicy</span></tt></a> of the tor instance that
we’re connected to</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><ul class="first simple">
<li><a class="reference internal" href="#stem.ControllerError" title="stem.ControllerError"><tt class="xref py py-class docutils literal"><span class="pre">stem.ControllerError</span></tt></a> if unable to query the policy</li>
<li><strong>ValueError</strong> if unable to parse the policy</li>
</ul>
<p class="last">An exception is only raised if we weren’t provided a default response.</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.get_socks_listeners">
<tt class="descname">get_socks_listeners</tt><big>(</big><em>default='<Undefined_ >'</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.get_socks_listeners"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.get_socks_listeners" title="Permalink to this definition">¶</a></dt>
<dd><p>Provides the SOCKS <strong>(address, port)</strong> tuples that tor has open.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>default</strong> (<em>object</em>) – response if the query fails</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">list of <strong>(address, port)</strong> tuples for the available SOCKS
listeners</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><a class="reference internal" href="#stem.ControllerError" title="stem.ControllerError"><tt class="xref py py-class docutils literal"><span class="pre">stem.ControllerError</span></tt></a> if unable to determine the listeners
and no default was provided</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.get_protocolinfo">
<tt class="descname">get_protocolinfo</tt><big>(</big><em>default='<Undefined_ >'</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.get_protocolinfo"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.get_protocolinfo" title="Permalink to this definition">¶</a></dt>
<dd><p>A convenience method to get the protocol info of the controller.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><p class="first"><strong>default</strong> (<em>object</em>) – response if the query fails</p>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first"><a class="reference internal" href="response.html#stem.response.protocolinfo.ProtocolInfoResponse" title="stem.response.protocolinfo.ProtocolInfoResponse"><tt class="xref py py-class docutils literal"><span class="pre">ProtocolInfoResponse</span></tt></a> provided by tor</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><ul class="first simple">
<li><a class="reference internal" href="#stem.ProtocolError" title="stem.ProtocolError"><tt class="xref py py-class docutils literal"><span class="pre">stem.ProtocolError</span></tt></a> if the PROTOCOLINFO response is
malformed</li>
<li><a class="reference internal" href="#stem.SocketError" title="stem.SocketError"><tt class="xref py py-class docutils literal"><span class="pre">stem.SocketError</span></tt></a> if problems arise in establishing or
using the socket</li>
</ul>
<p class="last">An exception is only raised if we weren’t provided a default response.</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.get_user">
<tt class="descname">get_user</tt><big>(</big><em>default='<Undefined_ >'</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.get_user"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.get_user" title="Permalink to this definition">¶</a></dt>
<dd><p>Provides the user tor is running as. This often only works if tor is
running locally. Also, most of its checks are platform dependent, and hence
are not entirely reliable.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>default</strong> (<em>object</em>) – response if the query fails</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">str with the username tor is running as</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.get_pid">
<tt class="descname">get_pid</tt><big>(</big><em>default='<Undefined_ >'</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.get_pid"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.get_pid" title="Permalink to this definition">¶</a></dt>
<dd><p>Provides the process id of tor. This often only works if tor is running
locally. Also, most of its checks are platform dependent, and hence are not
entirely reliable.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>default</strong> (<em>object</em>) – response if the query fails</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">int with our process’ pid</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><strong>ValueError</strong> if unable to determine the pid and no default was
provided</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.get_microdescriptor">
<tt class="descname">get_microdescriptor</tt><big>(</big><em>relay</em>, <em>default='<Undefined_ >'</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.get_microdescriptor"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.get_microdescriptor" title="Permalink to this definition">¶</a></dt>
<dd><p>Provides the microdescriptor for the relay with the given fingerprint or
nickname. If the relay identifier could be either a fingerprint <em>or</em>
nickname then it’s queried as a fingerprint.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>relay</strong> (<em>str</em>) – fingerprint or nickname of the relay to be queried</li>
<li><strong>default</strong> (<em>object</em>) – response if the query fails</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first"><a class="reference internal" href="descriptor/microdescriptor.html#stem.descriptor.microdescriptor.Microdescriptor" title="stem.descriptor.microdescriptor.Microdescriptor"><tt class="xref py py-class docutils literal"><span class="pre">Microdescriptor</span></tt></a> for the given relay</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><ul class="first simple">
<li><a class="reference internal" href="#stem.ControllerError" title="stem.ControllerError"><tt class="xref py py-class docutils literal"><span class="pre">stem.ControllerError</span></tt></a> if unable to query the descriptor</li>
<li><strong>ValueError</strong> if <strong>relay</strong> doesn’t conform with the pattern for being
a fingerprint or nickname</li>
</ul>
<p class="last">An exception is only raised if we weren’t provided a default response.</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.get_microdescriptors">
<tt class="descname">get_microdescriptors</tt><big>(</big><em>default='<Undefined_ >'</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.get_microdescriptors"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.get_microdescriptors" title="Permalink to this definition">¶</a></dt>
<dd><p>Provides an iterator for all of the microdescriptors that tor presently
knows about.</p>
<p><strong>Tor does not expose this information via the control protocol</strong>
(<a class="reference external" href="https://trac.torproject.org/8323">ticket 8323</a>). Until it does this reads the microdescriptors from disk,
and hence won’t work remotely or if we lack read permissions.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>default</strong> (<em>list</em>) – items to provide if the query fails</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">iterates over
<a class="reference internal" href="descriptor/microdescriptor.html#stem.descriptor.microdescriptor.Microdescriptor" title="stem.descriptor.microdescriptor.Microdescriptor"><tt class="xref py py-class docutils literal"><span class="pre">Microdescriptor</span></tt></a> for relays in
the tor network</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><a class="reference internal" href="#stem.ControllerError" title="stem.ControllerError"><tt class="xref py py-class docutils literal"><span class="pre">stem.ControllerError</span></tt></a> if unable to query tor and no
default was provided</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.get_server_descriptor">
<tt class="descname">get_server_descriptor</tt><big>(</big><em>relay</em>, <em>default='<Undefined_ >'</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.get_server_descriptor"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.get_server_descriptor" title="Permalink to this definition">¶</a></dt>
<dd><p>Provides the server descriptor for the relay with the given fingerprint or
nickname. If the relay identifier could be either a fingerprint <em>or</em>
nickname then it’s queried as a fingerprint.</p>
<p><strong>As of Tor version 0.2.3.25 relays no longer get server descriptors by
default.</strong> It’s advised that you use microdescriptors instead, but if you
really need server descriptors then you can get them by setting
‘UseMicrodescriptors 0’.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>relay</strong> (<em>str</em>) – fingerprint or nickname of the relay to be queried</li>
<li><strong>default</strong> (<em>object</em>) – response if the query fails</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first"><a class="reference internal" href="descriptor/server_descriptor.html#stem.descriptor.server_descriptor.RelayDescriptor" title="stem.descriptor.server_descriptor.RelayDescriptor"><tt class="xref py py-class docutils literal"><span class="pre">RelayDescriptor</span></tt></a> for the given relay</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><ul class="first simple">
<li><a class="reference internal" href="#stem.ControllerError" title="stem.ControllerError"><tt class="xref py py-class docutils literal"><span class="pre">stem.ControllerError</span></tt></a> if unable to query the descriptor</li>
<li><strong>ValueError</strong> if <strong>relay</strong> doesn’t conform with the pattern for being
a fingerprint or nickname</li>
</ul>
<p class="last">An exception is only raised if we weren’t provided a default response.</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.get_server_descriptors">
<tt class="descname">get_server_descriptors</tt><big>(</big><em>default='<Undefined_ >'</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.get_server_descriptors"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.get_server_descriptors" title="Permalink to this definition">¶</a></dt>
<dd><p>Provides an iterator for all of the server descriptors that tor presently
knows about.</p>
<p><strong>As of Tor version 0.2.3.25 relays no longer get server descriptors by
default.</strong> It’s advised that you use microdescriptors instead, but if you
really need server descriptors then you can get them by setting
‘UseMicrodescriptors 0’.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>default</strong> (<em>list</em>) – items to provide if the query fails</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">iterates over
<a class="reference internal" href="descriptor/server_descriptor.html#stem.descriptor.server_descriptor.RelayDescriptor" title="stem.descriptor.server_descriptor.RelayDescriptor"><tt class="xref py py-class docutils literal"><span class="pre">RelayDescriptor</span></tt></a> for relays in
the tor network</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><a class="reference internal" href="#stem.ControllerError" title="stem.ControllerError"><tt class="xref py py-class docutils literal"><span class="pre">stem.ControllerError</span></tt></a> if unable to query tor and no
default was provided</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.get_network_status">
<tt class="descname">get_network_status</tt><big>(</big><em>relay</em>, <em>default='<Undefined_ >'</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.get_network_status"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.get_network_status" title="Permalink to this definition">¶</a></dt>
<dd><p>Provides the router status entry for the relay with the given fingerprint
or nickname. If the relay identifier could be either a fingerprint <em>or</em>
nickname then it’s queried as a fingerprint.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>relay</strong> (<em>str</em>) – fingerprint or nickname of the relay to be queried</li>
<li><strong>default</strong> (<em>object</em>) – response if the query fails</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first"><a class="reference internal" href="descriptor/router_status_entry.html#stem.descriptor.router_status_entry.RouterStatusEntryV3" title="stem.descriptor.router_status_entry.RouterStatusEntryV3"><tt class="xref py py-class docutils literal"><span class="pre">RouterStatusEntryV3</span></tt></a>
for the given relay</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><ul class="first simple">
<li><a class="reference internal" href="#stem.ControllerError" title="stem.ControllerError"><tt class="xref py py-class docutils literal"><span class="pre">stem.ControllerError</span></tt></a> if unable to query the descriptor</li>
<li><strong>ValueError</strong> if <strong>relay</strong> doesn’t conform with the pattern for being
a fingerprint or nickname</li>
</ul>
<p class="last">An exception is only raised if we weren’t provided a default response.</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.get_network_statuses">
<tt class="descname">get_network_statuses</tt><big>(</big><em>default='<Undefined_ >'</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.get_network_statuses"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.get_network_statuses" title="Permalink to this definition">¶</a></dt>
<dd><p>Provides an iterator for all of the router status entries that tor
presently knows about.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>default</strong> (<em>list</em>) – items to provide if the query fails</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">iterates over
<a class="reference internal" href="descriptor/router_status_entry.html#stem.descriptor.router_status_entry.RouterStatusEntryV3" title="stem.descriptor.router_status_entry.RouterStatusEntryV3"><tt class="xref py py-class docutils literal"><span class="pre">RouterStatusEntryV3</span></tt></a> for
relays in the tor network</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><a class="reference internal" href="#stem.ControllerError" title="stem.ControllerError"><tt class="xref py py-class docutils literal"><span class="pre">stem.ControllerError</span></tt></a> if unable to query tor and no
default was provided</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.get_conf">
<tt class="descname">get_conf</tt><big>(</big><em>param</em>, <em>default='<Undefined_ >'</em>, <em>multiple=False</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.get_conf"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.get_conf" title="Permalink to this definition">¶</a></dt>
<dd><p>Queries the current value for a configuration option. Some configuration
options (like the ExitPolicy) can have multiple values. This provides a
<strong>list</strong> with all of the values if <strong>multiple</strong> is <strong>True</strong>. Otherwise this
will be a <strong>str</strong> with the first value.</p>
<p>If provided with a <strong>default</strong> then that is provided if the configuration
option was unset or the query fails (invalid configuration option, error
response, control port closed, initiated, etc).</p>
<p>If the configuration value is unset and no <strong>default</strong> was given then this
provides <strong>None</strong> if <strong>multiple</strong> was <strong>False</strong> and an empty list if it was
<strong>True</strong>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>param</strong> (<em>str</em>) – configuration option to be queried</li>
<li><strong>default</strong> (<em>object</em>) – response if the option is unset or the query fails</li>
<li><strong>multiple</strong> (<em>bool</em>) – if <strong>True</strong> then provides a list with all of the
present values (this is an empty list if the config option is unset)</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first"><p>Response depends upon how we were called as follows...</p>
<ul class="simple">
<li><strong>str</strong> with the configuration value if <strong>multiple</strong> was <strong>False</strong>,
<strong>None</strong> if it was unset</li>
<li><strong>list</strong> with the response strings if multiple was <strong>True</strong></li>
<li>default if one was provided and the configuration option was either
unset or our call failed</li>
</ul>
</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><ul class="first last simple">
<li><a class="reference internal" href="#stem.ControllerError" title="stem.ControllerError"><tt class="xref py py-class docutils literal"><span class="pre">stem.ControllerError</span></tt></a> if the call fails and we weren’t
provided a default response</li>
<li><a class="reference internal" href="#stem.InvalidArguments" title="stem.InvalidArguments"><tt class="xref py py-class docutils literal"><span class="pre">stem.InvalidArguments</span></tt></a> if the configuration option
requested was invalid</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.get_conf_map">
<tt class="descname">get_conf_map</tt><big>(</big><em>params</em>, <em>default='<Undefined_ >'</em>, <em>multiple=True</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.get_conf_map"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.get_conf_map" title="Permalink to this definition">¶</a></dt>
<dd><p>Similar to <a class="reference internal" href="#stem.control.Controller.get_conf" title="stem.control.Controller.get_conf"><tt class="xref py py-func docutils literal"><span class="pre">get_conf()</span></tt></a> but queries multiple
configuration options, providing back a mapping of those options to their
values.</p>
<p>There are three use cases for GETCONF:</p>
<blockquote>
<div><ol class="arabic simple">
<li>a single value is provided (e.g. <strong>ControlPort</strong>)</li>
<li>multiple values are provided for the option (e.g. <strong>ExitPolicy</strong>)</li>
<li>a set of options that weren’t necessarily requested are returned (for
instance querying <strong>HiddenServiceOptions</strong> gives <strong>HiddenServiceDir</strong>,
<strong>HiddenServicePort</strong>, etc)</li>
</ol>
</div></blockquote>
<p>The vast majority of the options fall into the first two categories, in
which case calling <a class="reference internal" href="#stem.control.Controller.get_conf" title="stem.control.Controller.get_conf"><tt class="xref py py-func docutils literal"><span class="pre">get_conf()</span></tt></a> is sufficient.
However, for batch queries or the special options that give a set of values
this provides back the full response. As of tor version 0.2.1.25
<strong>HiddenServiceOptions</strong> was the only option that falls into the third
category.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>params</strong> (<em>str,list</em>) – configuration option(s) to be queried</li>
<li><strong>default</strong> (<em>object</em>) – value for the mappings if the configuration option
is either undefined or the query fails</li>
<li><strong>multiple</strong> (<em>bool</em>) – if <strong>True</strong> then the values provided are lists with
all of the present values</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first"><p><strong>dict</strong> of the ‘config key => value’ mappings. The value is a...</p>
<ul class="simple">
<li><strong>str</strong> if <strong>multiple</strong> is <strong>False</strong>, <strong>None</strong> if the configuration
option is unset</li>
<li><strong>list</strong> if <strong>multiple</strong> is <strong>True</strong></li>
<li>the <strong>default</strong> if it was set and the value was either undefined or our
lookup failed</li>
</ul>
</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><ul class="first last simple">
<li><a class="reference internal" href="#stem.ControllerError" title="stem.ControllerError"><tt class="xref py py-class docutils literal"><span class="pre">stem.ControllerError</span></tt></a> if the call fails and we weren’t provided
a default response</li>
<li><a class="reference internal" href="#stem.InvalidArguments" title="stem.InvalidArguments"><tt class="xref py py-class docutils literal"><span class="pre">stem.InvalidArguments</span></tt></a> if the configuration option requested
was invalid</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.set_conf">
<tt class="descname">set_conf</tt><big>(</big><em>param</em>, <em>value</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.set_conf"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.set_conf" title="Permalink to this definition">¶</a></dt>
<dd><p>Changes the value of a tor configuration option. Our value can be any of
the following...</p>
<ul class="simple">
<li>a string to set a single value</li>
<li>a list of strings to set a series of values (for instance the ExitPolicy)</li>
<li>None to either set the value to 0/NULL</li>
</ul>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>param</strong> (<em>str</em>) – configuration option to be set</li>
<li><strong>value</strong> (<em>str,list</em>) – value to set the parameter to</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body"><ul class="first last simple">
<li><a class="reference internal" href="#stem.ControllerError" title="stem.ControllerError"><tt class="xref py py-class docutils literal"><span class="pre">stem.ControllerError</span></tt></a> if the call fails</li>
<li><a class="reference internal" href="#stem.InvalidArguments" title="stem.InvalidArguments"><tt class="xref py py-class docutils literal"><span class="pre">stem.InvalidArguments</span></tt></a> if configuration options
requested was invalid</li>
<li><a class="reference internal" href="#stem.InvalidRequest" title="stem.InvalidRequest"><tt class="xref py py-class docutils literal"><span class="pre">stem.InvalidRequest</span></tt></a> if the configuration setting is
impossible or if there’s a syntax error in the configuration values</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.reset_conf">
<tt class="descname">reset_conf</tt><big>(</big><em>*params</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.reset_conf"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.reset_conf" title="Permalink to this definition">¶</a></dt>
<dd><p>Reverts one or more parameters to their default values.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><p class="first"><strong>params</strong> (<em>str</em>) – configuration option to be reset</p>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body"><ul class="first last simple">
<li><a class="reference internal" href="#stem.ControllerError" title="stem.ControllerError"><tt class="xref py py-class docutils literal"><span class="pre">stem.ControllerError</span></tt></a> if the call fails</li>
<li><a class="reference internal" href="#stem.InvalidArguments" title="stem.InvalidArguments"><tt class="xref py py-class docutils literal"><span class="pre">stem.InvalidArguments</span></tt></a> if configuration options requested was invalid</li>
<li><a class="reference internal" href="#stem.InvalidRequest" title="stem.InvalidRequest"><tt class="xref py py-class docutils literal"><span class="pre">stem.InvalidRequest</span></tt></a> if the configuration setting is
impossible or if there’s a syntax error in the configuration values</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.set_options">
<tt class="descname">set_options</tt><big>(</big><em>params</em>, <em>reset=False</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.set_options"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.set_options" title="Permalink to this definition">¶</a></dt>
<dd><p>Changes multiple tor configuration options via either a SETCONF or
RESETCONF query. Both behave identically unless our value is None, in which
case SETCONF sets the value to 0 or NULL, and RESETCONF returns it to its
default value. This accepts str, list, or None values in a similar fashion
to <a class="reference internal" href="#stem.control.Controller.set_conf" title="stem.control.Controller.set_conf"><tt class="xref py py-func docutils literal"><span class="pre">set_conf()</span></tt></a>. For example...</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">my_controller</span><span class="o">.</span><span class="n">set_options</span><span class="p">({</span>
<span class="s">"Nickname"</span><span class="p">:</span> <span class="s">"caerSidi"</span><span class="p">,</span>
<span class="s">"ExitPolicy"</span><span class="p">:</span> <span class="p">[</span><span class="s">"accept *:80"</span><span class="p">,</span> <span class="s">"accept *:443"</span><span class="p">,</span> <span class="s">"reject *:*"</span><span class="p">],</span>
<span class="s">"ContactInfo"</span><span class="p">:</span> <span class="s">"caerSidi-exit@someplace.com"</span><span class="p">,</span>
<span class="s">"Log"</span><span class="p">:</span> <span class="bp">None</span><span class="p">,</span>
<span class="p">})</span>
</pre></div>
</div>
<p>The params can optionally be a list of key/value tuples, though the only
reason this type of argument would be useful is for hidden service
configuration (those options are order dependent).</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>params</strong> (<em>dict,list</em>) – mapping of configuration options to the values
we’re setting it to</li>
<li><strong>reset</strong> (<em>bool</em>) – issues a RESETCONF, returning <strong>None</strong> values to their
defaults if <strong>True</strong></li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body"><ul class="first last simple">
<li><a class="reference internal" href="#stem.ControllerError" title="stem.ControllerError"><tt class="xref py py-class docutils literal"><span class="pre">stem.ControllerError</span></tt></a> if the call fails</li>
<li><a class="reference internal" href="#stem.InvalidArguments" title="stem.InvalidArguments"><tt class="xref py py-class docutils literal"><span class="pre">stem.InvalidArguments</span></tt></a> if configuration options
requested was invalid</li>
<li><a class="reference internal" href="#stem.InvalidRequest" title="stem.InvalidRequest"><tt class="xref py py-class docutils literal"><span class="pre">stem.InvalidRequest</span></tt></a> if the configuration setting is
impossible or if there’s a syntax error in the configuration values</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.add_event_listener">
<tt class="descname">add_event_listener</tt><big>(</big><em>listener</em>, <em>*events</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.add_event_listener"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.add_event_listener" title="Permalink to this definition">¶</a></dt>
<dd><p>Directs further tor controller events to a given function. The function is
expected to take a single argument, which is a
<a class="reference internal" href="response.html#stem.response.events.Event" title="stem.response.events.Event"><tt class="xref py py-class docutils literal"><span class="pre">Event</span></tt></a> subclass. For instance the following
would print the bytes sent and received by tor over five seconds...</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">time</span>
<span class="kn">from</span> <span class="nn">stem.control</span> <span class="kn">import</span> <span class="n">Controller</span><span class="p">,</span> <span class="n">EventType</span>
<span class="k">def</span> <span class="nf">print_bw</span><span class="p">(</span><span class="n">event</span><span class="p">):</span>
<span class="k">print</span> <span class="s">"sent: </span><span class="si">%i</span><span class="s">, received: </span><span class="si">%i</span><span class="s">"</span> <span class="o">%</span> <span class="p">(</span><span class="n">event</span><span class="o">.</span><span class="n">written</span><span class="p">,</span> <span class="n">event</span><span class="o">.</span><span class="n">read</span><span class="p">)</span>
<span class="k">with</span> <span class="n">Controller</span><span class="o">.</span><span class="n">from_port</span><span class="p">(</span><span class="n">port</span> <span class="o">=</span> <span class="mi">9051</span><span class="p">)</span> <span class="k">as</span> <span class="n">controller</span><span class="p">:</span>
<span class="n">controller</span><span class="o">.</span><span class="n">authenticate</span><span class="p">()</span>
<span class="n">controller</span><span class="o">.</span><span class="n">add_event_listener</span><span class="p">(</span><span class="n">print_bw</span><span class="p">,</span> <span class="n">EventType</span><span class="o">.</span><span class="n">BW</span><span class="p">)</span>
<span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>
</pre></div>
</div>
<p>If a new control connection is initialized then this listener will be
reattached.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>listener</strong> (<em>functor</em>) – function to be called when an event is received</li>
<li><strong>events</strong> (<a class="reference internal" href="#stem.control.EventType" title="stem.control.EventType"><em>stem.control.EventType</em></a>) – event types to be listened for</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body"><p class="first last"><a class="reference internal" href="#stem.ProtocolError" title="stem.ProtocolError"><tt class="xref py py-class docutils literal"><span class="pre">stem.ProtocolError</span></tt></a> if unable to set the events</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.remove_event_listener">
<tt class="descname">remove_event_listener</tt><big>(</big><em>listener</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.remove_event_listener"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.remove_event_listener" title="Permalink to this definition">¶</a></dt>
<dd><p>Stops a listener from being notified of further tor events.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>listener</strong> (<em>stem.control.EventListener</em>) – listener to be removed</td>
</tr>
<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body"><a class="reference internal" href="#stem.ProtocolError" title="stem.ProtocolError"><tt class="xref py py-class docutils literal"><span class="pre">stem.ProtocolError</span></tt></a> if unable to set the events</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.is_caching_enabled">
<tt class="descname">is_caching_enabled</tt><big>(</big><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.is_caching_enabled"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.is_caching_enabled" title="Permalink to this definition">¶</a></dt>
<dd><p><strong>True</strong> if caching has been enabled, <strong>False</strong> otherwise.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body">bool to indicate if caching is enabled</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.set_caching">
<tt class="descname">set_caching</tt><big>(</big><em>enabled</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.set_caching"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.set_caching" title="Permalink to this definition">¶</a></dt>
<dd><p>Enables or disables caching of information retrieved from tor.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>enabled</strong> (<em>bool</em>) – <strong>True</strong> to enable caching, <strong>False</strong> to disable it</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.clear_cache">
<tt class="descname">clear_cache</tt><big>(</big><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.clear_cache"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.clear_cache" title="Permalink to this definition">¶</a></dt>
<dd><p>Drops any cached results.</p>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.load_conf">
<tt class="descname">load_conf</tt><big>(</big><em>configtext</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.load_conf"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.load_conf" title="Permalink to this definition">¶</a></dt>
<dd><p>Sends the configuration text to Tor and loads it as if it has been read from
the torrc.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>configtext</strong> (<em>str</em>) – the configuration text</td>
</tr>
<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body"><a class="reference internal" href="#stem.ControllerError" title="stem.ControllerError"><tt class="xref py py-class docutils literal"><span class="pre">stem.ControllerError</span></tt></a> if the call fails</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.save_conf">
<tt class="descname">save_conf</tt><big>(</big><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.save_conf"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.save_conf" title="Permalink to this definition">¶</a></dt>
<dd><p>Saves the current configuration options into the active torrc file.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><ul class="first last simple">
<li><a class="reference internal" href="#stem.ControllerError" title="stem.ControllerError"><tt class="xref py py-class docutils literal"><span class="pre">stem.ControllerError</span></tt></a> if the call fails</li>
<li><a class="reference internal" href="#stem.OperationFailed" title="stem.OperationFailed"><tt class="xref py py-class docutils literal"><span class="pre">stem.OperationFailed</span></tt></a> if the client is unable to save
the configuration file</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.is_feature_enabled">
<tt class="descname">is_feature_enabled</tt><big>(</big><em>feature</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.is_feature_enabled"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.is_feature_enabled" title="Permalink to this definition">¶</a></dt>
<dd><p>Checks if a control connection feature is enabled. These features can be
enabled using <a class="reference internal" href="#stem.control.Controller.enable_feature" title="stem.control.Controller.enable_feature"><tt class="xref py py-func docutils literal"><span class="pre">enable_feature()</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>feature</strong> (<em>str</em>) – feature to be checked</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><strong>True</strong> if feature is enabled, <strong>False</strong> otherwise</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.enable_feature">
<tt class="descname">enable_feature</tt><big>(</big><em>features</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.enable_feature"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.enable_feature" title="Permalink to this definition">¶</a></dt>
<dd><p>Enables features that are disabled by default to maintain backward
compatibility. Once enabled, a feature cannot be disabled and a new
control connection must be opened to get a connection with the feature
disabled. Feature names are case-insensitive.</p>
<p>The following features are currently accepted:</p>
<blockquote>
<div><ul class="simple">
<li>EXTENDED_EVENTS - Requests the extended event syntax</li>
<li>VERBOSE_NAMES - Replaces ServerID with LongName in events and GETINFO results</li>
</ul>
</div></blockquote>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><p class="first"><strong>features</strong> (<em>str,list</em>) – a single feature or a list of features to be enabled</p>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body"><ul class="first last simple">
<li><a class="reference internal" href="#stem.ControllerError" title="stem.ControllerError"><tt class="xref py py-class docutils literal"><span class="pre">stem.ControllerError</span></tt></a> if the call fails</li>
<li><a class="reference internal" href="#stem.InvalidArguments" title="stem.InvalidArguments"><tt class="xref py py-class docutils literal"><span class="pre">stem.InvalidArguments</span></tt></a> if features passed were invalid</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.get_circuit">
<tt class="descname">get_circuit</tt><big>(</big><em>circuit_id</em>, <em>default='<Undefined_ >'</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.get_circuit"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.get_circuit" title="Permalink to this definition">¶</a></dt>
<dd><p>Provides a circuit presently available from tor.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>circuit_id</strong> (<em>int</em>) – circuit to be fetched</li>
<li><strong>default</strong> (<em>object</em>) – response if the query fails</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first"><a class="reference internal" href="response.html#stem.response.events.CircuitEvent" title="stem.response.events.CircuitEvent"><tt class="xref py py-class docutils literal"><span class="pre">stem.response.events.CircuitEvent</span></tt></a> for the given circuit</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><ul class="first simple">
<li><a class="reference internal" href="#stem.ControllerError" title="stem.ControllerError"><tt class="xref py py-class docutils literal"><span class="pre">stem.ControllerError</span></tt></a> if the call fails</li>
<li><strong>ValueError</strong> if the circuit doesn’t exist</li>
</ul>
<p class="last">An exception is only raised if we weren’t provided a default response.</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.get_circuits">
<tt class="descname">get_circuits</tt><big>(</big><em>default='<Undefined_ >'</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.get_circuits"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.get_circuits" title="Permalink to this definition">¶</a></dt>
<dd><p>Provides tor’s currently available circuits.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>default</strong> (<em>object</em>) – response if the query fails</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><strong>list</strong> of <a class="reference internal" href="response.html#stem.response.events.CircuitEvent" title="stem.response.events.CircuitEvent"><tt class="xref py py-class docutils literal"><span class="pre">stem.response.events.CircuitEvent</span></tt></a> for our circuits</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><a class="reference internal" href="#stem.ControllerError" title="stem.ControllerError"><tt class="xref py py-class docutils literal"><span class="pre">stem.ControllerError</span></tt></a> if the call fails and no default was provided</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.new_circuit">
<tt class="descname">new_circuit</tt><big>(</big><em>path=None</em>, <em>purpose='general'</em>, <em>await_build=False</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.new_circuit"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.new_circuit" title="Permalink to this definition">¶</a></dt>
<dd><p>Requests a new circuit. If the path isn’t provided, one is automatically
selected.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>path</strong> (<em>list,str</em>) – one or more relays to make a circuit through</li>
<li><strong>purpose</strong> (<em>str</em>) – “general” or “controller”</li>
<li><strong>await_build</strong> (<em>bool</em>) – blocks until the circuit is built if <strong>True</strong></li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">str of the circuit id of the newly created circuit</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><p class="first last"><a class="reference internal" href="#stem.ControllerError" title="stem.ControllerError"><tt class="xref py py-class docutils literal"><span class="pre">stem.ControllerError</span></tt></a> if the call fails</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.extend_circuit">
<tt class="descname">extend_circuit</tt><big>(</big><em>circuit_id='0'</em>, <em>path=None</em>, <em>purpose='general'</em>, <em>await_build=False</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.extend_circuit"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.extend_circuit" title="Permalink to this definition">¶</a></dt>
<dd><p>Either requests the creation of a new circuit or extends an existing one.</p>
<p>When called with a circuit value of zero (the default) a new circuit is
created, and when non-zero the circuit with that id is extended. If the
path isn’t provided, one is automatically selected.</p>
<p>A python interpreter session used to create circuits could look like this...</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">control</span><span class="o">.</span><span class="n">extend_circuit</span><span class="p">(</span><span class="s">'0'</span><span class="p">,</span> <span class="p">[</span><span class="s">"718BCEA286B531757ACAFF93AE04910EA73DE617"</span><span class="p">,</span> <span class="s">"30BAB8EE7606CBD12F3CC269AE976E0153E7A58D"</span><span class="p">,</span> <span class="s">"2765D8A8C4BBA3F89585A9FFE0E8575615880BEB"</span><span class="p">])</span>
<span class="go">19</span>
<span class="gp">>>> </span><span class="n">control</span><span class="o">.</span><span class="n">extend_circuit</span><span class="p">(</span><span class="s">'0'</span><span class="p">)</span>
<span class="go">20</span>
<span class="gp">>>> </span><span class="k">print</span> <span class="n">control</span><span class="o">.</span><span class="n">get_info</span><span class="p">(</span><span class="s">'circuit-status'</span><span class="p">)</span>
<span class="go">20 EXTENDED $718BCEA286B531757ACAFF93AE04910EA73DE617=KsmoinOK,$649F2D0ACF418F7CFC6539AB2257EB2D5297BAFA=Eskimo BUILD_FLAGS=NEED_CAPACITY PURPOSE=GENERAL TIME_CREATED=2012-12-06T13:51:11.433755</span>
<span class="go">19 BUILT $718BCEA286B531757ACAFF93AE04910EA73DE617=KsmoinOK,$30BAB8EE7606CBD12F3CC269AE976E0153E7A58D=Pascal1,$2765D8A8C4BBA3F89585A9FFE0E8575615880BEB=Anthracite PURPOSE=GENERAL TIME_CREATED=2012-12-06T13:50:56.969938</span>
</pre></div>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>circuit_id</strong> (<em>str</em>) – id of a circuit to be extended</li>
<li><strong>path</strong> (<em>list,str</em>) – one or more relays to make a circuit through, this is
required if the circuit id is non-zero</li>
<li><strong>purpose</strong> (<em>str</em>) – “general” or “controller”</li>
<li><strong>await_build</strong> (<em>bool</em>) – blocks until the circuit is built if <strong>True</strong></li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">str of the circuit id of the created or extended circuit</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><ul class="first last simple">
<li><a class="reference internal" href="#stem.InvalidRequest" title="stem.InvalidRequest"><tt class="xref py py-class docutils literal"><span class="pre">stem.InvalidRequest</span></tt></a> if one of the parameters were invalid</li>
<li><a class="reference internal" href="#stem.CircuitExtensionFailed" title="stem.CircuitExtensionFailed"><tt class="xref py py-class docutils literal"><span class="pre">stem.CircuitExtensionFailed</span></tt></a> if we were waiting for the circuit
to build but it failed</li>
<li><a class="reference internal" href="#stem.ControllerError" title="stem.ControllerError"><tt class="xref py py-class docutils literal"><span class="pre">stem.ControllerError</span></tt></a> if the call fails</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.repurpose_circuit">
<tt class="descname">repurpose_circuit</tt><big>(</big><em>circuit_id</em>, <em>purpose</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.repurpose_circuit"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.repurpose_circuit" title="Permalink to this definition">¶</a></dt>
<dd><dl class="docutils">
<dt>Changes a circuit’s purpose. Currently, two purposes are recognized...</dt>
<dd><ul class="first last simple">
<li>general</li>
<li>controller</li>
</ul>
</dd>
</dl>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>circuit_id</strong> (<em>str</em>) – id of the circuit whose purpose is to be changed</li>
<li><strong>purpose</strong> (<em>str</em>) – purpose (either “general” or “controller”)</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body"><p class="first last"><a class="reference internal" href="#stem.InvalidArguments" title="stem.InvalidArguments"><tt class="xref py py-class docutils literal"><span class="pre">stem.InvalidArguments</span></tt></a> if the circuit doesn’t exist or if the purpose was invalid</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.close_circuit">
<tt class="descname">close_circuit</tt><big>(</big><em>circuit_id</em>, <em>flag=''</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.close_circuit"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.close_circuit" title="Permalink to this definition">¶</a></dt>
<dd><p>Closes the specified circuit.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>circuit_id</strong> (<em>str</em>) – id of the circuit to be closed</li>
<li><strong>flag</strong> (<em>str</em>) – optional value to modify closing, the only flag available
is “IfUnused” which will not close the circuit unless it is unused</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body"><p class="first"><a class="reference internal" href="#stem.InvalidArguments" title="stem.InvalidArguments"><tt class="xref py py-class docutils literal"><span class="pre">stem.InvalidArguments</span></tt></a> if the circuit is unknown</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><p class="first last"><a class="reference internal" href="#stem.InvalidRequest" title="stem.InvalidRequest"><tt class="xref py py-class docutils literal"><span class="pre">stem.InvalidRequest</span></tt></a> if not enough information is provided</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.get_streams">
<tt class="descname">get_streams</tt><big>(</big><em>default='<Undefined_ >'</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.get_streams"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.get_streams" title="Permalink to this definition">¶</a></dt>
<dd><p>Provides the list of streams tor is currently handling.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>default</strong> (<em>object</em>) – response if the query fails</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">list of <a class="reference internal" href="response.html#stem.response.events.StreamEvent" title="stem.response.events.StreamEvent"><tt class="xref py py-class docutils literal"><span class="pre">stem.response.events.StreamEvent</span></tt></a> objects</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><a class="reference internal" href="#stem.ControllerError" title="stem.ControllerError"><tt class="xref py py-class docutils literal"><span class="pre">stem.ControllerError</span></tt></a> if the call fails and no default was
provided</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.attach_stream">
<tt class="descname">attach_stream</tt><big>(</big><em>stream_id</em>, <em>circuit_id</em>, <em>exiting_hop=None</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.attach_stream"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.attach_stream" title="Permalink to this definition">¶</a></dt>
<dd><p>Attaches a stream to a circuit.</p>
<p>Note: Tor attaches streams to circuits automatically unless the
__LeaveStreamsUnattached configuration variable is set to “1”</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>stream_id</strong> (<em>str</em>) – id of the stream that must be attached</li>
<li><strong>circuit_id</strong> (<em>str</em>) – id of the circuit to which it must be attached</li>
<li><strong>exiting_hop</strong> (<em>int</em>) – hop in the circuit where traffic should exit</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body"><ul class="first last simple">
<li><a class="reference internal" href="#stem.InvalidRequest" title="stem.InvalidRequest"><tt class="xref py py-class docutils literal"><span class="pre">stem.InvalidRequest</span></tt></a> if the stream or circuit id were unrecognized</li>
<li><a class="reference internal" href="#stem.UnsatisfiableRequest" title="stem.UnsatisfiableRequest"><tt class="xref py py-class docutils literal"><span class="pre">stem.UnsatisfiableRequest</span></tt></a> if the stream isn’t in a state where it can be attached</li>
<li><a class="reference internal" href="#stem.OperationFailed" title="stem.OperationFailed"><tt class="xref py py-class docutils literal"><span class="pre">stem.OperationFailed</span></tt></a> if the stream couldn’t be attached for any other reason</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.close_stream">
<tt class="descname">close_stream</tt><big>(</big><em>stream_id</em>, <em>reason='MISC'</em>, <em>flag=''</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.close_stream"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.close_stream" title="Permalink to this definition">¶</a></dt>
<dd><p>Closes the specified stream.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>stream_id</strong> (<em>str</em>) – id of the stream to be closed</li>
<li><strong>reason</strong> (<a class="reference internal" href="#stem.RelayEndReason" title="stem.RelayEndReason"><em>stem.RelayEndReason</em></a>) – reason the stream is closing</li>
<li><strong>flag</strong> (<em>str</em>) – not currently used</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body"><p class="first"><a class="reference internal" href="#stem.InvalidArguments" title="stem.InvalidArguments"><tt class="xref py py-class docutils literal"><span class="pre">stem.InvalidArguments</span></tt></a> if the stream or reason are not recognized</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><p class="first last"><a class="reference internal" href="#stem.InvalidRequest" title="stem.InvalidRequest"><tt class="xref py py-class docutils literal"><span class="pre">stem.InvalidRequest</span></tt></a> if the stream and/or reason are missing</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.signal">
<tt class="descname">signal</tt><big>(</big><em>signal</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.signal"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.signal" title="Permalink to this definition">¶</a></dt>
<dd><p>Sends a signal to the Tor client.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>signal</strong> (<a class="reference internal" href="#stem.Signal" title="stem.Signal"><em>stem.Signal</em></a>) – type of signal to be sent</td>
</tr>
<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body"><a class="reference internal" href="#stem.InvalidArguments" title="stem.InvalidArguments"><tt class="xref py py-class docutils literal"><span class="pre">stem.InvalidArguments</span></tt></a> if signal provided wasn’t recognized</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.is_geoip_unavailable">
<tt class="descname">is_geoip_unavailable</tt><big>(</big><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.is_geoip_unavailable"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.is_geoip_unavailable" title="Permalink to this definition">¶</a></dt>
<dd><p>Provides <strong>True</strong> if we’ve concluded hat our geoip database is unavailable,
<strong>False</strong> otherwise. This is determined by having our ‘GETINFO
ip-to-country/*’ lookups fail so this will default to <strong>False</strong> if we
aren’t making those queries.</p>
<p>Geoip failures will be untracked if caching is disabled.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body"><strong>bool</strong> to indicate if we’ve concluded our geoip database to be
unavailable or not</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.control.Controller.map_address">
<tt class="descname">map_address</tt><big>(</big><em>mapping</em><big>)</big><a class="reference internal" href="../_modules/stem/control.html#Controller.map_address"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.control.Controller.map_address" title="Permalink to this definition">¶</a></dt>
<dd><p>Map addresses to replacement addresses. Tor replaces subseqent connections
to the original addresses with the replacement addresses.</p>
<p>If the original address is a null address, i.e., one of “0.0.0.0”, ”::0”, or
”.” Tor picks an original address itself and returns it in the reply. If the
original address is already mapped to a different address the mapping is
removed.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><p class="first"><strong>mapping</strong> (<em>dict</em>) – mapping of original addresses to replacement addresses</p>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Raises :</th><td class="field-body"><ul class="first simple">
<li><a class="reference internal" href="#stem.InvalidRequest" title="stem.InvalidRequest"><tt class="xref py py-class docutils literal"><span class="pre">stem.InvalidRequest</span></tt></a> if the addresses are malformed</li>
<li><a class="reference internal" href="#stem.OperationFailed" title="stem.OperationFailed"><tt class="xref py py-class docutils literal"><span class="pre">stem.OperationFailed</span></tt></a> if Tor couldn’t fulfill the request</li>
</ul>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last"><strong>dict</strong> with ‘original -> replacement’ address mappings</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
</dd></dl>
<div class="section" id="exceptions-and-attribute-enums">
<h2>Exceptions and Attribute Enums<a class="headerlink" href="#exceptions-and-attribute-enums" title="Permalink to this headline">¶</a></h2>
<span class="target" id="module-stem"></span><p>Library for working with the tor process.</p>
<p><strong>Module Overview:</strong></p>
<div class="highlight-python"><pre>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.
| +- InvalidRequest - Invalid request.
| +- InvalidArguments - Invalid request parameters.
+- SocketError - Communication with the socket failed.
+- SocketClosed - Socket has been shut down.</pre>
</div>
<dl class="data">
<dt id="stem.Runlevel">
<tt class="descclassname">stem.</tt><tt class="descname">Runlevel</tt><big>(</big><em>enum</em><big>)</big><a class="headerlink" href="#stem.Runlevel" title="Permalink to this definition">¶</a></dt>
<dd><p>Rating of importance used for event logging.</p>
<table border="1" class="docutils">
<colgroup>
<col width="17%" />
<col width="83%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Runlevel</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><strong>ERR</strong></td>
<td>critical issues that impair tor’s ability to function</td>
</tr>
<tr class="row-odd"><td><strong>WARN</strong></td>
<td>non-critical issues the user should be aware of</td>
</tr>
<tr class="row-even"><td><strong>NOTICE</strong></td>
<td>information that may be helpful to the user</td>
</tr>
<tr class="row-odd"><td><strong>INFO</strong></td>
<td>high level runtime information</td>
</tr>
<tr class="row-even"><td><strong>DEBUG</strong></td>
<td>low level runtime information</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="data">
<dt id="stem.Signal">
<tt class="descclassname">stem.</tt><tt class="descname">Signal</tt><big>(</big><em>enum</em><big>)</big><a class="headerlink" href="#stem.Signal" title="Permalink to this definition">¶</a></dt>
<dd><p>Signals that the tor process will accept.</p>
<table border="1" class="docutils">
<colgroup>
<col width="17%" />
<col width="83%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Signal</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><strong>RELOAD</strong> or <strong>HUP</strong></td>
<td>reloads our torrc</td>
</tr>
<tr class="row-odd"><td><strong>SHUTDOWN</strong> or <strong>INT</strong></td>
<td>shut down, waiting ShutdownWaitLength first if we’re a relay</td>
</tr>
<tr class="row-even"><td><strong>DUMP</strong> or <strong>USR1</strong></td>
<td>dumps information about open connections and circuits to our log</td>
</tr>
<tr class="row-odd"><td><strong>DEBUG</strong> or <strong>USR2</strong></td>
<td>switch our logging to the DEBUG runlevel</td>
</tr>
<tr class="row-even"><td><strong>HALT</strong> or <strong>TERM</strong></td>
<td>exit tor immediately</td>
</tr>
<tr class="row-odd"><td><strong>NEWNYM</strong></td>
<td>switch to new circuits, so new application requests don’t share any circuits with old ones (this also clears our DNS cache)</td>
</tr>
<tr class="row-even"><td><strong>CLEARDNSCACHE</strong></td>
<td>clears cached DNS results</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="data">
<dt id="stem.Flag">
<tt class="descclassname">stem.</tt><tt class="descname">Flag</tt><big>(</big><em>enum</em><big>)</big><a class="headerlink" href="#stem.Flag" title="Permalink to this definition">¶</a></dt>
<dd><p>Flag assigned to tor relays by the authorities to indicate various
characteristics.</p>
<table border="1" class="docutils">
<colgroup>
<col width="10%" />
<col width="90%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Flag</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><strong>AUTHORITY</strong></td>
<td>relay is a directory authority</td>
</tr>
<tr class="row-odd"><td><strong>BADEXIT</strong></td>
<td>relay shouldn’t be used as an exit due to being either problematic or malicious (<a class="reference external" href="https://trac.torproject.org/projects/tor/wiki/doc/badRelays">wiki</a>)</td>
</tr>
<tr class="row-even"><td><strong>BADDIRECTORY</strong></td>
<td>relay shouldn’t be used for directory information</td>
</tr>
<tr class="row-odd"><td><strong>EXIT</strong></td>
<td>relay’s exit policy makes it more useful as an exit rather than middle hop</td>
</tr>
<tr class="row-even"><td><strong>FAST</strong></td>
<td>relay’s suitable for high-bandwidth circuits</td>
</tr>
<tr class="row-odd"><td><strong>GUARD</strong></td>
<td>relay’s suitable for being an entry guard (first hop)</td>
</tr>
<tr class="row-even"><td><strong>HSDIR</strong></td>
<td>relay is being used as a v2 hidden service directory</td>
</tr>
<tr class="row-odd"><td><strong>NAMED</strong></td>
<td>relay can be referred to by its nickname</td>
</tr>
<tr class="row-even"><td><strong>RUNNING</strong></td>
<td>relay is currently usable</td>
</tr>
<tr class="row-odd"><td><strong>STABLE</strong></td>
<td>relay’s suitable for long-lived circuits</td>
</tr>
<tr class="row-even"><td><strong>UNNAMED</strong></td>
<td>relay isn’t presently bound to a nickname</td>
</tr>
<tr class="row-odd"><td><strong>V2DIR</strong></td>
<td>relay supports the v2 directory protocol</td>
</tr>
<tr class="row-even"><td><strong>VALID</strong></td>
<td>relay has been validated</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="data">
<dt id="stem.CircStatus">
<tt class="descclassname">stem.</tt><tt class="descname">CircStatus</tt><big>(</big><em>enum</em><big>)</big><a class="headerlink" href="#stem.CircStatus" title="Permalink to this definition">¶</a></dt>
<dd><p>Statuses that a circuit can be in. Tor may provide statuses not in this enum.</p>
<table border="1" class="docutils">
<colgroup>
<col width="18%" />
<col width="82%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">CircStatus</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><strong>LAUNCHED</strong></td>
<td>new circuit was created</td>
</tr>
<tr class="row-odd"><td><strong>BUILT</strong></td>
<td>circuit finished being created and can accept traffic</td>
</tr>
<tr class="row-even"><td><strong>EXTENDED</strong></td>
<td>circuit has been extended by a hop</td>
</tr>
<tr class="row-odd"><td><strong>FAILED</strong></td>
<td>circuit construction failed</td>
</tr>
<tr class="row-even"><td><strong>CLOSED</strong></td>
<td>circuit has been closed</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="data">
<dt id="stem.CircBuildFlag">
<tt class="descclassname">stem.</tt><tt class="descname">CircBuildFlag</tt><big>(</big><em>enum</em><big>)</big><a class="headerlink" href="#stem.CircBuildFlag" title="Permalink to this definition">¶</a></dt>
<dd><p>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.</p>
<table border="1" class="docutils">
<colgroup>
<col width="26%" />
<col width="74%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">CircBuildFlag</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><strong>ONEHOP_TUNNEL</strong></td>
<td>single hop circuit to fetch directory information</td>
</tr>
<tr class="row-odd"><td><strong>IS_INTERNAL</strong></td>
<td>circuit that won’t be used for client traffic</td>
</tr>
<tr class="row-even"><td><strong>NEED_CAPACITY</strong></td>
<td>circuit only includes high capacity relays</td>
</tr>
<tr class="row-odd"><td><strong>NEED_UPTIME</strong></td>
<td>circuit only includes relays with a high uptime</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="data">
<dt id="stem.CircPurpose">
<tt class="descclassname">stem.</tt><tt class="descname">CircPurpose</tt><big>(</big><em>enum</em><big>)</big><a class="headerlink" href="#stem.CircPurpose" title="Permalink to this definition">¶</a></dt>
<dd><p>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.</p>
<table border="1" class="docutils">
<colgroup>
<col width="24%" />
<col width="76%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">CircPurpose</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><strong>GENERAL</strong></td>
<td>client traffic or fetching directory information</td>
</tr>
<tr class="row-odd"><td><strong>HS_CLIENT_INTRO</strong></td>
<td>client side introduction point for a hidden service circuit</td>
</tr>
<tr class="row-even"><td><strong>HS_CLIENT_REND</strong></td>
<td>client side hidden service rendezvous circuit</td>
</tr>
<tr class="row-odd"><td><strong>HS_SERVICE_INTRO</strong></td>
<td>server side introduction point for a hidden service circuit</td>
</tr>
<tr class="row-even"><td><strong>HS_SERVICE_REND</strong></td>
<td>server side hidden service rendezvous circuit</td>
</tr>
<tr class="row-odd"><td><strong>TESTING</strong></td>
<td>testing to see if we’re reachable, so we can be used as a relay</td>
</tr>
<tr class="row-even"><td><strong>CONTROLLER</strong></td>
<td>circuit that was built by a controller</td>
</tr>
<tr class="row-odd"><td><strong>MEASURE_TIMEOUT</strong></td>
<td>circuit being kept around to see how long it takes</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="data">
<dt id="stem.CircClosureReason">
<tt class="descclassname">stem.</tt><tt class="descname">CircClosureReason</tt><big>(</big><em>enum</em><big>)</big><a class="headerlink" href="#stem.CircClosureReason" title="Permalink to this definition">¶</a></dt>
<dd><p>Reason that a circuit is being closed or failed to be established. Tor may
provide reasons not in this enum.</p>
<table border="1" class="docutils">
<colgroup>
<col width="26%" />
<col width="74%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">CircClosureReason</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><strong>NONE</strong></td>
<td>no reason given</td>
</tr>
<tr class="row-odd"><td><strong>TORPROTOCOL</strong></td>
<td>violation in the tor protocol</td>
</tr>
<tr class="row-even"><td><strong>INTERNAL</strong></td>
<td>internal error</td>
</tr>
<tr class="row-odd"><td><strong>REQUESTED</strong></td>
<td>requested by the client via a TRUNCATE command</td>
</tr>
<tr class="row-even"><td><strong>HIBERNATING</strong></td>
<td>relay is presently hibernating</td>
</tr>
<tr class="row-odd"><td><strong>RESOURCELIMIT</strong></td>
<td>relay is out of memory, sockets, or circuit IDs</td>
</tr>
<tr class="row-even"><td><strong>CONNECTFAILED</strong></td>
<td>unable to contact the relay</td>
</tr>
<tr class="row-odd"><td><strong>OR_IDENTITY</strong></td>
<td>relay had the wrong OR identification</td>
</tr>
<tr class="row-even"><td><strong>OR_CONN_CLOSED</strong></td>
<td>connection failed after being established</td>
</tr>
<tr class="row-odd"><td><strong>FINISHED</strong></td>
<td>circuit has expired (see tor’s MaxCircuitDirtiness config option)</td>
</tr>
<tr class="row-even"><td><strong>TIMEOUT</strong></td>
<td>circuit construction timed out</td>
</tr>
<tr class="row-odd"><td><strong>DESTROYED</strong></td>
<td>circuit unexpectedly closed</td>
</tr>
<tr class="row-even"><td><strong>NOPATH</strong></td>
<td>not enough relays to make a circuit</td>
</tr>
<tr class="row-odd"><td><strong>NOSUCHSERVICE</strong></td>
<td>requested hidden service does not exist</td>
</tr>
<tr class="row-even"><td><strong>MEASUREMENT_EXPIRED</strong></td>
<td>same as <strong>TIMEOUT</strong> except that it was left open for measurement purposes</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="data">
<dt id="stem.CircEvent">
<tt class="descclassname">stem.</tt><tt class="descname">CircEvent</tt><big>(</big><em>enum</em><big>)</big><a class="headerlink" href="#stem.CircEvent" title="Permalink to this definition">¶</a></dt>
<dd><p>Type of change reflected in a circuit by a CIRC_MINOR event. Tor may provide
event types not in this enum.</p>
<table border="1" class="docutils">
<colgroup>
<col width="26%" />
<col width="74%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">CircEvent</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><strong>PURPOSE_CHANGED</strong></td>
<td>circuit purpose or hidden service state has changed</td>
</tr>
<tr class="row-odd"><td><strong>CANNIBALIZED</strong></td>
<td>circuit connections are being reused for a different circuit</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="data">
<dt id="stem.HiddenServiceState">
<tt class="descclassname">stem.</tt><tt class="descname">HiddenServiceState</tt><big>(</big><em>enum</em><big>)</big><a class="headerlink" href="#stem.HiddenServiceState" title="Permalink to this definition">¶</a></dt>
<dd><p>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.</p>
<p>Enumerations fall into four groups based on their prefix...</p>
<table border="1" class="docutils">
<colgroup>
<col width="18%" />
<col width="82%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Prefix</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>HSCI_*</td>
<td>client-side introduction-point</td>
</tr>
<tr class="row-odd"><td>HSCR_*</td>
<td>client-side rendezvous-point</td>
</tr>
<tr class="row-even"><td>HSSI_*</td>
<td>service-side introduction-point</td>
</tr>
<tr class="row-odd"><td>HSSR_*</td>
<td>service-side rendezvous-point</td>
</tr>
</tbody>
</table>
<table border="1" class="docutils">
<colgroup>
<col width="35%" />
<col width="65%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">HiddenServiceState</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><strong>HSCI_CONNECTING</strong></td>
<td>connecting to the introductory point</td>
</tr>
<tr class="row-odd"><td><strong>HSCI_INTRO_SENT</strong></td>
<td>sent INTRODUCE1 and awaiting a reply</td>
</tr>
<tr class="row-even"><td><strong>HSCI_DONE</strong></td>
<td>received a reply, circuit is closing</td>
</tr>
<tr class="row-odd"><td><strong>HSCR_CONNECTING</strong></td>
<td>connecting to the introductory point</td>
</tr>
<tr class="row-even"><td><strong>HSCR_ESTABLISHED_IDLE</strong></td>
<td>rendezvous-point established, awaiting an introduction</td>
</tr>
<tr class="row-odd"><td><strong>HSCR_ESTABLISHED_WAITING</strong></td>
<td>introduction received, awaiting a rend</td>
</tr>
<tr class="row-even"><td><strong>HSCR_JOINED</strong></td>
<td>connected to the hidden service</td>
</tr>
<tr class="row-odd"><td><strong>HSSI_CONNECTING</strong></td>
<td>connecting to the introductory point</td>
</tr>
<tr class="row-even"><td><strong>HSSI_ESTABLISHED</strong></td>
<td>established introductory point</td>
</tr>
<tr class="row-odd"><td><strong>HSSR_CONNECTING</strong></td>
<td>connecting to the introductory point</td>
</tr>
<tr class="row-even"><td><strong>HSSR_JOINED</strong></td>
<td>connected to the rendezvous-point</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="data">
<dt id="stem.RelayEndReason">
<tt class="descclassname">stem.</tt><tt class="descname">RelayEndReason</tt><big>(</big><em>enum</em><big>)</big><a class="headerlink" href="#stem.RelayEndReason" title="Permalink to this definition">¶</a></dt>
<dd><p>Reasons why the stream is to be closed.</p>
<table border="1" class="docutils">
<colgroup>
<col width="22%" />
<col width="78%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">RelayEndReason</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><strong>MISC</strong></td>
<td>none of the following reasons</td>
</tr>
<tr class="row-odd"><td><strong>RESOLVEFAILED</strong></td>
<td>unable to resolve the hostname</td>
</tr>
<tr class="row-even"><td><strong>CONNECTREFUSED</strong></td>
<td>remote host refused the connection</td>
</tr>
<tr class="row-odd"><td><strong>EXITPOLICY</strong></td>
<td>OR refuses to connect to the destination</td>
</tr>
<tr class="row-even"><td><strong>DESTROY</strong></td>
<td>circuit is being shut down</td>
</tr>
<tr class="row-odd"><td><strong>DONE</strong></td>
<td>connection has been closed</td>
</tr>
<tr class="row-even"><td><strong>TIMEOUT</strong></td>
<td>connection timed out</td>
</tr>
<tr class="row-odd"><td><strong>NOROUTE</strong></td>
<td>routing error while contacting the destination</td>
</tr>
<tr class="row-even"><td><strong>HIBERNATING</strong></td>
<td>relay is temporarily hibernating</td>
</tr>
<tr class="row-odd"><td><strong>INTERNAL</strong></td>
<td>internal error at the relay</td>
</tr>
<tr class="row-even"><td><strong>RESOURCELIMIT</strong></td>
<td>relay has insufficient resources to service the request</td>
</tr>
<tr class="row-odd"><td><strong>CONNRESET</strong></td>
<td>connection was unexpectedly reset</td>
</tr>
<tr class="row-even"><td><strong>TORPROTOCOL</strong></td>
<td>violation in the tor protocol</td>
</tr>
<tr class="row-odd"><td><strong>NOTDIRECTORY</strong></td>
<td>directory information requested from a relay that isn’t mirroring it</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="data">
<dt id="stem.StreamStatus">
<tt class="descclassname">stem.</tt><tt class="descname">StreamStatus</tt><big>(</big><em>enum</em><big>)</big><a class="headerlink" href="#stem.StreamStatus" title="Permalink to this definition">¶</a></dt>
<dd><p>State that a stream going through tor can have. Tor may provide states not in
this enum.</p>
<table border="1" class="docutils">
<colgroup>
<col width="27%" />
<col width="73%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">StreamStatus</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><strong>NEW</strong></td>
<td>request for a new connection</td>
</tr>
<tr class="row-odd"><td><strong>NEWRESOLVE</strong></td>
<td>request to resolve an address</td>
</tr>
<tr class="row-even"><td><strong>REMAP</strong></td>
<td>address is being re-mapped to another</td>
</tr>
<tr class="row-odd"><td><strong>SENTCONNECT</strong></td>
<td>sent a connect cell along a circuit</td>
</tr>
<tr class="row-even"><td><strong>SENTRESOLVE</strong></td>
<td>sent a resolve cell along a circuit</td>
</tr>
<tr class="row-odd"><td><strong>SUCCEEDED</strong></td>
<td>stream has been established</td>
</tr>
<tr class="row-even"><td><strong>FAILED</strong></td>
<td>stream is detached, and won’t be re-established</td>
</tr>
<tr class="row-odd"><td><strong>DETACHED</strong></td>
<td>stream is detached, but might be re-established</td>
</tr>
<tr class="row-even"><td><strong>CLOSED</strong></td>
<td>stream has closed</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="data">
<dt id="stem.StreamClosureReason">
<tt class="descclassname">stem.</tt><tt class="descname">StreamClosureReason</tt><big>(</big><em>enum</em><big>)</big><a class="headerlink" href="#stem.StreamClosureReason" title="Permalink to this definition">¶</a></dt>
<dd><p>Reason that a stream is being closed or failed to be established. This
includes all values in the <a class="reference internal" href="#stem.RelayEndReason" title="stem.RelayEndReason"><tt class="xref py py-data docutils literal"><span class="pre">RelayEndReason</span></tt></a> enumeration as
well as the following. Tor may provide reasons not in this enum.</p>
<table border="1" class="docutils">
<colgroup>
<col width="27%" />
<col width="73%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">StreamClosureReason</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><strong>END</strong></td>
<td>endpoint has sent a RELAY_END cell</td>
</tr>
<tr class="row-odd"><td><strong>PRIVATE_ADDR</strong></td>
<td>endpoint was a private address (127.0.0.1, 10.0.0.1, etc)</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="data">
<dt id="stem.StreamSource">
<tt class="descclassname">stem.</tt><tt class="descname">StreamSource</tt><big>(</big><em>enum</em><big>)</big><a class="headerlink" href="#stem.StreamSource" title="Permalink to this definition">¶</a></dt>
<dd><p>Cause of a stream being remapped to another address. Tor may provide sources
not in this enum.</p>
<table border="1" class="docutils">
<colgroup>
<col width="23%" />
<col width="77%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">StreamSource</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><strong>CACHE</strong></td>
<td>tor is remapping because of a cached answer</td>
</tr>
<tr class="row-odd"><td><strong>EXIT</strong></td>
<td>exit relay requested the remap</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="data">
<dt id="stem.StreamPurpose">
<tt class="descclassname">stem.</tt><tt class="descname">StreamPurpose</tt><big>(</big><em>enum</em><big>)</big><a class="headerlink" href="#stem.StreamPurpose" title="Permalink to this definition">¶</a></dt>
<dd><p>Purpsoe of the stream. This is only provided with new streams and tor may
provide purposes not in this enum.</p>
<table border="1" class="docutils">
<colgroup>
<col width="21%" />
<col width="79%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">StreamPurpose</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><strong>DIR_FETCH</strong></td>
<td>fetching directory information (descriptors, consensus, etc)</td>
</tr>
<tr class="row-odd"><td><strong>DIR_UPLOAD</strong></td>
<td>uploading our descriptor to an authority</td>
</tr>
<tr class="row-even"><td><strong>DNS_REQUEST</strong></td>
<td>user initiated DNS request</td>
</tr>
<tr class="row-odd"><td><strong>DIRPORT_TEST</strong></td>
<td>checking that our directory port is reachable externally</td>
</tr>
<tr class="row-even"><td><strong>USER</strong></td>
<td>either relaying user traffic or not one of the above categories</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="data">
<dt id="stem.ORStatus">
<tt class="descclassname">stem.</tt><tt class="descname">ORStatus</tt><big>(</big><em>enum</em><big>)</big><a class="headerlink" href="#stem.ORStatus" title="Permalink to this definition">¶</a></dt>
<dd><p>State that an OR connection can have. Tor may provide states not in this
enum.</p>
<table border="1" class="docutils">
<colgroup>
<col width="19%" />
<col width="81%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">ORStatus</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><strong>NEW</strong></td>
<td>received OR connection, starting server-side handshake</td>
</tr>
<tr class="row-odd"><td><strong>LAUNCHED</strong></td>
<td>launched outbound OR connection, starting client-side handshake</td>
</tr>
<tr class="row-even"><td><strong>CONNECTED</strong></td>
<td>OR connection has been established</td>
</tr>
<tr class="row-odd"><td><strong>FAILED</strong></td>
<td>attempt to establish OR connection failed</td>
</tr>
<tr class="row-even"><td><strong>CLOSED</strong></td>
<td>OR connection has been closed</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="data">
<dt id="stem.ORClosureReason">
<tt class="descclassname">stem.</tt><tt class="descname">ORClosureReason</tt><big>(</big><em>enum</em><big>)</big><a class="headerlink" href="#stem.ORClosureReason" title="Permalink to this definition">¶</a></dt>
<dd><p>Reason that an OR connection is being closed or failed to be established. Tor
may provide reasons not in this enum.</p>
<table border="1" class="docutils">
<colgroup>
<col width="19%" />
<col width="81%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">ORClosureReason</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><strong>DONE</strong></td>
<td>OR connection shut down cleanly</td>
</tr>
<tr class="row-odd"><td><strong>CONNECTREFUSED</strong></td>
<td>got a ECONNREFUSED when connecting to the relay</td>
</tr>
<tr class="row-even"><td><strong>IDENTITY</strong></td>
<td>identity of the relay wasn’t what we expected</td>
</tr>
<tr class="row-odd"><td><strong>CONNECTRESET</strong></td>
<td>got a ECONNRESET or similar error from relay</td>
</tr>
<tr class="row-even"><td><strong>TIMEOUT</strong></td>
<td>got a ETIMEOUT or similar error from relay</td>
</tr>
<tr class="row-odd"><td><strong>NOROUTE</strong></td>
<td>got a ENOTCONN, ENETUNREACH, ENETDOWN, EHOSTUNREACH, or similar error from relay</td>
</tr>
<tr class="row-even"><td><strong>IOERROR</strong></td>
<td>got a different kind of error from relay</td>
</tr>
<tr class="row-odd"><td><strong>RESOURCELIMIT</strong></td>
<td>relay has insufficient resources to service the request</td>
</tr>
<tr class="row-even"><td><strong>MISC</strong></td>
<td>connection refused for another reason</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="data">
<dt id="stem.AuthDescriptorAction">
<tt class="descclassname">stem.</tt><tt class="descname">AuthDescriptorAction</tt><big>(</big><em>enum</em><big>)</big><a class="headerlink" href="#stem.AuthDescriptorAction" title="Permalink to this definition">¶</a></dt>
<dd><p>Actions that directory authorities might take with relay descriptors. Tor may
provide reasons not in this enum.</p>
<table border="1" class="docutils">
<colgroup>
<col width="29%" />
<col width="71%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">AuthDescriptorAction</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><strong>ACCEPTED</strong></td>
<td>accepting the descriptor as the newest version</td>
</tr>
<tr class="row-odd"><td><strong>DROPPED</strong></td>
<td>descriptor rejected without notifying the relay</td>
</tr>
<tr class="row-even"><td><strong>REJECTED</strong></td>
<td>relay notified that its descriptor has been rejected</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="data">
<dt id="stem.StatusType">
<tt class="descclassname">stem.</tt><tt class="descname">StatusType</tt><big>(</big><em>enum</em><big>)</big><a class="headerlink" href="#stem.StatusType" title="Permalink to this definition">¶</a></dt>
<dd><p>Sources for tor status events. Tor may provide types not in this enum.</p>
<table border="1" class="docutils">
<colgroup>
<col width="18%" />
<col width="82%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">StatusType</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><strong>GENERAL</strong></td>
<td>general tor activity, not specifically as a client or relay</td>
</tr>
<tr class="row-odd"><td><strong>CLIENT</strong></td>
<td>related to our activity as a tor client</td>
</tr>
<tr class="row-even"><td><strong>SERVER</strong></td>
<td>related to our activity as a tor relay</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="data">
<dt id="stem.GuardType">
<tt class="descclassname">stem.</tt><tt class="descname">GuardType</tt><big>(</big><em>enum</em><big>)</big><a class="headerlink" href="#stem.GuardType" title="Permalink to this definition">¶</a></dt>
<dd><p>Use a guard relay can be for. Tor may provide types not in this enum.</p>
<table border="1" class="docutils">
<colgroup>
<col width="24%" />
<col width="76%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">GuardType</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><strong>ENTRY</strong></td>
<td>used to connect to the tor network</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="data">
<dt id="stem.GuardStatus">
<tt class="descclassname">stem.</tt><tt class="descname">GuardStatus</tt><big>(</big><em>enum</em><big>)</big><a class="headerlink" href="#stem.GuardStatus" title="Permalink to this definition">¶</a></dt>
<dd><p>Status a guard relay can have. Tor may provide types not in this enum.</p>
<table border="1" class="docutils">
<colgroup>
<col width="17%" />
<col width="83%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">GuardStatus</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><strong>NEW</strong></td>
<td>new guard that we weren’t previously using</td>
</tr>
<tr class="row-odd"><td><strong>DROPPED</strong></td>
<td>removed from use as one of our guards</td>
</tr>
<tr class="row-even"><td><strong>UP</strong></td>
<td>guard is now reachable</td>
</tr>
<tr class="row-odd"><td><strong>DOWN</strong></td>
<td>guard is now unreachable</td>
</tr>
<tr class="row-even"><td><strong>BAD</strong></td>
<td>consensus or relay considers this relay to be unusable as a guard</td>
</tr>
<tr class="row-odd"><td><strong>GOOD</strong></td>
<td>consensus or relay considers this relay to be usable as a guard</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="data">
<dt id="stem.TimeoutSetType">
<tt class="descclassname">stem.</tt><tt class="descname">TimeoutSetType</tt><big>(</big><em>enum</em><big>)</big><a class="headerlink" href="#stem.TimeoutSetType" title="Permalink to this definition">¶</a></dt>
<dd><p>Way in which the timeout value of a circuit is changing. Tor may provide
types not in this enum.</p>
<table border="1" class="docutils">
<colgroup>
<col width="17%" />
<col width="83%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">TimeoutSetType</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><strong>COMPUTED</strong></td>
<td>tor has computed a new timeout based on prior circuits</td>
</tr>
<tr class="row-odd"><td><strong>RESET</strong></td>
<td>timeout reverted to its default</td>
</tr>
<tr class="row-even"><td><strong>SUSPENDED</strong></td>
<td>timeout reverted to its default until network connectivity has recovered</td>
</tr>
<tr class="row-odd"><td><strong>DISCARD</strong></td>
<td>throwing out timeout value from when the network was down</td>
</tr>
<tr class="row-even"><td><strong>RESUME</strong></td>
<td>resumed calculations to determine the proper timeout</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="exception">
<dt id="stem.ControllerError">
<em class="property">exception </em><tt class="descclassname">stem.</tt><tt class="descname">ControllerError</tt><a class="reference internal" href="../_modules/stem.html#ControllerError"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.ControllerError" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref py py-class docutils literal"><span class="pre">exceptions.Exception</span></tt></p>
<p>Base error for controller communication issues.</p>
</dd></dl>
<dl class="exception">
<dt id="stem.ProtocolError">
<em class="property">exception </em><tt class="descclassname">stem.</tt><tt class="descname">ProtocolError</tt><a class="reference internal" href="../_modules/stem.html#ProtocolError"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.ProtocolError" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#stem.ControllerError" title="stem.ControllerError"><tt class="xref py py-class docutils literal"><span class="pre">stem.ControllerError</span></tt></a></p>
<p>Malformed content from the control socket.</p>
</dd></dl>
<dl class="exception">
<dt id="stem.OperationFailed">
<em class="property">exception </em><tt class="descclassname">stem.</tt><tt class="descname">OperationFailed</tt><big>(</big><em>code=None</em>, <em>message=None</em><big>)</big><a class="reference internal" href="../_modules/stem.html#OperationFailed"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.OperationFailed" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#stem.ControllerError" title="stem.ControllerError"><tt class="xref py py-class docutils literal"><span class="pre">stem.ControllerError</span></tt></a></p>
<p>Base exception class for failed operations that return an error code</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Variables:</th><td class="field-body"><ul class="first last simple">
<li><strong>code</strong> (<em>str</em>) – error code returned by Tor</li>
<li><strong>message</strong> (<em>str</em>) – error message returned by Tor or a human readable error
message</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="exception">
<dt id="stem.UnsatisfiableRequest">
<em class="property">exception </em><tt class="descclassname">stem.</tt><tt class="descname">UnsatisfiableRequest</tt><big>(</big><em>code=None</em>, <em>message=None</em><big>)</big><a class="reference internal" href="../_modules/stem.html#UnsatisfiableRequest"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.UnsatisfiableRequest" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#stem.OperationFailed" title="stem.OperationFailed"><tt class="xref py py-class docutils literal"><span class="pre">stem.OperationFailed</span></tt></a></p>
<p>Exception raised if Tor was unable to process our request.</p>
</dd></dl>
<dl class="exception">
<dt id="stem.CircuitExtensionFailed">
<em class="property">exception </em><tt class="descclassname">stem.</tt><tt class="descname">CircuitExtensionFailed</tt><big>(</big><em>message</em>, <em>circ=None</em><big>)</big><a class="reference internal" href="../_modules/stem.html#CircuitExtensionFailed"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.CircuitExtensionFailed" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#stem.UnsatisfiableRequest" title="stem.UnsatisfiableRequest"><tt class="xref py py-class docutils literal"><span class="pre">stem.UnsatisfiableRequest</span></tt></a></p>
<p>An attempt to create or extend a circuit failed.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Variables:</th><td class="field-body"><strong>circ</strong> (<em>stem.response.CircuitEvent</em>) – response notifying us of the failure</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="exception">
<dt id="stem.InvalidRequest">
<em class="property">exception </em><tt class="descclassname">stem.</tt><tt class="descname">InvalidRequest</tt><big>(</big><em>code=None</em>, <em>message=None</em><big>)</big><a class="reference internal" href="../_modules/stem.html#InvalidRequest"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.InvalidRequest" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#stem.OperationFailed" title="stem.OperationFailed"><tt class="xref py py-class docutils literal"><span class="pre">stem.OperationFailed</span></tt></a></p>
<p>Exception raised when the request was invalid or malformed.</p>
</dd></dl>
<dl class="exception">
<dt id="stem.InvalidArguments">
<em class="property">exception </em><tt class="descclassname">stem.</tt><tt class="descname">InvalidArguments</tt><big>(</big><em>code=None</em>, <em>message=None</em>, <em>arguments=None</em><big>)</big><a class="reference internal" href="../_modules/stem.html#InvalidArguments"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.InvalidArguments" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#stem.InvalidRequest" title="stem.InvalidRequest"><tt class="xref py py-class docutils literal"><span class="pre">stem.InvalidRequest</span></tt></a></p>
<p>Exception class for requests which had invalid arguments.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Variables:</th><td class="field-body"><ul class="first last simple">
<li><strong>code</strong> (<em>str</em>) – error code returned by Tor</li>
<li><strong>message</strong> (<em>str</em>) – error message returned by Tor or a human readable error
message</li>
<li><strong>arguments</strong> (<em>list</em>) – a list of arguments which were invalid</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="exception">
<dt id="stem.SocketError">
<em class="property">exception </em><tt class="descclassname">stem.</tt><tt class="descname">SocketError</tt><a class="reference internal" href="../_modules/stem.html#SocketError"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.SocketError" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#stem.ControllerError" title="stem.ControllerError"><tt class="xref py py-class docutils literal"><span class="pre">stem.ControllerError</span></tt></a></p>
<p>Error arose while communicating with the control socket.</p>
</dd></dl>
<dl class="exception">
<dt id="stem.SocketClosed">
<em class="property">exception </em><tt class="descclassname">stem.</tt><tt class="descname">SocketClosed</tt><a class="reference internal" href="../_modules/stem.html#SocketClosed"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.SocketClosed" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="#stem.SocketError" title="stem.SocketError"><tt class="xref py py-class docutils literal"><span class="pre">stem.SocketError</span></tt></a></p>
<p>Control socket was closed before completing the message.</p>
</dd></dl>
</div>
</div>
</div>
<div class="bottomnav">
</div>
<div class="footer">
</div>
</body>
</html>
