Surface properties (#2813)

* test commit

* attributes

* forgot stubs

* changes as per request

* python setup.py docs removed this?

* removed w and h

* forgot stub removal

* Fixed docs for review

* Make arrow spacing more consistent in surf docs

* removed unnecessary section in docs

---------

Co-authored-by: Andrew Coffey <[email protected]>
Co-authored-by: Starbuck5 <[email protected]>

Author: 3 people

buildconfig/stubs/pygame/surface.pyi

@@ -42,6 +42,12 @@ _ViewKind = Literal[
 
 class Surface:
     _pixels_address: int
+    @property
+    def width(self) -> int: ...
+    @property
+    def height(self) -> int: ...
+    @property
+    def size(self) -> Tuple[int, int]: ...
     @overload
     def __init__(
         self,

docs/reST/ref/surface.rst

@@ -719,7 +719,7 @@
       | :sl:`get the dimensions of the Surface`
       | :sg:`get_size() -> (width, height)`
 
-      Return the width and height of the Surface in pixels.
+      Return the width and height of the Surface in pixels. Can also be accessed with :attr:`size`
 
       .. ## Surface.get_size ##
 
@@ -728,7 +728,7 @@
       | :sl:`get the width of the Surface`
       | :sg:`get_width() -> width`
 
-      Return the width of the Surface in pixels.
+      Return the width of the Surface in pixels. Can also be accessed with :attr:`width`
 
       .. ## Surface.get_width ##
 
@@ -737,7 +737,7 @@
       | :sl:`get the height of the Surface`
       | :sg:`get_height() -> height`
 
-      Return the height of the Surface in pixels.
+      Return the height of the Surface in pixels. Can also be accessed with :attr:`height`
 
       .. ## Surface.get_height ##
 
@@ -1030,6 +1030,33 @@
 
       .. ## Surface.premul_alpha ##
 
+    .. attribute:: width
+
+        | :sl:`Surface width in pixels (read-only)`
+        | :sg:`width -> int`
+
+        Read-only attribute. Same as :meth:`get_width()`
+
+    .. versionadded:: 2.5.0
+
+    .. attribute:: height
+
+        | :sl:`Surface height in pixels (read-only)`
+        | :sg:`height -> int`
+
+        Read-only attribute. Same as :meth:`get_height()`
+
+    .. versionadded:: 2.5.0
+
+    .. attribute:: size
+
+        | :sl:`Surface size in pixels (read-only)`
+        | :sg:`height -> tuple[int, int]`
+
+        Read-only attribute. Same as :meth:`get_size()`
+
+    .. versionadded:: 2.5.0
+
    .. ## pygame.Surface ##
 
 

src_c/doc/surface_doc.h

@@ -52,3 +52,6 @@
 #define DOC_SURFACE_GETBUFFER "get_buffer() -> BufferProxy\nacquires a buffer object for the pixels of the Surface."
 #define DOC_SURFACE_PIXELSADDRESS "_pixels_address -> int\npixel buffer address"
 #define DOC_SURFACE_PREMULALPHA "premul_alpha() -> Surface\nreturns a copy of the surface with the RGB channels pre-multiplied by the alpha channel."
+#define DOC_SURFACE_WIDTH "width -> int\nSurface width in pixels (read-only)"
+#define DOC_SURFACE_HEIGHT "height -> int\nSurface height in pixels (read-only)"
+#define DOC_SURFACE_SIZE "height -> tuple[int, int]\nSurface size in pixels (read-only)"

src_c/surface.c

@@ -266,6 +266,9 @@ _PgSurface_SrcAlpha(SDL_Surface *surf);
 static PyGetSetDef surface_getsets[] = {
     {"_pixels_address", (getter)surf_get_pixels_address, NULL,
      "pixel buffer address (readonly)", NULL},
+    {"width", (getter)surf_get_width, NULL, DOC_SURFACE_WIDTH, NULL},
+    {"height", (getter)surf_get_height, NULL, DOC_SURFACE_HEIGHT, NULL},
+    {"size", (getter)surf_get_size, NULL, DOC_SURFACE_SIZE, NULL},
     {NULL, NULL, NULL, NULL, NULL}};
 
 static struct PyMethodDef surface_methods[] = {

test/surface_test.py

@@ -674,6 +674,18 @@ def test_get_width__size_and_height(self):
                 self.assertEqual(s.get_height(), h)
                 self.assertEqual(s.get_size(), (w, h))
 
+    def test_attributes(self):
+        """Test width, height, and size attributes of surface"""
+        s = pygame.Surface((100, 50))
+        self.assertEqual(s.width, 100)
+        self.assertEqual(s.height, 50)
+        self.assertEqual(s.size, (100, 50))
+
+        attrs = ["width", "height", "size"]
+        for attr in attrs:
+            with self.assertRaises(AttributeError):
+                setattr(s, attr, 200)
+
     def test_get_view(self):
         """Ensure a buffer view of the surface's pixels can be retrieved."""
         # Check that BufferProxys are returned when array depth is supported,