def __init__(self, user):
""" Argument user can be either a ID or screen-name of a user
:param user: Either string or integer/long value \
of twitter user to query time-line from
:raises: TwitterSearchException
"""
self.arguments.update({'count': '%s' % self._max_count})
# see: https://dev.twitter.com/docs/api/1.1/get/statuses/user_timeline
self.set_include_rts(True)
self.set_exclude_replies(False)
self.url = ''
if py3k:
if isinstance(user, int):
self.arguments.update({'user_id': '%i' % user})
elif isinstance(user, str):
self.arguments.update({'screen_name': user})
else:
raise TwitterSearchException(1017)
else:
if isinstance(user, (int, long)):
self.arguments.update({'user_id': '%i' % user})
elif isinstance(user, basestring):
self.arguments.update({'screen_name': user})
else:
raise TwitterSearchException(1017)
def set_geocode(self, latitude, longitude, radius, imperial_metric=True):
""" Sets geolocation parameters to return only tweets by users \
located within a given radius of the given latitude/longitude. \
The location is preferentially taking from the Geotagging API, \
but will fall back to their Twitter profile.
:param latitude: A integer or long describing the latitude
:param longitude: A integer or long describing the longitude
:param radius: A integer or long describing the radius
:param imperial_metric: Whether the radius is given in metric \
(kilometers) or imperial (miles) system. \
Default is ``True`` which relates to usage of the \
imperial kilometer metric
:raises: TwitterSearchException
"""
if not isinstance(radius, int if py3k else (int, long)) or radius <= 0:
raise TwitterSearchException(1004)
if isinstance(latitude, float) and isinstance(longitude, float):
if isinstance(imperial_metric, bool):
self.arguments.update({
'geocode':
'%s,%s,%s%s' % (latitude, longitude, radius,
'km' if imperial_metric else 'mi')
})
else:
raise TwitterSearchException(1005)
else:
raise TwitterSearchException(1004)
def setGeocode(self, latitude, longitude, radius, unit):
if isinstance(latitude, float) and isinstance(
longitude, float) and isinstance(radius, (long, int)):
if unit == 'mi' or unit == 'km':
self.arguments.update({
'geocode':
'%s,%s,%s%s' % (latitude, longitude, radius, unit)
})
else:
raise TwitterSearchException('Invalid unit')
else:
raise TwitterSearchException('Not a valid number')
def searchTweets(self, order):
if not isinstance(order, TwitterSearchOrder):
raise TwitterSearchException(
'Not a valid TwitterSearchOrder object')
self.sentSearch(order.createSearchURL())
return self.response
def __next__(self):
if not self.__response:
raise TwitterSearchException(1014)
if self.__next_tweet < self.get_amount_of_tweets():
self.__next_tweet += 1
if self.__order_is_search:
return (self.__response['content']
['statuses'][self.__next_tweet-1])
else:
return self.__response['content'][self.__next_tweet-1]
try:
self.search_next_results()
except TwitterSearchException:
raise StopIteration
if self.get_amount_of_tweets() != 0:
self.__next_tweet = 1
if self.__order_is_search:
return (self.__response['content']
['statuses'][self.__next_tweet-1])
else:
return self.__response['content'][self.__next_tweet-1]
raise StopIteration
def addKeyword(self, word):
if isinstance(word, basestring) and word:
self.searchterms.append(word)
elif isinstance(word, list):
self.searchterms += word
else:
raise TwitterSearchException('Neither a list nor a string')
def create_search_url(self):
""" Generates (urlencoded) query string from stored key-values tuples
:returns: A string containing all arguments in a url-encoded format
"""
if len(self.searchterms) == 0:
raise TwitterSearchException(1015)
url = '?q='
url += '+'.join([quote_plus(i) for i in self.searchterms])
if self.attitude_filter is not None:
url += '+%s' % quote_plus(
self._attitudes[0 if self.attitude_filter else 1])
if self.source_filter:
url += '+%s' % quote_plus(self._source + self.source_filter)
if self.link_filter:
url += '+%s' % quote_plus(self._link)
if self.question_filter:
url += '+%s' % quote_plus(self._question)
for key, value in self.arguments.items():
url += '&%s=%s' % (quote_plus(key), (quote_plus(value) if
key != 'geocode' else value))
self.url = url
return self.url
def setIncludeEntities(self, include):
if not isinstance(include,
(bool, int)) and (include == 1 or include == 0):
raise TwitterSearchException('Not a valid boolean')
if include:
self.arguments.update({'include_entities': 'True'})
else:
self.arguments.update({'include_entities': 'False'})
def set_include_rts(self, rts):
""" Sets 'include_rts' parameter. When set to False, \
the timeline will strip any native retweets from the returned timeline
:param rts: Boolean triggering the usage of the parameter
:raises: TwitterSearchException
"""
if not isinstance(rts, bool):
raise TwitterSearchException(1008)
self.arguments.update({'include_rts': 'true' if rts else 'false'})
def set_max_id(self, twid):
""" Sets 'max_id' parameter used to return only results \
with an ID less than (that is, older than) or equal to the specified ID
:param twid: A valid tweet ID in either long (Py2k) \
or integer (Py2k + Py3k) format
:raises: TwitterSearchException
"""
if py3k:
if not isinstance(twid, int):
raise TwitterSearchException(1004)
else:
if not isinstance(twid, (int, long)):
raise TwitterSearchException(1004)
if twid > 0:
self.arguments.update({'max_id': '%s' % twid})
else:
raise TwitterSearchException(1004)
def sentSearch(self, url):
if not isinstance(url, basestring):
raise TwitterSearchException('No valid string')
self.response['meta'], content = self.client.request(
self.search_url + url, 'GET')
# raise exceptions based on http status
http_status = int(self.response['meta']['status'])
if http_status in self.exceptions:
raise TwitterSearchException(
'HTTP status %i - %s' %
(http_status, self.exceptions[http_status]))
self.response['content'] = simplejson.loads(content)
if self.response['content']['search_metadata'].get('next_results'):
self.nextresults = self.response['content']['search_metadata'][
'next_results']
else:
self.nextresults = None
return self.response['meta'], self.response['content']
def get_tweets(self):
""" Returns all available data from last query. \
See `Advanced usage <advanced_usage.html>`_ for example
:returns: All tweets found using the last query as a ``dict``
:raises: TwitterSearchException
"""
if not self.__response:
raise TwitterSearchException(1013)
return self.__response['content']
def set_proxy(self, proxy):
""" Sets a HTTPS proxy to query the Twitter API
:param proxy: A string of containing a HTTPS proxy \
e.g. ``set_proxy("my.proxy.com:8080")``.
:raises: TwitterSearchException
"""
if isinstance(proxy, str if py3k else basestring):
self.__proxy = proxy
else:
raise TwitterSearchException(1009)
def set_callback(self, func):
""" Sets 'callback' parameter. If supplied, the response \
will use the JSONP format with a callback of the given name
:param func: A string containing the name of the callback function
:raises: TwitterSearchException
"""
if isinstance(func, str if py3k else basestring) and func:
self.arguments.update({'callback': '%s' % func})
else:
raise TwitterSearchException(1006)
def set_exclude_replies(self, exclude):
""" Sets 'exclude_replies' parameter used to \
prevent replies from appearing in the returned timeline
:param exclude: Boolean triggering the usage of the parameter
:raises: TwitterSearchException
"""
if not isinstance(exclude, bool):
raise TwitterSearchException(1008)
self.arguments.update(
{'exclude_replies': 'true' if exclude else 'false'})
def set_include_entities(self, include):
""" Sets 'include entities' parameter to either \
include or exclude the entities node within the results
:param include: Boolean to trigger the 'include entities' parameter
:raises: TwitterSearchException
"""
if not isinstance(include, bool):
raise TwitterSearchException(1008)
self.arguments.update(
{'include_entities': 'true' if include else 'false'})
def set_trim_user(self, trim):
""" Sets 'trim_user' parameter. When set to True, \
each tweet returned in a timeline will include a \
user object including only the status authors numerical ID
:param trim: Boolean triggering the usage of the parameter
:raises: TwitterSearchException
"""
if not isinstance(trim, bool):
raise TwitterSearchException(1008)
self.arguments.update({'trim_user': '******' if trim else 'false'})
def set_locale(self, lang):
""" Sets 'locale' parameter to specify the language \
of the query you are sending (only ja is currently effective)
:param lang: A 2-letter language code string (ISO 6391 compatible)
:raises: TwitterSearchException
"""
if lang in self.iso_6391:
self.arguments.update({'locale': '%s' % lang})
else:
raise TwitterSearchException(1002)
def set_language(self, lang):
""" Sets 'lang' parameter used to only fetch tweets within \
a certain language
:param lang: A 2-letter language code string (ISO 6391 compatible)
:raises: TwitterSearchException
"""
if lang in self.iso_6391:
self.arguments.update({'lang': '%s' % lang})
else:
raise TwitterSearchException(1002)
def get_metadata(self):
""" Returns all available meta data collected during last query. \
See `Advanced usage <advanced_usage.html>`_ for example
:returns: Available meta information about the \
last query in form of a ``dict``
:raises: TwitterSearchException
"""
if not self.__response:
raise TwitterSearchException(1012)
return self.__response['meta']
def set_until(self, date):
""" Sets 'until' parameter used to return \
only tweets generated before the given date
:param date: A datetime instance
:raises: TwitterSearchException
"""
if isinstance(date, datetime.date) and date <= datetime.date.today():
self.arguments.update({'until': '%s' % date.strftime('%Y-%m-%d')})
else:
raise TwitterSearchException(1007)
def get_amount_of_tweets(self):
""" Returns current amount of tweets available within this instance
:returns: The amount of tweets currently available
:raises: TwitterSearchException
"""
if not self.__response:
raise TwitterSearchException(1013)
return (len(self.__response['content']['statuses'])
if self.__order_is_search
else len(self.__response['content']))
def set_source_filter(self, source):
""" Only search for tweets entered via given source
:param source: String. Name of the source to search for. An example \
would be ``source=twitterfeed`` for tweets submitted via TwitterFeed
:raises: TwitterSearchException
"""
if isinstance(source,
str if py3k else basestring) and len(source) >= 2:
self.source_filter = source
else:
raise TwitterSearchException(1009)
def set_count(self, cnt):
""" Sets 'count' parameter used to define the number of \
tweets to return per page. Maximum and default value is 100
:param cnt: Integer containing the number of tweets per \
page within a range of 1 to 100
:raises: TwitterSearchException
"""
if isinstance(cnt, int) and cnt > 0 and cnt <= 100:
self.arguments.update({'count': '%s' % cnt})
else:
raise TwitterSearchException(1004)
def check_http_status(self, http_status):
""" Checks if given HTTP status code is within the list at \
``TwitterSearch.exceptions`` and raises a ``TwitterSearchException`` \
if this is the case. Example usage: ``checkHTTPStatus(200)`` and \
``checkHTTPStatus(401)``
:param http_status: Integer value of the HTTP status of the \
last query. Invalid statuses will raise an exception.
:raises: TwitterSearchException
"""
if http_status in self.exceptions:
raise TwitterSearchException(http_status,
self.exceptions[http_status])
def set_contributor_details(self, contdetails):
""" Sets 'contributor_details' parameter used to enhance the \
contributors element of the status response to include \
the screen_name of the contributor. By default only \
the user_id of the contributor is included
:param contdetails: Boolean triggering the usage of the parameter
:raises: TwitterSearchException
"""
if not isinstance(contdetails, bool):
raise TwitterSearchException(1008)
self.arguments.update(
{'contributor_details': 'true' if contdetails else 'false'})
def set_keywords(self, words, or_operator=False):
""" Sets a given list as the new keyword list
:param words: A list of at least 2 character long new keywords
:param or_operator: Boolean. Concatenates all elements of parameter \
word with ``OR``. Enables searches for ``foo OR bar``. Default value \
is False which corresponds to a search of ``foo AND bar``.
:raises: TwitterSearchException
"""
if not isinstance(words, (tuple, list)):
raise TwitterSearchException(1001)
words = [(i if " " not in i else '"%s"' % i) for i in words]
self.searchterms = [" OR ".join(words)] if or_operator else words
def get_minimal_id(self):
""" Returns the minimal tweet ID of the current response
:returns: minimal tweet identification number
:raises: TwitterSearchException
"""
if not self.__response:
raise TwitterSearchException(1013)
return min(
self.__response['content']['statuses'] if self.__order_is_search
else self.__response['content'],
key=lambda i: i['id']
)['id'] - 1
def search_next_results(self):
""" Triggers the search for more results using the Twitter API. \
Raises exception if no further results can be found. \
See `Advanced usage <advanced_usage.html>`_ for example
:returns: ``True`` if there are more results available \
within the Twitter Search API
:raises: TwitterSearchException
"""
if not self.__next_max_id:
raise TwitterSearchException(1011)
self.send_search(
"%s&max_id=%i" % (self._start_url, self.__next_max_id)
)
return True
def add_keyword(self, word, or_operator=False):
""" Adds a given string or list to the current keyword list
:param word: String or list of at least 2 character long keyword(s)
:param or_operator: Boolean. Concatenates all elements of parameter \
word with ``OR``. Is ignored is word is not a list. Thus it is \
possible to search for ``foo OR bar``. Default value is False \
which corresponds to a search of ``foo AND bar``.
:raises: TwitterSearchException
"""
if isinstance(word, str if py3k else basestring) and len(word) >= 2:
self.searchterms.append(word if " " not in word else '"%s"' % word)
elif isinstance(word, (tuple, list)):
word = [(i if " " not in i else '"%s"' % i) for i in word]
self.searchterms += [" OR ".join(word)] if or_operator else word
else:
raise TwitterSearchException(1000)