2.5 docs

docs/README.rst

@@ -0,0 +1,37 @@
+Instructions for Generating Documentation with Sphinx
+=====================================================
+
+Generate HTML Files
+-------------------
+
+In a command shell::
+
+	cd TwitterAPI\docs
+
+Edit RST files.
+
+In a command shell::
+
+	make html
+
+Open in a browser::
+
+	TwitterAPI\docs\_build\html\index.html
+
+Repeat until happy
+
+Clean Up
+--------
+
+In a command shell::
+
+	rm -r TwitterAPI\docs\_build
+
+Publish to Git Repository
+-------------------------
+
+In a command shell::
+
+	git add *
+	git commit -am '2.2.4 docs'
+	git push origin gh-pages

docs/authentication.rst

@@ -1,9 +1,9 @@
 Authentication
 ==============
 
-The first thing you need to do is create an application on `apps.twitter.com <http://apps.twitter.com>`_ and generate your oAuth keys. 
+Before you can do anything you must create an application on `apps.twitter.com <http://apps.twitter.com>`_ and generate oAuth keys. 
 
-Twitter supports both user and application authentication, known as oAuth 1 and oAuth 2, respectively. User authentication gives you access to all API endpoints, basically read and write persmission. Application authentication gives you access to just the read portion of the API -- so, no creating or destroying tweets. Application authentication also has elevated rate limits.
+Twitter supports both user and application authentication, called oAuth 1 and oAuth 2, respectively. User authentication gives you access to all API endpoints, basically read and write persmission. It is also required in order to using the Streaming API. Application authentication gives you access to just the read portion of the API -- so, no creating or destroying tweets. Application authentication, however, has elevated rate limits.
 
 User Authentication
 -------------------

docs/conf.py

@@ -53,9 +53,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '2.3'
+version = '2.5'
 # The full version, including alpha/beta/rc tags.
-release = '2.3'
+release = '2.5'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/errors.rst

@@ -1,7 +1,7 @@
 Error Handling
 ==============
 
-Besides tweet statuses, the REST API and Streaming API iterators may return error and other messages. It is up to the application to test what type of object has been returned. Message types are documented `here <http://dev.twitter.com/overview/api/response-codes>`_ and `here <http://dev.twitter.com/streaming/overview/messages-types>`_.
+Besides tweet statuses, the REST API and Streaming API iterators can return errors and other messages. It is up to the application to test what type of object has been returned. Message types are documented `here <http://dev.twitter.com/overview/api/response-codes>`_ and `here <http://dev.twitter.com/streaming/overview/messages-types>`_.
 
 REST API Messages
 -----------------
@@ -20,7 +20,7 @@ REST API endpoints can return many more types of messages than Streaming API end
 Streaming API Messages
 ----------------------
 
-Streaming API endpoints return a variety of messages, most are not really errors. For example, a "limit" message contains the number of tweets missing from the stream. This happens when the number of tweets matching your filter exceeds a threshold set by Twitter. Other useful messages are "disconnect" and "delete". The pattern is similar to the one preceding:
+Streaming API endpoints return a variety of messages. Some are not errors. For example, a "limit" message contains the number of tweets missing from the stream. This happens when the number of tweets matching your filter exceeds a threshold set by Twitter. Other useful messages are "disconnect" and "delete".
 
 .. code-block:: python
 
@@ -34,4 +34,4 @@ Streaming API endpoints return a variety of messages, most are not really errors
             print 'disconnecting because %s' % item['disconnect']['reason']
             break
 
-Even if you are not interested in handling errors it is necessary to test that the object returned by an iterator is a valid tweet status before using the object.
+Even if you are not interested in handling errors it is necessary to test that the object returned by an iterator is a valid tweet status before using the object. Valid tweet objects have a 'text' property (or a 'full_text' property if it is an extended tweet).

docs/faulttolerance.rst

@@ -53,10 +53,9 @@ One final consideration is the endpoint's rate limit, determinted by the endpoin
 .. code-block:: python
 
     iterator = TwitterPager(api, 'search/tweets', {'q':'pizza'}).get_iterator(wait=2)
-    try:
-        for item in iterator:
-            if 'text' in item:
-                print(item['text'])
-            elif 'message' in item:
-                # something needs to be fixed before re-connecting
-                raise Exception(item['message'])
+    for item in iterator:
+        if 'text' in item:
+            print(item['text'])
+        elif 'message' in item:
+            # something needs to be fixed before re-connecting
+            raise Exception(item['message'])

docs/index.rst

@@ -3,7 +3,7 @@ Introduction
 
 *Minimal Python wrapper for Twitter's REST and Streaming APIs*
 
-The principle behind TwitterAPI's design is to provide a single method for accessing the Twitter API. You can call the ``request`` method with *any* endpoint found on Twitter's `developer site <https://dev.twitter.com/overview/documentation>`_, the complete reference for all endpoints. The benefits of a single-method approach are: less code for me to maintain, and just a single method for you to learn. Here is a quck example:
+The principle behind TwitterAPI's design is to provide a single method for accessing the Twitter API. The ``request`` method allows one to call *any* endpoint found on Twitter's `developer site <https://dev.twitter.com/overview/documentation>`_, the complete reference for all endpoints. The benefits of a single-method approach are: 1) less code for me to maintain, and 2) a single method for you to learn. Here is a quck example:
 
 .. code-block:: python
 
@@ -12,16 +12,16 @@ The principle behind TwitterAPI's design is to provide a single method for acces
     r = api.request('search/tweets', {'q':'pizza'})
     print r.status_code
 
-If you want Twitter's entire response as one long string, containing tweets in this example, you would use ``r.text``. But, often an iterator is more useful:
+Get Twitter's entire response as one long string containing tweets (in this example) by calling ``r.text``. More often an iterator is useful:
 
 .. code-block:: python
 
     for item in r.get_iterator():
         print item['user']['screen_name'], item['text']
 
-The iterator returns decoded JSON objects. What makes the iterator very powerful is it works with both REST API and Streaming API endpoints. No syntax changes required; just supply any endpoint and parameters that are found on Twitter's dev site.
+The iterator returns JSON objects. What makes the iterator very powerful is it works with both REST API and Streaming API endpoints. No syntax changes required -- supply any endpoint and parameters that are found on Twitter's developer site.
 
-TwitterAPI is compatible with Python 2 and Python 3. It authenticates using either OAauth 1 or OAuth 2. It also supports web proxy server authentication. All with very little code change for you.
+TwitterAPI is compatible with Python 2 and Python 3. It authenticates using either OAauth 1 or OAuth 2. It also supports web proxy server authentication. All this with minimal code change for you.
 
 Topics
 ======
@@ -30,10 +30,10 @@ Topics
    :maxdepth: 1
 
    authentication.rst
-   errors.rst
    paging.rst
-   examples.rst
+   errors.rst
    faulttolerance.rst
+   examples.rst
 
 Modules
 =======

docs/paging.rst

@@ -1,9 +1,7 @@
 Paging Results
 ==============
 
-Paging refers to getting successive batches of results. The Streaming API endpoints in a sense do this inherently. REST API endpoints will never return more than a specificied maximum number of results. When you request `search/tweets`, for example, by default you will get at most 20 tweets. You can increase that number to a maximum of 100. This is the page size. Twitter provides a `way <http://dev.twitter.com/rest/public/timelines>`_ to get successive pages, so it is possible to get more than 100 tweets with `search/tweets`, just not in a single request.
-
-If you don't want to implement paging yourself, you can use the `TwitterPager <./twitterpager.html>`_ helper class with any REST API endpoint that returns multiples of something. The following, for example, searches for all tweets containing 'pizza' that Twitter has stored -- about a week's worth.
+Whether one is searching for tweets with `search/tweets` or downloading a user's timeline with `statuses/user_timeline` Twitter limits the number of tweets. So, in order to get more tweets, one must make successive requests and with each request skip the previously acquired tweets. This is done by specifying the tweet id from where to start. Twitter has a description `here <http://dev.twitter.com/rest/public/timelines>`_. If you don't want to implement paging yourself, you can use the `TwitterPager <./twitterpager.html>`_ helper class with any REST API endpoint that returns multiples of something. The following, for example, searches for all tweets containing 'pizza' that Twitter has stored -- up to about a week's worth maximum.
 
 .. code-block:: python 
 
@@ -14,3 +12,5 @@ If you don't want to implement paging yourself, you can use the `TwitterPager <.
         elif 'message' in item and item['code'] == 88:
             print 'SUSPEND, RATE LIMIT EXCEEDED: %s\n' % item['message']
             break
+
+By default there is a built-in wait time of 5 seconds between successive calls. This value is overridden with an argument to `get_iterator()`. See the documentation also to learn how to wait for new tweets. In other words, the iterator can be setup to poll for newer pages of tweets rather than older pages.