Internals

Overview

Here is an overview of the multiple files that compound turses, each of them with a comment explaining their goal.

turses
├── requirements
│   ├── base.txt
│   └── dev.txt
├── setup.py
└── turses
    ├── api
    │   ├── base.py      # definition of an interface to the Twitter API
    │   ├── backends.py  # Twitter API implementations
    │   ├── debug.py     # mock API implementation for debugging
    │   └── __init__.py
    ├── cli.py           # logic for launching `turses`
    ├── config.py        # configuration management
    ├── core.py          # core logic: controller and event handling
    ├── __init__.py
    ├── meta.py          # decorators and abstract base classes
    ├── models.py        # data structures
    ├── ui.py            # UI widgets
    └── utils.py         # misc funcions that don't fit elsewhere

turses.cli

Handle the invocation of turses from the command line.

turses.cli.main()

Launch turses.

turses.config

class turses.config.Configuration

Generate and parse configuration files. When instantiated, it loads the defaults.

Calling Configuration.parse_args() with an argparse.ArgumentParser instance will modify the instance to match the options provided by the command line arguments.

Calling turses.config.Configuration.load() on this class’ instances reads the preferences from the user configuration files. If no configuration or token files are found, this class will take care of creating them.

Offers backwards compatibility with the Tyrs configuration.

turses.core

This module contains the controller and key handling logic of turses.

class turses.core.InputHandler(controller)

Maps user input to calls to Controller functions.

class turses.core.Controller(ui, api, timelines)

The Controller.

turses.meta

This module contains abstract classes and decorators.

Decorators

turses.meta.wrap_exceptions(func)

Augments the function arguments with the on_error and on_success keyword arguments.

Executes the decorated function in a try except block and calls on_success (if given) if no exception was raised, otherwise calls on_error (if given).

turses.meta.async(func)

Decorator for executing a function in a separate threading.Thread.

turses.meta.filter_result(func, filter_func=None)

Decorator for filtering the output of func with filter_func.

Abstract base classes

The abstract base classes can be understood as interfaces; they define a set of methods and properties that their subclasses must implement. They provide very general pieces of functionality.

class turses.meta.ActiveList

A list that contains an active element.

This abstract class implements some functions but the subclasses must define the turses.meta.ActiveList.active property, as well as turses.meta.ActiveList.is_valid_index() and turses.meta.ActiveList.activate_last(). methods.

class turses.meta.UnsortedActiveList

A ActiveList in which the active element position can be shifted either to the beginning or to the end.

All the methods contained in this class are abstract.

class turses.meta.Observable

An implementation of the observer pattern.

Zero or more observers can subscribe to the changes in the instances of this class. When the instance changes, it will call its notify method, which loops through the observers and calls update() on them.

class turses.meta.Updatable(update_function=None, update_function_args=None, update_function_kwargs=None)

An abstract class for making a class updatable.

The constructor takes an update function and arguments used to update the subclasses of Updatable.

When update() is executed, update_callback() is called, passing it the result.

class turses.meta.Observable

An implementation of the observer pattern.

Zero or more observers can subscribe to the changes in the instances of this class. When the instance changes, it will call its notify method, which loops through the observers and calls update() on them.

class turses.meta.Observer

An abstract class that can subscribe to updates from Observable instances.

turses.meta.notify(func)

Wrap an instance method func, calling the instance’s notify method after executing func.

turses.models

This module contains the data structures that power turses and the Twitter entities represented into it.

Base model

The model on which turses is based is TimelineList, a list of Timeline objects. This model is mapped into the list of buffers that appear on the user interface.

class turses.models.TimelineList

A list of Timeline instances that implements the UnsortedActiveList interface, thus having an active element and a group of adjacent visible timelines.

Twitter models

The Twitter entities represented on turses are the following:

class turses.models.Timeline(name='', statuses=None, **kwargs)

List of Twitter statuses ordered reversely by date, optionally with a name and a function that updates the current timeline and its arguments.

Its Updatable and implements the ActiveList interface.

class turses.models.User(id, name, screen_name, description, url, created_at, friends_count, followers_count, favorites_count, status=None)

A Twitter user.

class turses.models.Status(id, created_at, user, text, author='', entities=None, is_reply=False, in_reply_to_user='', in_reply_to_status_id=None, is_retweet=False, retweeted_status=None, retweet_count=0, is_favorite=False)

A Twitter status.

class turses.models.DirectMessage(id, created_at, sender_screen_name, recipient_screen_name, text, entities=None)

A Twitter direct message.

class turses.models.List(id, owner, created_at, name, slug, description, member_count, subscriber_count, private=False)

A Twitter list.

turses.ui

This module contains the curses UI widgets.

class turses.ui.CursesInterface

Creates a curses interface for the program, providing functions to draw all the components of the UI.

Provides a facade API to draw the representation of the TimelineList, help HelpBuffer and intro Banner screens.

Note

The list of widgets presented here is not complete.

Widget wrappers

turses make heavy usage of the urwid.WidgetWrap class to compose custom widgets.

ScrollableWidgetWrap helps to make widgets that implement the Scrollable interface, thus are navigable with the motion commands up, down, scroll_to_top and scroll_to_bottom.

class turses.ui.ScrollableWidgetWrap(contents=None)

A urwid.WidgetWrap for Scrollable, list-like widgets.

Twitter Widgets

Here’s a list with some of the widgets that represent Twitter entities:

class turses.ui.TimelinesBuffer(timelines=None, **kwargs)

A widget that displays one or more Timeline objects.

Another widget can be placed on top of it.

class turses.ui.StatusWidget(status)

Widget containing a Twitter status.

class turses.ui.UserInfo(user, last_statuses)

A widget for displaying a Twitter user info.

Other widgets

class turses.ui.HelpBuffer

A widget that displays all the keybindings of the given configuration.

class turses.ui.Banner

Displays information about the program.

turses.utils

This module contains functions used across different modules.