code/twython
1
Fork 0
Code Issues 23 Pull requests 4 Projects Releases 5 Packages Wiki Activity Actions

Updating docs

Browse source 
[ci skip]
This commit is contained in:
Mike Helmick 2013-06-13 11:05:18 -04:00
parent 8a1b55e343
commit 9f864a341c
6 changed files with 83 additions and 39 deletions
Download patch file Download diff file Expand all files Collapse all files

22
docs/usage/advanced_usage.rst
View file

@ -3,15 +3,17 @@
Advanced Usage
==============
This section will cover how to use Twython and interact with some a little more advanced API calls
This section will cover how to use Twython and interact with some more advanced API calls
Before you make any API calls, make sure you :ref:`authenticated <starting-out>` the user!
Before you make any API calls, make sure you :ref:`authenticated the user <starting-out>` (or :ref:`app <oauth2>`)!
.. note:: All sections on this page will assume you're using a Twython instance
*******************************************************************************
Create a Twython instance with your application keys and the users OAuth tokens::
Create a Twython instance with your application keys and the users OAuth tokens
.. code-block:: python
from twython import Twython
twitter = Twython(APP_KEY, APP_SECRET
@ -22,17 +24,17 @@ Updating Status with Image
Documentation: https://dev.twitter.com/docs/api/1.1/get/account/verify_credentials
::
.. code-block:: python
photo = open('/path/to/file/image.jpg', 'rb')
twitter.update_status_with_media(status='Checkout this cool image!', media=photo)
Posting a Status with an Editing Image
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--------------------------------------
This example resizes an image
::
.. code-block:: python
# Assume you are working with a JPEG
@ -63,7 +65,7 @@ So, if you're pretty into Python, you probably know about `generators <http://do
That being said, Twython offers a generator for search results and can be accessed by using the following code:
::
.. code-block:: python
search = twitter.search_gen('python')
for result in search:
@ -78,7 +80,7 @@ Twython uses the `requests <http://python-requests.org>`_ library to make API ca
Here is an example of sending custom headers to a Twitter API request:
::
.. code-block:: python
from twython import Twython
@ -94,7 +96,7 @@ Here is an example of sending custom headers to a Twitter API request:
Here is an example of sending the request through proxies:
::
.. code-block:: python
from twython import Twython
@ -111,7 +113,7 @@ Here is an example of sending the request through proxies:
or both (and set a timeout variable):
::
.. code-block:: python
from twython import Twython

23
docs/usage/basic_usage.rst
View file

@ -5,7 +5,7 @@ Basic Usage
This section will cover how to use Twython and interact with some basic Twitter API calls
Before you make any API calls, make sure you :ref:`authenticated <starting-out>` the user!
Before you make any API calls, make sure you :ref:`authenticated the user <oauth1>` (or :ref:`app <oauth2>`)!
.. note:: All sections on this page will assume you're using a Twython instance
@ -17,7 +17,9 @@ Authenticated Calls
OAuth 1
~~~~~~~
Create a Twython instance with your application keys and the users OAuth tokens::
Create a Twython instance with your application keys and the users OAuth tokens
.. code-block:: python
from twython import Twython
twitter = Twython(APP_KEY, APP_SECRET
@ -28,7 +30,7 @@ User Information
Documentation: https://dev.twitter.com/docs/api/1.1/get/account/verify_credentials
::
.. code-block:: python
twitter.verify_credentials()
@ -37,7 +39,7 @@ Authenticated Users Home Timeline
Documentation: https://dev.twitter.com/docs/api/1.1/get/statuses/home_timeline
::
.. code-block:: python
twitter.get_home_timeline()
@ -48,7 +50,7 @@ This method makes use of dynamic arguments, :ref:`read more about them <dynamica
Documentation: https://dev.twitter.com/docs/api/1/post/statuses/update
::
.. code-block:: python
twitter.update_status(status='See how easy using Twython is!')
@ -56,7 +58,9 @@ Documentation: https://dev.twitter.com/docs/api/1/post/statuses/update
OAuth 2
~~~~~~~
Create a Twython instance with your application key and access token::
Create a Twython instance with your application key and access token
.. code-block:: python
from twython import Twython
twitter = Twython(APP_KEY, access_token=ACCESS_TOKEN)
@ -70,7 +74,7 @@ Searching
Documentation: https://dev.twitter.com/docs/api/1.1/get/search/tweets
::
.. code-block:: python
twitter.search(q='python')
@ -78,7 +82,10 @@ Documentation: https://dev.twitter.com/docs/api/1.1/get/search/tweets
.. important:: To help explain :ref:`dynamic function arguments <dynamicfunctionarguments>` a little more, you can see that the previous call used the keyword argument ``q``, that is because Twitter specifies in their `search documentation <https://dev.twitter.com/docs/api/1.1/get/search/tweets>`_ that the search call accepts the parameter "q". You can pass mutiple keyword arguments. The search documentation also specifies that the call accepts the parameter "result_type"
::
.. code-block:: python
twitter.search(q='python', result_type='popular')
*******************************************************************************
So, now, you're pretty well versed on making authenticated calls to Twitter using Twython. Check out the :ref:`advanced usage <advanced-usage>` section, for some functions that may be a little more complicated.

24
docs/usage/install.rst
View file

@ -10,11 +10,15 @@ Information on how to properly install Twython
Pip or Easy Install
-------------------
Install Twython via `pip <http://www.pip-installer.org/>`_::
Install Twython via `pip <http://www.pip-installer.org/>`_
.. code-block:: bash
$ pip install twython
or, with `easy_install <http://pypi.python.org/pypi/setuptools>`_::
or, with `easy_install <http://pypi.python.org/pypi/setuptools>`_
.. code-block:: bash
$ easy_install twython
@ -26,19 +30,27 @@ Source Code
Twython is actively maintained on GitHub
Feel free to clone the repository::
Feel free to clone the repository
.. code-block:: bash
git clone git://github.com/ryanmcgrath/twython.git
`tarball <https://github.com/ryanmcgrath/twython/tarball/master>`_::
`tarball <https://github.com/ryanmcgrath/twython/tarball/master>`_
.. code-block:: bash
$ curl -OL https://github.com/ryanmcgrath/twython/tarball/master
`zipball <https://github.com/ryanmcgrath/twython/tarball/master>`_::
`zipball <https://github.com/ryanmcgrath/twython/tarball/master>`_
.. code-block:: bash
$ curl -OL https://github.com/ryanmcgrath/twython/zipball/master
Now that you have the source code, install it into your site-packages directory::
Now that you have the source code, install it into your site-packages directory
.. code-block:: bash
$ python setup.py install

37
docs/usage/starting_out.rst
View file

@ -23,7 +23,7 @@ Twython offers support for both OAuth 1 and OAuth 2 authentication.
The difference:
- :ref:`OAuth 1 <oauth1>` is for user authenticated calls (tweeting, following people, sneding DMs, etc.)
- :ref:`OAuth 1 <oauth1>` is for user authenticated calls (tweeting, following people, sending DMs, etc.)
- :ref:`OAuth 2 <oauth2>` is for application authenticated calls (when you don't want to authenticate a user and make read-only calls to Twitter, i.e. searching, reading a public users timeline)
.. _oauth1:
@ -33,7 +33,9 @@ OAuth 1 (User Authentication)
.. important:: Again, if your web app is planning on using interacting with users, this **IS** the authentication type for you. If you're not interested in authenticating a user and plan on making read-only calls, check out the :ref:`OAuth 2 <oauth2>` section.
First, you'll want to import Twython::
First, you'll want to import Twython
.. code-block:: python
from twython import Twython
@ -42,7 +44,7 @@ Now, you'll want to create a Twython instance with your ``Consumer Key`` and ``C
Obtain Authorization URL
^^^^^^^^^^^^^^^^^^^^^^^^
::
.. code-block:: python
APP_KEY = 'YOUR_APP_KEY'
APP_SECET = 'YOUR_APP_SECRET'
@ -50,11 +52,15 @@ Obtain Authorization URL
twitter = Twython(APP_KEY, APP_SECRET)
auth = twitter.get_authentication_tokens(callback_url='http://mysite.com/callback')
From the ``auth`` variable, save the ``oauth_token_secret`` for later use. In Django or other web frameworks, you might want to store it to a session variable::
From the ``auth`` variable, save the ``oauth_token_secret`` for later use. In Django or other web frameworks, you might want to store it to a session variable
.. code-block:: python
OAUTH_TOKEN_SECRET = auth['oauth_token_secret']
Send the user to the authentication url, you can obtain it by accessing::
Send the user to the authentication url, you can obtain it by accessing
.. code-block:: python
auth['auth_url']
@ -66,19 +72,24 @@ After they authorize your application to access some of their account details, t
You'll want to extract the ``oauth_token`` and ``oauth_verifier`` from the url.
Django example:
::
.. code-block:: python
OAUTH_TOKEN = request.GET['oauth_token']
oauth_verifier = request.GET['oauth_verifier']
Now that you have the ``oauth_token`` and ``oauth_verifier`` stored to variables, you'll want to create a new instance of Twython and grab the final user tokens::
Now that you have the ``oauth_token`` and ``oauth_verifier`` stored to variables, you'll want to create a new instance of Twython and grab the final user tokens
.. code-block:: python
twitter = Twython(APP_KEY, APP_SECRET,
OAUTH_TOKEN, OAUTH_TOKEN_SECRET)
final_step = twitter.get_authorized_tokens(oauth_verifier)
Once you have the final user tokens, store them in a database for later use!::
Once you have the final user tokens, store them in a database for later use!
.. code-block:: python
OAUTH_TOKEN = final_step['oauth_token']
OAUTH_TOKEN_SECERT = final_step['oauth_token_secret']
@ -93,14 +104,16 @@ OAuth 2 (Application Authentication)
OAuth 2 authentication is 100x easier than OAuth 1.
Let's say you *just* made your application and have your ``Consumer Key`` and ``Consumer Secret``
First, you'll want to import Twython::
First, you'll want to import Twython
.. code-block:: python
from twython import Twython
Obtain an OAuth 2 Access Token
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
::
.. code-block:: python
APP_KEY = 'YOUR_APP_KEY'
APP_SECET = 'YOUR_APP_SECRET'
@ -108,12 +121,12 @@ Obtain an OAuth 2 Access Token
twitter = Twython(APP_KEY, APP_SECRET, oauth_version=2)
ACCESS_TOKEN = twitter.obtain_access_token()
# Save ACCESS_TOKEN in a database or something for later use!
Save ``ACCESS_TOKEN`` in a database or something for later use!
Use the Access Token
^^^^^^^^^^^^^^^^^^^^
::
.. code-block:: python
APP_KEY = 'YOUR_APP_KEY'
ACCESS_TOKEN = 'YOUR_ACCESS_TOKEN'

6
docs/usage/streaming_api.rst
View file

@ -16,13 +16,13 @@ Setting Up Your Streamer
Make sure you import ``TwythonStreamer``
::
.. code-block:: python
from twython import TwythonStreamer
Now set up how you want to handle the signals.
::
.. code-block:: python
class MyStreamer(TwythonStreamer):
def on_success(self, data):
@ -41,7 +41,7 @@ More signals that you can extend on can be found in the Developer Interface sect
Filtering Public Statuses
-------------------------
::
.. code-block:: python
stream = MyStreamer(APP_KEY, APP_SECRET,
OAUTH_TOKEN, OAUTH_TOKEN_SECRET)