Finishing touches.

Author: gresm

buildconfig/stubs/gen_stubs.py

@@ -104,15 +104,9 @@ def get_all(mod: Any):
     except KeyError:
         pygame_all_imports[f".{k}"] = val
 
-# this is overriden by __init__.py
-if ".base" in pygame_all_imports and "warn" in pygame_all_imports[".base"]:
-    pygame_all_imports[".base"].remove("warn")
 
 # misc stubs that must be added to __init__.pyi
-misc_stubs = """from typing import Type
-
-def warn(message: str, urgency: int, level: int = 2, category: Type[Warning] = UserWarning): ...
-"""
+misc_stubs = """"""
 
 # write constants.pyi file
 constants_file = pathlib.Path(__file__).parent / "pygame" / "constants.pyi"

buildconfig/stubs/pygame/__init__.pyi

@@ -1,9 +1,6 @@
 # buildconfig/stubs/gen_stubs.py
 # A script to auto-generate locals.pyi, constants.pyi, debug.pyi and __init__.pyi typestubs
 # IMPORTANT NOTE: Do not edit this file by hand!
-from typing import Type
-
-def warn(message: str, urgency: int, level: int = 2, category: Type[Warning] = UserWarning): ...
 
 from pygame import (
     display as display,
@@ -74,6 +71,7 @@ from .base import (
     register_quit as register_quit,
     set_error as set_error,
     set_warnings_filter as set_warnings_filter,
+    warn as warn,
 )
 
 from .rwobject import (

buildconfig/stubs/pygame/base.pyi

@@ -19,6 +19,6 @@ def register_quit(callable: Callable[[], Any], /) -> None: ...
 
 # undocumented part of pygame API, kept here to make stubtest happy
 def get_array_interface(arg: Any, /) -> dict: ...
-def warn(message: str, category: Type[Warning], level: int, urgency: int, /): ...
+def warn(message: str, urgency: int, level: int = 1, category: Type[Warning] = UserWarning): ...
 def get_warnings_filter() -> int: ...
 def set_warnings_filter(val: int, /): ...

buildconfig/stubs/pygame/debug.pyi

@@ -1,9 +1,6 @@
 # buildconfig/stubs/gen_stubs.py
 # A script to auto-generate locals.pyi, constants.pyi, debug.pyi and __init__.pyi typestubs
 # IMPORTANT NOTE: Do not edit this file by hand!
-from typing import Type
-
-def warn(message: str, urgency: int, level: int = 2, category: Type[Warning] = UserWarning): ...
 
 from pygame import (
     display as display,
@@ -74,6 +71,7 @@ from .base import (
     register_quit as register_quit,
     set_error as set_error,
     set_warnings_filter as set_warnings_filter,
+    warn as warn,
 )
 
 from .rwobject import (

docs/reST/ref/pygame.rst

@@ -227,7 +227,7 @@ object instead of the module, which can be used to test for availability.
 .. function:: warn
 
    | :sl:`throws a warning`
-   | :sg:`warn(message, urgency, level=2, category=UserWarning)`
+   | :sg:`warn(message, urgency, level=1, category=UserWarning)`
 
    Throws a warning with a given urgency. See documentation for :c:func:`pgWarn` for more information on urgency system.
 
@@ -236,14 +236,17 @@ object instead of the module, which can be used to test for availability.
 
    .. note::
       This function is mostly used internally, but might be also useful for extensions.
-      Arg ``level`` denotes how much to trace back in the call stack.
-      Beware, that the default value is 2, meaning the caller of a function with ``pygame.warn(...)`` will be blamed: ::
+      Arg ``level`` denotes how much to trace back in the call stack. If it is equal to 0, that means that the caller wil be blamed.
+      Beware, that the default value is 1, meaning the caller of a function with ``pygame.warn(...)`` will be blamed: ::
          
          >>> def my_func():
          ...     pygame.warn("Warning!", urgency=0)
          ... 
          >>> my_func()
-         <stdin>:1: UserWarning: Warning! (0: urgent)
+         <stdin>:1: UserWarning: Warning! (urgent: 0)
+         >>> def my_func2():
+         ...     pygame.warn("Warning!", urgency=0, level=0)
+         <stdin>:2: UserWarning: Warning! (urgent: 0)
 
    .. # pygame.warn ""
 
@@ -584,4 +587,29 @@ This hint only affects the windows platform, other platforms can control DPI awa
 via a Window creation keyword parameter called "allow_high_dpi".
 
 
+:mod:`pygame.debug`
+=====================
+
+.. module:: pygame.debug
+   :synopsis: small plug-in for enabling debugging information
+
+| :sl:`small plug-in for enabling debugging information`
+
+This is a simple plug-in that can be used as a drop-in repleacement for ``import pygame`` and imports alike.
+Example usage: ::
+
+   import pygame.debug as pg  # works the same as "import pygame as pg"
+
+   window = pg.display.set_mode((100, 100))
+
+   while True:
+      for event in pg.event.get():
+         if event.type == pg.QUIT:
+            pg.quit()
+            quit()
+      
+      pg.display.flip()
+
+Doing this will enable more detailed warnings and will print additional debug information.
+(Side note: this will automatically call ``pygame.init()`` to make debug information more complete, but this shouldn't have any side effects.)
 

src_c/base.c

@@ -2088,28 +2088,85 @@ pg_EnvShouldBlendAlphaSDL2(void)
     return pg_env_blend_alpha_SDL2;
 }
 
+static inline int
+intSizeAsStr(int num)
+{
+    if (num == 0) {
+        // printf("i s=1, zero");
+        return 1;
+    }
+    else if (num < 0) {
+        // printf("i s=%i, neg", ceil(log10(-num + 1)) + 1);
+        return ceil(log10(-num + 1)) + 1;
+    }
+    return ceil(log10(num + 1));
+}
+
 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);
+
+    const char *extra;
+
+    switch (urgency) {
+        case 0:
+            extra = "urgent: ";
+            break;
+        case 1:
+            extra = "mild: ";
+            break;
+        case 2:
+            extra = "note: ";
+            break;
+        default:
+            extra = "";
+    }
+
+    //         12              3 4
+    // "message (extra{urgency})\0"
+    printf("%s (%s%i)\n", message, extra, urgency);
+    printf("%lu, %lu, %i\n", strlen(message), strlen(extra),
+           intSizeAsStr(urgency));
+    size_t str_size =
+        strlen(message) + strlen(extra) + intSizeAsStr(urgency) + 4;
+
+    char *formatted = malloc(str_size);
+    if (formatted == NULL) {
+        PyErr_SetString(PyExc_MemoryError,
+                        "cannot allocate memory to format warning message");
+        return -1;
+    }
+
+    PyOS_snprintf(formatted, str_size, "%s (%s%i)", message, extra, urgency);
+
+    int ret = PyErr_WarnEx(category, formatted, stack_level);
+    free(formatted);
+    return ret;
 }
 
 static PyObject *
-pg_warn(PyObject *self, PyObject *args)
+pg_warn(PyObject *self, PyObject *args, PyObject *kwargs)
 {
-    PyObject *category;
+    PyObject *category = NULL;
     const char *message;
-    Py_ssize_t stack_level;
+    Py_ssize_t stack_level = -1;
     int urgency;
+    char *kw_names[] = {"message", "urgency", "level", "category", NULL};
 
-    if (!PyArg_ParseTuple(args, "sOni", &message, &category, &stack_level,
-                          &urgency))
+    if (!PyArg_ParseTupleAndKeywords(args, kwargs, "si|nO", kw_names, &message,
+                                     &urgency, &stack_level, &category))
         return NULL;
 
-    if (pgWarn(category, message, stack_level, urgency) < 0)
+    if (category == NULL)
+        category = PyExc_UserWarning;
+
+    if (stack_level < 0)
+        stack_level = 1;
+
+    if (pgWarn(category, message, stack_level + 1, urgency) < 0)
         return NULL;
 
     Py_RETURN_NONE;
@@ -2246,7 +2303,7 @@ static PyMethodDef _base_methods[] = {
 
     {"get_array_interface", (PyCFunction)pg_get_array_interface, METH_O,
      "return an array struct interface as an interface dictionary"},
-    {"warn", (PyCFunction)pg_warn, METH_VARARGS,
+    {"warn", (PyCFunction)pg_warn, METH_VARARGS | METH_KEYWORDS,
      "throw a warning with a given severity which is only used for filtering"},
     {"get_warnings_filter", (PyCFunction)pg_get_warnings_filter, METH_NOARGS,
      "get value of a warning filter by severity (smaller number - more "

src_c/doc/pygame_doc.h

@@ -13,9 +13,10 @@
 #define DOC_ENCODESTRING "encode_string([obj [, encoding [, errors [, etype]]]]) -> bytes or None\nEncode a Unicode or bytes object"
 #define DOC_ENCODEFILEPATH "encode_file_path([obj [, etype]]) -> bytes or None\nEncode a Unicode or bytes object as a file system path"
 #define DOC_PRINTDEBUGINFO "print_debug_info(filename=None) -> None\nretrieves useful information for debugging and issue-reporting purposes"
-#define DOC_WARN "warn(message, urgency, level=2, category=UserWarning)\nthrows a warning"
+#define DOC_WARN "warn(message, urgency, level=1, category=UserWarning)\nthrows a warning"
 #define DOC_VERSION "small module containing version information"
 #define DOC_VERSION_VER "ver = '1.2'\nversion number as a string"
 #define DOC_VERSION_VERNUM "vernum = (1, 5, 3)\ntupled integers of the version"
 #define DOC_VERSION_REV "rev = 'a6f89747b551+'\nrepository revision of the build"
 #define DOC_VERSION_SDL "SDL = '(2, 26, 5)'\ntupled integers of the SDL library version"
+#define DOC_DEBUG "small plug-in for enabling debugging information"

src_py/__init__.py

@@ -94,26 +94,6 @@ def _attribute_undefined(name):
 from pygame.constants import *  # now has __all__ pylint: disable=wildcard-import; lgtm[py/polluting-import]
 from pygame.version import *  # pylint: disable=wildcard-import; lgtm[py/polluting-import]
 
-_warn = warn
-del warn
-
-
-def warn(message, urgency, level=2, category=UserWarning):  # pylint: disable=function-redefined
-    """Throws a warning with a given urgency"""
-    names = {0: "urgent", 1: "mild", 2: "note"}
-
-    if urgency in names:
-        note = f"{urgency}: {names[urgency]}"
-    else:
-        note = str(urgency)
-
-    _warn(
-        f"{message} ({note})",
-        category,
-        level + 1,
-        urgency,
-    )
-
 
 from pygame.rect import Rect, FRect
 from pygame.rwobject import encode_string, encode_file_path

test/base_test.py

@@ -629,7 +629,7 @@ def test_warn(self):
             self._warn("message", 0)
             self.assertEqual(len(cx.warnings), 1)
             warning = cx.warnings[0]
-            self.assertEqual(str(warning.message), "message (0: urgent)")
+            self.assertEqual(str(warning.message), "message (urgent: 0)")
             self.assertIn("base_test.py", warning.filename)
 
         with self.assertWarns(UserWarning) as cx: