Added keyword arguments to Font.render (#2000)

* Added kwargs to font.render

* Added docs and tests for kwargs for font.render

* Fix incompatible pointer

* Added wraplength to font.render

* Attempt to fix failing test

* Remove changes to ftfont.py

* Change a test to only run for FontTest class

* Fix formatting issue

* Adjusted keyword arg names for font.render and updated docs

* Fix documentation error

* Changed arguments fgcolor and bgcolor in ftfont

* Adjusted tests to include freetype font

* Adjusted formatting

* Fixed failing test in font_test

* Fixing font_test again

* Fixing font_test yet again

* Fix formatting

* Renamed fgcolor to color

* Fixed remaining mentions of background

Author: PurityLake

buildconfig/stubs/pygame/font.pyi

@@ -40,7 +40,7 @@ class Font:
         text: Union[str, bytes, None],
         antialias: bool,
         color: ColorValue,
-        background: Optional[ColorValue] = None,
+        bgcolor: Optional[ColorValue] = None,
         wraplength: int = 0
     ) -> Surface: ...
     def size(self, text: Union[str, bytes]) -> Tuple[int, int]: ...

docs/reST/ref/font.rst

@@ -278,7 +278,7 @@ solves no longer exists, it will likely be removed in the future.
    .. method:: render
 
       | :sl:`draw text on a new Surface`
-      | :sg:`render(text, antialias, color, background=None, wraplength=0) -> Surface`
+      | :sg:`render(text, antialias, color, bgcolor=None, wraplength=0) -> Surface`
 
       This creates a new Surface with the specified text rendered on it. 
       :mod:`pygame.font` provides no way to directly draw text on an existing
@@ -292,9 +292,9 @@ solves no longer exists, it will likely be removed in the future.
       UCS-4 range are supported. For char strings a ``LATIN1`` encoding is
       assumed. The antialias argument is a boolean: if True the characters
       will have smooth edges. The color argument is the color of the text
-      [e.g.: (0,0,255) for blue]. The optional background argument is a color
-      to use for the text background. If no background is passed the area
-      outside the text will be transparent.
+      [e.g.: (0,0,255) for blue]. The optional bgcolor argument is a color
+      to use for the text background. If bgcolor is ``None`` the area outside
+      the text will be transparent.
 
       The `wraplength` argument describes the width (in pixels) a line of text
       should be before wrapping to a new line. See
@@ -332,6 +332,8 @@ solves no longer exists, it will likely be removed in the future.
 
       .. versionadded:: 2.1.4 wraplength parameter
 
+      .. versionchanged:: 2.3.0 now supports keyword arguments.
+
       .. ## Font.render ##
 
    .. method:: size

src_c/doc/font_doc.h

@@ -15,7 +15,7 @@
 #define DOC_FONT_FONT_UNDERLINE "underline -> bool\nGets or sets whether the font should be rendered with an underline."
 #define DOC_FONT_FONT_STRIKETHROUGH "strikethrough -> bool\nGets or sets whether the font should be rendered with a strikethrough."
 #define DOC_FONT_FONT_ALIGN "align -> int\nSet how rendered text is aligned when given a wrap length"
-#define DOC_FONT_FONT_RENDER "render(text, antialias, color, background=None, wraplength=0) -> Surface\ndraw text on a new Surface"
+#define DOC_FONT_FONT_RENDER "render(text, antialias, color, bgcolor=None, wraplength=0) -> Surface\ndraw text on a new Surface"
 #define DOC_FONT_FONT_SIZE "size(text) -> (width, height)\ndetermine the amount of space needed to render text"
 #define DOC_FONT_FONT_SETUNDERLINE "set_underline(bool) -> None\ncontrol if text is rendered with an underline"
 #define DOC_FONT_FONT_GETUNDERLINE "get_underline() -> bool\ncheck if text will be rendered with an underline"

src_c/font.c

@@ -475,7 +475,7 @@ font_set_strikethrough(PyObject *self, PyObject *arg)
 }
 
 static PyObject *
-font_render(PyObject *self, PyObject *args)
+font_render(PyObject *self, PyObject *args, PyObject *kwds)
 {
     TTF_Font *font = PyFont_AsFont(self);
     int antialias;
@@ -486,8 +486,12 @@ font_render(PyObject *self, PyObject *args)
     const char *astring = "";
     int wraplength = 0;
 
-    if (!PyArg_ParseTuple(args, "OpO|Oi", &text, &antialias, &fg_rgba_obj,
-                          &bg_rgba_obj, &wraplength)) {
+    static char *kwlist[] = {"text",    "antialias",  "color",
+                             "bgcolor", "wraplength", NULL};
+
+    if (!PyArg_ParseTupleAndKeywords(args, kwds, "OpO|Oi", kwlist, &text,
+                                     &antialias, &fg_rgba_obj, &bg_rgba_obj,
+                                     &wraplength)) {
         return NULL;
     }
 
@@ -871,7 +875,8 @@ static PyMethodDef font_methods[] = {
     {"set_strikethrough", font_set_strikethrough, METH_O,
      DOC_FONT_FONT_SETSTRIKETHROUGH},
     {"metrics", font_metrics, METH_O, DOC_FONT_FONT_METRICS},
-    {"render", font_render, METH_VARARGS, DOC_FONT_FONT_RENDER},
+    {"render", (PyCFunction)font_render, METH_VARARGS | METH_KEYWORDS,
+     DOC_FONT_FONT_RENDER},
     {"size", font_size, METH_O, DOC_FONT_FONT_SIZE},
     {"set_script", font_set_script, METH_O, DOC_FONT_FONT_SETSCRIPT},
     {"set_direction", (PyCFunction)font_set_direction,

src_py/ftfont.py

@@ -59,7 +59,7 @@ def __init__(self, file=None, size=20):
         self.ucs4 = True
         self.underline_adjustment = 1.0
 
-    def render(self, text, antialias, color, background=None):
+    def render(self, text, antialias, color, bgcolor=None):
         """render(text, antialias, color, background=None) -> Surface
         draw text on a new Surface"""
 
@@ -74,7 +74,7 @@ def render(self, text, antialias, color, background=None):
         )
         self.antialiased = bool(antialias)
         try:
-            s, _ = super().render(text, color, background)
+            s, _ = super().render(text, color, bgcolor)
             return s
         finally:
             self.antialiased = save_antialiased

test/font_test.py

@@ -9,7 +9,6 @@
 import pygame
 from pygame import font as pygame_font  # So font can be replaced with ftfont
 
-
 FONTDIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "fixtures", "fonts")
 
 
@@ -245,6 +244,31 @@ def test_render_args(self):
         self.assertEqual(tuple(screen.get_at((0, 0)))[:3], (255, 255, 255))
         self.assertEqual(tuple(screen.get_at(font_rect.topleft))[:3], (255, 255, 255))
 
+        # ftfont and font render with different arguments
+        if pygame_font.__name__ == "pygame.font":
+            font_surface = f.render(
+                text="   bar",
+                antialias=True,
+                color=(0, 0, 0),
+                bgcolor=(255, 255, 255),
+                wraplength=0,
+            )
+        else:
+            font_surface = f.render(
+                text="   bar",
+                antialias=True,
+                color=(0, 0, 0),
+                bgcolor=(255, 255, 255),
+            )
+        screen.fill((10, 10, 10))
+        font_rect = font_surface.get_rect()
+        font_rect.topleft = rect.topleft
+        self.assertTrue(font_surface)
+        screen.blit(font_surface, font_rect, font_rect)
+        pygame.display.update()
+        self.assertEqual(tuple(screen.get_at((0, 0)))[:3], (255, 255, 255))
+        self.assertEqual(tuple(screen.get_at(font_rect.topleft))[:3], (255, 255, 255))
+
         # If we don't have a real display, don't do this test.
         # Transparent background doesn't seem to work without a read video card.
         if os.environ.get("SDL_VIDEODRIVER") != "dummy":