fixes, refactors and docs

Author: itzpr3d4t0r

buildconfig/stubs/pygame/__init__.pyi

@@ -646,8 +646,4 @@ from .constants import (
     WINDOWSHOWN as WINDOWSHOWN,
     WINDOWSIZECHANGED as WINDOWSIZECHANGED,
     WINDOWTAKEFOCUS as WINDOWTAKEFOCUS,
-)
-from .geometry import (
-    Circle as Circle,
-    CircleType as CircleType
 )

buildconfig/stubs/pygame/geometry.py renamed to buildconfig/stubs/pygame/geometry.pyi

@@ -13,8 +13,10 @@ def __init__(self, x: float, y: float, r: float) -> None: ...
     @overload
     def __init__(self, pos: Sequence[float], r: float) -> None: ...
     @overload
-    def __init__(self, circle) -> None: ...
-    def __copy__(self) -> "Circle": ...
+    def __init__(self, circle: Circle) -> None: ...
+    @overload
+    def __init__(self, obj_with_circle_attr) -> None: ...
+    def __copy__(self) -> Circle: ...
     copy = __copy__
 
 CircleType = Circle

docs/reST/ext/boilerplate.py

@@ -337,6 +337,7 @@ def lowercase_name(d):
         "music",
         "pygame",
         "Rect",
+        "geometry",
         "Surface",
         "sprite",
         "time",

docs/reST/index.rst

@@ -179,6 +179,9 @@ Reference
 :doc:`ref/rect`
   Flexible container for a rectangle.
 
+:doc:`ref/geometry`
+  Geometry types and operations.
+
 :doc:`ref/scrap`
   Native clipboard access.
 

docs/reST/ref/geometry.rst

@@ -0,0 +1,57 @@
+.. include:: common.txt
+
+:mod:`pygame.geometry`
+======================
+
+.. module:: pygame.geometry
+   :synopsis: pygame geometry module
+
+   | :sl:`pygame module for the Circle, Rect, and Polygon objects`
+
+.. currentmodule:: pygame
+
+.. class:: Circle
+
+   | :sl:`pygame object representing a circle`
+   | :sg:`Circle(center, radius) -> Circle`
+   | :sg:`Circle(x, y, radius) -> Circle`
+   | :sg:`Circle(object) -> Circle`
+
+   .. attribute:: x
+
+         | :sl:`center x coordinate of the circle`
+         | :sg:`x -> float`
+
+         The `x` coordinate of the center of the circle.
+
+         .. ## Circle.x ##
+
+   .. attribute:: y
+
+         | :sl:`center y coordinate of the circle`
+         | :sg:`y -> float`
+
+         The `y` coordinate of the center of the circle.
+
+         .. ## Circle.y ##
+
+   .. attribute:: r
+
+         | :sl:`radius of the circle`
+         | :sg:`r -> float`
+
+         The `r` coordinate of the center of the circle. You cannot set the radius to a negative value.
+
+         .. ## Circle.r ##
+
+   .. method:: copy
+
+         | :sl:`returns a copy of the circle`
+         | :sg:`copy() -> Circle`
+
+         The `copy` method returns a new `Circle` object having the same position and radius
+         as the original `Circle`. The function takes no arguments.
+
+         .. ## Circle.copy ##
+
+   .. ## pygame.Circle ##

docs/reST/themes/classic/elements.html

@@ -40,7 +40,7 @@ <h5>pygame-ce documentation</h5>
 We render three sets of items based on how useful to most apps.
 
 #}
-{%- set basic = ['Color', 'display', 'draw', 'event', 'font', 'image', 'key', 'locals', 'mixer', 'mouse', 'music', 'pygame', 'Rect', 'Surface', 'time'] %}
+{%- set basic = ['Color', 'display', 'draw', 'event', 'font', 'image', 'key', 'locals', 'mixer', 'mouse', 'music', 'pygame', 'Rect', 'geometry', 'Surface', 'time'] %}
 {%- set advanced = ['BufferProxy', 'freetype', 'gfxdraw', 'midi', 'PixelArray', 'pixelcopy', 'sndarray', 'surfarray', 'cursors', 'joystick', 'mask', 'math', 'sprite', 'transform'] %}
 {%- set hidden = ['Overlay', 'cdrom', 'sdl2_video', 'sdl2_controller'] %}
 {%-   if pyg_sections %}

src_c/circle.c

@@ -1,4 +1,5 @@
 #include "geometry.h"
+#include "doc/geometry_doc.h"
 
 static PyObject *
 _pg_circle_subtype_new(PyTypeObject *type, pgCircleBase *circle)
@@ -34,13 +35,14 @@ pgCircle_FromObject(PyObject *obj, pgCircleBase *out)
         return 1;
     }
 
+    /* Paths for sequences */
     if (pgSequenceFast_Check(obj)) {
         PyObject **f_arr = PySequence_Fast_ITEMS(obj);
         length = PySequence_Fast_GET_SIZE(obj);
 
         if (length == 3) {
-            if (!pg_DoubleFromObj(f_arr[0], &(out->x)) ||
-                !pg_DoubleFromObj(f_arr[1], &(out->y)) ||
+            if (!pg_DoubleFromObj(f_arr[0], &out->x) ||
+                !pg_DoubleFromObj(f_arr[1], &out->y) ||
                 !_pg_circle_set_radius(f_arr[2], out)) {
                 return 0;
             }
@@ -53,7 +55,7 @@ pgCircle_FromObject(PyObject *obj, pgCircleBase *out)
             return 1;
         }
         else if (length == 2) {
-            if (!pg_TwoDoublesFromObj(f_arr[0], &(out->x), &(out->y)) ||
+            if (!pg_TwoDoublesFromObj(f_arr[0], &out->x, &out->y) ||
                 !_pg_circle_set_radius(f_arr[1], out)) {
                 return 0;
             }
@@ -66,21 +68,20 @@ pgCircle_FromObject(PyObject *obj, pgCircleBase *out)
         }
     }
     else if (PySequence_Check(obj)) {
-        /* Path for other sequences or Types that count as sequences*/
         PyObject *tmp = NULL;
         length = PySequence_Length(obj);
         if (length == 3) {
             /*These are to be substituted with better pg_DoubleFromSeqIndex()
              * implementations*/
             tmp = PySequence_ITEM(obj, 0);
-            if (!pg_DoubleFromObj(tmp, &(out->x))) {
+            if (!pg_DoubleFromObj(tmp, &out->x)) {
                 Py_DECREF(tmp);
                 return 0;
             }
             Py_DECREF(tmp);
 
             tmp = PySequence_ITEM(obj, 1);
-            if (!pg_DoubleFromObj(tmp, &(out->y))) {
+            if (!pg_DoubleFromObj(tmp, &out->y)) {
                 Py_DECREF(tmp);
                 return 0;
             }
@@ -97,7 +98,7 @@ pgCircle_FromObject(PyObject *obj, pgCircleBase *out)
         }
         else if (length == 2) {
             tmp = PySequence_ITEM(obj, 0);
-            if (!pg_TwoDoublesFromObj(tmp, &(out->x), &(out->y))) {
+            if (!pg_TwoDoublesFromObj(tmp, &out->x, &out->y)) {
                 Py_DECREF(tmp);
                 return 0;
             }
@@ -128,41 +129,41 @@ pgCircle_FromObject(PyObject *obj, pgCircleBase *out)
         }
     }
 
-    if (PyObject_HasAttrString(obj, "circle")) {
-        PyObject *circleattr;
-        circleattr = PyObject_GetAttrString(obj, "circle");
-        if (!circleattr) {
-            PyErr_Clear();
-            return 0;
-        }
-        if (PyCallable_Check(circleattr)) /*call if it's a method*/
-        {
-            PyObject *circleresult = PyObject_CallObject(circleattr, NULL);
-            Py_DECREF(circleattr);
-            if (!circleresult) {
-                PyErr_Clear();
-                return 0;
-            }
-            circleattr = circleresult;
-        }
-        if (!pgCircle_FromObject(circleattr, out)) {
+    /* Path for objects that have a circle attribute */
+    PyObject *circleattr;
+    if (!(circleattr = PyObject_GetAttrString(obj, "circle"))) {
+        PyErr_Clear();
+        return 0;
+    }
+
+    if (PyCallable_Check(circleattr)) /*call if it's a method*/
+    {
+        PyObject *circleresult = PyObject_CallObject(circleattr, NULL);
+        Py_DECREF(circleattr);
+        if (!circleresult) {
             PyErr_Clear();
-            Py_DECREF(circleattr);
             return 0;
         }
-        Py_DECREF(circleattr);
+        circleattr = circleresult;
+    }
 
-        return 1;
+    if (!pgCircle_FromObject(circleattr, out)) {
+        PyErr_Clear();
+        Py_DECREF(circleattr);
+        return 0;
     }
-    return 0;
+
+    Py_DECREF(circleattr);
+
+    return 1;
 }
 
 static PyObject *
 pg_circle_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
 {
     pgCircleObject *self = (pgCircleObject *)type->tp_alloc(type, 0);
 
-    if (self != NULL) {
+    if (self) {
         self->circle.x = self->circle.y = 0;
         self->circle.r = 1;
         self->weakreflist = NULL;
@@ -174,18 +175,19 @@ static int
 pg_circle_init(pgCircleObject *self, PyObject *args, PyObject *kwds)
 {
     if (!pgCircle_FromObject(args, &self->circle)) {
-        PyErr_SetString(PyExc_TypeError,
-                        "Argument must be Circle style object");
+        PyErr_SetString(
+            PyExc_TypeError,
+            "Arguments must be a Circle, a sequence of length 3 or 2, or an "
+            "object with an attribute called 'circle'");
         return -1;
     }
-
     return 0;
 }
 
 static void
 pg_circle_dealloc(pgCircleObject *self)
 {
-    if (self->weakreflist != NULL) {
+    if (self->weakreflist) {
         PyObject_ClearWeakRefs((PyObject *)self);
     }
 
@@ -235,11 +237,11 @@ pg_circle_str(pgCircleObject *self)
 }
 
 static struct PyMethodDef pg_circle_methods[] = {
-    {"__copy__", (PyCFunction)pg_circle_copy, METH_NOARGS, NULL},
-    {"copy", (PyCFunction)pg_circle_copy, METH_NOARGS, NULL},
+    {"__copy__", (PyCFunction)pg_circle_copy, METH_NOARGS, DOC_CIRCLE_COPY},
+    {"copy", (PyCFunction)pg_circle_copy, METH_NOARGS, DOC_CIRCLE_COPY},
     {NULL, NULL, 0, NULL}};
 
-#define GETSET_FOR_SIMPLE(name)                                               \
+#define GETTER_SETTER(name)                                                   \
     static PyObject *pg_circle_get##name(pgCircleObject *self, void *closure) \
     {                                                                         \
         return PyFloat_FromDouble(self->circle.name);                         \
@@ -249,19 +251,19 @@ static struct PyMethodDef pg_circle_methods[] = {
     {                                                                         \
         double val;                                                           \
         DEL_ATTR_NOT_SUPPORTED_CHECK_NO_NAME(value);                          \
-        if (pg_DoubleFromObj(value, &val)) {                                  \
-            self->circle.name = val;                                          \
-            return 0;                                                         \
+        if (!pg_DoubleFromObj(value, &val)) {                                 \
+            PyErr_Format(PyExc_TypeError, "Expected a number, got '%s'",      \
+                         Py_TYPE(value)->tp_name);                            \
+            return -1;                                                        \
         }                                                                     \
-        PyErr_SetString(PyExc_TypeError, "Expected a number");                \
-        return -1;                                                            \
+        self->circle.name = val;                                              \
+        return 0;                                                             \
     }
 
-// they are repetitive enough that we can abstract them like this
-GETSET_FOR_SIMPLE(x)
-GETSET_FOR_SIMPLE(y)
+GETTER_SETTER(x)
+GETTER_SETTER(y)
 
-#undef GETSET_FOR_SIMPLE
+#undef GETTER_SETTER
 
 static PyObject *
 pg_circle_getr(pgCircleObject *self, void *closure)
@@ -277,13 +279,13 @@ pg_circle_setr(pgCircleObject *self, PyObject *value, void *closure)
     DEL_ATTR_NOT_SUPPORTED_CHECK_NO_NAME(value);
 
     if (!pg_DoubleFromObj(value, &radius)) {
-        PyErr_SetString(PyExc_TypeError,
-                        "Invalid type for radius, must be numeric");
+        PyErr_Format(PyExc_TypeError, "Expected a number, got '%s'",
+                     Py_TYPE(value)->tp_name);
         return -1;
     }
 
     if (radius <= 0) {
-        PyErr_SetString(PyExc_ValueError, "Invalid radius value, must be > 0");
+        PyErr_SetString(PyExc_ValueError, "Radius must be positive");
         return -1;
     }
 
@@ -293,9 +295,9 @@ pg_circle_setr(pgCircleObject *self, PyObject *value, void *closure)
 }
 
 static PyGetSetDef pg_circle_getsets[] = {
-    {"x", (getter)pg_circle_getx, (setter)pg_circle_setx, NULL, NULL},
-    {"y", (getter)pg_circle_gety, (setter)pg_circle_sety, NULL, NULL},
-    {"r", (getter)pg_circle_getr, (setter)pg_circle_setr, NULL, NULL},
+    {"x", (getter)pg_circle_getx, (setter)pg_circle_setx, DOC_CIRCLE_X, NULL},
+    {"y", (getter)pg_circle_gety, (setter)pg_circle_sety, DOC_CIRCLE_Y, NULL},
+    {"r", (getter)pg_circle_getr, (setter)pg_circle_setr, DOC_CIRCLE_R, NULL},
     {NULL, 0, NULL, NULL, NULL}};
 
 static PyTypeObject pgCircle_Type = {
@@ -305,7 +307,7 @@ static PyTypeObject pgCircle_Type = {
     .tp_repr = (reprfunc)pg_circle_repr,
     .tp_str = (reprfunc)pg_circle_str,
     .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,
-    .tp_doc = NULL,
+    .tp_doc = DOC_CIRCLE,
     .tp_weaklistoffset = offsetof(pgCircleObject, weakreflist),
     .tp_methods = pg_circle_methods,
     .tp_getset = pg_circle_getsets,

src_c/doc/geometry_doc.h

@@ -0,0 +1,7 @@
+/* Auto generated file: with makeref.py .  Docs go in docs/reST/ref/ . */
+#define DOC_GEOMETRY "pygame module for the Circle, Rect, and Polygon objects"
+#define DOC_CIRCLE "Circle(center, radius) -> Circle\nCircle(x, y, radius) -> Circle\nCircle(object) -> Circle\npygame object representing a circle"
+#define DOC_CIRCLE_X "x -> float\ncenter x coordinate of the circle"
+#define DOC_CIRCLE_Y "y -> float\ncenter y coordinate of the circle"
+#define DOC_CIRCLE_R "r -> float\nradius of the circle"
+#define DOC_CIRCLE_COPY "copy() -> Circle\nreturns a copy of the circle"

src_c/geometry.c

@@ -25,7 +25,6 @@ MODINIT_DEFINE(geometry)
         return NULL;
     }
 
-    /* create the module */
     module = PyModule_Create(&_module);
     if (!module) {
         return NULL;

src_c/geometry.h

@@ -22,7 +22,6 @@ typedef struct {
 
 static PyTypeObject pgCircle_Type;
 
-// return 1 if success and 0 if failure
 static int
 pgCircle_FromObject(PyObject *obj, pgCircleBase *out);