dh1tw/pyhamtools
1
0
Fork 0
mirror of https://github.com/dh1tw/pyhamtools.git synced 2026-04-07 07:24:03 +00:00
Code Issues Projects Releases Packages Wiki Activity

Improved documentation

Browse source
This commit is contained in:
dh1tw 2014-06-15 14:06:17 +07:00
parent 8216f488ef
commit 91c30879f1
12 changed files with 246 additions and 96 deletions
Download patch file Download diff file Expand all files Collapse all files

87
docs/build/html/lookuplib.html vendored
View file

@ -56,7 +56,7 @@
</div>
<span class="target" id="module-pyhamtools.lookuplib"></span><dl class="class">
<dt id="pyhamtools.lookuplib.LookupLib">
<em class="property">class </em><tt class="descclassname">pyhamtools.lookuplib.</tt><tt class="descname">LookupLib</tt><big>(</big><em>lookuptype='countryfile'</em>, <em>apikey=None</em>, <em>filename=None</em>, <em>logger=None</em><big>)</big><a class="headerlink" href="#pyhamtools.lookuplib.LookupLib" title="Permalink to this definition"></a></dt>
<em class="property">class </em><tt class="descclassname">pyhamtools.lookuplib.</tt><tt class="descname">LookupLib</tt><big>(</big><em>lookuptype='countryfile'</em>, <em>apikey=None</em>, <em>filename=None</em>, <em>logger=None</em>, <em>redis_instance=None</em>, <em>redis_prefix=None</em><big>)</big><a class="headerlink" href="#pyhamtools.lookuplib.LookupLib" title="Permalink to this definition"></a></dt>
<dd><p>This class is a wrapper for the following three Amateur Radio databases:</p>
<ol class="arabic simple">
<li>Clublog.org (daily updated XML File)</li>
@ -64,28 +64,94 @@
<li>Country-files.com (infrequently updated PLIST File)</li>
</ol>
<p>It&#8217;s aim is to provide a homogeneous interface to different databases.</p>
<p>Typically an instance of this class is injected as a dependency in the <tt class="xref py py-class docutils literal"><span class="pre">Callinfo</span></tt> class, but it can also be used directly.</p>
<p>Typically an instance of this class is injected as a dependency in the <tt class="xref py py-class docutils literal"><span class="pre">Callinfo</span></tt> class, but it can also
be used directly.</p>
<p>Even the interface is the same for all lookup sources, the returning data can be different.
The documentation of the various methods provide more detail.</p>
<p>By default, LookupLib requires an Internet connection to download the libraries or perform the
lookup against the Clublog API.</p>
<p>The entire lookup data can also be copied into Redis, which an extremely fast in-memory Key/Value store.
A LookupLib object can be instanciated to perform then all lookups in Redis, instead processing and loading
the data from Internet / File. This saves some time and allows several instances of <a class="reference internal" href="#pyhamtools.lookuplib.LookupLib" title="pyhamtools.lookuplib.LookupLib"><tt class="xref py py-class docutils literal"><span class="pre">LookupLib</span></tt></a>
to query the same data concurrently.</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>lookuptype</strong> (<em>str</em>) &#8211; &#8220;clublogxml&#8221; or &#8220;clublogapi&#8221; or &#8220;countryfile&#8221;</li>
<li><strong>lookuptype</strong> (<em>str</em>) &#8211; &#8220;clublogxml&#8221; or &#8220;clublogapi&#8221; or &#8220;countryfile&#8221; or &#8220;redis&#8221;</li>
<li><strong>apikey</strong> (<em>str</em>) &#8211; Clublog API Key</li>
<li><strong>filename</strong> (<em>str, optional</em>) &#8211; Filename for Clublog XML or Country-files.com cty.plist file. When a local file is used, no Internet connection not API Key is necessary.</li>
<li><strong>filename</strong> (<em>str, optional</em>) &#8211; Filename for Clublog XML or Country-files.com cty.plist file. When a local file is</li>
<li><strong>logger</strong> (<em>logging.getLogger(__name__), optional</em>) &#8211; Python logger</li>
<li><strong>redis_instance</strong> (<em>redis.Redis(), optional</em>) &#8211; Instance of Redis</li>
<li><strong>redis_prefix</strong> (<em>str, optional</em>) &#8211; Prefix to identify the lookup data set in Redis</li>
</ul>
</td>
</tr>
</tbody>
</table>
<dl class="method">
<dt id="pyhamtools.lookuplib.LookupLib.copy_data_in_redis">
<tt class="descname">copy_data_in_redis</tt><big>(</big><em>redis_prefix</em>, <em>redis_instance</em><big>)</big><a class="headerlink" href="#pyhamtools.lookuplib.LookupLib.copy_data_in_redis" title="Permalink to this definition"></a></dt>
<dd><p>Copy the complete lookup data into redis. Old data will be overwritten.</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>redis_prefix</strong> (<em>str</em>) &#8211; Prefix to distinguish the data in redis for the different looktypes</li>
<li><strong>redis_instance</strong> (<em>str</em>) &#8211; an Instance of Redis</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">returns True when the data has been copied successfully into Redis</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Return type:</th><td class="field-body"><p class="first last">bool</p>
</td>
</tr>
</tbody>
</table>
<p class="rubric">Example</p>
<p>Copy the entire lookup data from the Country-files.com PLIST File into Redis. This example requires a running
instance of Redis, as well the python Redis connector (pip install redis-py).</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">pyhamtools</span> <span class="kn">import</span> <span class="n">LookupLib</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">redis</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">r</span> <span class="o">=</span> <span class="n">redis</span><span class="o">.</span><span class="n">Redis</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">my_lookuplib</span> <span class="o">=</span> <span class="n">LookupLib</span><span class="p">(</span><span class="n">lookuptype</span><span class="o">=</span><span class="s">&quot;countryfile&quot;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="n">my_lookuplib</span><span class="o">.</span><span class="n">copy_data_in_redis</span><span class="p">(</span><span class="n">redis_prefix</span><span class="o">=</span><span class="s">&quot;CF&quot;</span><span class="p">,</span> <span class="n">redis_instance</span><span class="o">=</span><span class="n">r</span><span class="p">)</span>
<span class="go">True</span>
</pre></div>
</div>
<p>Now let&#8217;s create an instance of LookupLib, using Redis to query the data
&gt;&gt;&gt; from pyhamtools import LookupLib
&gt;&gt;&gt; import redis
&gt;&gt;&gt; r = redis.Redis()
&gt;&gt;&gt; my_lookuplib = LookupLib(lookuptype=&#8221;countryfile&#8221;, redis_instance=r, redis_prefix=&#8221;CF&#8221;)
&gt;&gt;&gt; my_lookuplib.lookup_callsign(&#8220;3D2RI&#8221;)
{</p>
<blockquote>
<div>u&#8217;adif&#8217;: 460,
u&#8217;continent&#8217;: &#8216;OC&#8217;,
u&#8217;country&#8217;: &#8216;Rotuma Island&#8217;,
u&#8217;cqz&#8217;: 32,
u&#8217;ituz&#8217;: 56,
u&#8217;latitude&#8217;: -12.48,
u&#8217;longitude&#8217;: -177.08</div></blockquote>
<p>}</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>This method is available for the following lookup type</p>
<ul class="last simple">
<li>clublogxml</li>
<li>countryfile</li>
</ul>
</div>
</dd></dl>
<dl class="method">
<dt id="pyhamtools.lookuplib.LookupLib.is_invalid_operation">
<tt class="descname">is_invalid_operation</tt><big>(</big><em>callsign</em>, <em>timestamp=datetime.datetime(2014</em>, <em>4</em>, <em>29</em>, <em>13</em>, <em>1</em>, <em>27</em>, <em>518550</em>, <em>tzinfo=&lt;UTC&gt;)</em><big>)</big><a class="headerlink" href="#pyhamtools.lookuplib.LookupLib.is_invalid_operation" title="Permalink to this definition"></a></dt>
<tt class="descname">is_invalid_operation</tt><big>(</big><em>callsign</em>, <em>timestamp=datetime.datetime(2014</em>, <em>6</em>, <em>15</em>, <em>7</em>, <em>5</em>, <em>27</em>, <em>706858</em>, <em>tzinfo=&lt;UTC&gt;)</em><big>)</big><a class="headerlink" href="#pyhamtools.lookuplib.LookupLib.is_invalid_operation" title="Permalink to this definition"></a></dt>
<dd><p>Returns True if an operations is known as invalid</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
@ -134,13 +200,14 @@ API Key for Clublog missing or incorrect</li>
<p>This method is available for</p>
<ul class="last simple">
<li>clublogxml</li>
<li>redis</li>
</ul>
</div>
</dd></dl>
<dl class="method">
<dt id="pyhamtools.lookuplib.LookupLib.lookup_callsign">
<tt class="descname">lookup_callsign</tt><big>(</big><em>callsign=None</em>, <em>timestamp=datetime.datetime(2014</em>, <em>4</em>, <em>29</em>, <em>13</em>, <em>1</em>, <em>27</em>, <em>518519</em>, <em>tzinfo=&lt;UTC&gt;)</em><big>)</big><a class="headerlink" href="#pyhamtools.lookuplib.LookupLib.lookup_callsign" title="Permalink to this definition"></a></dt>
<tt class="descname">lookup_callsign</tt><big>(</big><em>callsign=None</em>, <em>timestamp=datetime.datetime(2014</em>, <em>6</em>, <em>15</em>, <em>7</em>, <em>5</em>, <em>27</em>, <em>706831</em>, <em>tzinfo=&lt;UTC&gt;)</em><big>)</big><a class="headerlink" href="#pyhamtools.lookuplib.LookupLib.lookup_callsign" title="Permalink to this definition"></a></dt>
<dd><p>Returns lookup data if an exception exists for a callsign</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
@ -193,6 +260,7 @@ API Key for Clublog missing or incorrect</li>
<li>clublogxml</li>
<li>clublogapi</li>
<li>countryfile</li>
<li>redis</li>
</ul>
</div>
</dd></dl>
@ -238,13 +306,14 @@ the id 273.</p>
<p>This method is available for the following lookup type</p>
<ul class="last simple">
<li>clublogxml</li>
<li>redis</li>
</ul>
</div>
</dd></dl>
<dl class="method">
<dt id="pyhamtools.lookuplib.LookupLib.lookup_prefix">
<tt class="descname">lookup_prefix</tt><big>(</big><em>prefix</em>, <em>timestamp=datetime.datetime(2014</em>, <em>4</em>, <em>29</em>, <em>13</em>, <em>1</em>, <em>27</em>, <em>518519</em>, <em>tzinfo=&lt;UTC&gt;)</em><big>)</big><a class="headerlink" href="#pyhamtools.lookuplib.LookupLib.lookup_prefix" title="Permalink to this definition"></a></dt>
<tt class="descname">lookup_prefix</tt><big>(</big><em>prefix</em>, <em>timestamp=datetime.datetime(2014</em>, <em>6</em>, <em>15</em>, <em>7</em>, <em>5</em>, <em>27</em>, <em>706831</em>, <em>tzinfo=&lt;UTC&gt;)</em><big>)</big><a class="headerlink" href="#pyhamtools.lookuplib.LookupLib.lookup_prefix" title="Permalink to this definition"></a></dt>
<dd><p>Returns lookup data of a Prefix</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
@ -295,13 +364,14 @@ database (default database).</p>
<ul class="last simple">
<li>clublogxml</li>
<li>countryfile</li>
<li>redis</li>
</ul>
</div>
</dd></dl>
<dl class="method">
<dt id="pyhamtools.lookuplib.LookupLib.lookup_zone_exception">
<tt class="descname">lookup_zone_exception</tt><big>(</big><em>callsign</em>, <em>timestamp=datetime.datetime(2014</em>, <em>4</em>, <em>29</em>, <em>13</em>, <em>1</em>, <em>27</em>, <em>518556</em>, <em>tzinfo=&lt;UTC&gt;)</em><big>)</big><a class="headerlink" href="#pyhamtools.lookuplib.LookupLib.lookup_zone_exception" title="Permalink to this definition"></a></dt>
<tt class="descname">lookup_zone_exception</tt><big>(</big><em>callsign</em>, <em>timestamp=datetime.datetime(2014</em>, <em>6</em>, <em>15</em>, <em>7</em>, <em>5</em>, <em>27</em>, <em>706866</em>, <em>tzinfo=&lt;UTC&gt;)</em><big>)</big><a class="headerlink" href="#pyhamtools.lookuplib.LookupLib.lookup_zone_exception" title="Permalink to this definition"></a></dt>
<dd><p>Returns a CQ Zone if an exception exists for the given callsign</p>
<p>Args:
callsign (string): Amateur radio callsign
@ -341,6 +411,7 @@ in CQ Zone 38</p>
<p>This method is available for</p>
<ul class="last simple">
<li>clublogxml</li>
<li>redis</li>
</ul>
</div>
</dd></dl>