================
Cython Changelog
================

3.2.5 (2026-05-23)
==================

Bugs fixed
----------

* A compile failure was fixed when using the walrus operator inside of try-except.
  (Github issue :issue:`7462`)

* Expressions with side-effects as object argument to ``isinstance()`` could get
  evaluated multiple times, e.g. when they use the walrus operator.
  (Github issue :issue:`7670`)

* Several problems generating the shared utility module were resolved, including
  a performance regression with memory views.
  (Github issues :issue:`7487`, :issue:`7497`, :issue:`7504`, :issue:`7558`)

* Some GC and refcounting issues were resolved for Cython functions in the Limited API.
  (Github issue :issue:`7594`)

* Refcounting errors and error handling issues were resolved in some rare error handling cases.
  (Github issues :issue:`7597`, :issue:`7599`, :issue:`7612`, :issue:`7673`)

* Using ``cython.pymutex`` in an extension type with ``cdef`` methods generated
  invalid C code missing the required ``PyMutex`` declarations.
  (Github issue :issue:`6995`)

* Calling ``.get_frame()`` on Cython coroutines could crash in freethreading Python.
  (Github issue :issue:`7632`)

* The vectorcall protocol was not used correctly in ``.throw()`` of Cython coroutines
  when raising the exception only by type (without value or traceback).
  (Github issue :issue:`7677`)

* A problem with cpdef enums in the Limited API of Python 3.11+ was resolved.
  (Github issue :issue:`7503`)

* Unicode predicates like ``.isdigit()`` are now allowed to fail in the Limited API.
  (Github issue :issue:`7602`)

* Conditional expressions mixing Python float and int object types could accidentally
  infer float as the common result type, instead of treating both independently.

* Using ``sizeof()`` in the size declarations of ``extern`` arrays failed.
  (Github issue :issue:`7451`)

* Enabling profiling generated invalid C code for non-Python return tuples.
  (Github issue :issue:`7580`)

* ``abs()`` on C ``long long`` values could generate invalid C code.

* When the ``CYTHON_AVOID_BORROWED_REFS`` C macro is enabled, e.g. in GraalPython,
  dict iteration could fail to compile.
  Patch by Michael Šimáček.  (Github issue :issue:`7631`)

* A C compiler warning about unused functions was resolved.
  (Github issue :issue:`7560`)

* The ``py_safe_call_once()`` C++ mutex helper function in ``libcpp.mutex``
  failed to compile.
  (Github issue :issue:`7585`)

* The ``cpython.array`` declarations were adapted for Python 3.15.  Direct access
  to the C struct of the ``array.array`` data type might require user code changes.
  (Github issue :issue:`7659`)

* Spaces in file paths written to the ``depfile`` were not escaped.
  Patch by Loïc Estève.  (Github issue :issue:`7423`)

* Cython's cache failed to restore multi-file results.
  (Github issue :issue:`7559`)

* Using Tempita from its command line failed with a name error.
  (Github issue :issue:`7567`)

Other changes
-------------

* The known builtin types were updated for Py3.15.


3.2.4 (2026-01-04)
==================

Features added
--------------

* In preparation of Cython 3.3, a new decorator ``@collection_type(tname)`` can be used
  to advertise an extension type as being a ``'sequence'`` or ``'mapping'``.  This currently
  only has the effect of setting the ``Py_TPFLAGS_SEQUENCE`` flag on the type or not, but
  is provided for convenience to allow using the new decorator already in Cython 3.2 code.

* Several C++ exception declarations were added to ``libcpp.exceptions``.
  (Github issue :issue:`7389`)

Bugs fixed
----------

* Pseudo-literal default values of function arguments like ``arg=str()`` could generate
  invalid C code when internally converted into a real literal.
  (Github issue :issue:`6192`)

* The pickle serialisation of extension types using the ``auto_pickle`` feature was
  larger than necessary since 3.2.0 for types without Python object attributes.
  It is now back to the state before 3.2.0 again.
  (Github issue :issue:`7443`)

* Constants are now only made immortal on freethreading Python if they are not shared.
  (Github issue :issue:`7439`)

* ``PyDict_SetDefaultRef()`` is now used when available to avoid temporary borrowed references.
  (Github issue :issue:`7347`)

* Includes all fixes as of Cython 3.1.8.


3.2.3 (2025-12-14)
==================

Features added
--------------

* The C-API declarations were updated to include the new ``PyList_*()`` functions.
  (Github issue :issue:`7291`)

* The ``Py_mod_gil`` module setting can now be changed with a C macro, overriding
  the ``freethreading_compatible`` directive setting.
  (Github issue :issue:`7404`)

Bugs fixed
----------

* t-strings lost the last element when compiled for the Limited API.
  (Github issue :issue:`7381`)

* The ``array.data`` property of the ``cpython.array`` declarations generated a
  useless exception check that degraded its use in ``nogil`` code.
  (Github issue :issue:`7408`)

* Parallel builds with the ``cythonize`` command could request more processes
  than allowed by the platform, thus failing the build.
  (Github issue :issue:`7384`)

* A minor thread sanitizer issue was resolved.
  (Github issue :issue:`7383`)


3.2.2 (2025-11-30)
==================

Features added
--------------

* The C-API declarations were updated to include the new ``PyDict_*Ref()`` functions.
  (Github issue :issue:`7291`)

Bugs fixed
----------

* Iteration over literal sequences and strings in generators generated invalid C code since 3.2.0.
  This was a regression due to the C array iteration optimisation in :issue:`6926`, which is now
  disabled inside of generators.
  (Github issue :issue:`7342`)

* Calling special methods of known exception types failed with an ``AttributeError``.
  (Github issue :issue:`7342`)

* Calling the unbound ``__mul__`` special method of builtin collections with subtypes failed.
  (Github issue :issue:`7340`)

* C string literals could generate invalid "const to non-const" casts in the C code.
  (Github issue :issue:`7346`)

* ``yield`` is no longer allowed inside of a ``cython.critical_section``,
  but *is* now allowed while holding a ``cython.pymutex``.
  (Github issue :issue:`7317`)

* Under lock congestion, acquiring the GIL could crash in Python 3.11, part 2.
  This bug was introduced in Cython 3.2.0.
  (Github issue :issue:`7312`)

* The new ``py_safe_*`` functions in ``libc.threads`` triggered C compiler warnings.
  (Github issue :issue:`7356`)


3.2.1 (2025-11-12)
==================

Features added
--------------

* Cython now leaves markers about its utility code dependencies in the generated C code
  to help debugging "unused function" C compiler warnings.
  (Github issue :issue:`7294`)

Bugs fixed
----------

* Relative imports could fail if the shared utility module is used.
  This bug was introduced in Cython 3.2.0.
  (Github issue :issue:`7290`)

* Under lock congestion, acquiring the GIL could crash in Python 3.11.
  This bug was introduced in Cython 3.2.0.
  (Github issue :issue:`7312`)

* Using the shared utility module left an unused C function in user modules with memoryviews.
  To make debugging this kind of issue easier, Cython now leaves "used by …" markers in the
  generated C files that indicate why a specific piece of utility code was included.
  This bug was introduced in Cython 3.2.0.
  (Github issue :issue:`7293`)

* Code using the pre-import scope failed with an undefined name.
  This bug was introduced in Cython 3.2.0.
  (Github issue :issue:`7304`)

* Includes all fixes as of Cython 3.1.7.


3.2.0 (2025-11-05)
==================

(Complete changelog for the 3.2.0 release, including pre-releases.)

Features added
--------------

* Builtin exception types are now inferred.
  (Github issue :issue:`6908`)

* The list of known, inferred and optimised Python builtins was updated.
  `range` is now considered a type. `ascii`, `bin`, `format`, `hex`, `oct` were added as functions.
  (Github issue :issue:`6931`)

* The f-string syntax was extended according to PEP-701.
  (Github issue :issue:`5452`)

* t-strings are implemented according to PEP-750.  The implementation backports the template classes
  but prefers existing backports if installed separately.
  (Github issue :issue:`6811`)

* Unknown return type annotations with `->` are no longer rejected but produce warnings.
  This allows better integration with Python type hints that are not always usable for Cython.
  ``-> None``  is also allowed now.
  Patch by jpe.  (Github issue :issue:`6946`)

* The runtime Python dispatch for fused functions is substantially faster.
  (Github issues :issue:`1385`, :issue:`6996`)

* Freelists (via cdef class decorator and for internally used types such as ``async``)
  are now also used in the Limited API and with extension type specs enabled.
  (Github issue :issue:`7151`)

* Module imports now quickly check for an already imported module to speed up reimports.
  Patch by Lysandros Nikolaou.  (Github issue :issue:`7035`)

* Type checks on PEP-604 union types (`int | None`) are optimised into separate checks.
  (Github issue :issue:`6935`)

* Assignments to the PEP-604 union type `float | None` allow any suitable Python number as input
  and convert it to a Python `float` automatically.
  (Github issue :issue:`5750`)

* Item type inference was improved for looping over literals.
  (Github issue :issue:`6912`)

* Looping over literal sequences and strings now uses efficient C array looping if possible.
  (Github issue :issue:`6926`)

* Releasing the GIL from an unknown lock state is more efficient.
  (Github issue :issue:`6847`)

* ``cython.critical_section(PyMutex)`` now works, as with Python objects.
  (Github issue :issue:`6847`)

* ``bool(c_int/float/ptr)`` avoid passing through Python objects.
  (Github issue :issue:`7015`)

* Variables assigned inside of ``prange`` loops can now be initialised outside of the loop.
  (Github issue :issue:`7178`)

* Unused exceptions in ``except`` clauses are detected in some more cases to avoid their normalisation.
  (Github issue :issue:`7021`)

* Mixed operations on C integers with Python ints use less code and are more streamlined for Py3.12+.
  (Github issue :issue:`7244`)

* Some object constants are now marked as ``immortal`` to speed up their reference counting
  in recent CPython versions.  This can be configured with the ``CYTHON_IMMORTAL_CONSTANTS`` C macro.
  (Github issue :issue:`7118`)

* Further improvements were made to reduce the size of the resulting extension modules.
  (Github issue :issue:`6983`, :issue:`7199`, :issue:`7220`, :issue:`7238`,
  :issue:`7255`, :issue:`7265`)

* Several improvements were made in freethreaded Python code.
  (Github issues :issue:`6936`, :issue:`6939`, :issue:`6949`, :issue:`6984`,
  :issue:`7011`, :issue:`7066`, :issue:`7114`, :issue:`7200`)

* Several improvements were made for the Limited API.
  (Github issues :issue:`6959`, :issue:`6991`)

* Several improvements were made for the GraalPython support.
  Patch by Michael Šimáček.  (Github issue :issue:`7074`)

* Some GIL-safe C-API wrappers were added to the libc/libcpp declarations.
  (Github issue :issue:`6829`, :issue:`6993`)

* String and number constants use less storage space in the module.
  (Github issues :issue:`6971`, :issue:`6978`, :issue:`6986`)

* The managed dict/weakref support in CPython 3.12+ is used for internal types
  to benefit from future CPython optimisations here.
  (Github issue :issue:`6891`)

* Using ``NaN`` as exception return value is supported.
  (Github issues :issue:`6900`, :issue:`6903`)

* Declarations for C++ condition variables were added.
  (Github issue :issue:`6836`)

* The annotated source HTML page shows alternating +/− markers to open/close lines.
  Patch by Kamil Monicz.  (Github issue :issue:`7099`)

* ``cython --embed`` gained a new option ``--embed-modules=…`` to list further extension modules
  that will be statically linked into the generated extension module, to get them initialised
  on application start.
  (Github issue :issue:`2849`)

* The ``setup.py`` script of Cython now allows passing the desired Limited API version
  like ``--cython-limited-api=3.11``.
  (Github issue :issue:`7228`)

* Unicode 16.0.0 is used to parse identifiers.
  (Github issue :issue:`6836`)

Bugs fixed
----------

* Special float exception values could generate invalid C code.
  (Github issues :issue:`6900`, :issue:`6903`)

* References to the Python ``bool`` type could generate invalid C code.
  (Github issue :issue:`6902`)

* Using ``cython.pymutex`` in an extension type declared as ``public`` or ``api``
  generated invalid C code missing the required ``PyMutex`` declarations.
  (Github issues :issue:`6992`, :issue:`6995`)

* Cython's type sharing across modules suffered from race conditions if multiple modules
  tried to initialise and share their types concurrently.  This is due to an underlying
  CPython issue and cannot easily be worked around completely.  In the common case that
  module dicts are plain Python dict objects, however, Cython now uses a ``.setdefault()``
  equivalent for thread-safe type sharing.
  See https://github.com/python/cpython/issues/137422
  (Github issue :issue:`7076`)

* Cython incorrectly called ``PyList_GetItemRef()`` in PyPy and GraalPython before Py3.13.
  (Github issue :issue:`7269`)

* Iterating over temporary memoryviews could crash Cython.
  (Github issue :issue:`7005`)

* Type casts on constants as part of numeric expressions could crash Cython.
  (Github issue :issue:`6779`)

* Long code bodies in ``with`` statements could crash Cython.
  (Github issue :issue:`7122`)

* Vectorcalls could use needless temp assignments for ``self``.
  (Github issue :issue:`6909`)

* Indexing ``bytes`` failed to optimise in some cases.
  (Github issue :issue:`6997`)

* Optimised C integer formatting in f-strings failed to apply to typedef types.
  (Github issue :issue:`7170`)

* In auto-pickling, trying to unpickle an object that has no ``__dict__`` from object pickle data
  that includes instance dict state is now an error.
  (Github issue :issue:`7222`)

* The type objects of heap types were not always correctly decrefed on deallocation.
  (Github issue :issue:`7145`)

* Pure mode type aliases like ``p_int`` or ``ulong`` leaked into some C type contexts,
  risking to conflict with user declarations.
  (Github issues :issue:`6922`, :issue:`6339`)

* Boolean (emptyness) tests on builtin containers could fail to handle (unlikely) errors.
  (Github issue :issue:`7090`)

* The return type of ``bytes.join()`` was sometimes inferred as plain ``object``.
  (Github issue :issue:`6987`)

* Type inference could fail to understand ``prange()`` arguments.
  (Github issue :issue:`6974`)

* ``embedsignatures`` failed if ``lambda`` was used in function default arguments.
  (Github issue :issue:`6880`)

* An internal C function was not marked as ``static`` and leaked a linker symbol.
  (Github issue :issue:`6957`)

* ``PyType_FromModuleAndSpec`` was incorrectly used in Limited API code before Py3.10.
  (Github issue :issue:`7181`)

* Conversion code for memoryview dtypes from and to Python objects generated C warnings about
  incorrect ``const`` / non-``const``  casting code.
  (Github issue :issue:`7219`)

* Cython's tools and frontend scripts now use ``python3``  instead of just ``python``
  in their shebang line.
  Patch by Matti Picus.  (Github issue :issue:`7053`)

* Extension arguments defined for the shared code module were ignored in ``cythonize()``.
  (Github issue :issue:`7251`)

* Failures while following package attributes in ``import pkg.module as …`` were not handled.

* Trying to instantiate internal types used by Cython is now prohibited.
  (Github issue :issue:`7263`)

* The ``setup.py`` script in the ``Demos/`` subdirectory failed to build.
  (Github issue :issue:`7228`)

* The ``cygdb`` program failed to work with virtualenvs on Windows.
  Patch by Merlin.  (Github issue :issue:`7268`)

* Includes all fixes as of Cython 3.1.6.

Other changes
-------------

* Some lesser used platforms (Windows ARM/i686, macOS x86_64, Linux i686, musllinux)
  now use Py3.9 abi3 binary wheels instead of Python version specific wheels.
  We also added an abi3 wheel for armv7l.
  (Github issues :issue:`7227`, :issue:`7248`, :issue:`7250`)

* Usages of `Py_TPFLAGS_HAVE_FINALIZE` were removed.  The constant remains available as cimport from
  ``cpython.object`` for legacy reasons.
  (Github issue :issue:`6423`)


3.2.0b3 (2025-10-30)
====================

Bugs fixed
----------

* Using ``cython.pymutex`` in an extension type declared as ``public`` or ``api``
  generated invalid C code missing the required ``PyMutex`` declarations.
  (Github issues :issue:`6992`, :issue:`6995`)

* 3.2.0b2 generated incorrect pointer casts in the ``cimport`` importing code.
  (Github issue :issue:`7268`)

* Cython's type sharing across modules suffered from race conditions if multiple modules
  tried to initialise and share their types concurrently.  This is due to an underlying
  CPython issue and cannot easily be worked around completely.  In the common case that
  module dicts are plain Python dict objects, however, Cython now uses a ``.setdefault()``
  equivalent for thread-safe type sharing.
  See https://github.com/python/cpython/issues/137422
  (Github issue :issue:`7076`)

* Cython incorrectly called ``PyList_GetItemRef()`` in PyPy and GraalPython before Py3.13.
  (Github issue :issue:`7269`)


3.2.0b2 (2025-10-27)
====================

Features added
--------------

* The code generated for importing and exporting cimports across modules uses less space.
  (Github issues :issue:`7255`, :issue:`7265`)

Bugs fixed
----------

* Iteration over memoryviews could loop indefinitely in 3.2b1 when encountering a ``continue`` statement.
  (Github issue :issue:`7259`)

* Extension arguments defined for the shared code module were ignored in ``cythonize()``.
  (Github issue :issue:`7251`)

* Failures while following package attributes in ``import pkg.module as …`` were not handled.

* Trying to instantiate internal types used by Cython is now prohibited.
  (Github issue :issue:`7263`)

* Includes all fixes as of Cython 3.1.6.

Other changes
-------------

* The ``musllinux`` platform is now served with an abi3 Cython wheel instead of Python specific ones.
  (Github issue :issue:`7250`)


3.2.0b1 (2025-10-22)
====================

Features added
--------------

* Builtin exception types are now inferred.
  (Github issue :issue:`6908`)

* The list of known, inferred and optimised Python builtins was updated.
  `range` is now considered a type. `ascii`, `bin`, `format`, `hex`, `oct` were added as functions.
  (Github issue :issue:`6931`)

* The f-string syntax was extended according to PEP-701.
  (Github issue :issue:`5452`)

* t-strings are implemented according to PEP-750.  The implementation backports the template classes
  but prefers existing backports if installed separately.
  (Github issue :issue:`6811`)

* Unknown return type annotations with `->` are no longer rejected but produce warnings.
  This allows better integration with Python type hints that are not always usable for Cython.
  ``-> None``  is also allowed now.
  Patch by jpe.  (Github issue :issue:`6946`)

* The runtime Python dispatch for fused functions is substantially faster.
  (Github issues :issue:`1385`, :issue:`6996`)

* Freelists (via cdef class decorator and for internally used types such as ``async``)
  are now also used in the Limited API and with extension type specs enabled.
  (Github issue :issue:`7151`)

* Module imports now quickly check for an already imported module to speed up reimports.
  Patch by Lysandros Nikolaou.  (Github issue :issue:`7035`)

* Type checks on PEP-604 union types (`int | None`) are optimised into separate checks.
  (Github issue :issue:`6935`)

* Assignments to the PEP-604 union type `float | None` allow any suitable Python number as input
  and convert it to a Python `float` automatically.
  (Github issue :issue:`5750`)

* Item type inference was improved for looping over literals.
  (Github issue :issue:`6912`)

* Looping over literal sequences and strings now uses efficient C array looping if possible.
  (Github issue :issue:`6926`)

* Releasing the GIL from an unknown lock state is more efficient.
  (Github issue :issue:`6847`)

* ``cython.critical_section(PyMutex)`` now works, as with Python objects.
  (Github issue :issue:`6847`)

* ``bool(c_int/float/ptr)`` avoid passing through Python objects.
  (Github issue :issue:`7015`)

* Variables assigned inside of ``prange`` loops can now be initialised outside of the loop.
  (Github issue :issue:`7178`)

* Unused exceptions in ``except`` clauses are detected in some more cases to avoid their normalisation.
  (Github issue :issue:`7021`)

* Mixed operations on C integers with Python ints use less code and are more streamlined for Py3.12+.
  (Github issue :issue:`7244`)

* Some object constants are now marked as ``immortal`` to speed up their reference counting
  in recent CPython versions.  This can be configured with the ``CYTHON_IMMORTAL_CONSTANTS`` C macro.
  (Github issue :issue:`7118`)

* Further improvements were made to reduce the size of the resulting extension modules.
  (Github issue :issue:`6983`, :issue:`7199`, :issue:`7220`, :issue:`7238`)

* Several improvements were made in freethreaded Python code.
  (Github issues :issue:`6936`, :issue:`6939`, :issue:`6949`, :issue:`6984`,
  :issue:`7011`, :issue:`7066`, :issue:`7114`, :issue:`7200`)

* Several improvements were made for the Limited API.
  (Github issues :issue:`6959`, :issue:`6991`)

* Several improvements were made for the GraalPython support.
  Patch by Michael Šimáček.  (Github issue :issue:`7074`)

* Some GIL-safe C-API wrappers were added to the libc/libcpp declarations.
  (Github issue :issue:`6829`, :issue:`6993`)

* String and number constants use less storage space in the module.
  (Github issues :issue:`6971`, :issue:`6978`, :issue:`6986`)

* The managed dict/weakref support in CPython 3.12+ is used for internal types
  to benefit from future CPython optimisations here.
  (Github issue :issue:`6891`)

* Using ``NaN`` as exception return value is supported.
  (Github issues :issue:`6900`, :issue:`6903`)

* Declarations for C++ condition variables were added.
  (Github issue :issue:`6836`)

* The annotated source HTML page shows alternating +/− markers to open/close lines.
  Patch by Kamil Monicz.  (Github issue :issue:`7099`)

* ``cython --embed`` gained a new option ``--embed-modules=…`` to list further extension modules
  that will be statically linked into the generated extension module, to get them initialised
  on application start.
  (Github issue :issue:`2849`)

* The ``setup.py`` script of Cython now allows passing the desired Limited API version
  like ``--cython-limited-api=3.11``.
  (Github issue :issue:`7228`)

* Unicode 16.0.0 is used to parse identifiers.
  (Github issue :issue:`6836`)

Bugs fixed
----------

* Special float exception values could generate invalid C code.
  (Github issues :issue:`6900`, :issue:`6903`)

* References to the Python ``bool`` type could generate invalid C code.
  (Github issue :issue:`6902`)

* Unicode characters formatted from C integers with ``f"{value:c}"`` could result in
  invalid Python string objects since Cython 3.1.0.
  (Github issue :issue:`7240`)

* Vectorcalls could use needless temp assignments for ``self``.
  (Github issue :issue:`6909`)

* Iterating over temporary memoryviews could crash Cython.
  (Github issue :issue:`7005`)

* Type casts on constants as part of numeric expressions could crash Cython.
  (Github issue :issue:`6779`)

* Long code bodies in ``with`` statements could crash Cython.
  (Github issue :issue:`7122`)

* Indexing ``bytes`` failed to optimise in some cases.
  (Github issue :issue:`6997`)

* Optimised C integer formatting in f-strings failed to apply to typedef types.
  (Github issue :issue:`7170`)

* In auto-pickling, trying to unpickle an object that has no ``__dict__`` from object pickle data
  that includes instance dict state is now an error.
  (Github issue :issue:`7222`)

* The type objects of heap types were not always correctly decrefed on deallocation.
  (Github issue :issue:`7145`)

* Pure mode type aliases like ``p_int`` or ``ulong`` leaked into some C type contexts,
  risking to conflict with user declarations.
  (Github issues :issue:`6922`, :issue:`6339`)

* Boolean (emptyness) tests on builtin containers could fail to handle (unlikely) errors.
  (Github issue :issue:`7090`)

* The return type of ``bytes.join()`` was sometimes inferred as plain ``object``.
  (Github issue :issue:`6987`)

* Type inference could fail to understand ``prange()`` arguments.
  (Github issue :issue:`6974`)

* ``embedsignatures`` failed if ``lambda`` was used in function default arguments.
  (Github issue :issue:`6880`)

* An internal C function was not marked as ``static`` and leaked a linker symbol.
  (Github issue :issue:`6957`)

* ``PyType_FromModuleAndSpec`` was incorrectly used in Limited API code before Py3.10.
  (Github issue :issue:`7181`)

* Conversion code for memoryview dtypes from and to Python objects generated C warnings about
  incorrect ``const`` / non-``const``  casting code.
  (Github issue :issue:`7219`)

* ``cythonize`` (program and function) now uses ``concurrent.futures.ProcessPoolExecutor``
  instead of ``multiprocessing.Pool`` to fix a hang on build failures in parallel builds.
  A possible work-around is to disable parallel builds.
  Patch by Sviatoslav Sydorenko.  (Github issue :issue:`7183`)

* Cython's tools and frontend scripts now use ``python3``  instead of just ``python``
  in their shebang line.
  Patch by Matti Picus.  (Github issue :issue:`7053`)

* The ``setup.py`` script in the ``Demos/`` subdirectory failed to build.
  (Github issue :issue:`7228`)

* Includes all fixes as of Cython 3.1.5.

Other changes
-------------

* Some lesser used platforms (Windows ARM/i686, macOS x86_64, Linux i686) now use Py3.9 abi3 binary wheels
  instead of Python version specific wheels.  We also added a abi3 wheel for armv7l.
  (Github issues :issue:`7227`, :issue:`7248`)

* Usages of `Py_TPFLAGS_HAVE_FINALIZE` were removed.  The constant remains available as cimport from
  ``cpython.object`` for legacy reasons.
  (Github issue :issue:`6423`)


3.1.8 (2026-01-03)
==================

Bugs fixed
----------

* Assignment expressions used in comprehensions could look at the wrong scope,
  thus using different variables and different data.
  (Github issue :issue:`6547`)

* Some internal C symbols were not declared as ``static``, preventing static linking
  of multiple modules.
  Patch by Yury Popov.  (Github issue :issue:`7310`)

* Accidentally using ``except +`` in C mode did not raise a compile error but generated
  invalid C code leading to obscure error messages.
  Patch by user202729.  (Github issue :issue:`6560`)


3.1.7 (2025-11-12)
==================

Bugs fixed
----------

* Unicode characters formatted from C integers with padding, as in ``f"{value:XXc}"``,
  could result in invalid Python string objects since Cython 3.1.0.
  Also, lone surrogates failed to format in this way.
  (Github issue :issue:`7298`)

* Assigning nested structs from a list of structs (item by item) could crash Cython.
  (Github issue :issue:`7308`)

* Cython incorrectly called ``PyList_GetItemRef()`` in PyPy and GraalPython before Py3.13.
  (Github issue :issue:`7269`)

* Trying to instantiate internal types used by Cython is now prohibited.
  (Github issue :issue:`7263`)


3.1.6 (2025-10-23)
==================

Bugs fixed
----------

* Unicode characters formatted from C integers with ``f"{value:c}"`` could result in
  invalid Python string objects since Cython 3.1.0.
  (Github issue :issue:`7240`)

* ``cythonize`` (program and function) now uses ``concurrent.futures.ProcessPoolExecutor``
  instead of ``multiprocessing.Pool`` to fix a hang on build failures in parallel builds.
  A possible work-around is to disable parallel builds.
  Patch by Sviatoslav Sydorenko.  (Github issue :issue:`7183`)


3.1.5 (2025-10-20)
==================

Bugs fixed
----------

* Conversion from C++ strings longer than ``PY_SSIZE_T_MAX`` did not validate the length.

* Some non-Limited API code was incorrectly used in generated header files.
  (Github issue :issue:`7157`)

* Optimised unpacking of Python integers in expressions uses a slightly safer scheme.
  (Github issue :issue:`7134`)

* Empty return statements were not always reported when tracing.
  (Github issue :issue:`7022`)

* Value conversion errors when tracing C return statements no longer fail the trace
  but fall back to reporting ``None`` returns instead.
  (Github issue :issue:`6503`)


3.1.4 (2025-09-16)
==================

Features added
--------------

* Declarations for the new ``PyUnstable_*()`` refcounting C-API functions in Py3.14 were added.
  (Github issue :issue:`6836`)

Bugs fixed
----------

* The monitoring code could crash on tracing.
  (Github issue :issue:`7050`)

* Initialising the monitoring code could fail with a CPython exception.
  See https://github.com/nedbat/coveragepy/issues/1790#issuecomment-3257410149

* Optimised integer shifting triggered undefined behaviour in C.
  (Github issue :issue:`7089`)

* Deallocating objects that inherit from external types defined in pxd files
  could run into an infinite loop.
  (Github issue :issue:`7143`)

* A reference to metaclasses could be leaked on instantiation.
  (Github issue :issue:`7130`)

* (Unlikely) error handling during empty builtin container tests was ineffective.
  (Github issue :issue:`7190`)

* Generated ``*_api.h`` files used potentially unknown Cython configuration macros.
  (Github issue :issue:`7108`)

* ``cythonize()`` avoids parallel compiler runs on systems using ``spawn()`` in multiprocessing.
  Patch by Marcel Bargull.  (Github issue :issue:`3262`)

* The ``@cython.ufunc``  decorator was missing in type checker stubs.
  Patch by jayClean.  (Github issue :issue:`7109`)


3.1.3 (2025-08-13)
==================

Bugs fixed
----------

* Some method calls with 0 or 1 argument failed to use ``PyObject_VectorCallMethod()``.

* Walrus assignments of literal Python integers could generate invalid C code.
  (Github issue :issue:`6989`)

* ``cython.pythread_type_lock`` (also used as fallback for ``cython.pymutex``)
  could stall on heavily contended locks.
  (Github issue :issue:`6999`)

* C string arrays (not pointers) always coerced to the Python default string type,
  even on explicit casts to other string types.
  (Github issue :issue:`7020`)

* Unterminated ``\N{}`` character escapes in strings could unrail the parser.
  (Github issue :issue:`7056`)

* An internal C function was not marked as ``static`` and leaked a linker symbol.
  (Github issue :issue:`6957`)

* Some Unicode letters were not recognised as lexically valid name parts.
  (Github issue :issue:`7059`)

* Compatibility with PyPy3.8 was lost by accident.

* The Linux binary wheels of 3.1.2 used SSSE3 CPU instructions which are not available on some CPUs.
  (Github issue :issue:`7038`)


3.1.2 (2025-06-09)
==================

Bugs fixed
----------

* Attribute lookups failed on the ``bool`` builtin type.
  (Github issue :issue:`6905`)

* Type checks on or-ed union types could incorrectly return false.
  (Github issue :issue:`6420`)

* Negative list indexing could accidentally wrap around twice in PyPy and the Limited API.

* Iterating over literal sequences with starred (unpacked) items could infer a wrong
  type for the loop variable and fail to assign the values.
  (Github issue :issue:`6924`)

* Calls to C functions taking exception types failed to check for a `None` argument.
  (Github issue :issue:`6420`)

* Fused functions had an incorrect ``__module__`` attribute.
  (Github issue :issue:`6897`)

* The type of Cython implemented functions had an incorrect ``__module__`` attribute.
  (Github issue :issue:`6841`)

* Errors while indexing into ``bytearray`` or ``str`` in ``nogil`` sections could crash.
  (Github issue :issue:`6947`)

* ``bytearray.append()`` could silently accept some invalid character numbers.

* The C++11 ``<type_traits>`` header was included regardless of the C++ version.
  (Github issue :issue:`6896`)

* ``PyDict_GetItemStringRef()`` was accidentally used in older Limited API versions.
  (Github issue :issue:`6914`)

* ``abort()`` was used but not always available in the Limited API.
  (Github issue :issue:`6918`)

* Some dependencies were missing from the ``depfile``.
  (Github issue :issue:`6938`)

* Embedded function signatures were not always separated from the existing docstring.
  (Github issue :issue:`6904`)

* ``numpy.math`` was missing from ``Cython/Includes/`` and could not be cimported.
  (Github issue :issue:`6859`)

* Some tests were adapted for NumPy 2.x.
  (Github issue :issue:`6898`)

* Some C compiler warnings were fixed.
  (Github issue :issue:`6870`)

* ``Cython.Build`` was not officially exposing the ``cythonize`` function.
  (Github issue :issue:`6934`)


3.1.1 (2025-05-19)
==================

Bugs fixed
----------

* A reference leak in the async delegation code was fixed.
  (Github issues :issue:`6850`, :issue:`6878`)

* Conditional if-else expressions mixing Python and C (numeric) types could end up
  inferring an overly tight result type, thus leading to unexpected type conversions,
  runtime exceptions on assignment, or incorrect "temporary assignment" compile errors.
  (Github issue :issue:`6854`)

* Some Limited API issues were resolved.
  (Github issue :issue:`6862`)

* Large C ``long long`` values could be truncated when passed into PyPy.
  (Github issue :issue:`6890`)

* ``callable()`` incorrectly reported ``False`` in PyPy for classes with metaclasses.
  Patch by Anatolii Aniskovych. (Github issue :issue:`6892`)

* The signature of fused functions was no longer introspectable in Cython 3.1.0.
  (Github issue :issue:`6855`)

* Coroutines could generate invalid C with line tracing enabled.
  (Github issue :issue:`6865`)

* Code using ``complex()`` could generate invalid C code missing type declarations.
  (Github issue :issue:`6860`)

* Code using e.g. ``list[int | None]``  outside of variable/argument annotations failed to compile.
  (Github issue :issue:`6856`)

* Code using ctuples in a ``const`` context could generate invalid C.
  (Github issue :issue:`6864`)

* Accessing special methods on cpdef enums failed to compile.

* Some C compiler warnings were resolved.
  Patches by Daniel Larraz.  (Github issues :issue:`6876`, :issue:`3172`, :issue:`6873`, :issue:`6877`)

* Re-establish support for PyPy 3.8.
  (Github issue :issue:`6867`)


3.1.0 (2025-05-08)
==================

Other changes
-------------

* No functional changes since 3.1.0 rc 2.


3.1.0 rc 2 (2025-05-07)
=======================

Features added
--------------

* Declarations for C++ ``std::stop_token`` were added as ``libcpp.stop_token`` to provide
  additional low-level synchronisation primitives also in the light of free-threading Python.
  (Github issue :issue:`6820`)

* The generation of the shared module now happens automatically from ``cythonize()`` in a
  ``setuptools`` build if a corresponding ``Extension`` has been configured.
  This avoids an additional step outside of the ``setup.py`` or ``pip wheel`` run.
  (Github issue :issue:`6842`)

Bugs fixed
----------

* Variables typed as builtin Python exception types now accept subtypes instead of rejecting them.
  This specifically impacted types like ``BaseException``, ``Exception`` or ``OSError``,
  which almost always intend to reference subtypes.
  (Github issue :issue:`6828`)
