May 25, 2011

Python Twitter API python-twitter の使い方 (Part2): 初歩的なAPI





PythonでTwitterアプリケーションを作る時には、Pyton Twitter APIであるpython-twitter。これを使ってまずはTwitter APIに慣れることから始めると良いと思います。私も今まさにこれから始めています。

※ この記事は、Pythonの環境があって基本的なコードが書けて、これからTwitter APIを学習したい方向けに書かれています。


さて、公式ドキュメントは以下のコマンドでローカルでも参照可能です。



% pydoc twitter

Help on module twitter:

NAME
twitter - A library that provides a Python interface to the Twitter API

FILE
/usr/local/lib/python2.7/dist-packages/python_twitter-0.8.2-py2.7.egg/twitter.py

CLASSES
__builtin__.object
Api
DirectMessage
Hashtag
List
Status
Trend
Url
User
exceptions.Exception(exceptions.BaseException)
TwitterError

(snip)


python-twitterで扱えるクラスは上記のとおりです。そのうちtwitter.Apiクラスから様々な情報や命令を操作することが多いと思います。まずはこのクラスの使い方から紐解いていきます。備忘録よろしく、とりあえず遊べそうなメソッドを試したメモでまとめていきます。

ちなみに、いわゆるTweetは、Twitterのシステム的にはStatusと呼びます。





まずは前述のとおり、カスタマーキーやアクセスキーを揃えてください。保存方法は個人の自由ですが、仮に別ファイルにしてsecret.py内に格納しておくとします。

dict = {
'consumer_key' : '********',
'consumer_secret' : '********',
'access_token_key' : '********',
'access_token_secret' : '********'
}


メインスクリプトのテンプレートを以下のようにするとします。
import twitter
import secret

api = twitter.Api(
consumer_key = secret.dict['consumer_key'],
consumer_secret = secret.dict['consumer_secret'],
access_token_key = secret.dict['access_token_key'],
access_token_secret = secret.dict['access_token_secret']
)

#
# ここにテストコードを書く
#




ここから先は、簡単に使えそうなメソッドの使用例をメモって行きます。





twitter.Api.GetPublicTimeline = GetPublicTimeline(self, since_id=None, include_rts=None, include_entities=None) unbound twitter.Api method
このメソッドは、パブリックタイムライン(全ユーザーのTweets)を順番に取り出し(fetch)します。それらはtwitter.Statusクラスのオブジェクトです。

引数
since_id: since_id以上のIDを持つStatusを取得します。APIから取得できるTweetsには上限があります。もしその上限に達するIDを指定してしまった場合は、可能な範囲の最も古いIDに置き換えられます(オプション)
include_rts: もしTrueなら、公式Retweetを含みます(オプション)
include_entities: もしTrueなら、各Tweetに"entities"を含ませます。これには様々なメタデータが含まれます(user_mentions, urls, hashtags)(オプション)

返り値
twitter.Statusインスタンスを順に返します。



twitter.Api.GetPublicTimeline()はOAuthが必要ありませんので下記のように認証なしで簡単に実行できます。それは誰でもPublicのTweetを取得できるからです。デフォルトでは最新から20のTweetsを取得します。

import twitter
api = twitter.Api()
statuses = api.GetPublicTimeline()

for s in statuses:
print s.id, s,text


この例では、パブリックタイムラインから最新20Tweetsのtwitter.Statusオブジェクトを取得し、それらのプロパティであるid(Tweetが持っているユニークなID)とtext(Tweetの内容)を出力しています。

twitter.Statusクラスのリファレンスを確認してみましょう。

% pydoc twitter.Status

Help on class Status in twitter:

twitter.Status = class Status(__builtin__.object)
|  A class representing the Status structure used by the twitter API.
| 
|  The Status structure exposes the following properties:
| 
|    status.created_at
|    status.created_at_in_seconds # read only
|    status.favorited
|    status.in_reply_to_screen_name
|    status.in_reply_to_user_id
|    status.in_reply_to_status_id
|    status.truncated
|    status.source
|    status.id   # これを使いました
|    status.text # これを使いました
|    status.location
|    status.relative_created_at # read only
|    status.user
|    status.urls
|    status.user_mentions
|    status.hashtags
|    status.geo
|    status.place
|    status.coordinates
|    status.contributors

(snip)


Statusクラスのメソッドの中で、Get*はプロパティを取得するだけのメソッドで、プロパティを参照したときと同じ結果を返します。Set*は、取得したStatusクラスのインスタンスのプロパティに値を上書き(Set)しちゃいます。Set*は下記のよう使えます。

import twitter
api = twitter.Api()
statuses = api.GetPublicTimeline()
s = statuses[0]

print s.id, s.text # オリジナルのtextを返します

s.SetText(u'hahaha')

print s.id, s.text # hahaha と書き換えられたtextを返します









改めてtwitter.Apiクラスを見てみましょう。

% pydoc twitter.Api

(snip)
|    There are many other methods, including:
| 
|      >>> api.PostUpdates(status)
|      >>> api.PostDirectMessage(user, text)
|      >>> api.GetUser(user)
|      >>> api.GetReplies()
|      >>> api.GetUserTimeline(user)
|      >>> api.GetStatus(id)
|      >>> api.DestroyStatus(id)
|      >>> api.GetFriendsTimeline(user)
|      >>> api.GetFriends(user)
|      >>> api.GetFollowers()
|      >>> api.GetFeatured()
|      >>> api.GetDirectMessages()
|      >>> api.PostDirectMessage(user, text)
|      >>> api.DestroyDirectMessage(id)
|      >>> api.DestroyFriendship(user)
|      >>> api.CreateFriendship(user)
|      >>> api.GetUserByEmail(email)
|      >>> api.VerifyCredentials()
(snip)


メソッドはこれ以外にもありますが、このなかから簡単に使えそうなメソッドで練習してみましょう。

twitter.Api.GetUser = GetUser(self, user) unbound twitter.Api method
指定したユーザーのUserインスタンスを返します。

引数
user: nameあるいはid

返り値
twitter.Userインスタンスオブジェクト



このGetUserメソッドを、今度はインタプリタを起動して使ってみましょう。

% python
Python 2.7.1+ (r271:86832, Apr 11 2011, 18:05:24)
[GCC 4.5.2] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import twitter
>>> api = twitter.Api()
>>> u = api.GetUser("hogeo")  # hogeo ユーザのインスタンスを作成します
>>> u.__class__
<class 'twitter.User'>  # twitter.User クラスであることが確認できます
>>> u.name  # Userインスタンスのnameプロパティを参照します
u'Kenichi Terashita'



ちなみに、前述でGetPublicTimeline()メソッドでStatusインスタンスを取得しましたが、Statusインスタンスのuserプロパティには、そのstatus(Tweet)発信元のUserインスタンスが格納されています。

% python
>>> import twitter
>>> api = twitter.Api()
>>> statuses = api.GetPublicTimeline()
>>> status = statuses[0]
>>> u = status.user
>>> u.__class__
<class 'twitter.User'>
>>> u.screen_name
u'HirooTC'  # ←Public Timelineからたまたま引いた誰か



メソッドを試しに実行して見るたびに、インタプリタを起動しなおして1からコードを書く事を繰り返すと、段々体がAPIを覚えていきます。
色々と予期せずエラーになることがあるので、エラーが発生するケースをデバッグし、API一つ一つを身につけていきましょう。

twitter.Apiのいくつかのメソッドは、OAuth済みのApiインスタンスを使わなければ呼び出せないものもあります。
任意のユーザー本位(あなた自身)での実行が必要なものや、権限の関係で必要とされます。



% python
Python 2.7.1+ (r271:86832, Apr 11 2011, 18:05:24)
>>> import twitter
>>> api = twitter.Api()
>>> results = api.FilterPublicTimeline('the')  # 'the'を含むStatusを、最新20のPublic TimelineからFilterします
>>> results
[<twitter.Status object at 0xb722bb2c>]  # ひとつだけヒットしたようです
>>> print results[0].text  # textプロパティを表示
Got school tomorrow nd I'm still up with these clowns!


「明日は学校だ、私はまだclown達と一緒だぜ!」

この人は学生でしょうか?どこにいるどんな人なのでしょう。

# (続き)
>>> results[0].user  # Userインスタンスを参照できます
<twitter.user object="" at="" 0xb722bb0c="">
>>> u = results[0]
>>> print u.user.location
City of Lost Dreams, AL
>>> print u.user.description
God is working on me! Be patient! #teamArmy #DontBeDumbGang #TeamLadyMaMaz #Teamtaurus #Teamprettygirl #TeamSingle


ちょっと・・・、よくわかりませんね。






基本的なTwitter APIの呼び出し方や、Get系のメソッドの使い方には慣れたと思います。この後は実際にstatusをPostしてみる練習に挑戦してみると良いかもしれません。
間違って大量Postして他人様やシステムに迷惑をかけないように。


そろそろお気づきの方がいるかもしれませんが、Twitter APIの呼び出し回数には制限があります。詳しくはDeveloperサイトRate Limitingを確認してください。これは将来変更される可能性がありますので、最新情報には注意しておきましょう。

例えば本日(2011/5/26)現在では、以下のような制限があります。
  • OAuthで認証されたAPIの呼び出しにはユーザー毎に毎時350 Requestまで、未認証のAPI呼び出しには、1 IPアドレス毎に毎時150 Requestまで
  • GETリクエストにはRate Limitが適用されるが、POSTリクエストは基本的に制限されない
  • ただし、いくつかのメソッドについてはRate Limitが適用される場合がるので、詳しくはメソッドのドキュメントで要確認
  • Rate Limitを越えてAPIをCallすると、HTTP 400のレスポンスコードが返ります


もちろん他にも詳しく定められていますので、本格的にTwitter APIを回し始める際にはこのRate Limitを意識したプログラムにしましょう。

そして、Rate Limitを確認するメソッドもあります。twitter.Api.GetRateLimitStatus()です。

twitter.Api.GetRateLimitStatus = GetRateLimitStatus(self) unbound twitter.Api method
現在の認証ユーザー(あるいは非認証時のIPアドレスベース)によるRate Limitのステータスを取得します。

返り値(dictionary型)
reset_time: Limitがリセットされる日時
remaining_hits: 残りのRequest数
hourly_limit: 最大Request数
reset_time_in_seconds: リセットされるEpoch秒(UNIX時間)



(インタプリタ入力途中から)
>>> api.GetRateLimitStatus()
{u'reset_time': u'Thu May 26 13:11:07 +0000 2011', u'remaining_hits': 150, u'hourly_limit': 150, u'reset_time_in_seconds': 1306415467}
>>> api.GetUser("hogeo")  # Limit消費するメソッドをCall
<twitter.User object at 0xa2e80cc>
>>> api.GetRateLimitStatus()  # remaining_hitsが-1されている
{u'reset_time': u'Thu May 26 13:11:07 +0000 2011', u'remaining_hits': 149, u'hourly_limit': 150, u'reset_time_in_seconds': 1306415467





さて、いかがでしょうか。
これからPythonを学びたい方向けに、なるべくサンプルになるようにテストコードを繰り返し記載して、順を追って同じようにタイプして学習できるように書いてきました。
すでにPart1(2011/5/26現在英語ですが)とPart2を読まれると、PythonによるTwitter APIを何かしら自分でも使い始められるようになるのではないでしょうか。