Replace get_surface method of Window with surface property

buildconfig/stubs/pygame/window.pyi

@@ -26,7 +26,8 @@ class Window:
     def minimize(self) -> None: ...
     def set_modal_for(self, parent: Window, /) -> None: ...
     def set_icon(self, icon: Surface, /) -> None: ...
-    def get_surface(self) -> Surface: ...
+    @property
+    def surface(self) -> Surface: ...
     def flip(self) -> None: ...
 
     grab_mouse: bool

docs/reST/ref/window.rst

@@ -241,16 +241,16 @@
 
       .. deprecated:: 2.4.0
 
-   .. method:: get_surface
+   .. attribute:: surface
 
       | :sl:`Get the window surface`
-      | :sg:`get_surface() -> Surface`
+      | :sg:`surface -> Surface`
 
-      Returns a "display surface" for this Window. The surface returned is
+      Get a "display surface" for this Window. The surface obtained by this is
       analogous to the surface returned by :func:`pygame.display.set_mode`.
 
-      This method allows software rendering (classic pygame rendering) on top
-      of the Window API. This method should not be called when using hardware
+      This property allows software rendering (classic pygame rendering) on top
+      of the Window API. This attribute should not be used when using hardware
       rendering (coming soon).
 
       Similarly to the "display surface" returned by :mod:`pygame.display`,
@@ -273,24 +273,21 @@
       of the Window API. This method should not be called when using hardware
       rendering (coming soon).
 
-      Here is a runnable example of using ``get_surface`` and ``flip``:
+      Here is a runnable example of using ``surface`` property and ``flip``:
 
       .. code-block:: python
 
          import pygame
 
          win = pygame.Window()
-         surf = win.get_surface()  # get the window surface
-
          while True:
             for event in pygame.event.get():
                if event.type == pygame.QUIT:
                      pygame.quit()
                      raise SystemExit
 
             # draw something on the surface
-            surf.fill("red")
-
+            win.surface.fill("red")
             win.flip()  # update the surface to the window
 
 

src_c/doc/window_doc.h

@@ -16,7 +16,7 @@
 #define DOC_WINDOW_POSITION "position -> (int, int) or WINDOWPOS_CENTERED or WINDOWPOS_UNDEFINED\nGet or set the window position in screen coordinates"
 #define DOC_WINDOW_OPACITY "opacity -> float\nGet or set the window opacity, between 0.0 (fully transparent) and 1.0 (fully opaque)"
 #define DOC_WINDOW_FROMDISPLAYMODULE "from_display_module() -> Window\nCreate a Window object using window data from display module"
-#define DOC_WINDOW_GETSURFACE "get_surface() -> Surface\nGet the window surface"
+#define DOC_WINDOW_SURFACE "surface -> Surface\nGet the window surface"
 #define DOC_WINDOW_FLIP "flip() -> None\nUpdate the display surface to the window."
 #define DOC_WINDOW_SETWINDOWED "set_windowed() -> None\nEnable windowed mode (exit fullscreen)"
 #define DOC_WINDOW_SETFULLSCREEN "set_fullscreen(desktop=False) -> None\nEnter fullscreen"

src_c/window.c

@@ -139,7 +139,7 @@ window_destroy(pgWindowObject *self, PyObject *_null)
 }
 
 static PyObject *
-window_get_surface(pgWindowObject *self)
+window_get_surface(pgWindowObject *self, void *v)
 {
     PyObject *surf = NULL;
     SDL_Surface *_surf;
@@ -1022,13 +1022,12 @@ static PyMethodDef window_methods[] = {
      DOC_WINDOW_SETMODALFOR},
     {"set_icon", (PyCFunction)window_set_icon, METH_O, DOC_WINDOW_SETICON},
     {"flip", (PyCFunction)window_flip, METH_NOARGS, DOC_WINDOW_FLIP},
-    {"get_surface", (PyCFunction)window_get_surface, METH_NOARGS,
-     DOC_WINDOW_GETSURFACE},
     {"from_display_module", (PyCFunction)window_from_display_module,
      METH_CLASS | METH_NOARGS, DOC_WINDOW_FROMDISPLAYMODULE},
     {NULL, NULL, 0, NULL}};
 
 static PyGetSetDef _window_getset[] = {
+    {"surface", (getter)window_get_surface, NULL, DOC_WINDOW_SURFACE, NULL},
     {"grab_mouse", (getter)window_get_grab_mouse,
      (setter)window_set_grab_mouse, DOC_WINDOW_GRABMOUSE, NULL},
     {"grab_keyboard", (getter)window_get_grab_keyboard,

test/window_test.py

@@ -321,40 +321,37 @@ def test_from_display_module(self):
 
     def test_window_surface(self):
         win = Window(size=(640, 480))
-        surf = win.get_surface()
 
-        self.assertIsInstance(surf, pygame.Surface)
+        self.assertIsInstance(win.surface, pygame.Surface)
 
         # test auto resize
-        self.assertTupleEqual(win.size, surf.get_size())
+        self.assertTupleEqual(win.size, win.surface.get_size())
         win.size = (100, 100)
-        self.assertTupleEqual(win.size, surf.get_size())
+        self.assertTupleEqual(win.size, win.surface.get_size())
         win.size = (1280, 720)
-        self.assertTupleEqual(win.size, surf.get_size())
+        self.assertTupleEqual(win.size, win.surface.get_size())
 
         # window surface should be invalid after the window is destroyed
         win.destroy()
-        self.assertRaises(pygame.error, lambda: surf.fill((0, 0, 0)))
+        self.assertRaises(pygame.error, lambda: win.surface.fill((0, 0, 0)))
 
     def test_window_surface_with_display_module(self):
-        # get_surface() should raise an error if the set_mode() is not called.
+        # surface property should raise an error if the set_mode() is not called.
         pygame.display.set_mode((640, 480))
         win1 = Window.from_display_module()
         pygame.display.quit()
         pygame.init()
-        self.assertRaises(pygame.error, lambda: win1.get_surface())
+        self.assertRaises(pygame.error, lambda: win1.surface)
 
-        # the surface returned by get_surface() should be
+        # the surface returned by surface property should be
         # the surface returned by set_mode()
         surf1 = pygame.display.set_mode((640, 480))
         win2 = Window.from_display_module()
-        surf2 = win2.get_surface()
-        self.assertIs(surf1, surf2)
+        self.assertIs(surf1, win2.surface)
 
     def test_window_flip(self):
         win = Window(size=(640, 480))
-        surf = win.get_surface()
-        surf.fill((255, 0, 0))
+        win.surface.fill((255, 0, 0))
 
         self.assertRaises(TypeError, lambda: win.flip("an argument"))
         self.assertIs(win.flip(), None)