The API module contains the modules and classes that will be used for any developer that want to create an application or script based on libturpial. We can call it the public interface. Here you can find the Core, all the models that represent libturpial entities and the Managers


class libturpial.api.core.Core(load_accounts=True)

This is the main object in libturpial. This should be the only class you need to instantiate to use libturpial. Most important arguments used in Core are account_id and column_id.

  • account_id: Is a composite string formed by the username and the protocol_id that identify every single account.
  • column_id: Is composite string formed by account_id and the column_name that identify one column of one account.

Examples of account_id:

>>> my_twitter_account = 'foo-twitter'
>>> my_identica_account = 'foo-identica'

Example of column_id:

>>> twitter_timeline = 'foo-twitter-timeline'
>>> identica_replies = 'foo-identica-replies'

When you instantiate Core it will load all registered accounts automatically, so you don’t need to worry about it. If you already registered the accounts before, they will be available after you create the core object.

All the Core methods will return an object defined in libturpial.api.models or a valid python object if request is successful, otherwise they will raise an exception.

If the request returns an array, you can iterate over the elements with:

>>> for object in response:
>>>     print object
In all the following functions the following apply:
account_id must be a string (“username-service”) column_id must be a string (“columnname-username-service”)

Retrieve an image by it URL. Return the binary data of the image


Return an array with the ids of all registered accounts. For example:

>>> ['foo-twitter', 'foo-identica']

Register account into config files. account must be a valid and authenticated libturpial.api.models.account.Account object.

When instantiating Core() all accounts get automatically registered.

Return a string with the id of the account registered.

unregister_account(account_id, delete_all=False)

Removes the account identified by account_id from memory. If delete_all is True it deletes all the files asociated to that account from disk otherwise the account will be available the next time you load Core.

Return a string with the id of the account unregistered.


Return a dictionary with all columns per account. Example:

>>> {'foo-twitter': [libturpial.api.models.Column foo-twitter-timeline,
    libturpial.api.models.Column foo-twitter-replies,
    libturpial.api.models.Column foo-twitter-direct,
    libturpial.api.models.Column foo-twitter-sent,
    libturpial.api.models.Column foo-twitter-favorites]}

Register a column identified by column_id column and return a string with the id of the column registered on success.


Removes the column identified by column_id from config and return a string with the id if the column unregistered on success.


Return an array with the ids of supported protocols. For example:

>>> ['twitter', 'identica']

Return a dictionary with all available (non-registered-yet) columns per account. Example:

>>> {'foo-twitter': [libturpial.api.models.Column foo-twitter-direct,
    libturpial.api.models.Column foo-twitter-replies,
    libturpial.api.models.Column foo-twitter-sent]}

Return a dict with libturpial.api.models.column.Column objects per column registered. This method DO NOT return columns in the order they have been registered. For ordered columns check registered_columns_by_order()


Return a list with libturpial.api.models.column.Column objects per each column in the same order they have been registered.


Return a dict with all registered accounts as an array of libturpial.api.models.account.Account objects registered


Return the libturpial.api.models.column.Column object identified with column_id


Return the libturpial.api.models.account.Account object identified with account_id

get_column_statuses(account_id, column_id, count=20, since_id=None)

Fetch the statuses for the account account_id and the column column_id. count let you specify how many statuses do you want to fetch, values range goes from 0-200. If since_id is not None libturpial will only fetch statuses newer than that.

get_public_timeline(account_id, count=20, since_id=None)

Fetch the public timeline for the service associated to the account account_id. count and since_id work in the same way that in libturpial.api.core.Core.get_column_statuses()

get_followers(account_id, only_id=False)

Return a libturpial.api.models.profile.Profile list with all the followers of the account account_id

get_following(account_id, only_id=False)

Return a libturpial.api.models.profile.Profile list of all the accounts that account_id follows


Return a list with all the username friends of all the registered accounts.

get_user_profile(account_id, user=None)

Return the profile of the user, using the account_id, if user is None, it returns the profile of account_id itself.

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

Updates the account account_id with content of text

if in_reply_id is not None, specifies the tweets that is being answered.

media can specify the filepath of an image. If not None, the status is posted with the image attached. At this moment, this method is only valid for Twitter.

broadcast_status(account_id_array, text)

Updates all the accounts in account_id_array with the content of text

if account_id_array is None or an empty list all registered accounts get updated.

destroy_status(account_id, status_id)

Deletes status of account_id specified by status_id

get_single_status(account_id, status_id)

Retrieves a single status with account_id that corresponds with status_id

repeat_status(account_id, status_id)

Allows to send the same status again by using repeat option in API

mark_status_as_favorite(account_id, status_id)

Marks status of account_id specified by status_id as favorite

unmark_status_as_favorite(account_id, status_id)

Unmarks status of account_id specified by status_id as favorite

send_direct_message(account_id, username, message)

Sends a direct update with the contant of message to username using account_id

destroy_direct_message(account_id, status_id)

Deletes a direct update from account_id defined by its status_id

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

Updates the account_id public profile with the information in variables fullname = Complete account name url = Blog or personal URL of the account bio = Small resume location = Geographic location

follow(account_id, username, by_id=False)

Makes account_id a follower of username. Return a libturpial.api.models.profile.Profile object with the user profile

unfollow(account_id, username)

Stops account_id from being a follower of username. Return a libturpial.api.models.profile.Profile object with the user profile

block(account_id, username)

Blocks username in account_id. Return a libturpial.api.models.profile.Profile object with the user profile

unblock(account_id, username)

Unblocks username in account_id. Return a libturpial.api.models.profile.Profile object with the user profile

report_as_spam(account_id, username)

Reports username as SPAM using account_id. Return a libturpial.api.models.profile.Profile object with the user profile


Adds username into the muted list, so that no more statuses from that account are shown


Removes username from the muted list, so that statuses from that account are now shown

verify_friendship(account_id, username)

Return True if the owner of account_id and username are following each other. False otherwise.

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

Performs a search using Twitter API, defined by: account_id = Account to be used for the search query = Search Term acount = Max number of results since_id = if limited to a status id and on.

get_profile_image(account_id, username, use_cache=True)

Return the local path to a the profile image of username in original size. If use_cache is True it will try to return the cached file, otherwise it will fetch the real image.


Return the local path to a the profile image of the username to post status in 48x48 px size


Return an array of libturpial.api.models.trend.TrendLocation objects with all the locations with trending topics registered.

Return an array of libturpial.api.models.trend.Trend objects with trending topics for the specified location. location_id is the Yahoo! Where On Earth ID for the location.

update_profile_image(account_id, image_path)

Update profile image of account_id with the image specified by image_path. Return a libturpial.api.models.profile.Profile object with the user profile updated.

register_new_config_option(section, option, default_value)

Register a new configuration option in section to be handled by external modules. libturpial will set default_value as value if the option doesn’t exist.

This method should be used if a module that uses libturpial needs to handle configuration options not registered by default.

For example, if you want to register an option to handle notifications on login the code should looks like:

>>> core = Core()
>>> core.register_new_config_option('Notifications', 'login', 'on')

From this point you can use config methods over this value as usual.


Return True is username is muted. False otherwise


Return how many statuses should be fetched in each requests


Return a libturpial.api.models.proxy.Proxy object with the configuration stored in disk.


Return the timeout set for the socket connections


Return a list with all registered filters


Save lst a the new filters list


Delete current configuration file. This action can not be undone


Delete all files in cache


Return current space used by cache


Save username into the friends list


Remove username from friends list


Here you can find the representation of the information used by libturpial mapped to Python objects. They handle the methods and properties of each entity and guarantee the data consistency.


class libturpial.api.models.account.Account(protocol_id, username=None)

This class represents an user account and holds all it related methods. This is done thanks to one libturpial.lib.interfaces.protocol.Protocol instance associated to the user account that handles all the dirty work against the service (Twitter, Identi.ca, etc) as well as one libturpial.api.models.profile.Profile model that store the user details.

This is the class you must instanciate if you want to handle/authenticate a user account.

Account let you perform three actions to build an account: create a new account from scratch, create a new account from params and load a previously registered account. To create a new account from scratch do:

>>> account = Account.new('twitter')

If you know the username too, then you can pass it as argument:

>>> account = Account.new('twitter', 'username')

At this point, that account is not a valid account yet because it hasn’t been authenticated. You should do the authentication by yourself. This is, request OAuth access:

>>> url = account.request_oauth_access()

That method will return an URL that your user must visit to authorize the app. After that, you must to ask for the PIN returned by the service and execute:

>>> account.authorize_oauth_access('the_pin')

And voilá! You now have a valid and fully authenticated account ready to be registered in libturpial.api.core.Core.

But Account let you create accounts passing all the params needed for the OAuth authentication. If you already know those params (user key, user secret and PIN) then you just need to execute:

>>> account = Account.new_from_params('twitter', 'username', 'key', 'secret', 'the_pin')

And you will have a valid and fully authenticated account ready to be registered in libturpial.api.core.Core too.

Now, what if you did all this process before and registered the account in libturpial.api.core.Core? Well, you just need to load the account then:

>>> account = Account.load('username-twitter')

And you will have an account already authenticated and ready to be used.

From this point you can use the method described here to handle the account object.

static new(protocol_id, username=None)

Return a new account object associated to the protocol identified by protocol_id. If username is not None it will build the account_id for the account.

This account is empty and must be authenticated before it can be registered in libturpial.api.core.Core.


None information is stored at disk at this point.

static new_from_params(protocol_id, username, key, secret, verifier)

Return a new account object associated to the protocol identified by protocol_id and authenticated against the respective service (Twitter, Identi.ca, etc) using username, key, secret and verifier (aka PIN).

This account is authenticated after creation, so it can be registered in libturpial.api.core.Core immediately.


None information is stored at disk at this point.

static load(account_id)

Return the account object associated to account_id loaded from existing configuration. If the account_id does not correspond to a valid account it returns a libturpial.exceptions.ErrorLoadingAccount exception.

If credentials in configuration file are empty it returns a libturpial.exceptions.EmptyOAuthCredentials exception.


Ask for an OAuth token. Return an URL that must be visited for the user in order to authenticate the app.


Take the pin returned by OAuth service and authenticate the token requested with request_oauth_access


Save to disk the configuration and credentials for the account. If the account hasn’t been authenticated it will raise an libturpial.exceptions.AccountNotAuthenticated exception.


Retrieve the user profile information and return the id of the account on success. This method authenticate the account.


Retrieve all the friends for the user and return an array of string where each element correspond to the user_id of the friend.


Return an array of libturpial.api.models.column.Column with all the available columns for the user


Delete all config files related to this account


Delete all files cached for this account


Return disk space used by cache in bytes


Return True if the current account has been logged in, False otherwise

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

Update the fullname, url, bio or location of the user profile. You may specify one or more arguments. Return an libturpial.api.models.profile.Profile object containing the user profile


class libturpial.api.models.column.Column(account_id, slug, singular_unit='tweet', plural_unit='tweets')

This model represents a column that holds libturpial.api.models.status.Status objects. You need to specify to what account_id are they associated, as well as the column slug. Available column slugs are available in libturpial.common.ColumnType.

  • id – Column id (for example: “johndoe-twitter-timeline”)
  • slug – Column slug
  • account_id – id of account associated to the column
  • size – max number of statuses that this column can hold
  • singular_unit – unit used to identify one status (for example: ‘tweet’)
  • plural_unit – unit used to identify more than one status (for example: ‘tweets’)


class libturpial.api.models.list.List

This class handles the information about a user list. It receives the id_, the user who owns it, the name (also known as slug), the title or caption, the number of suscribers, it description and the units used for plural and singular: singular_unit, plural_unit.

  • id – List id
  • user – User that owns the list
  • slug – List name
  • title – List title
  • suscribers – Suscribed users (count)
  • description – List description
  • single_unit – Singularized unit (‘tweet’ for example)
  • plural_unit – Pluralized unit (‘tweet’ for example)


class libturpial.api.models.status.Status

This model represents and holds all the information of a status.

  • id – Status id
  • account_id – Id of the account associated to this status
  • text – Text of the status
  • username – Name of the user that updated the status
  • avatar – Display image of the user that updated the status
  • source – Client used to upload this status
  • timestamp – Time of publishing of this status (Unix time)
  • in_reply_to_id – Contains the id of the status answered (if any)
  • in_reply_to_user – Contains the user answered with status (if any)
  • is_favoriteTrue if this status has been marked as favorite. False otherwise
  • is_protectedTrue if this status is from a protected account. False otherwise
  • is_verifiedTrue if this status is from a verified account. False otherwise
  • repeatedTrue if this status has been repeated (retweeted) by you. False otherwise
  • repeated_by – More users that have repeated this status
  • repeated_count – How much times this status has been repeated
  • original_status_id – Id of the original status (not-repeated)
  • created_at – Original timestamp from the service
  • datetime – Humanized representation of the date/time of this status
  • is_ownTrue if the status belongs to the same user of the associated account. False otherwise
  • entities – A dict with all the entities found in status
  • type – Status type.

Sometimes a status can hold one or more entities (URLs, hashtags, etc). In this case the entities variable will store a dict with lists for each category. For example:

>>> status.entities
{'urls': [], 'hashtags': [], 'mentions': [], 'groups': []}

A status can handle two possible types: libturpial.api.models.status.Status.NORMAL for regular statuses or libturpial.api.models.status.Status.DIRECT for private (direct) statuses.


Returns all usernames mentioned in status (even the author of the status)


Return True if this status is a direct message


Return the protocol_id associated to this status


Parse the source text in the status and store it in a libturpial.api.models.client.Client object.


class libturpial.api.models.profile.Profile

This model handles all the information stored for a user profile.

  • id – Profile id
  • account_id – Account id that fetched this profile
  • fullname – Full name of the user
  • avatar – Display image
  • location – User location
  • url – User URL
  • bio – User bio or description
  • following – Indicate if the user is following to the account_id owner (True`or `False)
  • followed_by – Indicate if the user is followed by the account_id owner (True`or `False)
  • follow_request – Indicate if there is a pending follow request of this profile
  • followers_count – Number of followers of this user
  • friends_count – Number of friends of this user
  • favorites_count – Number of favorite statuses of this user
  • statuses_count – Number of statuses this user has done
  • link_color – Color used to highlight entities (URLs, hashtags, etc)
  • last_update – Text of the last status updated
  • last_update_id – Id of the last status updated
  • protected – Indicate if the profile is protected (True`or `False)
  • verified – Indicate if the profile is verified (True`or `False)

Return True if the username of the profile is the same of the associated account, otherwise False. This method can be useful to determinate if a status belongs to given account.


Returns the protocol_id for this profile


class libturpial.api.models.entity.Entity(account_id, url, text, search)

Sometimes a libturpial.api.models.status.Status can content mentions, URLs, hashtags and other class of interactuable objects, so this class models that data in a structured way

  • account_id – Id of the account that holds the status
  • url – A possible URL for the media/content
  • display_text – Text that must be displayed to user
  • search_for – Text that must be used to search this object


class libturpial.api.models.client.Client(name=None, url=None)

This class models the information of the client of a given status

  • name – Client name
  • url – Client URL


class libturpial.api.models.media.Media(type_, name, content, path=None, info=None)

This class represents a media object (image, video or map) that can be rendered on the UI. type_ could be libturpial.api.models.media.IMAGE, libturpial.api.models.media.VIDEO or libturpial.api.models.media.MAP, name is the filename and content holds the binary data of the media. If path is None a temporary path will be created using the filename. info stores any additional information about the resource.

static new_image(name, content, path=None, info=None)

Create an image media


Saves the content of the media in the path specified.


Returns True if the media is a video


Returns True if the media is an image


Returns True if the media is a map


class libturpial.api.models.proxy.Proxy(host, port, username=None, password=None, secure=False)

This class models the information of a proxy server used to establish an HTTP connection. host and port are required. For an authenticated proxy set username and password with according credentilas and if proxy uses HTTPS set secure to True, otherwise let it empty or False

For example, to store the information of a non-authenticated HTTPS proxy:

>>> proxy = Proxy('', '1234', secure=True)

And for an authenticated HTTP proxy:

>>> proxy = Proxy('', '1234', 'my_user', 'secret_password')
  • host – Proxy host address
  • port – Proxy port
  • username – (Optional) Username for authentication
  • password – (Optional) Password for authentication
  • secure – Indicate whether proxy uses HTTP or HTTPS (Default False)


This classes are used by libturpial.api.core.Core to handle and organize multiple instances of columns and accounts. They are responsible of add, delete and manage both.

Account Manager

class libturpial.api.managers.accountmanager.AccountManager(config, load=True)

This class has methods to manage accounts. You can register new accounts, load and unregister existing accounts.

This manager can be iterated and each element will have the account id and the respective object. For example:

>>> for item in accman:
        print item
('foo-twitter', <libturpial.api.models.account.Account object at 0x10c5c2e10>)
('bar-twitter', <libturpial.api.models.account.Account object at 0x10c5c2910>)

To check how much accounts are registered simply use the len function:

>>> len(accman)

Load and existing account identified by account_id. If the load fails an libturpial.exceptions.ErrorLoadingAccount exception will raise. Return the id of the account loaded on success


Register the account object passed as argument. If the account hasn’t been authenticated it will raise a libturpial.exceptions.AccountNotAuthenticated exception. If the account is already registered a libturpial.exceptions.AccountAlreadyRegistered exception will raise. Return the id of the account registered on success

unregister(account_id, delete_all)

Remove the account identified by account_id from memory. If delete_all is True all configuration files are deleted from disk. Be careful because this operation can not be undone. Return the id of the unregistered column on success, None otherwise


Obtain the account identified by account_id. If the account is not loaded yet, it will be loaded immediately. Return a libturpial.api.models.account.Account object on success


Return an alphabetically sorted list with all the ids of the registered accounts.


Return a list of libturpial.api.models.account.Account objects with all the accounts registered

Column Manager

class libturpial.api.managers.columnmanager.ColumnManager(config)

This class has methods to manage columns. You can register new columns, load and unregister existing columns.

This manager can be iterated and each element will have a list of columns per account. For example:

>>> for item in column_manager:
        print item
('foo-twitter', [<libturpial.api.models.column.Column instance at 0x10a9ce368>, 
    <libturpial.api.models.column.Column instance at 0x10a9ce8c0>])

Register a new column identified by column_id. If the column is already registered a libturpial.exceptions.ColumnAlreadyRegistered exception will raise. Return the id of the column registered on success


Remove the column identified by column_id from memory. Return the id of the unregistered column.


Obtain the column identified by column_id and return a libturpial.api.models.column.Column object on success. None otherwise.


Return a dict where each key represents an account_id and it value is a list of libturpial.api.models.column.Column objects with all the columns registered.

For example:

>>> column_manager.columns()
{'foo-twitter': [<libturpial.api.models.column.Column instance at 0x10a9cbb48>, 
    <libturpial.api.models.column.Column instance at 0x10a9cb6c8>]}

Return True if column identified by column_id is registered. False otherwise.