Source

eggDiscover / documentation / build / twitter.html

Full commit


<!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>The Twitter Module &mdash; EggDiscover 0.1 documentation</title>
    
    <link rel="stylesheet" href="_static/default.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',
        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>
    <link rel="top" title="EggDiscover 0.1 documentation" href="index.html" />
    <link rel="up" title="External apps used in this project" href="externalapps.html" />
    <link rel="next" title="The Celery Module" href="celery.html" />
    <link rel="prev" title="The Django Celery Module" href="djcelery.html" /> 
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="celery.html" title="The Celery Module"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="djcelery.html" title="The Django Celery Module"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">EggDiscover 0.1 documentation</a> &raquo;</li>
          <li><a href="externalapps.html" accesskey="U">External apps used in this project</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="module-twitter">
<span id="the-twitter-module"></span><h1>The Twitter Module<a class="headerlink" href="#module-twitter" title="Permalink to this headline"></a></h1>
<p>The minimalist yet fully featured Twitter API and Python toolset.</p>
<p>The Twitter and TwitterStream classes are the key to building your own
Twitter-enabled applications.</p>
<div class="section" id="the-twitter-class">
<h2>The Twitter class<a class="headerlink" href="#the-twitter-class" title="Permalink to this headline"></a></h2>
<blockquote>
<div><p>The minimalist yet fully featured Twitter API class.</p>
<p>Get RESTful data by accessing members of this class. The result
is decoded python objects (lists and dicts).</p>
<p>The Twitter API is documented here:</p>
<blockquote>
<div><a class="reference external" href="http://dev.twitter.com/doc">http://dev.twitter.com/doc</a></div></blockquote>
<p>Examples:</p>
<div class="highlight-python"><pre>twitter = Twitter(
    auth=OAuth(token, token_key, con_secret, con_secret_key)))

# Get the public timeline
twitter.statuses.public_timeline()

# Get a particular friend's timeline
twitter.statuses.friends_timeline(id="billybob")

# Also supported (but totally weird)
twitter.statuses.friends_timeline.billybob()

# Send a direct message
twitter.direct_messages.new(
    user="billybob",
    text="I think yer swell!")

# Get the members of a particular list of a particular friend
twitter.user.listname.members(user="billybob", listname="billysbuds")</pre>
</div>
<p>Searching Twitter:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">twitter_search</span> <span class="o">=</span> <span class="n">Twitter</span><span class="p">(</span><span class="n">domain</span><span class="o">=</span><span class="s">&quot;search.twitter.com&quot;</span><span class="p">)</span>

<span class="c"># Find the latest search trends</span>
<span class="n">twitter_search</span><span class="o">.</span><span class="n">trends</span><span class="p">()</span>

<span class="c"># Search for the latest News on #gaza</span>
<span class="n">twitter_search</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="n">q</span><span class="o">=</span><span class="s">&quot;#gaza&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>Twitter API calls return decoded JSON. This is converted into
a bunch of Python lists, dicts, ints, and strings. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">x</span> <span class="o">=</span> <span class="n">twitter</span><span class="o">.</span><span class="n">statuses</span><span class="o">.</span><span class="n">public_timeline</span><span class="p">()</span>

<span class="c"># The first &#39;tweet&#39; in the timeline</span>
<span class="n">x</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>

<span class="c"># The screen name of the user who wrote the first &#39;tweet&#39;</span>
<span class="n">x</span><span class="p">[</span><span class="mi">0</span><span class="p">][</span><span class="s">&#39;user&#39;</span><span class="p">][</span><span class="s">&#39;screen_name&#39;</span><span class="p">]</span>
</pre></div>
</div>
<p>If you prefer to get your Twitter data in XML format, pass
format=&#8221;xml&#8221; to the Twitter object when you instantiate it:</p>
<div class="highlight-python"><pre>twitter = Twitter(format="xml")

The output will not be parsed in any way. It will be a raw string
of XML.</pre>
</div>
</div></blockquote>
</div>
<div class="section" id="the-twitterstream-class">
<h2>The TwitterStream class<a class="headerlink" href="#the-twitterstream-class" title="Permalink to this headline"></a></h2>
<blockquote>
<div><p>Interface to the Twitter Stream API (stream.twitter.com). This can
be used pretty much the same as the Twitter class except the
result of calling a method will be an iterator that yields objects
decoded from the stream. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">twitter_stream</span> <span class="o">=</span> <span class="n">TwitterStream</span><span class="p">(</span><span class="n">auth</span><span class="o">=</span><span class="n">UserPassAuth</span><span class="p">(</span><span class="s">&#39;joe&#39;</span><span class="p">,</span> <span class="s">&#39;joespassword&#39;</span><span class="p">))</span>
<span class="n">iterator</span> <span class="o">=</span> <span class="n">twitter_stream</span><span class="o">.</span><span class="n">statuses</span><span class="o">.</span><span class="n">sample</span><span class="p">()</span>

<span class="k">for</span> <span class="n">tweet</span> <span class="ow">in</span> <span class="n">iterator</span><span class="p">:</span>
    <span class="o">...</span><span class="n">do</span> <span class="n">something</span> <span class="k">with</span> <span class="n">this</span> <span class="n">tweet</span><span class="o">...</span>
</pre></div>
</div>
<p>The iterator will yield tweets forever and ever (until the stream
breaks at which point it raises a TwitterHTTPError.)</p>
</div></blockquote>
</div>
<div class="section" id="twitter-response-objects">
<h2>Twitter Response Objects<a class="headerlink" href="#twitter-response-objects" title="Permalink to this headline"></a></h2>
<blockquote>
<div><p>Response from a twitter request. Behaves like a list or a string
(depending on requested format) but it has a few other interesting
attributes.</p>
<p><cite>headers</cite> gives you access to the response headers as an
httplib.HTTPHeaders instance. You can do
<cite>response.headers.getheader(&#8216;h&#8217;)</cite> to retrieve a header.</p>
</div></blockquote>
</div>
<div class="section" id="authentication-objects">
<h2>Authentication Objects<a class="headerlink" href="#authentication-objects" title="Permalink to this headline"></a></h2>
<p>You can authenticate with Twitter in three ways: NoAuth, OAuth, or
UserPassAuth. Get help() on these classes to learn how to use them.</p>
</div>
<div class="section" id="other-things">
<h2>Other things<a class="headerlink" href="#other-things" title="Permalink to this headline"></a></h2>
<p>read_token_file and write_token_file are utility methods to read and
write OAuth token and secret key values. The values are stored as
strings in the file. Not terribly exciting.</p>
<dl class="class">
<dt id="twitter.Twitter">
<em class="property">class </em><tt class="descclassname">twitter.</tt><tt class="descname">Twitter</tt><big>(</big><em>format='json'</em>, <em>domain='api.twitter.com'</em>, <em>secure=True</em>, <em>auth=None</em>, <em>api_version=&lt;class 'twitter.api._DEFAULT'&gt;</em><big>)</big><a class="headerlink" href="#twitter.Twitter" title="Permalink to this definition"></a></dt>
<dd><p>The minimalist yet fully featured Twitter API class.</p>
<p>Get RESTful data by accessing members of this class. The result
is decoded python objects (lists and dicts).</p>
<p>The Twitter API is documented here:</p>
<blockquote>
<div><a class="reference external" href="http://dev.twitter.com/doc">http://dev.twitter.com/doc</a></div></blockquote>
<p>Examples:</p>
<div class="highlight-python"><pre>twitter = Twitter(
    auth=OAuth(token, token_key, con_secret, con_secret_key)))

# Get the public timeline
twitter.statuses.public_timeline()

# Get a particular friend's timeline
twitter.statuses.friends_timeline(id="billybob")

# Also supported (but totally weird)
twitter.statuses.friends_timeline.billybob()

# Send a direct message
twitter.direct_messages.new(
    user="billybob",
    text="I think yer swell!")

# Get the members of a particular list of a particular friend
twitter.user.listname.members(user="billybob", listname="billysbuds")</pre>
</div>
<p>Searching Twitter:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">twitter_search</span> <span class="o">=</span> <span class="n">Twitter</span><span class="p">(</span><span class="n">domain</span><span class="o">=</span><span class="s">&quot;search.twitter.com&quot;</span><span class="p">)</span>

<span class="c"># Find the latest search trends</span>
<span class="n">twitter_search</span><span class="o">.</span><span class="n">trends</span><span class="p">()</span>

<span class="c"># Search for the latest News on #gaza</span>
<span class="n">twitter_search</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="n">q</span><span class="o">=</span><span class="s">&quot;#gaza&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>Twitter API calls return decoded JSON. This is converted into
a bunch of Python lists, dicts, ints, and strings. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">x</span> <span class="o">=</span> <span class="n">twitter</span><span class="o">.</span><span class="n">statuses</span><span class="o">.</span><span class="n">public_timeline</span><span class="p">()</span>

<span class="c"># The first &#39;tweet&#39; in the timeline</span>
<span class="n">x</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>

<span class="c"># The screen name of the user who wrote the first &#39;tweet&#39;</span>
<span class="n">x</span><span class="p">[</span><span class="mi">0</span><span class="p">][</span><span class="s">&#39;user&#39;</span><span class="p">][</span><span class="s">&#39;screen_name&#39;</span><span class="p">]</span>
</pre></div>
</div>
<p>If you prefer to get your Twitter data in XML format, pass
format=&#8221;xml&#8221; to the Twitter object when you instantiate it:</p>
<div class="highlight-python"><pre>twitter = Twitter(format="xml")

The output will not be parsed in any way. It will be a raw string
of XML.</pre>
</div>
</dd></dl>

<dl class="class">
<dt id="twitter.TwitterStream">
<em class="property">class </em><tt class="descclassname">twitter.</tt><tt class="descname">TwitterStream</tt><big>(</big><em>domain='stream.twitter.com'</em>, <em>secure=False</em>, <em>auth=None</em>, <em>api_version='1'</em><big>)</big><a class="headerlink" href="#twitter.TwitterStream" title="Permalink to this definition"></a></dt>
<dd><p>Interface to the Twitter Stream API (stream.twitter.com). This can
be used pretty much the same as the Twitter class except the
result of calling a method will be an iterator that yields objects
decoded from the stream. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">twitter_stream</span> <span class="o">=</span> <span class="n">TwitterStream</span><span class="p">(</span><span class="n">auth</span><span class="o">=</span><span class="n">UserPassAuth</span><span class="p">(</span><span class="s">&#39;joe&#39;</span><span class="p">,</span> <span class="s">&#39;joespassword&#39;</span><span class="p">))</span>
<span class="n">iterator</span> <span class="o">=</span> <span class="n">twitter_stream</span><span class="o">.</span><span class="n">statuses</span><span class="o">.</span><span class="n">sample</span><span class="p">()</span>

<span class="k">for</span> <span class="n">tweet</span> <span class="ow">in</span> <span class="n">iterator</span><span class="p">:</span>
    <span class="o">...</span><span class="n">do</span> <span class="n">something</span> <span class="k">with</span> <span class="n">this</span> <span class="n">tweet</span><span class="o">...</span>
</pre></div>
</div>
<p>The iterator will yield tweets forever and ever (until the stream
breaks at which point it raises a TwitterHTTPError.)</p>
</dd></dl>

<dl class="class">
<dt id="twitter.TwitterResponse">
<em class="property">class </em><tt class="descclassname">twitter.</tt><tt class="descname">TwitterResponse</tt><big>(</big><em>headers</em><big>)</big><a class="headerlink" href="#twitter.TwitterResponse" title="Permalink to this definition"></a></dt>
<dd><p>Response from a twitter request. Behaves like a list or a string
(depending on requested format) but it has a few other interesting
attributes.</p>
<p><cite>headers</cite> gives you access to the response headers as an
httplib.HTTPHeaders instance. You can do
<cite>response.headers.getheader(&#8216;h&#8217;)</cite> to retrieve a header.</p>
<dl class="attribute">
<dt id="twitter.TwitterResponse.rate_limit_remaining">
<tt class="descname">rate_limit_remaining</tt><a class="headerlink" href="#twitter.TwitterResponse.rate_limit_remaining" title="Permalink to this definition"></a></dt>
<dd><p>Remaining requests in the current rate-limit.</p>
</dd></dl>

<dl class="attribute">
<dt id="twitter.TwitterResponse.rate_limit_reset">
<tt class="descname">rate_limit_reset</tt><a class="headerlink" href="#twitter.TwitterResponse.rate_limit_reset" title="Permalink to this definition"></a></dt>
<dd><p>Time in UTC epoch seconds when the rate limit will reset.</p>
</dd></dl>

</dd></dl>

<dl class="exception">
<dt id="twitter.TwitterError">
<em class="property">exception </em><tt class="descclassname">twitter.</tt><tt class="descname">TwitterError</tt><a class="headerlink" href="#twitter.TwitterError" title="Permalink to this definition"></a></dt>
<dd><p>Base Exception thrown by the Twitter object when there is a
general error interacting with the API.</p>
</dd></dl>

<dl class="exception">
<dt id="twitter.TwitterHTTPError">
<em class="property">exception </em><tt class="descclassname">twitter.</tt><tt class="descname">TwitterHTTPError</tt><big>(</big><em>e</em>, <em>uri</em>, <em>format</em>, <em>uriparts</em><big>)</big><a class="headerlink" href="#twitter.TwitterHTTPError" title="Permalink to this definition"></a></dt>
<dd><p>Exception thrown by the Twitter object when there is an
HTTP error interacting with twitter.com.</p>
</dd></dl>

<dl class="class">
<dt id="twitter.NoAuth">
<em class="property">class </em><tt class="descclassname">twitter.</tt><tt class="descname">NoAuth</tt><a class="headerlink" href="#twitter.NoAuth" title="Permalink to this definition"></a></dt>
<dd><p>No authentication authenticator.</p>
</dd></dl>

<dl class="class">
<dt id="twitter.OAuth">
<em class="property">class </em><tt class="descclassname">twitter.</tt><tt class="descname">OAuth</tt><big>(</big><em>token</em>, <em>token_secret</em>, <em>consumer_key</em>, <em>consumer_secret</em><big>)</big><a class="headerlink" href="#twitter.OAuth" title="Permalink to this definition"></a></dt>
<dd><p>An OAuth authenticator.</p>
</dd></dl>

<dl class="class">
<dt id="twitter.UserPassAuth">
<em class="property">class </em><tt class="descclassname">twitter.</tt><tt class="descname">UserPassAuth</tt><big>(</big><em>username</em>, <em>password</em><big>)</big><a class="headerlink" href="#twitter.UserPassAuth" title="Permalink to this definition"></a></dt>
<dd><p>Basic auth authentication using email/username and
password. Deprecated.</p>
</dd></dl>

<dl class="function">
<dt id="twitter.read_token_file">
<tt class="descclassname">twitter.</tt><tt class="descname">read_token_file</tt><big>(</big><em>filename</em><big>)</big><a class="headerlink" href="#twitter.read_token_file" title="Permalink to this definition"></a></dt>
<dd><p>Read a token file and return the oauth token and oauth token secret.</p>
</dd></dl>

<dl class="function">
<dt id="twitter.write_token_file">
<tt class="descclassname">twitter.</tt><tt class="descname">write_token_file</tt><big>(</big><em>filename</em>, <em>oauth_token</em>, <em>oauth_token_secret</em><big>)</big><a class="headerlink" href="#twitter.write_token_file" title="Permalink to this definition"></a></dt>
<dd><p>Write a token file to hold the oauth token and oauth token secret.</p>
</dd></dl>

</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
  <h3><a href="index.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">The Twitter Module</a><ul>
<li><a class="reference internal" href="#the-twitter-class">The Twitter class</a></li>
<li><a class="reference internal" href="#the-twitterstream-class">The TwitterStream class</a></li>
<li><a class="reference internal" href="#twitter-response-objects">Twitter Response Objects</a></li>
<li><a class="reference internal" href="#authentication-objects">Authentication Objects</a></li>
<li><a class="reference internal" href="#other-things">Other things</a></li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="djcelery.html"
                        title="previous chapter">The Django Celery Module</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="celery.html"
                        title="next chapter">The Celery Module</a></p>
  <h3>This Page</h3>
  <ul class="this-page-menu">
    <li><a href="_sources/twitter.txt"
           rel="nofollow">Show Source</a></li>
  </ul>
<div id="searchbox" style="display: none">
  <h3>Quick search</h3>
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="celery.html" title="The Celery Module"
             >next</a> |</li>
        <li class="right" >
          <a href="djcelery.html" title="The Django Celery Module"
             >previous</a> |</li>
        <li><a href="index.html">EggDiscover 0.1 documentation</a> &raquo;</li>
          <li><a href="externalapps.html" >External apps used in this project</a> &raquo;</li> 
      </ul>
    </div>
    <div class="footer">
        &copy; Copyright 2012, Yohann Gabory.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.2.
    </div>
  </body>
</html>