Implementing warnings system and pygame.debug

[gresm]

Fixes #2894

Notes (mostly to self):

• Should pygame.base.get_warnings_filter/pygame.base.set_warnings_filter be public API (likely not)?
• Current idea of warning priorities (can be changed):
  • 0 is the most impactful - if a warning of its type is triggered, probably the code won't work
  • 1 is less severe - like deprecation warnings
  • 2 is least important - warnings might be pedantic or about conventions or detection of common pitfalls that can contain false positives, so is suppressed by default
• This PR does not introduce new warnings to guide users, only sets up a system for filtering them. Porting opinionated warnings pygame/pygame#1682 or implementing something like that is still needed, but in a separate PR.

[bilhox]

Everything in the side of documentation seems fine. Maybe if you add a code example that makes full use of the function argument, it would be more helpful to users.

[Starbuck5]

Hello, thanks for looking at this.

This is a complex patch, and I don't really see what adding a pygame-ce specific paradigm of filtering our existing warnings does for us.

I did not anticipate pygame.debug changing any existing warnings. It instead would add a whole new category of more opiniated ones and extra information. Maybe it could use SDL_Log and change the SDL log level so we get SDL debug information too? But then again maybe the juice isn't worth the squeeze for this.

[gresm]

Well, this is a large patch, but it isn't complex - the logic behind it is quite simple, there are just a lot of places that needed to be updated to use the new warnings system (just renaming the PyErr_WarnEx to pgWarn and adding the urgency value).

Why I'm using what I'm using and not something like SDL warnings which have urgency? Because python warnings system was already used in the code base and I think that benefits that come from using python warnings system outweighs those of SDL warnings system (seamless integration with python code, advanced filtering system supporting regex, unit testing, etc...). An alternative implementation could create multiple filtering rules to ignore given warnings, but it would be slower (warnings that wouldn't be shown, would still need to go through the python warnings system) and harder to maintain (the necessity to keep the filter lists and updating them when a warning is added/removed/changed), so I think this is near optimal solution. That's my opinion on this matters.

Note that this PR still needs some finishing touches - pgWarn should behave the same as pygame.warn and pygame.debug isn't documented yet, I just didn't have time to do this.

[Starbuck5]

Well, this is a large patch, but it isn't complex - the logic behind it is quite simple, there are just a lot of places that needed to be updated to use the new warnings system (just renaming the PyErr_WarnEx to pgWarn and adding the urgency value).

Sure, but why do we need a new warnings system?

[gresm]

This PR warnings system can be summarized as (omitting code for formatting warning message to include warning level):

static int
pgWarn(PyObject *category, const char *message, Py_ssize_t stack_level,
       int urgency)
{
    if (pg_warn_filter < urgency)
        return 0;

    return PyErr_WarnEx(category, message, stack_level);
}

I used incorrect wording there - this is not much "a new warnings system", but rather a thin wrapper around an existing one (and heavily used before).
This is something like @MyreMylar propesed in #2894 (comment), but using a slightly different approach at how the warnings are filtered out.

[Starbuck5]

But Myre is proposing adding a new warning there, not changing existing warnings to not trigger.

[gresm]

Fair point, I'd like to hear your opinion on the warnings level I set for them (I've split warnings between 0, 1 and 2, where 0 and 1 are by default enabled with the intention of possibility introducing something like pygame.quiet if ever needed in the future).