import pygame.debug

[MyreMylar]

Description

The idea here is to have a simple change that even a beginning user can make to their pygame script to enable a range of 'live' debugging information and warnings. It would replace import pygame and add debugging, diagnostic and warning information.

Credit to @Starbuck5 for the original idea, I'm just writing it up from discord discussion.

Example script:

import pygame.debug
import pygame.gfxdraw

pygame.init()


display_surf = pygame.display.set_mode(
    (800, 600), flags=pygame.SCALED | pygame.HWSURFACE, vsync=1
)
pygame.display.set_caption("Test")

clock = pygame.time.Clock()

while True:
    clock.tick(60)

    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            pygame.quit()

    display_surf.fill("black")

    pygame.gfxdraw.aacircle(display_surf, 100, 100, 50, pygame.Color("white"))
    pygame.display.flip()

Example output (exact message format not relevant):

pygame-ce 2.5.0.dev3 (SDL 2.30.3, Python 3.11.1) - try pygame.print_debug_info() for more environment details

WARNING: flag pygame.HWSURFACE is deprecated and no longer does anything.
WARNING: using vsync together with a frame limit in clock.tick() is not recommended.
WARNING: pygame.gfxdraw.aacircle() is now superseded by pygame.draw.aacircle().

Whereas with the standard import pygame at the top we would default to a 'release' mode with nothing printed to the console by pygame-ce.

I hope this idea could resolve a bunch of stalled issues and longstanding debates regarding what warnings are too much and what we should or should not be printing to the console. The slight caveat is reducing user awareness of things like deprecation warnings so perhaps there could be some debate about what should remain in 'standard/release' mode and what would be hidden under pgyame.debug

This simple change could be added to our beginner tutorials and some documentation example code snippets (perhaps with an explanatory comment). We could also advise it to users asking questions on reddit, discord and in issues here (a quick change to the bug report template) as a good first step when helping to diagnose problems.

What is incorporated into import pygame.debug could evolve over time and I think a basic implementation that moved, say the support prompt over to it would be enough to get started and resolve this issue.

[MyreMylar]

Related #1103, #1122, #2963, #820, #470, #858, #1147

Some of those are closed already, but generally with a 'won't fix' type answer so worth revisiting if we actually will fix.

[Starbuck5]

Some challenges here—

Adds complexity to our implementation
Performance implications of adding more internal of statements?
Will people actually use it?

[MyreMylar]

Some challenges here—

Adds complexity to our implementation

I guess this depends on how it grows. I'm mentally envisioning something like:

// at end of function
#ifndef PYGAME_STRIPPED   // Set as build option for meson build
if (SDL_getenv("PYGAME_DEBUG")) {  // Environment variable set to true when importing pygame.debug
    if (flags & PGS_HWSURFACE) {
        if (PyErr_WarnEx(PyExc_Warning, "HWSURFACE no longer does anything since version 2.0.0", 1) != 0) {
            return NULL;
        }
    }
}
#endif

if __debug__ and "PYGAME_DEBUG" in os.environ:
    print(
          f"pygame-ce {ver} (SDL {'.'.join(map(str, get_sdl_version()))}, "
          f"Python {platform.python_version()},
          try pygame.print_debug_info() for more environment details)"
      )

Performance implications of adding more internal of statements?

Yeah, I'm concerned by this as well - but I guess at the minute we are mostly sticking these warnings and prints to the console in in the standard mode of operation so changing them out for a single if check branch in the standard mode may sometimes speed things up. Printing to the console is usually slower than an if branch.

Will people actually use it?

That would be partly a publicity effort of saying (after the mode has developed for a while) to people reporting vague issues:

"have you tried switching import pygame for import pygame.debug?"

and doing things like adding it to new user tutorials. I think many programmers more widely are also familiar with the general concept of a debug & release mode for code.

[MyreMylar]

Incidentally I just discovered python -O