Lib¶

Interfaces¶

Protocol.py¶

class libturpial.lib.interfaces.protocol.Protocol¶

Bridge class to define abstract functions that must have any protocol implementation

IDENTICA = 'identica'¶

TWITTER = 'twitter'¶

__init__()¶

__module__ = 'libturpial.lib.interfaces.protocol'¶

available_trend_locations()¶: Search for trend locations

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

static availables()¶

block(user)¶: Blocks the specified user

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

convert_time(str_datetime)¶: Takes the str_datetime and convert it into Unix time

destroy_direct_message(direct_message_id)¶: Destroy a direct message

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

destroy_status(status_id)¶: Destroy a posted update

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

follow(user, by_id)¶: Follow somebody

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

get_blocked()¶: Fetch the list of blocked users

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

get_conversation(status_id)¶: Fetch a whole conversation starting from status_id

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

get_directs(count, since_id)¶: Fetch count direct messages received starting from since_id. If since_id is None it will fetch the last count statuses

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

get_directs_sent(count, since_id)¶: Fetch count direct messages sent starting from since_id. If since_id is None it will fetch the last count statuses

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

get_entities(status)¶

get_favorites(count)¶: Fetch count favorite statuses starting from since_id. If since_id is None it will fetch the last count statuses

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

get_followers(only_id=False)¶: Fetch an array of :class list of followers

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

get_following(only_id=False)¶: Fetch the list of following

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

get_int_time(strdate)¶: Converts the strdate into a Unix time long integer (GMT 0)

get_list_statuses(list_id, since_id)¶: Fetch all statuses from list_id starting from since_id. If since_id is None it will fetch the last available statuses

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

get_lists(username)¶: Fetch all the lists where username is part of

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

get_profile(user)¶: Fetch an especific user profile

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

get_profile_image(user)¶: Returns the URL for the profile image of the given user

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

get_public_timeline(count, since_id)¶: Fetch count statuses from public timeline starting from since_id. If since_id is None it will fetch the last count statuses

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

get_rate_limits()¶: Fetch the rate limits for the service

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

get_repeaters(status_id, only_username=False)¶: Fetch all the users that repeated status_id

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

get_replies(count, since_id)¶: Fetch count mentions starting from since_id. If since_id is None it will fetch the last count statuses

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

get_sent(count, since_id)¶: Fetch count sent statuses starting from since_id. If since_id is None it will fetch the last count statuses

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

get_status(status_id)¶: Fetch the status identified by status_id

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

get_str_time(strdate)¶: Converts the strdate into a formatted string (GMT 0)

get_timeline(count, since_id)¶: Fetch count statuses from timeline starting from since_id. If since_id is None it will fetch the last count statuses

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

initialize_http()¶

Creates a new TurpialHTTP instance that must be stored in self.http

For OAuth do:

>>> from libturpial.lib.http import TurpialHTTPOAuth
>>> base_url = 'http://api.twitter.com/1.1'
>>> oauth_options = { 'consumer_key': 'APP_CONSUMER_KEY'}
>>> http = TurpialHTTPOAuth(base_url, oauth_options)

For Basic Auth do:

>>> from libturpial.lib.http import TurpialHTTPBasicAuth
>>> http = TurpialHTTPBasicAuth(base_url)

is_friend(user)¶: Returns True is user follows current account, False otherwise

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

json_to_list(response)¶: Takes a JSON response and returns a libturpial.api.models.list.List object

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

json_to_profile(response)¶: Takes a JSON response and returns a libturpial.api.models.profile.Profile object

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

json_to_ratelimit(response)¶: Takes a JSON response and returns a libturpial.api.models.ratelimit.RateLimit object

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

json_to_status(response)¶: Takes a JSON response and returns a libturpial.api.models.status.Status object

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

mark_as_favorite(status_id)¶: Mark an update as favorite

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

repeat_status(status_id)¶: Repeat to all your friends an update posted by somebody

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

report_as_spam(user)¶: Blocks and report the specified user as spammer

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

request_access()¶: Return an OAuth authorization URL. Do not overide if the protocol does not support OAuth

search(query, count, since_id=None, extra=None)¶: Execute a search query in server

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

send_direct_message(user, text)¶: Send a direct message

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

setup_user_credentials()¶: Set the information related to user credentials. key, secret and verifier for the OAuth case and username, password in the Basic case

trends(location_id)¶: Search for trending topics in location_id

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

unblock(user)¶: Unblocks the specified user

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

unfollow(user)¶: Unfollow somebody

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

unmark_as_favorite(status_id)¶: Unmark an update as favorite

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

update_profile(fullname=None, url=None, bio=None, location=None)¶: Update the user profile

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

update_profile_image(image_path)¶: Update user profile image and return user profile object

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

update_status(text, in_reply_to_id=None, media=None)¶: Post an update

Warning

This is an empty method and must be reimplemented on child class, otherwise it will raise a NotImplementedError exception

verify_credentials()¶

verify_credentials_provider()¶

Service.py¶

class libturpial.lib.interfaces.service.GenericService¶

__init__()¶

__module__ = 'libturpial.lib.interfaces.service'¶

_get_request(url, data=None)¶: Process a GET request and returns a text plain response

_json_request(url)¶: Process a GET request and returns a json hash

_parse_xml(key, xml)¶: Simple XML parser

_quote_url(url)¶

do_service(arg)¶

Http¶

Generic module to handle HTTP requests in libturpial

TurpialHTTPBase¶

class libturpial.lib.http.TurpialHTTPBase(base_url, proxies=None, timeout=None)¶

This class is the abstraction of the HTTP protocol for libturpial. It handles all the magic behind http requests: building, authenticating and fetching resources, in other words, it standarize the way you interact with end points and services.

You shouldn’t instantiate this class, instead you should use the proper implementation for OAuth (libturpial.api.interfaces.http.TurpialHTTPOAuth) or Basic Auth (libturpial.api.interfaces.http.TurpialHTTPBasicAuth) or even develop your own implementation if the authentication method is not supported.

base_url is the part of the URL common for all your requests (api.twitter.com/1.1 for example). proxies is a dict where you define HTTP/HTTPS proxies.

>>> proxies = {
...    "http": "http://10.10.1.10:3128",
...    "https": "https://10.10.1.10:1080",
... }

If your proxy uses HTTP authentication then you can set user and password with something like this:

>>> proxies = {
...    "http": "http://user:pass@10.10.1.10:3128",
... }

timeout is the maximum time in seconds that TurpialHTTPBase will wait before cancelling the current request. If timeout is not specified then DEFAULT_TIMEOUT will be used.

__init__(base_url, proxies=None, timeout=None)¶

__module__ = 'libturpial.lib.http'¶

get(uri, args=None, _format='json', base_url=None, secure=False, id_in_url=True)¶

Performs a GET request against the uri resource with args. You can specify the _format (‘json’ or ‘xml’) and can specify a different base_url. If secure is True the request will be perform as HTTPS, otherwise it will be performed as HTTP.

This method is an alias for request function using ‘GET’ as method.

post(uri, args=None, _format='json', base_url=None, secure=False, id_in_url=False, files=None)¶

Performs a POST request against the uri resource with args. You can specify the _format (‘json’ or ‘xml’) and can specify a different base_url. If secure is True the request will be perform as HTTPS, otherwise it will be performed as HTTP.

This method is an alias for request function using ‘POST’ as method

request(method, uri, args=None, _format='json', alt_base_url=None, secure=False, id_in_url=False, files=None)¶: Performs a GET or POST request against the uri resource with args. You can specify the _format (‘json’ or ‘xml’) and can specify a different base_url. If secure is True the request will be perform as HTTPS, otherwise it will be performed as HTTP

set_proxy(host, port, username='', password='', https=False)¶: Set an HTTP/HTTPS proxy for all requests. You must pass the host and port. If your proxy uses HTTP authentication you can pass the username and password too. If https is True your proxy will use HTTPS, otherwise HTTP.

set_timeout(timeout)¶: Configure the maximum time (in seconds) to wait before killing the current request.

sign_request(httpreq)¶

This is the method you need to overwrite if you subclass libturpial.api.interfaces.http.TurpialHTTPBase.

httpreq is the current request (a libturpial.api.interfaces.http.TurpialHTTPRequest object), you need to apply all the authentication/authorization methods to that object and make it valid; then exit. There is no need to return any value because all changes are done directly over the object.

If this method is not overwritten it will return a NotImplementedError exception.

TurpialHTTPOAuth¶

class libturpial.lib.http.TurpialHTTPOAuth(base_url, oauth_options, user_key=None, user_secret=None, verifier=None, proxies=None, timeout=None)¶

Implementation of TurpialHTTPBase for OAuth. base_url is the part of the URL common for all your requests (api.twitter.com/1.1 for example). oauth_options is a dict with all the OAuth configuration parameters. It must looks like:

>>> oauth_options = {
...    'consumer_key': 'APP_CONSUMER_KEY',
...    'consumer_secret': 'APP_CONSUMER_SECRET',
...    'request_token_url': 'http://request_url',
...    'authorize_token_url': 'http://authorize_url',
...    'access_token_url': 'http://access_url',
... }

consumer_key and consumer_secret are the credentials for your application (they must be provided by the OAuth service). request_token_url, authorize_token_url and access_token_url are the URLs designed by the OAuth service to fetch and authorize an OAuth token.

user_key, user_secret and verifier (a.k.a. PIN) are the token credentials granted to the user after the OAuth dance. They are optional and needed only if the user was already authenticated, otherwise you need to fetch a new token.

proxies and timeout work in the same way that in libturpial.api.interfaces.http.TurpialHTTPBase.

To request an OAuth token create a new TurpialHTTPOAuth object and request a token to your service:

>>> base_url = 'http://api.twitter.com/1.1'
>>> http = TurpialHTTPOAuth(base_url, oauth_options)
>>> url_to_auth = http.request_token()

Ask the user go to the url_to_auth URL and authorize your app. Then get the PIN the service will deliver to your user and authorize the token:

>>> pin = '123456'
>>> token = http.authorize_token(pin)

Use this token to store the key, secret and pin in a safe place to use it from now on. Then inform to TurpialHTTPOAuth that you have access granted:

>>> http.set_token_info(token.key, token.secret, token.verifier)

To use an existing token to fetch a resource create a new TurpialHTTPOAuth object and pass the user_key, user_secret and pin (verifier):

>>> user_key = 'example'
>>> user_secret = 'example'
>>> verifier = 'example'
>>> http = TurpialHTTPOAuth(base_url, oauth_options, user_key, user_secret,
...                         verifier)

To perform a request use the get or post method:

>>> http.get('/my_first/end_point', args={'arg1': '1'}, _format='json')
>>> http.post('/my_second/end_point', args={'arg1': '2'}, _format='json')

__init__(base_url, oauth_options, user_key=None, user_secret=None, verifier=None, proxies=None, timeout=None)¶

__module__ = 'libturpial.lib.http'¶

authorize_token(pin)¶: Uses the pin returned by the service to authorize the current token. Returns an oauth.OAuthToken object.

request_token()¶: Ask to the service for a fresh new token. Returns an URL that the user must access in order to authorize the client.

request_xauth_token(username, password)¶: Request a limited token without using the whole OAuth flow, it just uses the username and password through xAuth

set_token_info(user_key, user_secret, verifier)¶: Creates a new token using the existing user_key, user_secret and verifier. Use this method

sign_request(httpreq)¶: Signs the httpreq for OAuth using the previously defined user token

TurpialHTTPBasicAuth¶

class libturpial.lib.http.TurpialHTTPBasicAuth(base_url, proxies=None, timeout=None)¶

Implementation of TurpialHTTPBase for the HTTP Basic Authentication. base_url is the part of the URL common for all your requests. username and password are the username credentials. proxies and timeout work in the same way that in libturpial.api.interfaces.http.TurpialHTTPBase.

proxies and timeout work in the same way that in libturpial.api.interfaces.http.TurpialHTTPBase.

To fetch a resource using Basic Authentication just create a new TurpialHTTPBasicAuth object and pass the user credentials as parameters:

>>> base_url = 'http://identi.ca/api'
>>> username = 'example'
>>> password = 'example'
>>> http = TurpialHTTPBasicAuth(base_url, username, password)

Then perform the request desired using get or post methods:

>>> http.get('/my_first/end_point', args={'arg1': '1'}, _format='json')
>>> http.post('/my_second/end_point', args={'arg1': '2'}, _format='json')

__init__(base_url, proxies=None, timeout=None)¶

__module__ = 'libturpial.lib.http'¶

set_user_info(username, password)¶: Set the username and password for the basic authentication

sign_request(httpreq)¶: The httpreq is signed using the Authorization header as documented in the Basic Access Authentication Wiki

TurpialHTTPRequest¶

class libturpial.lib.http.TurpialHTTPRequest(method, uri, headers=None, params=None, _format='json', secure=False, files=None)¶: Encapsulate an URL request into a python object

Protocols¶

Twitter¶

class libturpial.lib.protocols.twitter.twitter.Main¶

Twitter implementation for libturpial

__init__()¶

__module__ = 'libturpial.lib.protocols.twitter.twitter'¶

authorize_token(pin)¶

available_trend_locations()¶

block(screen_name)¶

check_for_errors(response)¶: Receives a json response and raise an exception if there are errors

destroy_direct_message(direct_message_id)¶

destroy_status(status_id)¶

follow(screen_name, by_id=False)¶

get_blocked()¶

get_conversation(status_id)¶

get_directs(count=20, since_id=None)¶

get_directs_sent(count=20, since_id=None)¶

get_entities(tweet)¶

get_favorites(count=20)¶

get_followers(only_id=False)¶

get_following(only_id=False)¶

get_list_statuses(list_id, count=20, since_id=None)¶

get_lists(username)¶

get_oauth_token()¶

get_profile(user)¶

get_profile_image(user)¶

get_public_timeline(count=20, since_id=None)¶

get_repeaters(status_id, only_username=False)¶

get_replies(count=20, since_id=None)¶

get_sent(count=20, since_id=None)¶

get_status(status_id)¶

get_timeline(count=20, since_id=None)¶

initialize_http()¶

is_friend(user)¶

json_to_list(response)¶

json_to_profile(response)¶

json_to_status(response, column_id='', type_=1)¶

json_to_trend(response)¶

json_to_trend_location(response)¶

mark_as_favorite(status_id)¶

repeat_status(status_id)¶

report_as_spam(screen_name)¶

request_token()¶

search(query, count=20, since_id=None, extra=None)¶

send_direct_message(screen_name, text)¶

setup_user_credentials(account_id, key, secret, verifier=None)¶

setup_user_info(account_id)¶

trends(location_id)¶

unblock(screen_name)¶

unfollow(screen_name)¶

unmark_as_favorite(status_id)¶

update_profile(fullname=None, url=None, bio=None, location=None)¶

update_profile_image(image_path)¶

update_status(text, in_reply_id=None, media=None)¶

verify_credentials()¶

verify_credentials_provider(format_='json')¶

Identi.ca¶

class libturpial.lib.protocols.identica.identica.Main¶

Identi.ca implementation for libturpial

GROUP_PATTERN = <_sre.SRE_Pattern object>¶

_Main__build_basic_args(count, since_id)¶

__init__()¶

__module__ = 'libturpial.lib.protocols.identica.identica'¶

block(screen_name)¶

check_for_errors(response)¶: Receives a json response and raise an exception if there are errors

destroy_direct_message(direct_message_id)¶

destroy_status(status_id)¶

follow(screen_name, by_id=False)¶

get_blocked()¶

get_conversation(status_id)¶

get_directs(count=20, since_id=None)¶

get_directs_sent(count=20, since_id=None)¶

get_entities(status)¶

get_favorites(count=20)¶

get_followers(only_id=False)¶

get_following(only_id=False)¶

get_list_statuses(list_id, user, count=20, since_id=None)¶

get_lists(username)¶

get_profile(user)¶

get_profile_image(user)¶

get_public_timeline(count=20, since_id=None)¶

get_rate_limits()¶

get_replies(count=20, since_id=None)¶

get_sent(count=20, since_id=None)¶

get_status(status_id)¶

get_timeline(count=20, since_id=None)¶

initialize_http()¶

is_friend(user)¶

json_to_profile(response)¶

json_to_status(response, column_id='', type_=1)¶

mark_as_favorite(status_id)¶

repeat_status(status_id)¶

search(query, count=20, since_id=None)¶

send_direct_message(screen_name, text)¶

setup_user_credentials(account_id, username, password)¶

unblock(screen_name)¶

unfollow(screen_name)¶

unmark_as_favorite(status_id)¶

update_profile(p_args)¶

update_status(text, in_reply_id=None)¶

verify_credentials()¶