Welcome to ttrss-python’s documentation!

ttrss-python is a light-weight client library for the JSON API of Tiny Tiny RSS. Handling JSON in Python can be quite a pain, so this library abstracts all that away to deliver Python object representations of categories, feeds and articles. Also, the specific calls and POST data sent to the server is handled automatically, so that you can focus on the stuff that matters to your frontend application.

Sounds good so far? Great, let’s get started!

Installation

This package is available at PyPI, so the easiest way to install is by doing a pip install ttrss-python. This will install the latest released version, as well as all dependencies. Currently, the only dependency is the awesome Python requests library for handling all the http requests.

If you for some reason can’t or don’t want to use pip, just download the tarball and run python setup.py install manually.

It’s highly recommended to use virtualenv for this (and any other for that matter!) installation.

Basic usage

The first thing you need to do is instantiate a TTRClient. The constructor requires three arguments; URL, your username and your password:

>>> from ttrss.client import TTRClient
>>> client = TTRClient('http://url-to-tiny-tiny', 'username', 'super-secret-password')
>>> client.login()

If you want the client to login automatically, as well as automatically refresh an expired session cookie, you may supply the optional keyword argument auto_login=True. Note that this may affect performance in a high-traffic client application, since it uses a response hook to check every server response for a NOT_LOGGED_IN message:

>>> client = TTRClient('http://url-to-tiny-tiny', 'username', 'super-secret-password', auto_login=True)

Categories

Now you can retrieve a list of feed categories:

>>> categories = client.get_categories()

To be continued...

API Documentation

This section will become more detailed over time as I add docstrings to the source code.

client module

class ttrss.client.Article(attr, client=None)

Bases: ttrss.client.RemoteObject

publish()

refresh_status()

toggle_unread()

class ttrss.client.Category(attr, client=None)

Bases: ttrss.client.RemoteObject

feeds(**kwargs)

class ttrss.client.Feed(attr, client)

Bases: ttrss.client.RemoteObject

headlines()

class ttrss.client.Headline(attr, client=None)

Bases: ttrss.client.RemoteObject

full_article()

class ttrss.client.RemoteObject(attr, client=None)

Bases: object

class ttrss.client.TTRClient(url, user=None, password=None, auto_login=False)

Bases: object

This is the actual client interface to Tiny Tiny RSS.

This object retains a http session with the needed session cookies. From the client you can fetch categories, feeds, headlines and articles, all represented by Python objects. You can also update modify articles and feeds on the server.

get_articles(article_id)

Get a list of articles from article ids.

Parameters:article_id – A comma separated string of article ids to fetch.

get_categories()

Get a list of all available categories

get_feed_count()

Get total number of subscribed feeds.

get_feeds(cat_id=-1, unread_only=False, limit=0, offset=0, include_nested=False)

Get a list of feeds in a category.

Parameters:

• cat_id – Category id. This is available as the id property of a Category object.
• unread_only – Optional Include only feeds containing unread articles. Default is False.
• limit – Optional Limit number of included feeds to limit. Default is 0 (unlimited).
• offset – Optional Skip this number of feeds. Useful for pagination. Default is 0.
• include_nested – Optional Include child categories. Default is False.

get_headlines(feed_id=0)

Get a list of headlines from a specified feed.

Parameters:feed_id – Feed id. This is available as the id property of a Feed object.

get_unread_count()

Get total number of unread articles

logged_in()

login()

Manually log in (i.e. request a session cookie)

This method must be used if the client was not instantiated with auto_login=True

logout()

Log out.

After logging out, login() must be used to gain a valid session again. Please note that logging out invalidates any automatic re-login even after logging back in.

mark_read(article_id)

Mark an article as read.

Parameters:article_id – ID of article to mark as read.

mark_unread(article_id)

Mark an article as unread.

Parameters:article_id – ID of article to mark as unread.

refresh_article(article)

Update all properties of an article object with fresh information from the server.

Please note that this method alters the original object and does not return a new one.

Parameters:article – The article to refresh.

share_to_published(title, url, content)

Share an article to the published feed.

Parameters:

• title – Article title.
• url – Article url.
• content – Article content.

toggle_unread(article_id)

Toggle the unread status of an article.

Parameters:article_id – ID of the article to toggle.

Indices and tables

• Index
• Module Index
• Search Page