Add Python 3.14 support, experimental subinterpreter/freethreading support (#1279)

The bulk of the changes here is a rewrite of `recordobj.c` to use modern
CPython API to properly isolate the module (PEP 489, PEP 573, PEP 630).
This, along with Cython flags, enables support for safely importing
`asyncpg` in subinterpreters.  The `Record` freelist is now
thread-specific, so asyncpg should be thread-safe *at the C level*.
Support for subinterpreters and freethreading is EXPERIMENTAL.

Author: elprans

.clang-format

@@ -0,0 +1,17 @@
+# A clang-format style that approximates Python's PEP 7
+BasedOnStyle: Google
+AlwaysBreakAfterReturnType: All
+AllowShortIfStatementsOnASingleLine: false
+AlignAfterOpenBracket: Align
+BreakBeforeBraces: Stroustrup
+ColumnLimit: 95
+DerivePointerAlignment: false
+IndentWidth: 4
+Language: Cpp
+PointerAlignment: Right
+ReflowComments: true
+SpaceBeforeParens: ControlStatements
+SpacesInParentheses: false
+TabWidth: 4
+UseTab: Never
+SortIncludes: false

.clangd

@@ -0,0 +1,4 @@
+Diagnostics:
+  Includes:
+    IgnoreHeader:
+      - "pythoncapi_compat.*\\.h"

.github/workflows/tests.yml

@@ -17,7 +17,7 @@ jobs:
     # job.
     strategy:
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14", "3.14t"]
         os: [ubuntu-latest, macos-latest, windows-latest]
         loop: [asyncio, uvloop]
         exclude:

.gitignore

@@ -33,6 +33,8 @@ docs/_build
 /.pytest_cache/
 /.eggs
 /.vscode
+/.zed
 /.mypy_cache
 /.venv*
 /.tox
+/compile_commands.json

asyncpg/connection.py

@@ -2751,8 +2751,8 @@ def _check_record_class(record_class):
         and issubclass(record_class, protocol.Record)
     ):
         if (
-            record_class.__new__ is not object.__new__
-            or record_class.__init__ is not object.__init__
+            record_class.__new__ is not protocol.Record.__new__
+            or record_class.__init__ is not protocol.Record.__init__
         ):
             raise exceptions.InterfaceError(
                 'record_class must not redefine __new__ or __init__'

asyncpg/protocol/__init__.py

@@ -8,4 +8,5 @@
 
 from __future__ import annotations
 
-from .protocol import Protocol, Record, NO_TIMEOUT, BUILTIN_TYPE_NAME_MAP
+from .protocol import Protocol, NO_TIMEOUT, BUILTIN_TYPE_NAME_MAP
+from .record import Record

asyncpg/protocol/codecs/base.pxd

@@ -22,6 +22,18 @@ ctypedef object (*codec_decode_func)(Codec codec,
                                      FRBuffer *buf)
 
 
+cdef class CodecMap:
+    cdef:
+        void** binary_codec_map
+        void** text_codec_map
+        dict extra_codecs
+
+    cdef inline void *get_binary_codec_ptr(self, uint32_t idx)
+    cdef inline void set_binary_codec_ptr(self, uint32_t idx, void *ptr)
+    cdef inline void *get_text_codec_ptr(self, uint32_t idx)
+    cdef inline void set_text_codec_ptr(self, uint32_t idx, void *ptr)
+
+
 cdef enum CodecType:
     CODEC_UNDEFINED  = 0
     CODEC_C          = 1

asyncpg/protocol/codecs/base.pyx

@@ -11,9 +11,33 @@ import asyncpg
 from asyncpg import exceptions
 
 
-cdef void* binary_codec_map[(MAXSUPPORTEDOID + 1) * 2]
-cdef void* text_codec_map[(MAXSUPPORTEDOID + 1) * 2]
-cdef dict EXTRA_CODECS = {}
+# The class indirection is needed because Cython
+# does not (as of 3.1.0) store global cdef variables
+# in module state.
+@cython.final
+cdef class CodecMap:
+
+    def __cinit__(self):
+        self.extra_codecs = {}
+        self.binary_codec_map = <void **>cpython.PyMem_Calloc(
+            (MAXSUPPORTEDOID + 1) * 2, sizeof(void *))
+        self.text_codec_map = <void **>cpython.PyMem_Calloc(
+            (MAXSUPPORTEDOID + 1) * 2, sizeof(void *))
+
+    cdef inline void *get_binary_codec_ptr(self, uint32_t idx):
+        return <void*>self.binary_codec_map[idx]
+
+    cdef inline void set_binary_codec_ptr(self, uint32_t idx, void *ptr):
+        self.binary_codec_map[idx] = ptr
+
+    cdef inline void *get_text_codec_ptr(self, uint32_t idx):
+        return <void*>self.text_codec_map[idx]
+
+    cdef inline void set_text_codec_ptr(self, uint32_t idx, void *ptr):
+        self.text_codec_map[idx] = ptr
+
+
+codec_map = CodecMap()
 
 
 @cython.final
@@ -67,7 +91,7 @@ cdef class Codec:
                 )
 
         if element_names is not None:
-            self.record_desc = record.ApgRecordDesc_New(
+            self.record_desc = RecordDescriptor(
                 element_names, tuple(element_names))
         else:
             self.record_desc = None
@@ -271,7 +295,7 @@ cdef class Codec:
                 schema=self.schema,
                 data_type=self.name,
             )
-        result = record.ApgRecord_New(asyncpg.Record, self.record_desc, elem_count)
+        result = self.record_desc.make_record(asyncpg.Record, elem_count)
         for i in range(elem_count):
             elem_typ = self.element_type_oids[i]
             received_elem_typ = <uint32_t>hton.unpack_int32(frb_read(buf, 4))
@@ -301,7 +325,7 @@ cdef class Codec:
                     settings, frb_slice_from(&elem_buf, buf, elem_len))
 
             cpython.Py_INCREF(elem)
-            record.ApgRecord_SET_ITEM(result, i, elem)
+            recordcapi.ApgRecord_SET_ITEM(result, i, elem)
 
         return result
 
@@ -811,9 +835,9 @@ cdef inline Codec get_core_codec(
     if oid > MAXSUPPORTEDOID:
         return None
     if format == PG_FORMAT_BINARY:
-        ptr = binary_codec_map[oid * xformat]
+        ptr = (<CodecMap>codec_map).get_binary_codec_ptr(oid * xformat)
     elif format == PG_FORMAT_TEXT:
-        ptr = text_codec_map[oid * xformat]
+        ptr = (<CodecMap>codec_map).get_text_codec_ptr(oid * xformat)
 
     if ptr is NULL:
         return None
@@ -839,7 +863,10 @@ cdef inline Codec get_any_core_codec(
 
 
 cdef inline int has_core_codec(uint32_t oid):
-    return binary_codec_map[oid] != NULL or text_codec_map[oid] != NULL
+    return (
+        (<CodecMap>codec_map).get_binary_codec_ptr(oid) != NULL
+        or (<CodecMap>codec_map).get_text_codec_ptr(oid) != NULL
+    )
 
 
 cdef register_core_codec(uint32_t oid,
@@ -867,9 +894,9 @@ cdef register_core_codec(uint32_t oid,
     cpython.Py_INCREF(codec)  # immortalize
 
     if format == PG_FORMAT_BINARY:
-        binary_codec_map[oid * xformat] = <void*>codec
+        (<CodecMap>codec_map).set_binary_codec_ptr(oid * xformat, <void*>codec)
     elif format == PG_FORMAT_TEXT:
-        text_codec_map[oid * xformat] = <void*>codec
+        (<CodecMap>codec_map).set_text_codec_ptr(oid * xformat, <void*>codec)
     else:
         raise exceptions.InternalClientError(
             'invalid data format: {}'.format(format))
@@ -888,8 +915,8 @@ cdef register_extra_codec(str name,
     codec = Codec(INVALIDOID)
     codec.init(name, None, kind, CODEC_C, format, PG_XFORMAT_OBJECT,
                encode, decode, None, None, None, None, None, None, None, 0)
-    EXTRA_CODECS[name, format] = codec
+    (<CodecMap>codec_map).extra_codecs[name, format] = codec
 
 
 cdef inline Codec get_extra_codec(str name, ServerDataFormat format):
-    return EXTRA_CODECS.get((name, format))
+    return (<CodecMap>codec_map).extra_codecs.get((name, format))

asyncpg/protocol/coreproto.pyx

@@ -11,7 +11,7 @@ import hashlib
 include "scram.pyx"
 
 
-cdef dict AUTH_METHOD_NAME = {
+AUTH_METHOD_NAME = {
     AUTH_REQUIRED_KERBEROS: 'kerberosv5',
     AUTH_REQUIRED_PASSWORD: 'password',
     AUTH_REQUIRED_PASSWORDMD5: 'md5',
@@ -1229,5 +1229,5 @@ cdef class CoreProtocol:
         pass
 
 
-cdef bytes SYNC_MESSAGE = bytes(WriteBuffer.new_message(b'S').end_message())
-cdef bytes FLUSH_MESSAGE = bytes(WriteBuffer.new_message(b'H').end_message())
+SYNC_MESSAGE = bytes(WriteBuffer.new_message(b'S').end_message())
+FLUSH_MESSAGE = bytes(WriteBuffer.new_message(b'H').end_message())

asyncpg/protocol/encodings.pyx

@@ -10,7 +10,7 @@
 https://www.postgresql.org/docs/current/static/multibyte.html#CHARSET-TABLE
 '''
 
-cdef dict ENCODINGS_MAP = {
+ENCODINGS_MAP = {
     'abc': 'cp1258',
     'alt': 'cp866',
     'euc_cn': 'euccn',