bear · bear · Feb 19, 2016 · Jan 24, 2016 · Jan 25, 2016 · Feb 18, 2016
diff --git a/doc/getting_started.rst b/doc/getting_started.rst
@@ -0,0 +1,49 @@
+Getting Started
+===============
+
+Getting your application tokens
++++++++++++++++++++++++++++++++
+
+.. danger::
+
+This section is subject to changes made by Twitter and may not always be completely up-to-date. If you see something change on their end, please create a `new issue on Github <https://github.com/bear/python-twitter/issues/new>`_ or submit a pull request to update it.
+
+
+In order to use the python-twitter API client, you first need to acquire a set of application tokens. These will be your ``consumer_key`` and ``consumer_secret``, which get passed to ``twitter.Api()`` when starting your application.
+
+Create your app
+________________
+
+The first step in doing so is to create a `Twitter App <https://apps.twitter.com/>`_. Click the "Create New App" button and fill out the fields on the next page.
+
+
+.. image:: python-twitter-app-creation-part1.png
+
+If there are any problems with the information on that page, Twitter will complain and you can fix it. (Make sure to get the name correct - it is unclear if you can change this later.) On the next screen, you'll see the application that you created and some information about it:
+
+Your app
+_________
+
+Once your app is created, you'll be directed to a new page showing you some information about it.
+
+.. image:: python-twitter-app-creation-part2.png
+
+Your Keys
+_________
+
+Click on the "Keys and Access Tokens" tab on the top there, just under the green notification in the image above.
+
+
+.. image:: python-twitter-app-creation-part3.png
+
+At this point, you can test out your application using the keys under "Your Application Tokens". The ``twitter.Api()`` object can be created as follows::
+
+    import twitter
+    api = twitter.Api(consumer_key=[consumer key],
+                      consumer_secret=[consumer secret],
+                      access_token_key=[access token]
+                      access_token_secret=[access token secret])
+
+If you are creating an application for end users/consumers, then you will want them to authorize you application, but that is outside the scope of this document.
+
+And that should be it! If you need a little more help, check out the `examples on Github <https://github.com/bear/python-twitter/tree/master/examples>`_. If you have an open source application using python-twitter, send us a link and we'll add a link to it here.
diff --git a/doc/index.rst b/doc/index.rst
@@ -13,10 +13,12 @@ Contents:
    :maxdepth: 1
 
    installation.rst
+   getting_started.rst
    migration_v30.rst
    models.rst
    searching.rst
    with_django.rst
+   twitter.rst
 
 
 Introduction

diff --git a/doc/python-twitter-app-creation-part1.png b/doc/python-twitter-app-creation-part1.png
diff --git a/doc/python-twitter-app-creation-part2.png b/doc/python-twitter-app-creation-part2.png
diff --git a/doc/python-twitter-app-creation-part3.png b/doc/python-twitter-app-creation-part3.png
diff --git a/doc/twitter.rst b/doc/twitter.rst
@@ -1,15 +1,18 @@
-python-twitter package
-=============
+Modules Documentation
+=====================
 
 
-twitter.api
+API
 ----------------
 
 .. automodule:: twitter.api
     :members:
     :undoc-members:
     :show-inheritance:
 
+Models
+---------------------
+
 .. automodule:: twitter.category
     :members:
     :undoc-members:
@@ -60,6 +63,10 @@ twitter.api
     :undoc-members:
     :show-inheritance:
 
+
+Utilities
+---------------------
+
 .. automodule:: twitter.twitter_utils
     :members:
     :undoc-members:

diff --git a/examples/shorten_url.py b/examples/shorten_url.py
@@ -1,46 +1,77 @@
 #!/usr/bin/env python
-#
-# Copyright 2007-2013 The Python-Twitter Developers
-#
+
+# Copyright 2007-2016 The Python-Twitter Developers
+
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
-#
+
 # http://www.apache.org/licenses/LICENSE-2.0
-#
+
 # Unless required by applicable law or agreed to in writing, software
 # distributed under the License is distributed on an "AS IS" BASIS,
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""A class that defines the default URL Shortener.
-
-TinyURL is provided as the default and as an example.
-"""
-
-import urllib
-
-
+# ----------------------------------------------------------------------
 # Change History
 #
 # 2010-05-16
-#     TinyURL example and the idea for this comes from a bug filed by
-#     acolorado with patch provided by ghills.  Class implementation
-#     was done by bear.
+#   TinyURL example and the idea for this comes from a bug filed by
+#   acolorado with patch provided by ghills.  Class implementation
+#   was done by @bear.
 #
-#     Issue 19 http://code.google.com/p/python-twitter/issues/detail?id=19
+#   Issue #19: http://code.google.com/p/python-twitter/issues/detail?id=19
 #
+# 2016-02-18
+#   Updated example with code to demonstrate passing a status message through
+#   a shortener and then off to PostUpdate. Implemenation by @jeremylow from
+#   bug filed by @immanuelfactor
+#
+#   Issue #298: https://github.com/bear/python-twitter/issues/298
+
+# ----------------------------------------------------------------------
+# This file demonstrates how to shorten all URLs contained within a Tweet
+# by passing the tweet text to a shortener. In this case, we're using TinyURL
+# since it does not require any real authentication for our purposes. If you
+# are using a different service to shorten URLs, then you will need to modify
+# the ShortenURL class to suit your needs.
+
+# Note that this example shortens all URLs contained within the Tweet text.
+
+# To use this example, replace the W/X/Y/Zs with your keys obtained from
+# Twitter, or uncomment the lines for getting an environment variable. If you
+# are using a virtualenv on Linux, you can set environment variables in the
+# ~/VIRTUALENVDIR/bin/activate script.
+
+# If you need assistance with obtaining keys from Twitter, see the instructions
+# in doc/getting_started.rst.
+
+
+import re
+try:
+    from urllib.request import urlopen
+except:
+    from urllib2 import urlopen
+
+from twitter import Api
+from twitter.twitter_utils import URL_REGEXP
 
 
 class ShortenURL(object):
-    """Helper class to make URL Shortener calls if/when required"""
+    """ A class that defines the default URL Shortener.
+
+    TinyURL is provided as the default and as an example helper class to make
+    URL Shortener calls if/when required. """
 
     def __init__(self,
                  userid=None,
                  password=None):
-        """Instantiate a new ShortenURL object
-
+        """Instantiate a new ShortenURL object. TinyURL, which is used for this
+        example, does not require a userid or password, so you can try this
+        out without specifying either.
+
         Args:
             userid:   userid for any required authorization call [optional]
             password: password for any required authorization call [optional]
@@ -49,24 +80,68 @@ def __init__(self,
         self.password = password
 
     def Shorten(self,
-                longURL):
-        """Call TinyURL API and returned shortened URL result
-        
+                long_url):
+        """ Call TinyURL API and returned shortened URL result.
+
         Args:
-            longURL: URL string to shorten
-        
+            long_url: URL string to shorten
+
         Returns:
             The shortened URL as a string
 
         Note:
-            longURL is required and no checks are made to ensure completeness
+            long_url is required and no checks are made to ensure completeness
         """
 
         result = None
-        f = urllib.urlopen("http://tinyurl.com/api-create.php?url=%s" % longURL)
+        f = urlopen("http://tinyurl.com/api-create.php?url={0}".format(
+            long_url))
         try:
             result = f.read()
         finally:
             f.close()
 
-        return result
+        # The following check is required for py2/py3 compatibility, since
+        # urlopen on py3 returns a bytes-object, and urlopen on py2 returns a
+        # string.
+        if isinstance(result, bytes):
+            return result.decode('utf8')
+        else:
+            return result
+
+
+def _get_api():
+    # Either specify a set of keys here or use os.getenv('CONSUMER_KEY') style
+    # assignment:
+
+    CONSUMER_KEY = 'WWWWWWWW'
+    # CONSUMER_KEY = os.getenv("CONSUMER_KEY", None)
+    CONSUMER_SECRET = 'XXXXXXXX'
+    # CONSUMER_SECRET = os.getenv("CONSUMER_SECRET", None)
+    ACCESS_TOKEN = 'YYYYYYYY'
+    # ACCESS_TOKEN = os.getenv("ACCESS_TOKEN", None)
+    ACCESS_TOKEN_SECRET = 'ZZZZZZZZ'
+    # ACCESS_TOKEN_SECRET = os.getenv("ACCESS_TOKEN_SECRET", None)
+
+    return Api(CONSUMER_KEY,
+               CONSUMER_SECRET,
+               ACCESS_TOKEN,
+               ACCESS_TOKEN_SECRET)
+
+
+def PostStatusWithShortenedURL(status):
+    shortener = ShortenURL()
+    api = _get_api()
+
+    # Find all URLs contained within the status message. Value of ``urls`` will
+    # be a list.
+    urls = re.findall(URL_REGEXP, status)
+
+    for url in urls:
+        status = status.replace(url, shortener.Shorten(url), 1)
+
+    api.PostUpdate(status)
+
+
+if __name__ == '__main__':
+    PostStatusWithShortenedURL("this is a test: http://www.example.com/tests")
diff --git a/examples/streaming/track_users.py b/examples/streaming/track_users.py
@@ -0,0 +1,73 @@
+#!/usr/bin/env python
+
+# Copyright 2007-2016 The Python-Twitter Developers
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+# http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# ----------------------------------------------------------------------
+
+# This file demonstrates how to track mentions of a specific set of users and
+# archive those mentions to a local file. The output file will contain one
+# JSON string per line per Tweet.
+
+# To use this example, replace the W/X/Y/Zs with your keys obtained from
+# Twitter, or uncomment the lines for getting an environment variable. If you
+# are using a virtualenv on Linux, you can set environment variables in the
+# ~/VIRTUALENVDIR/bin/activate script.
+
+# If you need assistance with obtaining keys from Twitter, see the instructions
+# in doc/getting_started.rst.
+
+import os
+import json
+
+from twitter import Api
+
+# Either specify a set of keys here or use os.getenv('CONSUMER_KEY') style
+# assignment:
+
+CONSUMER_KEY = 'WWWWWWWW'
+# CONSUMER_KEY = os.getenv("CONSUMER_KEY", None)
+CONSUMER_SECRET = 'XXXXXXXX'
+# CONSUMER_SECRET = os.getenv("CONSUMER_SECRET", None)
+ACCESS_TOKEN = 'YYYYYYYY'
+# ACCESS_TOKEN = os.getenv("ACCESS_TOKEN", None)
+ACCESS_TOKEN_SECRET = 'ZZZZZZZZ'
+# ACCESS_TOKEN_SECRET = os.getenv("ACCESS_TOKEN_SECRET", None)
+
+# Users to watch for should be a list. This will be joined by Twitter and the
+# data returned will be for any tweet mentioning:
+# @twitter *OR* @twitterapi *OR* @support.
+USERS = ['@twitter',
+         '@twitterapi',
+         '@support']
+
+# Since we're going to be using a streaming endpoint, there is no need to worry
+# about rate limits.
+api = Api(CONSUMER_KEY,
+          CONSUMER_SECRET,
+          ACCESS_TOKEN,
+          ACCESS_TOKEN_SECRET)
+
+
+def main():
+    with open('output.txt', 'a') as f:
+        # api.GetStreamFilter will return a generator that yields one status
+        # message (i.e., Tweet) at a time as a JSON dictionary.
+        for line in api.GetStreamFilter(track=USERS):
+            f.write(json.dumps(line))
+            f.write('\n')
+
+
+if __name__ == '__main__':
+    main()