updating documentation; version 0.1.10

litl · Mar 15, 2012 · ce5d684 · ce5d684
1 parent 6f73125
commit ce5d684
Show file tree

Hide file tree

Showing 13 changed files with 131 additions and 34 deletions.
diff --git a/docs/_build/doctrees/environment.pickle b/docs/_build/doctrees/environment.pickle
diff --git a/docs/_build/doctrees/index.doctree b/docs/_build/doctrees/index.doctree
diff --git a/docs/_build/html/.buildinfo b/docs/_build/html/.buildinfo
@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: b9b126491ce3d87c154f3b01012d4f58
+config: 686d1d9a53cf9d513f5d3adea79e6b90
 tags: fbb0d17656682115ca4d033fb2f83ba1
diff --git a/docs/_build/html/_sources/index.txt b/docs/_build/html/_sources/index.txt
@@ -111,3 +111,6 @@ API
 
 .. autoclass:: webauth.service.OAuth1Service
     :members:
+
+.. autoclass:: webauth.hook.OAuth1Hook
+    :members:
diff --git a/docs/_build/html/genindex.html b/docs/_build/html/genindex.html
@@ -9,15 +9,15 @@
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 
-    <title>Index &mdash; Webauth 0.1.9 documentation</title>
+    <title>Index &mdash; Webauth 0.1.10 documentation</title>
 
     <link rel="stylesheet" href="_static/flasky.css" type="text/css" />
     <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
 
     <script type="text/javascript">
       var DOCUMENTATION_OPTIONS = {
         URL_ROOT:    '',
-        VERSION:     '0.1.9',
+        VERSION:     '0.1.10',
         COLLAPSE_INDEX: false,
         FILE_SUFFIX: '.html',
         HAS_SOURCE:  true
@@ -26,7 +26,7 @@
     <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>
-    <link rel="top" title="Webauth 0.1.9 documentation" href="index.html" /> 
+    <link rel="top" title="Webauth 0.1.10 documentation" href="index.html" /> 
   </head>
   <body>
 
@@ -52,6 +52,14 @@ <h2 id="G">G</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
   <td style="width: 33%" valign="top"><dl>
 
+  <dt><a href="index.html#webauth.hook.OAuth1Hook.generate_authorization_header">generate_authorization_header() (webauth.hook.OAuth1Hook method)</a>
+  </dt>
+
+
+  <dt><a href="index.html#webauth.hook.OAuth1Hook.generate_oauth_params">generate_oauth_params() (webauth.hook.OAuth1Hook method)</a>
+  </dt>
+
+
   <dt><a href="index.html#webauth.service.OAuth1Service.get_access_token">get_access_token() (webauth.service.OAuth1Service method)</a>
   </dt>
 
@@ -61,12 +69,12 @@ <h2 id="G">G</h2>
   </dt>
 
       </dl></dd>
+  </dl></td>
+  <td style="width: 33%" valign="top"><dl>
 
   <dt><a href="index.html#webauth.service.OAuth1Service.get_authenticated_session">get_authenticated_session() (webauth.service.OAuth1Service method)</a>
   </dt>
 
-  </dl></td>
-  <td style="width: 33%" valign="top"><dl>
 
   <dt><a href="index.html#webauth.service.OAuth1Service.get_authorize_url">get_authorize_url() (webauth.service.OAuth1Service method)</a>
   </dt>
@@ -92,16 +100,20 @@ <h2 id="O">O</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
   <td style="width: 33%" valign="top"><dl>
 
-  <dt><a href="index.html#webauth.service.OAuth1Service">OAuth1Service (class in webauth.service)</a>
+  <dt><a href="index.html#webauth.hook.OAuth1Hook">OAuth1Hook (class in webauth.hook)</a>
   </dt>
 
 
-  <dt><a href="index.html#webauth.service.OAuth2Service">OAuth2Service (class in webauth.service)</a>
+  <dt><a href="index.html#webauth.service.OAuth1Service">OAuth1Service (class in webauth.service)</a>
   </dt>
 
   </dl></td>
   <td style="width: 33%" valign="top"><dl>
 
+  <dt><a href="index.html#webauth.service.OAuth2Service">OAuth2Service (class in webauth.service)</a>
+  </dt>
+
+
   <dt><a href="index.html#webauth.service.OflyService">OflyService (class in webauth.service)</a>
   </dt>
 

diff --git a/docs/_build/html/index.html b/docs/_build/html/index.html
@@ -7,15 +7,15 @@
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 
-    <title>Webauth &mdash; Webauth 0.1.9 documentation</title>
+    <title>Webauth &mdash; Webauth 0.1.10 documentation</title>
 
     <link rel="stylesheet" href="_static/flasky.css" type="text/css" />
     <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
 
     <script type="text/javascript">
       var DOCUMENTATION_OPTIONS = {
         URL_ROOT:    '',
-        VERSION:     '0.1.9',
+        VERSION:     '0.1.10',
         COLLAPSE_INDEX: false,
         FILE_SUFFIX: '.html',
         HAS_SOURCE:  true
@@ -24,7 +24,7 @@
     <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>
-    <link rel="top" title="Webauth 0.1.9 documentation" href="#" /> 
+    <link rel="top" title="Webauth 0.1.10 documentation" href="#" /> 
   </head>
   <body>
 
@@ -180,11 +180,9 @@ <h2>API<a class="headerlink" href="#api" title="Permalink to this headline">¶</
 
 <dl class="method">
 <dt id="webauth.service.OflyService.request">
-<tt class="descname">request</tt><big>(</big><em>http_method</em>, <em>url</em>, <em>header_auth=False</em>, <em>**params</em><big>)</big><a class="headerlink" href="#webauth.service.OflyService.request" title="Permalink to this definition">¶</a></dt>
+<tt class="descname">request</tt><big>(</big><em>http_method</em>, <em>url</em>, <em>header_auth=False</em>, <em>params=None</em>, <em>data=None</em><big>)</big><a class="headerlink" href="#webauth.service.OflyService.request" title="Permalink to this definition">¶</a></dt>
 <dd><p>Sends a request to an Ofly endpoint, properly wrapped around
 requests.</p>
-<p>The first time an access token is provided it will be saved on the
-object for convenience.</p>
 <table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
@@ -194,8 +192,9 @@ <h2>API<a class="headerlink" href="#api" title="Permalink to this headline">¶</
 used.</li>
 <li><strong>url</strong> &#8211; The resource to be requested.</li>
 <li><strong>header_auth</strong> &#8211; Authenication via header, defaults to False.</li>
-<li><strong>params</strong> &#8211; Additional keyworded arguments to be added to the
-request querystring.</li>
+<li><strong>params</strong> &#8211; Additional arguments to be added to the request
+querystring.</li>
+<li><strong>data</strong> &#8211; Additional data to be included in the request body.</li>
 </ul>
 </td>
 </tr>
@@ -291,7 +290,7 @@ <h2>API<a class="headerlink" href="#api" title="Permalink to this headline">¶</
 
 <dl class="method">
 <dt id="webauth.service.OAuth2Service.request">
-<tt class="descname">request</tt><big>(</big><em>http_method</em>, <em>url</em>, <em>access_token=None</em>, <em>**params</em><big>)</big><a class="headerlink" href="#webauth.service.OAuth2Service.request" title="Permalink to this definition">¶</a></dt>
+<tt class="descname">request</tt><big>(</big><em>http_method</em>, <em>url</em>, <em>access_token=None</em>, <em>params=None</em>, <em>data=None</em><big>)</big><a class="headerlink" href="#webauth.service.OAuth2Service.request" title="Permalink to this definition">¶</a></dt>
 <dd><p>Sends a request to an OAuth 2.0 endpoint, properly wrapped around
 requests.</p>
 <p>The first time an access token is provided it will be saved on the
@@ -306,8 +305,9 @@ <h2>API<a class="headerlink" href="#api" title="Permalink to this headline">¶</
 <li><strong>url</strong> &#8211; The resource to be requested.</li>
 <li><strong>access_token</strong> &#8211; The access token as returned by
 <tt class="xref py py-class docutils literal"><span class="pre">get_access_token</span></tt>.</li>
-<li><strong>params</strong> &#8211; Additional keyworded arguments to be added to the
-request querystring.</li>
+<li><strong>params</strong> &#8211; Additional arguments to be added to the request
+querystring.</li>
+<li><strong>data</strong> &#8211; Additional data to be included in the request body.</li>
 </ul>
 </td>
 </tr>
@@ -489,6 +489,85 @@ <h2>API<a class="headerlink" href="#api" title="Permalink to this headline">¶</
 
 </dd></dl>
 
+<dl class="class">
+<dt id="webauth.hook.OAuth1Hook">
+<em class="property">class </em><tt class="descclassname">webauth.hook.</tt><tt class="descname">OAuth1Hook</tt><big>(</big><em>consumer_key</em>, <em>consumer_secret</em>, <em>access_token=None</em>, <em>access_token_secret=None</em>, <em>header_auth=False</em>, <em>signature=None</em><big>)</big><a class="headerlink" href="#webauth.hook.OAuth1Hook" title="Permalink to this definition">¶</a></dt>
+<dd><p>Provides a pre-request hook into requests for OAuth 1.0/a services.</p>
+<p>This package is built on the excellent Python Requests package. It
+functions by &#8220;hooking&#8221; into a request and appending various attributes to
+it which allow a client to interact with a standardized OAuth 1.0/a
+provider.</p>
+<p>You might intialize <tt class="xref py py-class docutils literal"><span class="pre">OAuthHook</span></tt> something like this:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="n">oauth</span> <span class="o">=</span> <span class="n">OAuthHook</span><span class="p">(</span><span class="n">consumer_key</span><span class="o">=</span><span class="mi">1234</span><span class="p">,</span>
+                  <span class="n">consumer_secret</span><span class="o">=</span><span class="mi">5678</span><span class="p">)</span>
+<span class="n">oauth_session</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">session</span><span class="p">(</span><span class="n">hooks</span><span class="o">=</span><span class="p">{</span><span class="s">&#39;pre_request&#39;</span><span class="p">:</span> <span class="n">oauth</span><span class="p">})</span>
+</pre></div>
+</div>
+<p>This establishes a requests session that is wrapped if the OAuth-capable
+hook. Using this session, an OAuth provider may be interacted with and
+will receive the proper formatting for requests.</p>
+<p>Note that this is normally used as a starting from which a request token
+would be generated whereupon an access token is received. Once such a token
+has been received, the wrapper should be reinitalized with this token:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="c"># we provide our consumer pair as well as the access pair as returned</span>
+<span class="c"># by the provider endpoint</span>
+<span class="n">oauth</span> <span class="o">=</span> <span class="n">OAuthHook</span><span class="p">(</span><span class="n">consumer_key</span><span class="o">=</span><span class="mi">1234</span><span class="p">,</span>
+                  <span class="n">consumer_secret</span><span class="o">=</span><span class="mi">5678</span><span class="p">,</span>
+                  <span class="n">access_token</span><span class="o">=</span><span class="mi">4321</span><span class="p">,</span>
+                  <span class="n">access_token_secret</span><span class="o">=</span><span class="mi">8765</span><span class="p">)</span>
+<span class="n">oauth_session</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">session</span><span class="p">(</span><span class="n">hooks</span><span class="o">=</span><span class="p">{</span><span class="s">&#39;pre_request&#39;</span><span class="p">:</span> <span class="n">oauth</span><span class="p">})</span>
+</pre></div>
+</div>
+<p>The session is now ready to make calls to the endpoints made available by
+the provider.</p>
+<p>Additionally some services will make use of header authentication. This is
+provided by passing <tt class="xref py py-class docutils literal"><span class="pre">__init__</span></tt> the <cite>auth_header</cite> parameter as
+<cite>True</cite>.</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>consumer_key</strong> &#8211; Client consumer key.</li>
+<li><strong>consumer_secret</strong> &#8211; Client consumer secret.</li>
+<li><strong>access_token</strong> &#8211; Access token key.</li>
+<li><strong>access_token_secret</strong> &#8211; Access token secret.</li>
+<li><strong>header_auth</strong> &#8211; Authenication via header, defauls to False.</li>
+<li><strong>signature</strong> &#8211; A signature method used to sign request parameters.</li>
+</ul>
+</td>
+</tr>
+</tbody>
+</table>
+<p>Defaults to None. If None the <cite>HmacSha1Signature</cite> method is used as
+default.</p>
+<dl class="method">
+<dt id="webauth.hook.OAuth1Hook.generate_authorization_header">
+<tt class="descname">generate_authorization_header</tt><big>(</big><em>oauth_params</em>, <em>realm=None</em><big>)</big><a class="headerlink" href="#webauth.hook.OAuth1Hook.generate_authorization_header" title="Permalink to this definition">¶</a></dt>
+<dd><p>This method constructs an authorization header.</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>oauth_params</strong> &#8211; The OAuth parameters to be added to the header.</li>
+<li><strong>realm</strong> &#8211; The authentication realm. Defaults to None.</li>
+</ul>
+</td>
+</tr>
+</tbody>
+</table>
+</dd></dl>
+
+<dl class="method">
+<dt id="webauth.hook.OAuth1Hook.generate_oauth_params">
+<tt class="descname">generate_oauth_params</tt><big>(</big><big>)</big><a class="headerlink" href="#webauth.hook.OAuth1Hook.generate_oauth_params" title="Permalink to this definition">¶</a></dt>
+<dd><p>This method handles generating the necessary URL parameters the
+OAuth provider will expect.</p>
+</dd></dl>
+
+</dd></dl>
+
 </div>
 </div>
 

diff --git a/docs/_build/html/objects.inv b/docs/_build/html/objects.inv
diff --git a/docs/_build/html/py-modindex.html b/docs/_build/html/py-modindex.html
@@ -7,15 +7,15 @@
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 
-    <title>Python Module Index &mdash; Webauth 0.1.9 documentation</title>
+    <title>Python Module Index &mdash; Webauth 0.1.10 documentation</title>
 
     <link rel="stylesheet" href="_static/flasky.css" type="text/css" />
     <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
 
     <script type="text/javascript">
       var DOCUMENTATION_OPTIONS = {
         URL_ROOT:    '',
-        VERSION:     '0.1.9',
+        VERSION:     '0.1.10',
         COLLAPSE_INDEX: false,
         FILE_SUFFIX: '.html',
         HAS_SOURCE:  true
@@ -24,7 +24,7 @@
     <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>
-    <link rel="top" title="Webauth 0.1.9 documentation" href="index.html" />
+    <link rel="top" title="Webauth 0.1.10 documentation" href="index.html" />
 
 
     <script type="text/javascript">

diff --git a/docs/_build/html/search.html b/docs/_build/html/search.html
@@ -7,15 +7,15 @@
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 
-    <title>Search &mdash; Webauth 0.1.9 documentation</title>
+    <title>Search &mdash; Webauth 0.1.10 documentation</title>
 
     <link rel="stylesheet" href="_static/flasky.css" type="text/css" />
     <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
 
     <script type="text/javascript">
       var DOCUMENTATION_OPTIONS = {
         URL_ROOT:    '',
-        VERSION:     '0.1.9',
+        VERSION:     '0.1.10',
         COLLAPSE_INDEX: false,
         FILE_SUFFIX: '.html',
         HAS_SOURCE:  true
@@ -25,7 +25,7 @@
     <script type="text/javascript" src="_static/underscore.js"></script>
     <script type="text/javascript" src="_static/doctools.js"></script>
     <script type="text/javascript" src="_static/searchtools.js"></script>
-    <link rel="top" title="Webauth 0.1.9 documentation" href="index.html" />
+    <link rel="top" title="Webauth 0.1.10 documentation" href="index.html" />
   <script type="text/javascript">
     jQuery(function() { Search.loadIndex("searchindex.js"); });
   </script>