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.