Unify the interface names, request for comment

[hupili]

I noticed that some users are passing keyword arguments rather than positional arguments to the function calls. We need to unify the names.

From SNSPocket, there are always one extra kwarg called channel. It means to execute the function (home_timeline, update, reply, forward, auth) on a specific channel. Without this parameter, it is meant to batch execute the functions (See #49 for the explanation of batch execution). The following is a list of interfaces of plugins.

home timeline

def home_timeline(count=20)

It means to retrieve no more than (can be less) count messages. See also #49

update

Original:

def update(text)

The initial use cases are just texts (no title, pic, etc)

The intended upgrade is:

def update(text, attachment=None)

or

def update(text, title=None, link=None, pic=None)

While the latter case work well for renren, it looks clumsy. Besides, the setting is not generic enough. For example, on FB everything is just a "story". As to Renren, blog, share, and statuses are all different things.

reply

def reply(messageID, text)

messageID was historically called statusID. Leave a note here for kwarg users. We want to unify it to "message" later.

This setup is valid because you only need to know the ID in order to reply a message. You don't have to know the content of the message. (I mean the program does not have to). Towards this end, messageID is the minimal requirement. Also note that messageID is platform specific. The plugins put in whatever information it is required to locate one message on it. That is, given the information in messageID, it is enough to reply the message.

In SNSPocket, we have instance detection for the first positional argument. Then we call either plugin.reply(message, ...) or plugin.reply(message.ID, ...). This is for the convenience to operate in CLI. The interface of pocket is:

def reply(message, text)

forward

def forward(message, text)

In order to forward, you need more than messageID. Theoretically speaking, given messageID, we can retrieve the original message (from the service provider). However, we decide to save API calls. The following are cases where we need message besides messageID:

• On platforms like Renren and Sina, the forwarding sequence (or called message trace) is supplied by the client. Without the message, we can not construct the correct forwarding sequence.
• On Twitter, there is no explicit "forward" equivalence. The way to implement it is actually update a status with your comments, at the original post owner, piggyback original text. User on Twitter are implementing this manually for many years.

[hupili]

To conclude:

• update is problematic. We are trying to find a better way.
• There may be kwarg name change in a major upgrade
• The current practice of other interfaces look nice.