Add function to list muted accounts

[hadley]

eg. https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/mute-block-report-users/api-reference/get-mutes-users-ids

[llrs]

Thanks! Yes, indeed is something I found missing. Fixing #467 would also help if people over-muted

[hadley]

I think the problem is that post_follow() is trying to do too much — it calls one of four different API endpoints depending on the combination of arguments used. I'd be happy to do a PR to fix this if you wanted.

[llrs]

Yes, PR are more than welcomed, if you have time send it please. Just not sure when I'll merge them. As currently I can't use the github actions to test the package, and I would like to prioritize fixing the long-standing open issues following #471

[hadley]

I think the most important thing is to get the tests working again, but I don't see an issue that tracks that?

[llrs]

Indeed! Maybe I should create one. There are a couple of things with tests:

1. I don't have access to the keys and token of the rstats2twitter app provided by rtweet (which is used for the test). They are not in Travis or GHA. I just sent today an email to @mkearney, asking him and explaining the situation, if I don't get any reply in a couple of weeks I will go ahead and provide a new token (Probably would get in touch with Twitter developers to make sure this is ok).

2. I'm kind of new contributing to this repository and my PR are first reviewed by @sckott. I provided a minor improvement in #478. As I didn't get any response on that front I halted a bit. But I created another branch (improve-tests) for a more through review of tests.

[hadley]

I'll wait until you're done with #527, before working on this issue, but I've been starting to think about the interface a little bit. We might as well tackle blocking at the same time in the same fashion, so I was thinking of the following six functions:

user_mute()          # POST mutes/users/create
user_unmute()        # POST mutes/users/destroy
user_block()         # POST blocks/create
user_unblock()       # POST blocks/destroy

user_list_muted()    # GET blocks/ids
user_list_blocked()  # GET mutes/users/ids

I think it makes the most sense to start the function names with the "type" of thing (user, tweet, list, message) because I think that's the most obvious part — you might not know exactly what type of operation you want to apply, but it seems likely that you'll know what to apply it to. Then we follow with a verb, matching how people normally talk about these operations.

user_list_muted() doesn't feel quite right to me because you're listing the users that you have muted, so it wouldn't take a user id. Maybe it should be self_list_muted()? I think maybe all the self_ functions would end up being list methods (e.g. other important actions would tweet_create(), dm_create(), user_follow()) so maybe the list is redundant and is should just be self_muted()?

user_mute()    # POST mutes/users/create
user_unmute()  # POST mutes/users/destroy
user_block()   # POST blocks/create
user_unblock() # POST blocks/destroy

self_muted()   # GET blocks/ids
self_blocked() # GET mutes/users/ids

The downside of this naming convention is that it requires the user to understand the different words associated with muting (i.e. mute, unmute, muted). Another approach would be to adhere closer to the twitter url scheme:

user_mute_create()    # POST mutes/users/create
user_mute_destroy()   # POST mutes/users/destroy
user_mute_list()      # GET blocks/ids

user_block_create()   # POST blocks/create
user_block_destroy()  # POST blocks/destroy
user_block_list()     # GET mutes/users/ids

But that's a little harder to understand because you have to think of mute and block as nouns, not verbs.

[llrs]

Not sure how people use rtweet (would like to explore, perhaps by looking at the dependencies), but to me it is the contrary I know what I want to do so I know what I need. What about a shorter direct more similar to the app/web names like:

tweet()
delete()

mute() # POST mutes/users/create
unmute() # POST mutes/users/destroy
muted() # GET blocks/ids

block()
unblock()
blocked()

lists()
enlist()
un/delist()

The major downside I see is that they are quite similar mute/muted

[hadley]

My worry with just using verbs is that the chances of finding good verbs for every single operation is low — e.g. at some point you're going to realise that there's something else you want to delete(), and since you've already used up the obvious verb, what are you going to use instead? Or how will you disambiguate the different types of search?

[llrs]

Sorry, been thinking about this for a while.

I think (now) your last proposal makes more sense mimic as possible the Twitter API. It will make it easier to expand to new endpoints and we can insert "_v2" if there is a conflict with new v2 API.

[steveharoz]

Coming over from #638. I lean more towards @hadley's suggestion because the verb names aren't always very obvious (e.g., it get_timeline, not user_tweets). And it'd be nice to differentiate the global actions (like search) from the actions on an item or group of items.

Here's a stab at a naming convention:

1. Prefix with tweet_, user_, or self_, depending on what the verb acts on. If it is a global function (e.g., search) skip the prefix.
2. Make the rest of the function name a verb.
3. For create and destroy, leave "create" functions simple (user_mute()) and add "destroy" (user_mute_destroy()). That will keep them adjacent in autocomplete, which can help with discoverability.
4. Try to stick to the twitter API when reasonable.

Apply to tweet:

tweet_get_liking_users()
tweet_get_retweeters()

Apply to user:

user_mute()          # POST mutes/users/create
user_mute_destroy()  # POST mutes/users/destroy
user_block()         # POST blocks/create
user_block_destroy() # POST blocks/destroy
user_get_timeline() # GET

Apply to self

self_get_muted()  
self_get_blocked() 
self_get_timeline() 
self_tweet()
self_tweet_destroy()
self_retweet()
self_retweet_destroy()

The get convention can help let people know they aren't taking action. I worry that with simple verbs, people may inadvertently make actions (mute), when they want to inquire (get_muted).

[steveharoz]

Thinking more about the naming scheme, should it be self_retweet() or tweet_retweet()? Maybe both? Having an alias wouldn't do much harm.