Refactor reference counting to use _Py_REFCNT and Py_SET_REFCNT

[cxzhong]

This change replaces direct access to ob_refcnt with proper API functions:

• Use _Py_REFCNT() for reading reference counts
• Use Py_SET_REFCNT() for setting reference counts

This ensures compatibility with Python's free-threaded mode and follows Python's recommended practices for reference count manipulation.

📝 Checklist

• The title is concise and informative.
• The description explains in detail what this PR is about.
• I have linked a relevant issue or discussion.
• I have created tests covering the changes.
• I have updated the documentation and checked the documentation preview.

⌛ Dependencies

[github-actions]

Documentation preview for this PR (built with commit cedb4c9; changes) is ready! 🎉
This preview will update shortly after each push to this PR.

[dimpase]

I am not too sure about _Py* - these are not for the public use, or at least they cannot be considered a stable API, no? @tobiasdiez ?

[cxzhong]

I am not too sure about _Py* - these are not for the public use, or at least they cannot be considered a stable API, no? @tobiasdiez ?

from cpython.ref import _Py_REFCNT, it is from cython file, nor direcly from cpython.
https://github.com/cython/cython/blob/master/Cython/Includes/cpython/ref.pxd
It just like cdef extern from 'Python.h'
And we use it in cysignals and cypari2 several times.
So it is Open API in cpython

[tobiasdiez]

I think it's public API, at least it's mentioned in the docs: https://cython.readthedocs.io/en/latest/src/userguide/language_basics.html#python-objects-as-parameters-and-return-values

It looks to me that the new Py_SET_REFCNT can be replaced by Py_INCREF/Py_DECREF, which are also available from cython.ref, and is a bit nicer.

[cxzhong]

I think it's public API, at least it's mentioned in the docs: https://cython.readthedocs.io/en/latest/src/userguide/language_basics.html#python-objects-as-parameters-and-return-values

It looks to me that the new Py_SET_REFCNT can be replaced by Py_INCREF/Py_DECREF, which are also available from cython.ref, and is a bit nicer.

But it does not like the original meaning. I think that The original meaning is to set the ref number is 1

[tobiasdiez]

I think it's public API, at least it's mentioned in the docs: https://cython.readthedocs.io/en/latest/src/userguide/language_basics.html#python-objects-as-parameters-and-return-values
It looks to me that the new Py_SET_REFCNT can be replaced by Py_INCREF/Py_DECREF, which are also available from cython.ref, and is a bit nicer.

But it does not like the original meaning. I think that The original meaning is to set the ref number is 1

It increases it from 0 to 1, or not?

[cxzhong]

I think it's public API, at least it's mentioned in the docs: https://cython.readthedocs.io/en/latest/src/userguide/language_basics.html#python-objects-as-parameters-and-return-values
It looks to me that the new Py_SET_REFCNT can be replaced by Py_INCREF/Py_DECREF, which are also available from cython.ref, and is a bit nicer.

But it does not like the original meaning. I think that The original meaning is to set the ref number is 1

It increases it from 0 to 1, or not?

The annotation said

  # The global_dummy_Integer may have a reference count larger than
  # one, but it is expected that newly created objects have a
  # reference count of one. This is potentially unneeded if
  # everybody plays nice, because the global_dummy_Integer has only
  # one reference in that case.

So the ref count may be larger than 1

[tobiasdiez]

oh, misread this part. Sorry. But in ginac it is really just increasing & decreasing, right?

[cxzhong]

oh, misread this part. Sorry. But in ginac it is really just increasing & decreasing, right?

It seems it redefine the Py_INCREF and Py_DECREF. I do not know why it needs to do that. I just preserve the original code's meaning.

[cxzhong]

oh, misread this part. Sorry. But in ginac it is really just increasing & decreasing, right?

And before that, it undefine the two functions

#undef Py_INCREF
#undef Py_DECREF

[cxzhong]

@dimpase help me review this. Thank you. It affect the compatibility of python 3.14 free-threading build

[cxzhong]

@tobiasdiez Can you help me review this again. it undefine Py_INCREF and Py_DECREF so we can not use the two functions. I think its method to redefine these two functions with error throwing？

[cxzhong]

@tobiasdiez Thank you for reviewing

[tobiasdiez]

This now broke all the uv-based workflows:

 DEBUG cython -M --fast-fail -3 -I /__w/sage/sage/src -I /__w/sage/sage/build/cp313/src '-X auto_pickle=False' '-X autotestdict=False' '-X binding=True' '-X c_api_binop_methods=True' '-X cdivision=True' '-X cpow=True' '-X embedsignature=True' --embed-positions '-X fast_getattr=True' '-X legacy_implicit_noexcept=True' '-X preliminary_late_includes_cy28=True' /__w/sage/sage/src/sage/libs/pari/convert_sage_matrix.pyx -o src/sage/libs/pari/convert_sage_matrix.cpython-313-x86_64-linux-gnu.so.p/src/sage/libs/pari/convert_sage_matrix.pyx.c
DEBUG 
DEBUG Error compiling Cython file:
DEBUG ------------------------------------------------------------
DEBUG ...
DEBUG from cpython.object cimport PyObject
DEBUG from cpython.ref cimport _Py_REFCNT
DEBUG ^
DEBUG ------------------------------------------------------------
DEBUG 
DEBUG /__w/sage/sage/src/sage/matrix/args.pxd:2:0: 'cpython/ref/_Py_REFCNT.pxd' not found

https://github.com/sagemath/sage/actions/runs/19874021091/job/56956791524#step:8:2159

could you please have a look @cxzhong

[cxzhong]

This now broke all the uv-based workflows:

 DEBUG cython -M --fast-fail -3 -I /__w/sage/sage/src -I /__w/sage/sage/build/cp313/src '-X auto_pickle=False' '-X autotestdict=False' '-X binding=True' '-X c_api_binop_methods=True' '-X cdivision=True' '-X cpow=True' '-X embedsignature=True' --embed-positions '-X fast_getattr=True' '-X legacy_implicit_noexcept=True' '-X preliminary_late_includes_cy28=True' /__w/sage/sage/src/sage/libs/pari/convert_sage_matrix.pyx -o src/sage/libs/pari/convert_sage_matrix.cpython-313-x86_64-linux-gnu.so.p/src/sage/libs/pari/convert_sage_matrix.pyx.c
DEBUG 
DEBUG Error compiling Cython file:
DEBUG ------------------------------------------------------------
DEBUG ...
DEBUG from cpython.object cimport PyObject
DEBUG from cpython.ref cimport _Py_REFCNT
DEBUG ^
DEBUG ------------------------------------------------------------
DEBUG 
DEBUG /__w/sage/sage/src/sage/matrix/args.pxd:2:0: 'cpython/ref/_Py_REFCNT.pxd' not found

https://github.com/sagemath/sage/actions/runs/19874021091/job/56956791524#step:8:2159

could you please have a look @cxzhong

OK. I notice that. Look that cython/cython@b684235
We need to use cython>3.1. Then cython has this function.

[cxzhong]

This now broke all the uv-based workflows:

 DEBUG cython -M --fast-fail -3 -I /__w/sage/sage/src -I /__w/sage/sage/build/cp313/src '-X auto_pickle=False' '-X autotestdict=False' '-X binding=True' '-X c_api_binop_methods=True' '-X cdivision=True' '-X cpow=True' '-X embedsignature=True' --embed-positions '-X fast_getattr=True' '-X legacy_implicit_noexcept=True' '-X preliminary_late_includes_cy28=True' /__w/sage/sage/src/sage/libs/pari/convert_sage_matrix.pyx -o src/sage/libs/pari/convert_sage_matrix.cpython-313-x86_64-linux-gnu.so.p/src/sage/libs/pari/convert_sage_matrix.pyx.c
DEBUG 
DEBUG Error compiling Cython file:
DEBUG ------------------------------------------------------------
DEBUG ...
DEBUG from cpython.object cimport PyObject
DEBUG from cpython.ref cimport _Py_REFCNT
DEBUG ^
DEBUG ------------------------------------------------------------
DEBUG 
DEBUG /__w/sage/sage/src/sage/matrix/args.pxd:2:0: 'cpython/ref/_Py_REFCNT.pxd' not found

https://github.com/sagemath/sage/actions/runs/19874021091/job/56956791524#step:8:2159

could you please have a look @cxzhong

Can you help me upgrade the uv lock file?