From 9f864a341cc756a0ecd5da5160a0139fabf83856 Mon Sep 17 00:00:00 2001 From: Mike Helmick Date: Thu, 13 Jun 2013 11:05:18 -0400 Subject: [PATCH] Updating docs [ci skip] --- docs/_static/custom.css | 10 ++++++++++ docs/usage/advanced_usage.rst | 22 +++++++++++---------- docs/usage/basic_usage.rst | 23 ++++++++++++++-------- docs/usage/install.rst | 24 +++++++++++++++++------ docs/usage/starting_out.rst | 37 +++++++++++++++++++++++------------ docs/usage/streaming_api.rst | 6 +++--- 6 files changed, 83 insertions(+), 39 deletions(-) diff --git a/docs/_static/custom.css b/docs/_static/custom.css index b7694cc..c9aa856 100644 --- a/docs/_static/custom.css +++ b/docs/_static/custom.css @@ -11,3 +11,13 @@ margin-right: 115px !important; } } + +.literal { + background: #f5f5f5; + padding: 2px 3px 3px; + border: 1px solid #ccc; + color: #11729B; + -webkit-border-radius: 3px; + border-radius: 3px; + margin: 0 3px; +} diff --git a/docs/usage/advanced_usage.rst b/docs/usage/advanced_usage.rst index fa75c67..5f5cb49 100644 --- a/docs/usage/advanced_usage.rst +++ b/docs/usage/advanced_usage.rst @@ -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 ` the user! +Before you make any API calls, make sure you :ref:`authenticated the user ` (or :ref:`app `)! .. 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 `_ 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 diff --git a/docs/usage/basic_usage.rst b/docs/usage/basic_usage.rst index 6efad57..cea60f0 100644 --- a/docs/usage/basic_usage.rst +++ b/docs/usage/basic_usage.rst @@ -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 ` the user! +Before you make any API calls, make sure you :ref:`authenticated the user ` (or :ref:`app `)! .. 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 ` a little more, you can see that the previous call used the keyword argument ``q``, that is because Twitter specifies in their `search documentation `_ 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 ` section, for some functions that may be a little more complicated. diff --git a/docs/usage/install.rst b/docs/usage/install.rst index 8bcff34..abd8049 100644 --- a/docs/usage/install.rst +++ b/docs/usage/install.rst @@ -10,11 +10,15 @@ Information on how to properly install Twython Pip or Easy Install ------------------- -Install Twython via `pip `_:: +Install Twython via `pip `_ + +.. code-block:: bash $ pip install twython -or, with `easy_install `_:: +or, with `easy_install `_ + +.. 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 `_:: +`tarball `_ + +.. code-block:: bash $ curl -OL https://github.com/ryanmcgrath/twython/tarball/master -`zipball `_:: +`zipball `_ + +.. 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 diff --git a/docs/usage/starting_out.rst b/docs/usage/starting_out.rst index a46d166..0525ac0 100644 --- a/docs/usage/starting_out.rst +++ b/docs/usage/starting_out.rst @@ -23,7 +23,7 @@ Twython offers support for both OAuth 1 and OAuth 2 authentication. The difference: -- :ref:`OAuth 1 ` is for user authenticated calls (tweeting, following people, sneding DMs, etc.) +- :ref:`OAuth 1 ` is for user authenticated calls (tweeting, following people, sending DMs, etc.) - :ref:`OAuth 2 ` 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 ` 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' diff --git a/docs/usage/streaming_api.rst b/docs/usage/streaming_api.rst index ec62800..8b21c70 100644 --- a/docs/usage/streaming_api.rst +++ b/docs/usage/streaming_api.rst @@ -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)