Plugin API: Add optional message to module.rate()

[dgw]

If set, send message as a notice to the calling user if the command was canceled due to rate-limit. Ideally, it would support a placeholder such as {time_left} for the message to tell the user when they can use the command again.

I'd be happy to code it up and PR it; just want to establish that it'd have a chance of being merged first, before putting in that time.

Could also have a third parameter to toggle between using NOTICE and PRIVMSG.

[dgw]

If one of the collaborators for this repo feels like assigning this to me, I just came across it while cleaning out my oldest issues in the GitHub dashboard view, and am reminded that this would still be useful to have (since the majority of my Sopel modules use bespoke rate-limiting that includes these features).

[dgw]

Thanks for the reminder that this exists, @kwaaak. Assigning to Sopel 7 milestone, as it's an API change.

[dgw]

Hmm, this is not going to be so nice to implement with the rework of @rate from #1065.

Adding another optional msg kwarg would be fine, I guess, but not nearly as elegant as what I originally wanted to do (when there was only one type of rate-limit).

I suppose long-term we could consider splitting @rate into three decorators, but… it's not worth complicating the API like that for such a minor feature.

[dgw]

NAK third parameter (OP edited); should always use NOTICE.

[Exirel]

Still not sure how to do that properly for so many different rate limits:

def rate(user=0, channel=0, server=0, message=None):

Or:

def rate(user=0, channel=0, server=0, user_message=None, channel_message=None, server_message=None):

Or:

def rate(user=0, channel=0, server=0):  # deprecated?
def rate_user(limit, message=None):
def rate_channel(limit, message=None):
def rate_server(limit, message=None):

@dgw any opinion?

[dgw]

Combination of 1 & 3, mostly so there's a way to add more specific messages if necessary:

def rate(user=0, channel=0, server=0, message=None):  # not deprecated
def rate_user(limit, message=None):
def rate_channel(limit, message=None):
def rate_server(limit, message=None):

One consideration: I think it'd be good to implement the new decorators in such a way that they always take precedence over the generic rate values, regardless of the decorator order, just in case. Like this:

@plugin.rate(7, 7, 7, "This must be Vegas!")
@plugin.rate_channel(3, "Little maids from school")
def plugin_thing(bot, trigger):
    """Allowed every 3 seconds per channel, not 7 seconds."""
    pass

Also: What about making both args to the rate_* decorators optional, so a plugin dev could give all the rates in one shorthand @plugin.rate call and override one or two messages with just e.g. @plugin.rate_user(message="I'm different.")?

Would be super cool to allow overriding the message for a rate limit type without even needing the message=, or if e.g. @rate(30, 'It's too soon!') acted like @rate_user(30, 'It's too soon!')—but I know how you feel about "smart" argument handling, especially in complex cases like that second example.

No objection to putting this in 8.0, either, as there's plenty left for 7.1 as it is.

[Exirel]

Yeah OK it's getting quite complex and Sopel 8 will handle it, because Sopel 8 is 7.1 but better.

[Exirel]

Working on that, I already have a working solution, I just need to iron out the tests and the documentation.