[GR-67331] Establish C API conventions

PullRequest: graalpython/3900

Author: msimacek

.pre-commit-config.yaml

@@ -4,24 +4,28 @@ repos:
   - id: checkcopyrights
     name: Copyright check
     language: system
+    require_serial: true
     entry: bash scripts/pre-commit-checkcopyrights.sh
     types: [text]
   - id: eclipseformat
     name: Eclipse formatter
     language: system
+    require_serial: true
     entry: bash scripts/pre-commit-eclipseformat.sh
     types: [text]
     files: '\.java$'
   - id: checkstyle
     name: Checkstyle
     language: system
+    require_serial: true
     entry: bash scripts/pre-commit-checkstyle.sh
     types: [text]
     files: '\.java$'
   - id: pylint
     name: Pylint on mx files
     language: system
     pass_filenames: false
+    require_serial: true
     entry: bash scripts/pre-commit-pylint.sh
     types: [text]
     files: '^mx\.graalpython/.*\.py$'

graalpython/com.oracle.graal.python.cext/include/abstract.h

@@ -1,4 +1,4 @@
-/* Copyright (c) 2018, 2024, Oracle and/or its affiliates.
+/* Copyright (c) 2018, 2025, Oracle and/or its affiliates.
  * Copyright (C) 1996-2020 Python Software Foundation
  *
  * Licensed under the PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2
@@ -755,13 +755,12 @@ PyAPI_FUNC(PyObject *) PySequence_Fast(PyObject *o, const char* m);
 #define PySequence_Fast_GET_ITEM(o, i)\
      (PyList_Check(o) ? PyList_GET_ITEM((o), (i)) : PyTuple_GET_ITEM((o), (i)))
 
-// GraalPy-specific
-PyAPI_FUNC(PyObject **) PyTruffleSequence_Fast_ITEMS(PyObject *o);
-
 /* Return a pointer to the underlying item array for
    an object returned by PySequence_Fast */
 // GraalPy change
-#define PySequence_Fast_ITEMS(sf) PyTruffleSequence_Fast_ITEMS(sf)
+#define PySequence_Fast_ITEMS(sf) \
+    (PyList_Check(sf) ? GraalPyList_ITEMS(_PyObject_CAST((sf))) \
+                      : GraalPyTuple_ITEMS(_PyObject_CAST((sf))))
 
 /* Return the number of occurrences on value on 'o', that is, return
    the number of keys for which o[key] == value.

graalpython/com.oracle.graal.python.cext/include/cpython/abstract.h

@@ -1,4 +1,4 @@
-/* Copyright (c) 2020, 2024, Oracle and/or its affiliates.
+/* Copyright (c) 2020, 2025, Oracle and/or its affiliates.
  * Copyright (C) 1996-2020 Python Software Foundation
  *
  * Licensed under the PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2
@@ -165,13 +165,10 @@ PyAPI_FUNC(Py_ssize_t) PyObject_LengthHint(PyObject *o, Py_ssize_t);
 
 /* === Sequence protocol ================================================ */
 
-// GraalPy-specific
-PyAPI_FUNC(PyObject*) PyTruffleSequence_ITEM(PyObject* obj, Py_ssize_t index);
-
 /* Assume tp_as_sequence and sq_item exist and that 'i' does not
    need to be corrected for a negative index. */
-// GraalPy change
-#define PySequence_ITEM(o, i) PyTruffleSequence_ITEM((o), (i))
+#define PySequence_ITEM(o, i)\
+    ( Py_TYPE(o)->tp_as_sequence->sq_item((o), (i)) )
 
 #define PY_ITERSEARCH_COUNT    1
 #define PY_ITERSEARCH_INDEX    2

graalpython/com.oracle.graal.python.cext/include/cpython/code.h

@@ -1,4 +1,4 @@
-/* Copyright (c) 2022, 2024, Oracle and/or its affiliates.
+/* Copyright (c) 2022, 2025, Oracle and/or its affiliates.
  * Copyright (C) 1996-2022 Python Software Foundation
  *
  * Licensed under the PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2
@@ -374,9 +374,9 @@ PyAPI_FUNC(PyObject *) PyCode_GetCellvars(PyCodeObject *code);
 /* Equivalent to getattr(code, 'co_freevars') in Python. */
 PyAPI_FUNC(PyObject *) PyCode_GetFreevars(PyCodeObject *code);
 
-/* GraalPy specific to avoid direct field access. Used by (at least) pytorch */
-PyAPI_FUNC(PyObject*) PyCode_GetFileName(PyCodeObject* code);
-PyAPI_FUNC(PyObject*) PyCode_GetName(PyCodeObject* code);
+/* GraalPy public API to avoid direct field access. Used by (at least) pytorch patch */
+PyAPI_FUNC(PyObject*) GraalPyCode_GetFileName(PyCodeObject* code);
+PyAPI_FUNC(PyObject*) GraalPyCode_GetName(PyCodeObject* code);
 
 typedef enum _PyCodeLocationInfoKind {
     /* short forms are 0 to 9 */

graalpython/com.oracle.graal.python.cext/include/cpython/descrobject.h

@@ -1,4 +1,4 @@
-/* Copyright (c) 2023, Oracle and/or its affiliates.
+/* Copyright (c) 2023, 2025, Oracle and/or its affiliates.
  * Copyright (C) 1996-2023 Python Software Foundation
  *
  * Licensed under the PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2
@@ -37,8 +37,8 @@ typedef struct {
 
 #define PyDescr_COMMON PyDescrObject d_common
 
-#define PyDescr_TYPE(x) PyDescrObject_GetType((PyObject*)(x))
-#define PyDescr_NAME(x) PyDescrObject_GetName((PyObject*)(x))
+#define PyDescr_TYPE(x) GraalPyDescrObject_GetType((PyObject*)(x))
+#define PyDescr_NAME(x) GraalPyDescrObject_GetName((PyObject*)(x))
 
 typedef struct {
     PyDescr_COMMON;
@@ -67,3 +67,12 @@ PyAPI_DATA(PyTypeObject) _PyMethodWrapper_Type;
 PyAPI_FUNC(PyObject *) PyDescr_NewWrapper(PyTypeObject *,
                                                 struct wrapperbase *, void *);
 PyAPI_FUNC(int) PyDescr_IsData(PyObject *);
+
+// GraalPy public API to replace struct accessors
+PyAPI_FUNC(PyMethodDef*) GraalPyMethodDescrObject_GetMethod(PyObject*);
+PyAPI_FUNC(PyTypeObject*) GraalPyDescrObject_GetType(PyObject*);
+PyAPI_FUNC(PyObject*) GraalPyDescrObject_GetName(PyObject*);
+// Deprecated aliases kept for current versions of Cython
+// Remove in 27.0
+#define PyDescrObject_GetType GraalPyDescrObject_GetType
+#define PyMethodDescrObject_GetMethod GraalPyMethodDescrObject_GetMethod

graalpython/com.oracle.graal.python.cext/include/cpython/floatobject.h

@@ -12,27 +12,17 @@ typedef struct {
     double ob_fval;
 } PyFloatObject;
 
-// GraalPy addition
-typedef struct {
-    GraalPyObject ob_base;
-    double ob_fval;
-} GraalPyFloatObject;
-
 #define _PyFloat_CAST(op) \
     (assert(PyFloat_Check(op)), _Py_CAST(PyFloatObject*, op))
 
+// GraalPy public API
+PyAPI_FUNC(double) GraalPyFloat_AS_DOUBLE(PyObject* op);
+
 // Static inline version of PyFloat_AsDouble() trading safety for speed.
 // It doesn't check if op is a double object.
 static inline double PyFloat_AS_DOUBLE(PyObject *op) {
-#if 0 // GraalPy change
-    return _PyFloat_CAST(op)->ob_fval;
-#else // GraalPy change
-    if (points_to_py_handle_space(op)) {
-        return ((GraalPyFloatObject*) pointer_to_stub(op))->ob_fval;
-    } else {
-        return _PyFloat_CAST(op)->ob_fval;
-    }
-#endif // GraalPy change
+    // GraalPy change
+    return GraalPyFloat_AS_DOUBLE(op);
 }
 #define PyFloat_AS_DOUBLE(op) PyFloat_AS_DOUBLE(_PyObject_CAST(op))
 

graalpython/com.oracle.graal.python.cext/include/cpython/frameobject.h

@@ -1,4 +1,4 @@
-/* Copyright (c) 2022, 2023, Oracle and/or its affiliates.
+/* Copyright (c) 2022, 2025, Oracle and/or its affiliates.
  * Copyright (C) 1996-2022 Python Software Foundation
  *
  * Licensed under the PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2
@@ -33,4 +33,7 @@ PyAPI_FUNC(int) _PyFrame_IsEntryFrame(PyFrameObject *frame);
 PyAPI_FUNC(int) PyFrame_FastToLocalsWithError(PyFrameObject *f);
 PyAPI_FUNC(void) PyFrame_FastToLocals(PyFrameObject *);
 
-PyAPI_FUNC(void) _PyFrame_SetLineNumber(PyFrameObject *, int);
+// GraalPy public API to avoid struct access
+PyAPI_FUNC(void) GraalPyFrame_SetLineNumber(PyFrameObject *, int);
+// Deprecated alias used by current Cython, remove in 27.0
+#define _PyFrame_SetLineNumber GraalPyFrame_SetLineNumber

graalpython/com.oracle.graal.python.cext/include/cpython/listobject.h

@@ -1,4 +1,4 @@
-/* Copyright (c) 2022, 2024, Oracle and/or its affiliates.
+/* Copyright (c) 2022, 2025, Oracle and/or its affiliates.
  * Copyright (C) 1996-2022 Python Software Foundation
  *
  * Licensed under the PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2
@@ -43,12 +43,13 @@ static inline Py_ssize_t PyList_GET_SIZE(PyObject *op) {
 
 #define PyList_GET_ITEM(op, index) (PyList_GetItem((PyObject*)(op), (index)))
 
-// GraalPy-specific
-PyAPI_FUNC(PyObject **) PyTruffleList_GetItems(PyObject *op);
+// GraalPy public API to replace direct access to ob_item
+PyAPI_FUNC(PyObject **) GraalPyList_ITEMS(PyObject *op);
+PyAPI_FUNC(void) GraalPyList_SET_ITEM(PyObject* a, Py_ssize_t b, PyObject* c);
 
 static inline void
 PyList_SET_ITEM(PyObject *op, Py_ssize_t index, PyObject *value) {
-    PyTruffleList_GetItems(op)[index] = value;
+    GraalPyList_SET_ITEM(op, index, value);
 }
 #define PyList_SET_ITEM(op, index, value) \
     PyList_SET_ITEM(_PyObject_CAST(op), (index), _PyObject_CAST(value))

graalpython/com.oracle.graal.python.cext/include/cpython/methodobject.h

@@ -1,4 +1,4 @@
-/* Copyright (c) 2022, 2024, Oracle and/or its affiliates.
+/* Copyright (c) 2022, 2025, Oracle and/or its affiliates.
  * Copyright (C) 1996-2022 Python Software Foundation
  *
  * Licensed under the PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2
@@ -39,6 +39,14 @@ PyAPI_DATA(PyTypeObject) PyCMethod_Type;
 #define PyCMethod_CheckExact(op) Py_IS_TYPE((op), &PyCMethod_Type)
 #define PyCMethod_Check(op) PyObject_TypeCheck((op), &PyCMethod_Type)
 
+// GraalPy public API functions to replace struct access. Return borrowed references
+PyAPI_FUNC(PyTypeObject *) GraalPyCMethod_GetClass(PyObject *func);
+PyAPI_FUNC(const char*) GraalPyCFunction_GetDoc(PyObject *func);
+PyAPI_FUNC(void) GraalPyCFunction_SetDoc(PyObject *func, const char *doc);
+PyAPI_FUNC(PyObject*) GraalPyCFunction_GetModule(PyObject* a);
+PyAPI_FUNC(PyMethodDef*) GraalPyCFunction_GetMethodDef(PyObject* a);
+PyAPI_FUNC(void) GraalPyCFunction_SetModule(PyObject* a, PyObject* b);
+PyAPI_FUNC(void) GraalPyCFunction_SetMethodDef(PyObject* a, PyMethodDef *b);
 
 /* Static inline functions for direct access to these values.
    Type checks are *not* done, so use with care. */
@@ -58,15 +66,6 @@ static inline int PyCFunction_GET_FLAGS(PyObject *func) {
 #define PyCFunction_GET_FLAGS(func) PyCFunction_GET_FLAGS(_PyObject_CAST(func))
 
 static inline PyTypeObject* PyCFunction_GET_CLASS(PyObject *func_obj) {
-    return PyCMethod_GetClass(func_obj);
+    return GraalPyCMethod_GetClass(func_obj);
 }
 #define PyCFunction_GET_CLASS(func) PyCFunction_GET_CLASS(_PyObject_CAST(func))
-
-/*
- * XXX These functions are GraalPy-only. We need them to replace field access.
- * Currently inserted by our autopatch_capi.py
- */
-PyAPI_FUNC(PyObject*) _PyCFunction_GetModule(PyObject* a);
-PyAPI_FUNC(PyMethodDef*) _PyCFunction_GetMethodDef(PyObject* a);
-PyAPI_FUNC(void) _PyCFunction_SetModule(PyObject* a, PyObject* b);
-PyAPI_FUNC(void) _PyCFunction_SetMethodDef(PyObject* a, PyMethodDef *b);

graalpython/com.oracle.graal.python.cext/include/cpython/tupleobject.h

@@ -31,20 +31,19 @@ static inline Py_ssize_t PyTuple_GET_SIZE(PyObject *op) {
 }
 #define PyTuple_GET_SIZE(op) PyTuple_GET_SIZE(_PyObject_CAST(op))
 
-PyAPI_FUNC(PyObject *) _PyTuple_GET_ITEM(PyObject *, Py_ssize_t);
-#define PyTuple_GET_ITEM(op, index) _PyTuple_GET_ITEM(_PyObject_CAST(op), (index))
+#define PyTuple_GET_ITEM(op, index) GraalPyTuple_GET_ITEM(_PyObject_CAST(op), (index))
 
-// GraalPy-specific
-PyAPI_FUNC(PyObject **) PyTruffleTuple_GetItems(PyObject *op);
+// GraalPy public API to avoid direct access to ob_item
+PyAPI_FUNC(PyObject **) GraalPyTuple_ITEMS(PyObject *op);
+PyAPI_FUNC(PyObject *) GraalPyTuple_GET_ITEM(PyObject *, Py_ssize_t);
+PyAPI_FUNC(void) GraalPyTuple_SET_ITEM(PyObject*, Py_ssize_t, PyObject*);
 
-// GraalPy change: Export PyTuple_SET_ITEM as regular API function to use in PyO3 and others
-PyAPI_FUNC(void) PyTuple_SET_ITEM(PyObject*, Py_ssize_t, PyObject*);
-
-/* Inline function to be used in the PyTuple_SET_ITEM macro. */
-static inline void graalpy_tuple_set_item(PyObject *op, Py_ssize_t index, PyObject *value) {
-    PyTruffleTuple_GetItems(op)[index] = value;
+/* Function *only* to be used to fill in brand new tuples */
+static inline void
+PyTuple_SET_ITEM(PyObject *op, Py_ssize_t index, PyObject *value) {
+    GraalPyTuple_SET_ITEM(op, index, value);
 }
 #define PyTuple_SET_ITEM(op, index, value) \
-    graalpy_tuple_set_item(_PyObject_CAST(op), (index), _PyObject_CAST(value))
+    PyTuple_SET_ITEM(_PyObject_CAST(op), (index), _PyObject_CAST(value))
 
 PyAPI_FUNC(void) _PyTuple_DebugMallocStats(FILE *out);