Documentation vs. code: Clarify and/or fix logic of "filter" function

[amotl]

Dear JP and Ben,

this is an important issue. Maybe you can find a few minutes to look into it.

With kind regards,
Andreas.

Introduction

I am bringing this up, because @sevmonster shared their experiences when using mqttwarn's filter feature, and because, after comparing it with the documentation, I discovered an anomaly between mqttwarn's documentation and implementation.

In its current incarnation, should it not be stopping all messages since it always returns False? Why are messages getting through? Am I misunderstanding the filter function usage?

I did individually test the logic in the conditional with dummy data so the rest of it should be sound and do what I want, with the understanding that True is a passing filter and False fails.

-- #632 (comment)

Documentation

While working on GH-635, I am now at the spot where the documentation states:

A function called from the filter property in a topic section needs to return False to stop the outbound notification.

-- Custom functions » Filter functions

Observations

However, while working on GH-632 and GH-635, we discovered that the opposite might be the case. Both code examples actually demonstrate that you need to return True to stop the outbound notification.

• Low battery notifications
• Frigate to Ntfy filter

[amotl]

mqttwarn's documentation would match Python's filter function ¹:

filter(function, iterable): Construct an iterator from those elements of iterable for which function is true.

However, mqttwarn's implementation is apparently doing it the other way round, contrary to its documentation. Is it a bug? How would we approach fixing this?

Footnotes

1. https://docs.python.org/3/library/functions.html#filter ↩

[codebude]

I also stumbled about this. I would suggest to keep the implementation as it is (to not break implementation done by all the users), but update the documentation to be more precise on how to create the filter.

E.g.:

A function called from the filter property in a topic section needs to return True to stop the outbound notification

[amotl]

Documentation fixed with 288392f. Thanks.