#! /usr/bin/env python # -*- coding: utf-8 -*- """ Twython is a library for Python that wraps the Twitter API. It aims to abstract away all the API endpoints, so that additions to the library and/or the Twitter API won't cause any overall problems. twythonrequests is twython implementation using requests. Questions, comments? ryan@venodesigns.net, me@kracekumar.com """ __author__ = "Ryan McGrath " __version__ = "1.4.6" """ Importing requests and requests-oauth. requests supports 2.5 and above and no support for 3.x. """ from urlparse import parse_qs from urllib2 import HTTPError try: #Python 2.6 and up import requests import oauth_hook except ImportError: raise Exception("twythonrequests requires requests - \ http://pypi.python.org/pypi/requests and \ requests-oauth -http://pypi.python.org/pypi/requests-oauth\ ") #since requests support 2.5 and above, check for json and if fails check for\ #simplejson if that fails, requests installation must be broken. try: import json except ImportError: try: import simplejson as json except ImportError: # This must be dead code still worth raise Exception("twythonrequests") class TwythonError(AttributeError): """ Generic error class, catch-all for most Twython issues. Special cases are handled by APILimit and AuthError. Note: To use these, the syntax has changed as of Twython 1.3. To catch \ these, you need to explicitly import them into your code, e.g: from twython import TwythonError, APILimit, AuthError """ def __init__(self, msg, error_code=None): self.msg = msg if error_code == 400: raise APILimit(msg) def __str__(self): return repr(self.msg) class APILimit(TwythonError): """ Raised when you've hit an API limit. Try to avoid these, read the API docs if you're running into issues here, Twython does not concern \ itself with this matter beyond telling you that you've done goofed. """ def __init__(self, msg): self.msg = msg def __str__(self): return repr(self.msg) class AuthError(TwythonError): """ Raised when you try to access a protected resource and it fails due \ to some issue with your authentication. """ def __init__(self, msg): self.msg = msg def __str__(self): return repr(self.msg) class Twython(object): def __init__(self, twitter_token = None, twitter_secret = None, \ oauth_token = None, oauth_token_secret = None, headers = None,\ callback_url = None): """ setup(self, oauth_token = None, headers = None) Instantiates an instance of Twython. Takes optional parameters for authentication and such (see below). Parameters: twitter_token - Given to you when you register your application with Twitter. twitter_secret - Given to you when you register your application with Twitter. oauth_token - If you've gone through the authentication process and have a token for this user, pass it in and it'll be used for all requests going forward. oauth_token_secret - see oauth_token; it's the other half. headers - User agent header, dictionary style aka {'User-Agent': 'Bert'} """ # API for accessing twitter data self.request_token_url = "http://twitter.com/oauth/request_token" self.access_token_url = "http://twitter.com/oauth/access_token" self.authorize_url = "http://twitter.com/oauth/authorize" self.authenticate_url = "http://twitter.com/oauth/authenticate" self.twitter_token = twitter_token self.twitter_secret = twitter_secret self.oauth_token = oauth_token self.oauth_secret = oauth_token_secret self.callback_url = callback_url or 'oob' self.oauth_hook = None self.client = None #In case headers are present lets add if headers is None: self.headers = {'User-agent': 'Twython python library v1.3 via \ python-requests'} else: self.headers = headers #next is oauth, here we use requests-oauth if self.twitter_token: OAuthHook.consumer_key = self.twitter_token if self.twitter_secret: OAuthHook.consumer_secret = self.twitter_secret #if users pass oauth token and secret we initialize with oauth_hook #code taken from maraujop/requests-oauth if self.oauth_token and self.oauth_secret: #Creating OAuthHooks self.oauth_hook = oauth_hook.OAuthHook(self.oauth_auth_token,\ self.ouath_secret) #real magic of requests start here self.client = requests.session(hooks={ 'pre_request': \ self.oauth_hook }) else: if self.twitter_token and self.twitter_secret: self.oauth_hook = oauth_hook.OAuthhook(\ consumer_key=self.twitter_token,\ consumer_secret=self.twitter_secret) self.client = requests.session(hooks={'pre_request':\ self.oauth_hook}) def __getattr__(self, api_call): pass def get(self, **kwargs): pass def get_authorized_tokens(self): return self.get_authentication_tokens(internal = 1) def get_authentication_tokens(self, internal = None): """ get_auth_url(self) Returns an authorization URL for a user to hit. """ if internal: self.response = self.client.post(self.request_token_url,\ {'oauth_callback': self.callback_url}) else: self.response = self.client.get(self.request_token_url) if self.response.code == 200: self.response = parse_qs(self.response.content) try: return {'oauth_token': self.response['oauth_token'],\ 'oauth_secret': self.response['oauth_token_secret']} except AttributeError, e: raise TwythonError("Something went wrong, with parsing or call\ \n get_authentication_token() failed with %s error code"% \ `e.code`) else: raise AuthError("Something went wrong\nError code:%s\n\ Error Message:%s"%(self.response.status_code,\ self.response.error.msg)) @staticmethod def shortenURL(url_to_shorten): """ This is the function which will shorten url. It uses is.gd. Url: http://is.gd/create.php Parameters: url_to_shorten - string - Long url which is to be shortened. Returns shorten url which is in unicode format. """ try: response = requests.post("http://is.gd/create.php", \ data={'format': 'simple', 'url': url_to_shorten}) response.raise_for_status() return response.content except HTTPError, e: raise TwythonError("shortenURL() failed with a %s error code."\ % `e.code`, e.code) def bulkUserLookup(self, ids = None, screen_names = None, version = 1,\ **kwargs): """ bulkUserLookup(self, ids = None, screen_names = None, version = 1, **kwargs): A method to do bulk user lookups against the Twitter API. Arguments (ids (numbers) / screen_names (strings)) should be flat. Arrays that contain their respective data sets. Statuses for the users in question will be returned inline if they exists. Requires authentication! """ if ids: kwargs['user_id'] = ','.join(map(str, ids)) if screen_names: kwargs['screen_name'] = ','.join(screen_names) try: self.response = requests.get("\ http://api.twitter.com/%d/users/lookup.json" %version,\ kwargs) self.response.raise_for_status() return json.loads(self.response.content) except HTTPError, e: raise TwythonError("bulkUserLookup() failed with a %s error code."\ % `e.code`, e.code) def search(self, q, **kwargs): """ search(**kwargs) Returns Tweets that match the specified query. Parameters: q: query to search for example See the documentation at http://dev.twitter.com/doc/get/ search. Pass in the API supported arguments as named parameters. e.g: x.search(q='python', page='2') """ try: self.response = requests.get(\ "http://search.twitter.com/search.json",\ params={'q': q}, **kwargs) self.response.raise_for_status() return json.loads(self.response.content) except HTTPError, e: raise TwythonError("search() failed with %s error code" \ % `e.code`, e.code) def searchTwitter(self, q, **kwargs): """ use search(). This will be removed soon. """ return self.search(q, **kwargs) def searchGen(self, q, **kwargs): """ seaarchGen(self, **kwargs) Returns a generator of tweets that match a specified query. Documentation: http://dev.twitter.com/doc/get/search e.g: x.searchGen(q='python', page='2') """ try: self.response = self.search(q, **kwargs) self.response.raise_for_status() self.response = json.loads(self.response.content) except HTTPError, e: raise TwythonError("searchGen() exited with %d status code and \ code "%self.response.status_code, e.code) if self.response['results']: raise StopIteration else: for tweet in data['results']: yield tweet if 'page' not in kwargs: kwargs['page'] = 2 else: try: # This line converts page param in query parameter to int and # adds one because we are running inside func which will yield # list of tweet using generator and converts to string. kwargs['page'] = str(int(kwargs['page']) + 1) except TypeError: raise TwythonError("searchGen() exited because it page \ takes string ") except e: raise TwythonError("searchGen() failed with %s error code"%\ `e.code`, e.code) for tweet in self.searchGen(**kwargs): yield tweet def searchTwitterGen(self, q, **kwargs): """ use searchGen(). This will be removed soon. """ return self.searchGen(q, **kwargs) def isListMember(self, list_id, id, username, version = 1): """ isListMember(self, list_id, id, username, version =1) Check if a specified user(id) is a member of the list in question (list_id) **Note: This method may not work for private/protected lists, unless you're authenticated and have access to those lists. Parameters: list_id - Required. The slug of the list to check against. id - Required. The ID of the user being checked in the list. username - User who owns the list you're checking against\ (username) version(number) - Optional. API version to \ request.\ version (number) - Optional. API version to request. Entire Twython class defaults to 1, but you can override on\ a function-by-function or class basis - (version=2), etc. """ try: self.response = requests.post("http://api.twitter.com/%d/%s/%s/\ members/%s.json" % (version, username, list_id,\ `id`), headers = self.headers) self.response.raise_for_status() return json.loads(Self.response.content) except HTTPError, e: raise TwythonError("isListMember() failed with status code %d"\ %self.response.status_code, e.code) def isListSubscriber(self, username, list_id, version = 1): """ isListSubscriber(self, username, list_id, id, version) Check if a specified user(id) is a subscriber of the list in \ question(list_id) **Note: This method may not work for private/protected lists, unless you're authenticated and have access to those lists. Parameters: list_id - Required. The slug of the list to check against. id - Required. The ID of the user being checked in the list. username - Required. The username of the owner of the list\ that you're seeing if someone is subscribed to. version (number) - Optional. API version to request. Entire Twython class defaults to 1, but you can override on\ a function-by-function or class basis - (version=2), etc. """ try: self.response = requests.post("http://api.twitter.com/%d/%s/%s\ following/%s.json" % (version,username,list_id,\ `id`), headers = self.headers) self.response.raise_for_status() return json.loads(self.response.content) except HTTPError, e: raise TwythonError("isListMember() failed with %d error code."%\ self.response.status_code, e.code) def updateProfileBackgroundImage(self,filename,tile="true",version=1): """ updateProfileBackgroundImage(filename,tile="true") Updates the authenticating user's profile background image. Parameters: image - Required. Must be a valid GIF, JPG, or PNG image of\ less than 800 kilobytes in size. Images with with larger \ than 2048 pixels will be forceably scaled down. tile - Optional (defaults to true). If set to true the \ background image will be displayed tiled. The image will not be tiled otherwise. ** Note: It's sad, but when using this method, pass the \ tile value as string, e.g. title="false" version (number) - Optional. API version to request.\ Entire Twython class defaults to 1, but you can override on\ a function-by-function or class basis - (version=2), etc. """ url = "http://api.twitter.com/%d/account/update_profile_background.\ json?tile=%s" %(version,tile) try: files = {filename: open(filename, 'rb')} except IOError, e: raise TwythonError("file reading %d error"%`e.code`, e.code) try: self.response = request.post(url, files=files) self.response.raise_for_status() return self.response.status_code except HTTPError, e: raise Twython("updateProfileBackgroundImage failed with %d\ error code"%self.response.status_code, e.code) def updateProfileImage(self,filename,version=1): """ updateProfileImage(filename) Updates the authenticating user's profile image (avatar). Parameters: image - Required. Must be valid GIF, JPG, or PNG image of\ less than 700 kilobytes in size. Image with width larger \ than 500 pixels will be scaled down. version (number) - Optional. API version to request. Entire Twython class defaults to 1, but you can override on\ a function-by-function or class basis - (version=2), etc. """ url = "http://api.twitter.com/%d/account/update_profile_image.json"\ %version try: files = {filename: open(filename, 'rb')} except IOError, e: raise TwythonError("file reading %d error"%`e.code`, e.code) try: self.response = requests.post(url, files=files) self.response.raise_for_status() return self.response.status_code except HTTPError, e: raise TwythonError("updateProfileImage() failed with %d error\ code"% self.response.status_code, e.code) def getProfileImageUrl(self, username, size=None, version=1): """ getProfileImageUrl(username) Gets the URL for the user's profile image. Parameters: username - Required. User name of the user you want the image url of. size - Optional.Options 'normal', 'mini', 'bigger'. Defaults to 'normal' if not given. version (number) - Optional. API version to request. Entire Twython class defaults to 1, but you can override on\ a function-by-function or class basis - (version=2), etc. """ url = "http://api.twitter.com/%s/users/profile_image/%s.json"%\ (version, username) try: self.response = requests.get(url, params={'size': size}) if self.response.status_code in (301, 302, 303, 307): return self.response.headers['location'] elif self.response.status_code == 200: return self.response.url self.response.raise_for_status() except HTTPError, e: raise TwythonError("getProfileIMageUrl() failed with %d \ error code"% `e.code`, e.code) @staticmethod def unicode2utf8(text): try: if isinstance(text, unicode): text = text.encode('utf-8') except: pass return text @staticmethod def encode(text): if isinstance(text, (str, unicode)): return Twython.unicode2utf8(text) return str(text)