TwitterSearch package¶

Submodules¶

TwitterSearch.TwitterOrder module¶

class TwitterSearch.TwitterOrder.TwitterOrder¶

Bases: object

Basic interface class to inherit from. Methods raising NotImplementedError exceptions need to be implemented by all children

arguments = {}¶

create_search_url()¶

Generates an url-encoded query string from stored key-values tuples. Has to be implemented within child classes

Raises:	NotImplementedError

set_count(cnt)¶

Sets ‘count’ parameter used to define the number of tweets to return per page. Maximum and default value is 100

Parameters:	cnt – Integer containing the number of tweets per page within a range of 1 to 100
Raises:	TwitterSearchException

set_include_entities(include)¶

Sets ‘include entities’ parameter to either include or exclude the entities node within the results

Parameters:	include – Boolean to trigger the ‘include entities’ parameter
Raises:	TwitterSearchException

set_max_id(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

Parameters:	twid – A valid tweet ID in either long (Py2k) or integer (Py2k + Py3k) format
Raises:	TwitterSearchException

set_search_url(url)¶

Reads given query string and stores key-value tuples. Has to be implemented within child classes

Parameters:	url – A string containing the twitter API endpoint URL
Raises:	NotImplementedError

set_since_id(twid)¶

Sets ‘since_id’ parameter used to return only results with an ID greater than (that is, more recent than) the specified ID

Parameters:	twid – A valid tweet ID in either long (Py2k) or integer (Py2k + Py3k) format
Raises:	TwitterSearchException

TwitterSearch.TwitterSearch module¶

class TwitterSearch.TwitterSearch.TwitterSearch(consumer_key, consumer_secret, access_token, access_token_secret, **attr)¶

Bases: object

This class contains the actual functionality of this library. It is responsible for correctly transmitting your data to the Twitter API (v1.1 only) and returning the results to your program afterwards. It is configured using an implementation of TwitterOrder along with valid Twitter credentials. Currently two different implementations are usable: TwitterUserOrder for retrieving the timeline of a certain user and TwitterSearchOrder for accessing the Twitter Search API.

The methods next(), __next__() and __iter__() are used during the iteration process. For more information about those methods please consult the official Python documentation.

authenticate(verify=True)¶

Creates an authenticated and internal oauth2 handler needed for queries to Twitter and verifies credentials if needed. If verify is true, it also checks if the user credentials are valid. The default value is True

Parameters:	verify – boolean variable to directly check. Default value is `True`

check_http_status(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)

Parameters:	http_status – Integer value of the HTTP status of the last query. Invalid statuses will raise an exception.
Raises:	TwitterSearchException

exceptions = {420: 'Enhance Your Calm: You are being rate limited', 502: 'Bad Gateway: Twitter is down or being upgraded', 422: 'Unprocessable Entity: Image unable to be processed', 429: ('Too Many Requests: Request cannot be served ', "due to the application's rate limit having ", 'been exhausted for the resource'), 400: 'Bad Request: The request was invalid', 401: ('Unauthorized: Authentication credentials ', ' were missing or incorrect'), 403: ('Forbidden: The request is understood, but', 'it has been refused or access is not allowed'), 500: 'Internal Server Error: Something is broken', 406: 'Not Acceptable: Invalid format is specified in the request', 503: ('Service Unavailable: The Twitter servers ', 'are up, but overloaded with requests'), 504: ("Gateway timeout: The request couldn't ", 'be serviced due to some failure within our stack'), 404: ('Not Found: The URI requested is invalid or', 'the resource requested does not exists'), 410: 'Gone: This resource is gone'}¶

get_amount_of_tweets()¶

Returns current amount of tweets available within this instance

Returns:	The amount of tweets currently available
Raises:	TwitterSearchException

get_metadata()¶

Returns all available meta data collected during last query. See Advanced usage for example

Returns:	Available meta information about the last query in form of a `dict`
Raises:	TwitterSearchException

get_minimal_id()¶

Returns the minimal tweet ID of the current response

Returns:	minimal tweet identification number
Raises:	TwitterSearchException

get_proxy()¶

Returns the current proxy url or None if no proxy is set

Returns:	A string containing the current HTTPS proxy (e.g. `my.proxy.com:8080`) or `None` is no proxy is used

get_statistics()¶

Returns dict with statistical information about amount of queries and received tweets. Returns statistical values about the number of queries and the sum of all tweets received by this very instance of TwitterSearch. Example usage: print("Queries done: %i. Tweets received: %i" % ts.get_statistics())

Returns:	A `tuple` with `queries` and `tweets` keys containing integers. E.g. `(1,100)` which stands for one query that contained one hundred tweets.

get_tweets()¶

Returns all available data from last query. See Advanced usage for example

Returns:	All tweets found using the last query as a `dict`
Raises:	TwitterSearchException

next()¶

Python2 comparability method. Simply returns self.__next__()

Returns:	the `__next__()` method of this class

search_next_results()¶

Triggers the search for more results using the Twitter API. Raises exception if no further results can be found. See Advanced usage for example

Returns:	`True` if there are more results available within the Twitter Search API
Raises:	TwitterSearchException

search_tweets(order)¶

Creates an query string through a given TwitterSearchOrder instance and takes care that it is send to the Twitter API. This method queries the Twitter API without iterating or reloading of further results and returns response. See Advanced usage for example

Parameters:	order – A TwitterOrder instance. Can be either TwitterSearchOrder or TwitterUserOrder
Returns:	Unmodified response as `dict`.
Raises:	TwitterSearchException

search_tweets_iterable(order, callback=None)¶

Returns itself and queries the Twitter API. Is called when using an instance of this class as iterable. See Basic usage for examples

Parameters:	order – An instance of TwitterOrder class (e.g. TwitterSearchOrder or TwitterUserOrder) callback – Function to be called after a new page is queried from the Twitter API
Returns:	Itself using `self` keyword

send_search(url)¶

Queries the Twitter API with a given query string and stores the results internally. Also validates returned HTTP status code and throws an exception in case of invalid HTTP states. Example usage sendSearch('?q=One+Two&count=100')

Parameters:	url – A string of the URL to send the query to
Raises:	TwitterSearchException

set_proxy(proxy)¶

Sets a HTTPS proxy to query the Twitter API

Parameters:	proxy – A string of containing a HTTPS proxy e.g. `set_proxy("my.proxy.com:8080")`.
Raises:	TwitterSearchException

set_supported_languages(order)¶

Loads currently supported languages from Twitter API and sets them in a given TwitterSearchOrder instance. See Advanced usage for example

Parameters:	order – A TwitterOrder instance. Can be either TwitterSearchOrder or TwitterUserOrder

TwitterSearch.TwitterSearchException module¶

exception TwitterSearch.TwitterSearchException.TwitterSearchException(code, msg=None)¶

Bases: Exception

This class is all about exceptions (surprise, surprise!). All exception based directly on TwitterSearch will consist of a code and a message describing the reason of the exception shortly.

TwitterSearch.TwitterSearchOrder module¶

class TwitterSearch.TwitterSearchOrder.TwitterSearchOrder¶

Bases: TwitterSearch.TwitterOrder.TwitterOrder

This class is for configurating all available arguments of the Twitter Search API (v1.1). It also creates valid query strings which can be used in other environments identical to the syntax of the Twitter Search API.

add_keyword(word, or_operator=False)¶

Adds a given string or list to the current keyword list

Parameters:	word – String or list of at least 2 character long keyword(s) 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

create_search_url()¶

Generates (urlencoded) query string from stored key-values tuples

Returns:	A string containing all arguments in a url-encoded format

iso_6391 = ('aa', 'ab', 'ae', 'af', 'ak', 'am', 'an', 'ar', 'as', 'av', 'ay', 'az', 'ba', 'be', 'bg', 'bh', 'bi', 'bm', 'bn', 'bo', 'br', 'bs', 'ca', 'ce', 'ch', 'co', 'cr', 'cs', 'cu', 'cv', 'cy', 'da', 'de', 'dv', 'dz', 'ee', 'el', 'en', 'eo', 'es', 'et', 'eu', 'fa', 'ff', 'fi', 'fj', 'fo', 'fr', 'fy', 'ga', 'gd', 'gl', 'gn', 'gu', 'gv', 'ha', 'he', 'hi', 'ho', 'hr', 'ht', 'hu', 'hy', 'hz', 'ia', 'id', 'ie', 'ig', 'ii', 'ik', 'io', 'is', 'it', 'iu', 'ja', 'jv', 'ka', 'kg', 'ki', 'kj', 'kk', 'kl', 'km', 'kn', 'ko', 'kr', 'ks', 'kv', 'kw', 'ky', 'la', 'lb', 'lg', 'li', 'ln', 'lo', 'lt', 'lu', 'lv', 'mg', 'mh', 'mi', 'mk', 'ml', 'mn', 'mr', 'ms', 'mt', 'my', 'na', 'nb', 'nd', 'ne', 'ng', 'nl', 'nn', 'no', 'nr', 'nv', 'ny', 'oc', 'oj', 'om', 'or', 'os', 'pa', 'pi', 'pl', 'ps', 'pt', 'qu', 'rm', 'rn', 'ro', 'ru', 'rw', 'sa', 'sc', 'sd', 'se', 'sg', 'si', 'sk', 'sl', 'sm', 'sn', 'so', 'sq', 'sr', 'ss', 'st', 'su', 'sv', 'sw', 'ta', 'te', 'tg', 'th', 'ti', 'tk', 'tl', 'tn', 'to', 'tr', 'ts', 'tt', 'tw', 'ty', 'ug', 'uk', 'ur', 'uz', 've', 'vi', 'vo', 'wa', 'wo', 'xh', 'yi', 'yo', 'za', 'zh', 'zu')¶

remove_all_filters()¶: Removes all filters

remove_attitude_filter()¶: Remove attitude filter

remove_link_filter()¶: Remove the current link filter

remove_question_filter()¶: Remove the current question filter

remove_source_filter()¶: Remove the current source filter

set_callback(func)¶

Sets ‘callback’ parameter. If supplied, the response will use the JSONP format with a callback of the given name

Parameters:	func – A string containing the name of the callback function
Raises:	TwitterSearchException

set_geocode(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.

Parameters:	latitude – A integer or long describing the latitude longitude – A integer or long describing the longitude radius – A integer or long describing the radius 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

set_keywords(words, or_operator=False)¶

Sets a given list as the new keyword list

Parameters:	words – A list of at least 2 character long new keywords 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

set_language(lang)¶

Sets ‘lang’ parameter used to only fetch tweets within a certain language

Parameters:	lang – A 2-letter language code string (ISO 6391 compatible)
Raises:	TwitterSearchException

set_link_filter()¶: Only search for tweets including links

set_locale(lang)¶

Sets ‘locale’ parameter to specify the language of the query you are sending (only ja is currently effective)

Parameters:	lang – A 2-letter language code string (ISO 6391 compatible)
Raises:	TwitterSearchException

set_negative_attitude_filter()¶: Only search for tweets with negative attitude

set_positive_attitude_filter()¶: Only search for tweets with positive attitude

set_question_filter()¶: Only search for tweets asking a question

set_result_type(result_type)¶

Sets ‘result_type’ parameter to specify what type of search results you would prefer to receive. The current default is “mixed.” Valid values include: - mixed: Include both popular and real time results - recent: return only the most recent results - popular: return only the most popular results :param result_type: A string containing one of the three valid result types

Raises:	TwitterSearchException

set_search_url(url)¶

Reads given query string and stores key-value tuples

Parameters:	url – A string containing a valid URL to parse arguments from

set_since(date)¶

Sets ‘since’ parameter used to return only tweets generated after the given date

Parameters:	date – A datetime instance
Raises:	TwitterSearchException

set_source_filter(source)¶

Only search for tweets entered via given source

Parameters:	source – String. Name of the source to search for. An example would be `source=twitterfeed` for tweets submitted via TwitterFeed
Raises:	TwitterSearchException

set_until(date)¶

Sets ‘until’ parameter used to return only tweets generated before the given date

Parameters:	date – A datetime instance
Raises:	TwitterSearchException

TwitterSearch.TwitterUserOrder module¶

class TwitterSearch.TwitterUserOrder.TwitterUserOrder(user)¶

Bases: TwitterSearch.TwitterOrder.TwitterOrder

This class configures all arguments available of the user_timeline endpoint of the Twitter API (version 1.1 only). It also creates a valid query string out of the current configuration.

create_search_url()¶

Generates (urlencoded) query string from stored key-values tuples

Returns:	A string containing all arguments in a url-encoded format

set_contributor_details(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

Parameters:	contdetails – Boolean triggering the usage of the parameter
Raises:	TwitterSearchException

set_exclude_replies(exclude)¶

Sets ‘exclude_replies’ parameter used to prevent replies from appearing in the returned timeline

Parameters:	exclude – Boolean triggering the usage of the parameter
Raises:	TwitterSearchException

set_include_rts(rts)¶

Sets ‘include_rts’ parameter. When set to False, the timeline will strip any native retweets from the returned timeline

Parameters:	rts – Boolean triggering the usage of the parameter
Raises:	TwitterSearchException

set_search_url(url)¶

Reads given query string and stores key-value tuples

Parameters:	url – A string containing a valid URL to parse arguments from

set_trim_user(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

Parameters:	trim – Boolean triggering the usage of the parameter
Raises:	TwitterSearchException

TwitterSearch package¶

Submodules¶

TwitterSearch.TwitterOrder module¶

TwitterSearch.TwitterSearch module¶

TwitterSearch.TwitterSearchException module¶

TwitterSearch.TwitterSearchOrder module¶

TwitterSearch.TwitterUserOrder module¶

TwitterSearch.utils module¶

Module contents¶