more work on ldap module documentation (take 2)

Stanford · Aug 26, 2024 · 3c3ff07 · 3c3ff07
1 parent 4b3dc34
commit 3c3ff07
Show file tree

Hide file tree

Showing 6 changed files with 101 additions and 7 deletions.
diff --git a/docs/genindex.html b/docs/genindex.html
@@ -42,6 +42,7 @@ <h1 id="index">Index</h1>
  | <a href="#G"><strong>G</strong></a>
  | <a href="#I"><strong>I</strong></a>
  | <a href="#K"><strong>K</strong></a>
+ | <a href="#L"><strong>L</strong></a>
  | <a href="#M"><strong>M</strong></a>
  | <a href="#P"><strong>P</strong></a>
  | <a href="#R"><strong>R</strong></a>
@@ -89,6 +90,8 @@ <h2 id="C">C</h2>
   </ul></td>
   <td style="width: 33%; vertical-align: top;"><ul>
       <li><a href="modules/kerberos.html#stanford.green.kerberos.KerberosTicket.cleanup">cleanup() (stanford.green.kerberos.KerberosTicket method)</a>
+</li>
+      <li><a href="modules/ldap.html#stanford.green.ldap.LDAP.connect">connect() (stanford.green.ldap.LDAP method)</a>
 </li>
       <li><a href="modules/kerberos.html#stanford.green.kerberos.KerberosTicket.create_ticket_file">create_ticket_file() (stanford.green.kerberos.KerberosTicket method)</a>
 </li>
@@ -164,6 +167,14 @@ <h2 id="K">K</h2>
   </ul></td>
 </tr></table>
 
+<h2 id="L">L</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="modules/ldap.html#stanford.green.ldap.LDAP">LDAP (class in stanford.green.ldap)</a>
+</li>
+  </ul></td>
+</tr></table>
+
 <h2 id="M">M</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
   <td style="width: 33%; vertical-align: top;"><ul>
@@ -204,6 +215,8 @@ <h2 id="R">R</h2>
 <h2 id="S">S</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
   <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="modules/ldap.html#stanford.green.ldap.LDAP.search">search() (stanford.green.ldap.LDAP method)</a>
+</li>
       <li>
     stanford.green
 
@@ -218,15 +231,15 @@ <h2 id="S">S</h2>
         <li><a href="modules/kerberos.html#module-stanford.green.kerberos">module</a>
 </li>
       </ul></li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
       <li>
     stanford.green.ldap
 
       <ul>
         <li><a href="modules/ldap.html#module-stanford.green.ldap">module</a>
 </li>
       </ul></li>
-  </ul></td>
-  <td style="width: 33%; vertical-align: top;"><ul>
       <li>
     stanford.green.oauth2
 

diff --git a/docs/index.html b/docs/index.html
@@ -59,6 +59,11 @@ <h1>stanford-green documentation<a class="headerlink" href="#stanford-green-docu
 <li class="toctree-l3"><a class="reference internal" href="modules/ldap.html#examples">Examples</a></li>
 <li class="toctree-l3"><a class="reference internal" href="modules/ldap.html#stanford.green.ldap.GreenLDAPNoResultsException"><code class="docutils literal notranslate"><span class="pre">GreenLDAPNoResultsException</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="modules/ldap.html#stanford.green.ldap.GreenUnknownLDAPAttribute"><code class="docutils literal notranslate"><span class="pre">GreenUnknownLDAPAttribute</span></code></a></li>
+<li class="toctree-l3"><a class="reference internal" href="modules/ldap.html#stanford.green.ldap.LDAP"><code class="docutils literal notranslate"><span class="pre">LDAP</span></code></a><ul>
+<li class="toctree-l4"><a class="reference internal" href="modules/ldap.html#stanford.green.ldap.LDAP.connect"><code class="docutils literal notranslate"><span class="pre">LDAP.connect()</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="modules/ldap.html#stanford.green.ldap.LDAP.search"><code class="docutils literal notranslate"><span class="pre">LDAP.search()</span></code></a></li>
+</ul>
+</li>
 <li class="toctree-l3"><a class="reference internal" href="modules/ldap.html#stanford.green.ldap.attribute_is_single_valued"><code class="docutils literal notranslate"><span class="pre">attribute_is_single_valued()</span></code></a></li>
 </ul>
 </li>

diff --git a/docs/modules/ldap.html b/docs/modules/ldap.html
@@ -38,8 +38,8 @@
 <p>Useful LDAP functions.</p>
 <section id="overview">
 <h2>Overview<a class="headerlink" href="#overview" title="Link to this heading">¶</a></h2>
-<p>LDAP functions useful for Stanford-based applications. Currenently the
-only authentication supported when connecting to an LDAP server is GSSAPI
+<p>LDAP functions useful for Stanford-based applications. Currently the
+only authentication method supported when connecting to an LDAP server is GSSAPI
 (Kerberos).</p>
 </section>
 <section id="examples">
@@ -66,6 +66,63 @@ <h2>Examples<a class="headerlink" href="#examples" title="Link to this heading">
 <em class="property"><span class="pre">exception</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">stanford.green.ldap.</span></span><span class="sig-name descname"><span class="pre">GreenUnknownLDAPAttribute</span></span><a class="headerlink" href="#stanford.green.ldap.GreenUnknownLDAPAttribute" title="Link to this definition">¶</a></dt>
 <dd></dd></dl>
 
+<dl class="py class">
+<dt class="sig sig-object py" id="stanford.green.ldap.LDAP">
+<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">stanford.green.ldap.</span></span><span class="sig-name descname"><span class="pre">LDAP</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">host</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">'ldap.stanford.edu'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">connect_on_init</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#stanford.green.ldap.LDAP" title="Link to this definition">¶</a></dt>
+<dd><p>The LDAP class.</p>
+<dl class="py method">
+<dt class="sig sig-object py" id="stanford.green.ldap.LDAP.connect">
+<span class="sig-name descname"><span class="pre">connect</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">Any</span></span></span><a class="headerlink" href="#stanford.green.ldap.LDAP.connect" title="Link to this definition">¶</a></dt>
+<dd><p>Create a connected ldap object.</p>
+<p>Currently, the only connection method is using GSSAPI. That is, there
+must be a valid Kerberos context.</p>
+</dd></dl>
+
+<dl class="py method">
+<dt class="sig sig-object py" id="stanford.green.ldap.LDAP.search">
+<span class="sig-name descname"><span class="pre">search</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">basedn</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">filterstr</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">'(objectClass=*)'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">attrlist</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">list</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">scope</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">'sub'</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">dict</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">dict</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">dict</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">list</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span></span></span><a class="headerlink" href="#stanford.green.ldap.LDAP.search" title="Link to this definition">¶</a></dt>
+<dd><p>Perform an LDAP search.</p>
+<dl class="field-list simple">
+<dt class="field-odd">Parameters<span class="colon">:</span></dt>
+<dd class="field-odd"><ul class="simple">
+<li><p><strong>basedn</strong> (<em>str</em>) – base DN on which to search</p></li>
+<li><p><strong>filterstr</strong> (<em>list</em><em>[</em><em>str</em><em>]</em>) – a valid LDAP filter clause (e.g., <code class="docutils literal notranslate"><span class="pre">(uid=jstanford)</span></code>)</p></li>
+<li><p><strong>filterstr</strong> – a list of attributes to return</p></li>
+<li><p><strong>scope</strong> (<em>str</em>) – the search scope; must be one “sub”, “base”, or “one”.</p></li>
+</ul>
+</dd>
+</dl>
+<p>This method is a thin wrapper around the ldap package’s search method. The
+difference is in how it behaves when there are no results and the format
+of the returned value.</p>
+<p>The returned result is a dict where each key is the dn of some
+tree result. Each key maps to another dict containing the attributes. This
+is most easily explained with an example:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">basedn</span> <span class="o">=</span> <span class="s2">&quot;dc=stanford,dc=edu&quot;</span>
+<span class="n">filterstr</span> <span class="o">=</span> <span class="s2">&quot;uid=jstanford&quot;</span>
+<span class="n">results</span> <span class="o">=</span> <span class="n">search</span><span class="p">(</span><span class="n">basdn</span><span class="p">,</span> <span class="n">filterstr</span><span class="o">=</span><span class="n">filterstr</span><span class="p">)</span>
+<span class="c1">#</span>
+<span class="c1"># results will look something like</span>
+<span class="c1"># {</span>
+<span class="c1">#   &#39;suRegID=f0d08565850320613717ebf068585447,cn=people,dc=stanford,dc=edu&#39;:</span>
+<span class="c1">#     {&#39;suMailCode&#39;: &#39;4321&#39;, &#39;suGwAffilCode1&#39;: &#39;stanford:staff&#39;, ... }</span>
+<span class="c1">#   &#39;uid=jstanford,cn=accounts,dc=stanford,dc=edu&#39;:</span>
+<span class="c1">#     { &#39;uid&#39;: &#39;jstanford&#39;, &#39;suSeasSunetID&#39;: [&#39;jstanford&#39;, &#39;jane.stanford&#39;], ... }</span>
+<span class="c1"># }</span>
+<span class="c1">#</span>
+<span class="c1"># There are two keys in the above: the &quot;suRegID=f0...&quot; one and the &quot;uid=jstanford,...&quot; one.</span>
+</pre></div>
+</div>
+<p>Note that the attributes are returned as either a string (for
+single-valued attributes) or a list (for multi-valued attributes).
+Furthermore, LDAP returns vaules as byte-strings so this method
+converts these byte-strings into regular utf8 strings.</p>
+<p>If no results are returned this method raises the
+<cite>LDAPNoResultsException</cite> exception.</p>
+</dd></dl>
+
+</dd></dl>
+
 <dl class="py function">
 <dt class="sig sig-object py" id="stanford.green.ldap.attribute_is_single_valued">
 <span class="sig-prename descclassname"><span class="pre">stanford.green.ldap.</span></span><span class="sig-name descname"><span class="pre">attribute_is_single_valued</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">attribute_name</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">bool</span></span></span><a class="headerlink" href="#stanford.green.ldap.attribute_is_single_valued" title="Link to this definition">¶</a></dt>
@@ -118,6 +175,11 @@ <h1 class="logo"><a href="../index.html">stanford-green</a></h1>
 <li class="toctree-l3"><a class="reference internal" href="#examples">Examples</a></li>
 <li class="toctree-l3"><a class="reference internal" href="#stanford.green.ldap.GreenLDAPNoResultsException"><code class="docutils literal notranslate"><span class="pre">GreenLDAPNoResultsException</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="#stanford.green.ldap.GreenUnknownLDAPAttribute"><code class="docutils literal notranslate"><span class="pre">GreenUnknownLDAPAttribute</span></code></a></li>
+<li class="toctree-l3"><a class="reference internal" href="#stanford.green.ldap.LDAP"><code class="docutils literal notranslate"><span class="pre">LDAP</span></code></a><ul>
+<li class="toctree-l4"><a class="reference internal" href="#stanford.green.ldap.LDAP.connect"><code class="docutils literal notranslate"><span class="pre">LDAP.connect()</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="#stanford.green.ldap.LDAP.search"><code class="docutils literal notranslate"><span class="pre">LDAP.search()</span></code></a></li>
+</ul>
+</li>
 <li class="toctree-l3"><a class="reference internal" href="#stanford.green.ldap.attribute_is_single_valued"><code class="docutils literal notranslate"><span class="pre">attribute_is_single_valued()</span></code></a></li>
 </ul>
 </li>

diff --git a/docs/objects.inv b/docs/objects.inv