Document "pygame.warn()".

Author: gresm

docs/reST/ref/pygame.rst

@@ -224,6 +224,26 @@ object instead of the module, which can be used to test for availability.
 
    .. ## pygame.print_debug_info ##
 
+.. function:: warn
+
+   | :sl:`throws a warning`
+   | :sg:`warn(message, urgency, level=2, category=RuntimeWarning)`
+
+   Throws a warning with a given urgency. See documentation for :c:func:`pgWarn` for more information on urgency system.
+
+   .. 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: ::
+         
+         >>> def my_func():
+         ...     pygame.warn("Warning!", urgency=0)
+         ... 
+         >>> my_func()
+         <stdin>:1: RuntimeWarning: Warning!
+
+   .. # pygame.warn ""
+
 
 :mod:`pygame.version`
 =====================

src_c/doc/pygame_doc.h

@@ -13,6 +13,7 @@
 #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=RuntimeWarning)\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"

src_py/__init__.py

@@ -100,7 +100,19 @@ def _attribute_undefined(name):
 
 def warn(message, urgency, level=2, category=RuntimeWarning):  # pylint: disable=function-redefined
     """Throws a warning with a given urgency"""
-    _warn(message, category, level + 1, 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

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")
+            self.assertEqual(str(warning.message), "message (0: urgent)")
             self.assertIn("base_test.py", warning.filename)
 
         with self.assertWarns(RuntimeWarning) as cx:

test/sysfont_test.py

@@ -86,7 +86,7 @@ def test_sysfont_warnings(self):
         with self.assertWarns(RuntimeWarning):
             pygame.font.SysFont(("non-existent font", "non-existent font2"), 40)
 
-        with self.assertWarns(RuntimeError):
+        with self.assertWarns(RuntimeWarning):
             pygame.font.SysFont(
                 (bytes("non-existent font", "utf-8"), "non-existent font2"), 40
             )