<!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>Descriptor — 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="Server Descriptor" href="server_descriptor.html" />
<link rel="prev" title="Version" href="../version.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>Descriptor</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="../control.html">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="descriptor">
<h1>Descriptor<a class="headerlink" href="#descriptor" title="Permalink to this headline">¶</a></h1>
<span class="target" id="module-stem.descriptor.__init__"></span><p>Package for parsing and processing descriptor data.</p>
<p><strong>Module Overview:</strong></p>
<div class="highlight-python"><pre>parse_file - Parses the descriptors in a file.
Descriptor - Common parent for all descriptor file types.
|- get_path - location of the descriptor on disk if it came from a file
|- get_archive_path - location of the descriptor within the archive it came from
|- get_bytes - similar to str(), but provides our original bytes content
|- get_unrecognized_lines - unparsed descriptor content
+- __str__ - string that the descriptor was made from</pre>
</div>
<dl class="data">
<dt id="stem.descriptor.__init__.DocumentHandler">
<tt class="descclassname">stem.descriptor.__init__.</tt><tt class="descname">DocumentHandler</tt><big>(</big><em>enum</em><big>)</big><a class="headerlink" href="#stem.descriptor.__init__.DocumentHandler" title="Permalink to this definition">¶</a></dt>
<dd><p>Ways in which we can parse a
<a class="reference internal" href="networkstatus.html#stem.descriptor.networkstatus.NetworkStatusDocument" title="stem.descriptor.networkstatus.NetworkStatusDocument"><tt class="xref py py-class docutils literal"><span class="pre">NetworkStatusDocument</span></tt></a>.</p>
<p>Both <strong>ENTRIES</strong> and <strong>BARE_DOCUMENT</strong> have a ‘thin’ document, which doesn’t
have a populated <strong>routers</strong> attribute. This allows for lower memory usage
and upfront runtime. However, if read time and memory aren’t a concern then
<strong>DOCUMENT</strong> can provide you with a fully populated document.</p>
<table border="1" class="docutils">
<colgroup>
<col width="9%" />
<col width="91%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">DocumentHandler</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><strong>ENTRIES</strong></td>
<td>Iterates over the contained <a class="reference internal" href="router_status_entry.html#stem.descriptor.router_status_entry.RouterStatusEntry" title="stem.descriptor.router_status_entry.RouterStatusEntry"><tt class="xref py py-class docutils literal"><span class="pre">RouterStatusEntry</span></tt></a>. Each has a reference to the bare document it came from (through its <strong>document</strong> attribute).</td>
</tr>
<tr class="row-odd"><td><strong>DOCUMENT</strong></td>
<td><a class="reference internal" href="networkstatus.html#stem.descriptor.networkstatus.NetworkStatusDocument" title="stem.descriptor.networkstatus.NetworkStatusDocument"><tt class="xref py py-class docutils literal"><span class="pre">NetworkStatusDocument</span></tt></a> with the <a class="reference internal" href="router_status_entry.html#stem.descriptor.router_status_entry.RouterStatusEntry" title="stem.descriptor.router_status_entry.RouterStatusEntry"><tt class="xref py py-class docutils literal"><span class="pre">RouterStatusEntry</span></tt></a> it contains (through its <strong>routers</strong> attribute).</td>
</tr>
<tr class="row-even"><td><strong>BARE_DOCUMENT</strong></td>
<td><a class="reference internal" href="networkstatus.html#stem.descriptor.networkstatus.NetworkStatusDocument" title="stem.descriptor.networkstatus.NetworkStatusDocument"><tt class="xref py py-class docutils literal"><span class="pre">NetworkStatusDocument</span></tt></a> <strong>without</strong> a reference to its contents (the <a class="reference internal" href="router_status_entry.html#stem.descriptor.router_status_entry.RouterStatusEntry" title="stem.descriptor.router_status_entry.RouterStatusEntry"><tt class="xref py py-class docutils literal"><span class="pre">RouterStatusEntry</span></tt></a> are unread).</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="function">
<dt id="stem.descriptor.__init__.parse_file">
<tt class="descclassname">stem.descriptor.__init__.</tt><tt class="descname">parse_file</tt><big>(</big><em>descriptor_file</em>, <em>descriptor_type=None</em>, <em>validate=True</em>, <em>document_handler='ENTRIES'</em>, <em>**kwargs</em><big>)</big><a class="reference internal" href="../../_modules/stem/descriptor/__init__.html#parse_file"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.descriptor.__init__.parse_file" title="Permalink to this definition">¶</a></dt>
<dd><p>Simple function to read the descriptor contents from a file, providing an
iterator for its <a class="reference internal" href="#stem.descriptor.__init__.Descriptor" title="stem.descriptor.__init__.Descriptor"><tt class="xref py py-class docutils literal"><span class="pre">Descriptor</span></tt></a> contents.</p>
<p>If you don’t provide a <strong>descriptor_type</strong> argument then this automatically
tries to determine the descriptor type based on the following...</p>
<ul class="simple">
<li>The @type annotation on the first line. These are generally only found in
the <a class="reference external" href="https://metrics.torproject.org">descriptor archives</a>.</li>
<li>The filename if it matches something from tor’s data directory. For
instance, tor’s ‘cached-descriptors’ contains server descriptors.</li>
</ul>
<p>This is a handy function for simple usage, but if you’re reading multiple
descriptor files you might want to consider the
<a class="reference internal" href="reader.html#stem.descriptor.reader.DescriptorReader" title="stem.descriptor.reader.DescriptorReader"><tt class="xref py py-class docutils literal"><span class="pre">DescriptorReader</span></tt></a>.</p>
<p>Descriptor types include the following, including further minor versions (ie.
if we support 1.1 then we also support everything from 1.0 and most things
from 1.2, but not 2.0)...</p>
<table border="1" class="docutils">
<colgroup>
<col width="22%" />
<col width="78%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Descriptor Type</th>
<th class="head">Class</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>server-descriptor 1.0</td>
<td><a class="reference internal" href="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></td>
</tr>
<tr class="row-odd"><td>extra-info 1.0</td>
<td><a class="reference internal" href="extrainfo_descriptor.html#stem.descriptor.extrainfo_descriptor.RelayExtraInfoDescriptor" title="stem.descriptor.extrainfo_descriptor.RelayExtraInfoDescriptor"><tt class="xref py py-class docutils literal"><span class="pre">RelayExtraInfoDescriptor</span></tt></a></td>
</tr>
<tr class="row-even"><td>microdescriptor 1.0</td>
<td><a class="reference internal" href="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></td>
</tr>
<tr class="row-odd"><td>directory 1.0</td>
<td><strong>unsupported</strong></td>
</tr>
<tr class="row-even"><td>network-status-2 1.0</td>
<td><a class="reference internal" href="router_status_entry.html#stem.descriptor.router_status_entry.RouterStatusEntryV2" title="stem.descriptor.router_status_entry.RouterStatusEntryV2"><tt class="xref py py-class docutils literal"><span class="pre">RouterStatusEntryV2</span></tt></a> (with a <a class="reference internal" href="networkstatus.html#stem.descriptor.networkstatus.NetworkStatusDocumentV2" title="stem.descriptor.networkstatus.NetworkStatusDocumentV2"><tt class="xref py py-class docutils literal"><span class="pre">NetworkStatusDocumentV2</span></tt></a>)</td>
</tr>
<tr class="row-odd"><td>dir-key-certificate-3 1.0</td>
<td><a class="reference internal" href="networkstatus.html#stem.descriptor.networkstatus.KeyCertificate" title="stem.descriptor.networkstatus.KeyCertificate"><tt class="xref py py-class docutils literal"><span class="pre">KeyCertificate</span></tt></a></td>
</tr>
<tr class="row-even"><td>network-status-consensus-3 1.0</td>
<td><a class="reference internal" href="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> (with a <a class="reference internal" href="networkstatus.html#stem.descriptor.networkstatus.NetworkStatusDocumentV3" title="stem.descriptor.networkstatus.NetworkStatusDocumentV3"><tt class="xref py py-class docutils literal"><span class="pre">NetworkStatusDocumentV3</span></tt></a>)</td>
</tr>
<tr class="row-odd"><td>network-status-vote-3 1.0</td>
<td><a class="reference internal" href="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> (with a <a class="reference internal" href="networkstatus.html#stem.descriptor.networkstatus.NetworkStatusDocumentV3" title="stem.descriptor.networkstatus.NetworkStatusDocumentV3"><tt class="xref py py-class docutils literal"><span class="pre">NetworkStatusDocumentV3</span></tt></a>)</td>
</tr>
<tr class="row-even"><td>network-status-microdesc-consensus-3 1.0</td>
<td><a class="reference internal" href="router_status_entry.html#stem.descriptor.router_status_entry.RouterStatusEntryMicroV3" title="stem.descriptor.router_status_entry.RouterStatusEntryMicroV3"><tt class="xref py py-class docutils literal"><span class="pre">RouterStatusEntryMicroV3</span></tt></a> (with a <a class="reference internal" href="networkstatus.html#stem.descriptor.networkstatus.NetworkStatusDocumentV3" title="stem.descriptor.networkstatus.NetworkStatusDocumentV3"><tt class="xref py py-class docutils literal"><span class="pre">NetworkStatusDocumentV3</span></tt></a>)</td>
</tr>
<tr class="row-odd"><td>bridge-network-status 1.0</td>
<td><a class="reference internal" href="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> (with a <a class="reference internal" href="networkstatus.html#stem.descriptor.networkstatus.BridgeNetworkStatusDocument" title="stem.descriptor.networkstatus.BridgeNetworkStatusDocument"><tt class="xref py py-class docutils literal"><span class="pre">BridgeNetworkStatusDocument</span></tt></a>)</td>
</tr>
<tr class="row-even"><td>bridge-server-descriptor 1.0</td>
<td><a class="reference internal" href="server_descriptor.html#stem.descriptor.server_descriptor.BridgeDescriptor" title="stem.descriptor.server_descriptor.BridgeDescriptor"><tt class="xref py py-class docutils literal"><span class="pre">BridgeDescriptor</span></tt></a></td>
</tr>
<tr class="row-odd"><td>bridge-extra-info 1.1</td>
<td><a class="reference internal" href="extrainfo_descriptor.html#stem.descriptor.extrainfo_descriptor.BridgeExtraInfoDescriptor" title="stem.descriptor.extrainfo_descriptor.BridgeExtraInfoDescriptor"><tt class="xref py py-class docutils literal"><span class="pre">BridgeExtraInfoDescriptor</span></tt></a></td>
</tr>
<tr class="row-even"><td>torperf 1.0</td>
<td><strong>unsupported</strong></td>
</tr>
<tr class="row-odd"><td>bridge-pool-assignment 1.0</td>
<td><strong>unsupported</strong></td>
</tr>
<tr class="row-even"><td>tordnsel 1.0</td>
<td><a class="reference internal" href="tordnsel.html#stem.descriptor.tordnsel.TorDNSEL" title="stem.descriptor.tordnsel.TorDNSEL"><tt class="xref py py-class docutils literal"><span class="pre">TorDNSEL</span></tt></a></td>
</tr>
</tbody>
</table>
<p>If you’re using <strong>python 3</strong> then beware that the open() function defaults to
using text mode. <strong>Binary mode</strong> is strongly suggested because it’s both
faster (by my testing by about 33x) and doesn’t do universal newline
translation which can make us misparse the document.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">my_descriptor_file</span> <span class="o">=</span> <span class="nb">open</span><span class="p">(</span><span class="n">descriptor_path</span><span class="p">,</span> <span class="s">'rb'</span><span class="p">)</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>descriptor_file</strong> (<em>str,file</em>) – path or opened file with the descriptor contents</li>
<li><strong>descriptor_type</strong> (<em>str</em>) – <a class="reference external" href="https://metrics.torproject.org/formats.html#descriptortypes">descriptor type</a>, this is guessed if not provided</li>
<li><strong>validate</strong> (<em>bool</em>) – checks the validity of the descriptor’s content if
<strong>True</strong>, skips these checks otherwise</li>
<li><strong>document_handler</strong> (<a class="reference internal" href="#stem.descriptor.__init__.DocumentHandler" title="stem.descriptor.__init__.DocumentHandler"><em>stem.descriptor.__init__.DocumentHandler</em></a>) – method in
which to parse the <a class="reference internal" href="networkstatus.html#stem.descriptor.networkstatus.NetworkStatusDocument" title="stem.descriptor.networkstatus.NetworkStatusDocument"><tt class="xref py py-class docutils literal"><span class="pre">NetworkStatusDocument</span></tt></a></li>
<li><strong>kwargs</strong> (<em>dict</em>) – additional arguments for the descriptor constructor</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">iterator for <a class="reference internal" href="#stem.descriptor.__init__.Descriptor" title="stem.descriptor.__init__.Descriptor"><tt class="xref py py-class docutils literal"><span class="pre">Descriptor</span></tt></a> instances in the file</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises :</th><td class="field-body"><ul class="first last simple">
<li><strong>ValueError</strong> if the contents is malformed and validate is True</li>
<li><strong>TypeError</strong> if we can’t match the contents of the file to a descriptor type</li>
<li><strong>IOError</strong> if unable to read from the descriptor_file</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="class">
<dt id="stem.descriptor.__init__.Descriptor">
<em class="property">class </em><tt class="descclassname">stem.descriptor.__init__.</tt><tt class="descname">Descriptor</tt><big>(</big><em>contents</em><big>)</big><a class="reference internal" href="../../_modules/stem/descriptor/__init__.html#Descriptor"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.descriptor.__init__.Descriptor" 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>Common parent for all types of descriptors.</p>
<dl class="method">
<dt id="stem.descriptor.__init__.Descriptor.get_path">
<tt class="descname">get_path</tt><big>(</big><big>)</big><a class="reference internal" href="../../_modules/stem/descriptor/__init__.html#Descriptor.get_path"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.descriptor.__init__.Descriptor.get_path" title="Permalink to this definition">¶</a></dt>
<dd><p>Provides the absolute path that we loaded this descriptor from.</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>str</strong> with the absolute path of the descriptor source</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.descriptor.__init__.Descriptor.get_archive_path">
<tt class="descname">get_archive_path</tt><big>(</big><big>)</big><a class="reference internal" href="../../_modules/stem/descriptor/__init__.html#Descriptor.get_archive_path"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.descriptor.__init__.Descriptor.get_archive_path" title="Permalink to this definition">¶</a></dt>
<dd><p>If this descriptor came from an archive then provides its path within the
archive. This is only set if the descriptor came from a
<a class="reference internal" href="reader.html#stem.descriptor.reader.DescriptorReader" title="stem.descriptor.reader.DescriptorReader"><tt class="xref py py-class docutils literal"><span class="pre">DescriptorReader</span></tt></a>, and is <strong>None</strong> if this
descriptor didn’t come from an archive.</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>str</strong> with the descriptor’s path within the archive</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.descriptor.__init__.Descriptor.get_bytes">
<tt class="descname">get_bytes</tt><big>(</big><big>)</big><a class="reference internal" href="../../_modules/stem/descriptor/__init__.html#Descriptor.get_bytes"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.descriptor.__init__.Descriptor.get_bytes" title="Permalink to this definition">¶</a></dt>
<dd><p>Provides the ASCII <strong>bytes</strong> of the descriptor. This only differs from
<strong>str()</strong> if you’re running python 3.x, in which case <strong>str()</strong> provides a
<strong>unicode</strong> string.</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>bytes</strong> for the descriptor’s contents</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="stem.descriptor.__init__.Descriptor.get_unrecognized_lines">
<tt class="descname">get_unrecognized_lines</tt><big>(</big><big>)</big><a class="reference internal" href="../../_modules/stem/descriptor/__init__.html#Descriptor.get_unrecognized_lines"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#stem.descriptor.__init__.Descriptor.get_unrecognized_lines" title="Permalink to this definition">¶</a></dt>
<dd><p>Provides a list of lines that were either ignored or had data that we did
not know how to process. This is most common due to new descriptor fields
that this library does not yet know how to process. Patches welcome!</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>list</strong> of lines of unrecognized content</td>
</tr>
</tbody>
</table>
</dd></dl>
</dd></dl>
</div>
</div>
<div class="bottomnav">
</div>
<div class="footer">
</div>
</body>
</html>
