diff --git a/doc/getting_started.rst b/doc/getting_started.rst new file mode 100644 index 00000000..ee478b27 --- /dev/null +++ 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 `_ 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 `_. 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 `_. If you have an open source application using python-twitter, send us a link and we'll add a link to it here. \ No newline at end of file diff --git a/doc/index.rst b/doc/index.rst index d89f2e67..e33b237a 100644 --- 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 new file mode 100644 index 00000000..1686de68 Binary files /dev/null and b/doc/python-twitter-app-creation-part1.png differ diff --git a/doc/python-twitter-app-creation-part2.png b/doc/python-twitter-app-creation-part2.png new file mode 100644 index 00000000..9ab561fc Binary files /dev/null and b/doc/python-twitter-app-creation-part2.png differ diff --git a/doc/python-twitter-app-creation-part3.png b/doc/python-twitter-app-creation-part3.png new file mode 100644 index 00000000..9c29b360 Binary files /dev/null and b/doc/python-twitter-app-creation-part3.png differ diff --git a/doc/twitter.rst b/doc/twitter.rst index 879d4f27..88fe4ed5 100644 --- a/doc/twitter.rst +++ b/doc/twitter.rst @@ -1,8 +1,8 @@ -python-twitter package -============= +Modules Documentation +===================== -twitter.api +API ---------------- .. automodule:: twitter.api @@ -10,6 +10,9 @@ twitter.api :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 index 8c7653de..e07ee7a3 100755 --- 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 new file mode 100644 index 00000000..fab36d55 --- /dev/null +++ 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()