======
README
======

These are four contents.

- License_
- Required_
- Installation_
- Tutorial_
- `Sample Code`_


License
=======

**Copyright (c) 2010 Kenko Abe**

The MIT License. See the LICENSE.rst for the complete license.


Required
========

Twitter_oauth requires Python 2.x superior to 2.5.


These modules are required.

- oauth2


Installation
============

Install from sources

::

    $ sudo python setup.py install

From PyPI:

::

    $ sudo easy_install twitter_oauth


Tutorial
========

First, you shold have two keys, 
'consumer key', 'consumer secret'.

If you don't have 'consumer key' and 'consumer secret', 
you cat get these keys to register your application to Twitter.
You cat register your application at next URL.

`http://twitter.com/apps`_

.. _`http://twitter.com/apps`: http://twitter.com/apps




Then, you shold get two keys, 'oauth_token', and 'oauth_token_secret'

To get these keys, you use GetOauth class in this module.

::

    >>> import twitter_oauth

    >>> # write your key and secret
    >>> consumer_key = '***'
    >>> consumer_secret = '***'
    
    >>> get_oauth_obj = twitter_oauth.GetOauth(consumer_key, consumer_secret)


Then, you get 'oauth_token' and 'oauth_token_secret' by using get_oauth method.
This method returns a dictionary that contain 'consumer key', 'consumer secret',
'oauth_token' and 'oauth_token_secret'

::

    >>> get_oauth_obj.get_oauth()
      Request Token:
      - oauth_token        = ***
      - oauth_token_secret = ***
      Go to the following link in your browser
      http://twitter.com/oauth/authorize?oauth_token=***
              
      What is the PIN? ***
      Access Token:
      - oauth_token        = ***
      - oauth_token_secret = ***
              
      You may now access protected resources using the access token above
       
  
  
Now, you can use twitter_oauth.Api class.
To use this class, you can post update, or get friends timeline, etc...
    
Next example is how to use twitter_oauth.Api class

::

   >>> # import twitter_oauth module
    >>> import twitter_oauth
    
    >>> # write yoru consumer_key, consumer_secret,
    >>> # oauth_token, oauth_token_secret
    >>> consumer_key = '***'
    >>> consumer_secret = '***'
    >>> oauth_token        = '***'
    >>> oauth_token_secret = '***'

    >>> # Then, create Api instance

    >>> api = twitter_oauth.Api(consumer_key, consumer_secret,
    >>>                         oauth_token, oauth_token_secret)

Use get_friends_timeline method.
You can get friends timeline to use this method.

::

    >>> friends_timeline = api.get_friends_timeline()
    >>> print [stauts.text for status in friends_timeline]
    
    Use get_user_timeline method.
    You can get user timeline to use this method.
    
    >>> user_timeline = api.get_user_timeline()
    >>> print [stauts.text for status in user_timeline]
    
    Use get_replies method.
    You can get replies to use this method.
    
    >>> replies = api.get_replies()
    >>> print [stauts.text for status in replies]


Use post_update method 
You can post message to Twitter.

CAUTION : post_update method shold take a unicode.
Especially, you can post a Japanese text.

::

    >>> post_update(u'Hello, Twitter')


Methods:
You can use next methods

- post_update()
- get_user_timeline()
- get_friends_timeline()
- get_replies()
- destroy_status()

Sample Code
===========

::

    #! /usr/bin/env python
    # coding:utf-8
    
    import twitter_oauth
    
    # write your oauth token and oauth token secret
    consumer_key = '***'
    consumer_secret = '***'
    
    # create GetOauth instance
    get_oauth_obj = twitter_oauth.GetOauth(consumer_key, consumer_secret)
    
    # get oauth_token and oauth token secret
    key_dict = get_oauth_obj.get_oauth()
    
    # create Api instance
    api = twitter_oauth.Api(consumer_key, consumer_secret, key_dict['oauth_token'], key_dict['oauth_token_secret'])
    
    # get friends timeline
    print [status.text for status in api.get_friends_timeline()]
    
    # get user timeline
    print [status.text for status in api.get_user_timeline()]
    
    # get replies
    print [status.text for status in api.get_replies()]
    
    # post update
    api.post_update(u'Hello, Twitter')
