Reconfigure CFFI porting scripts for SDL3, add _libtcod.pyi

Many SDL functions were renamed and I'd have to port them blind without
this new `_libtcod.py` file.

Current solution is crude and incomplete.

Author: HexDecimal

CHANGELOG.md

@@ -6,9 +6,20 @@ This project adheres to [Semantic Versioning](https://semver.org/) since version
 
 ## [Unreleased]
 
+### Changed
+
+- Switched to SDL3.
+  This will cause several breaking changes such as the names of keyboard constants and other SDL enums.
+
 ### Removed
 
 - Support dropped for Python 3.8 and 3.9.
+- Removed `Joystick.get_current_power` due to SDL3 changes.
+- `WindowFlags.FULLSCREEN_DESKTOP` is now just `WindowFlags.FULLSCREEN`
+
+### Fixed
+
+- `Joystick.get_ball` was broken.
 
 ## [18.1.0] - 2025-05-05
 

build_libtcod.py

@@ -13,6 +13,10 @@
 from pathlib import Path
 from typing import Any, ClassVar
 
+import attrs
+import pycparser  # type: ignore[import-untyped]
+import pycparser.c_ast  # type: ignore[import-untyped]
+import pycparser.c_generator  # type: ignore[import-untyped]
 from cffi import FFI
 
 # ruff: noqa: T201
@@ -204,7 +208,8 @@ def walk_sources(directory: str) -> Iterator[str]:
     extra_link_args.extend(GCC_CFLAGS[tdl_build])
 
 ffi = FFI()
-ffi.cdef(build_sdl.get_cdef())
+sdl_cdef = build_sdl.get_cdef()
+ffi.cdef(sdl_cdef)
 for include in includes:
     try:
         ffi.cdef(include.header)
@@ -383,10 +388,10 @@ def write_library_constants() -> None:
         f.write(f"""{parse_sdl_attrs("SDL_SCANCODE", None)[0]}\n""")
 
         f.write("\n# --- SDL keyboard symbols ---\n")
-        f.write(f"""{parse_sdl_attrs("SDLK", None)[0]}\n""")
+        f.write(f"""{parse_sdl_attrs("SDLK_", None)[0]}\n""")
 
         f.write("\n# --- SDL keyboard modifiers ---\n")
-        f.write("{}\n_REVERSE_MOD_TABLE = {}\n".format(*parse_sdl_attrs("KMOD", None)))
+        f.write("{}\n_REVERSE_MOD_TABLE = {}\n".format(*parse_sdl_attrs("SDL_KMOD", None)))
 
         f.write("\n# --- SDL wheel ---\n")
         f.write("{}\n_REVERSE_WHEEL_TABLE = {}\n".format(*parse_sdl_attrs("SDL_MOUSEWHEEL", all_names)))
@@ -411,5 +416,220 @@ def write_library_constants() -> None:
     Path("tcod/event.py").write_text(event_py, encoding="utf-8")
 
 
+def _fix_reserved_name(name: str) -> str:
+    """Add underscores to reserved Python keywords."""
+    assert isinstance(name, str)
+    if name in ("def", "in"):
+        return name + "_"
+    return name
+
+
+@attrs.define(frozen=True)
+class ConvertedParam:
+    name: str = attrs.field(converter=_fix_reserved_name)
+    hint: str
+    original: str
+
+
+def _type_from_names(names: list[str]) -> str:
+    if not names:
+        return ""
+    if names[-1] == "void":
+        return "None"
+    if names in (["unsigned", "char"], ["bool"]):
+        return "bool"
+    if names[-1] in ("size_t", "int", "ptrdiff_t"):
+        return "int"
+    return "Any"
+
+
+def _param_as_hint(node: pycparser.c_ast.Node, default_name: str) -> ConvertedParam:
+    original = pycparser.c_generator.CGenerator().visit(node)
+    name: str
+    names: list[str]
+    match node:
+        case pycparser.c_ast.Typename(type=pycparser.c_ast.TypeDecl(type=pycparser.c_ast.IdentifierType(names=names))):
+            # Unnamed type
+            return ConvertedParam(default_name, _type_from_names(names), original)
+        case pycparser.c_ast.Decl(
+            name=name, type=pycparser.c_ast.TypeDecl(type=pycparser.c_ast.IdentifierType(names=names))
+        ):
+            # Named type
+            return ConvertedParam(name, _type_from_names(names), original)
+        case pycparser.c_ast.Decl(
+            name=name,
+            type=pycparser.c_ast.ArrayDecl(
+                type=pycparser.c_ast.TypeDecl(type=pycparser.c_ast.IdentifierType(names=names))
+            ),
+        ):
+            # Named array
+            return ConvertedParam(name, "Any", original)
+        case pycparser.c_ast.Decl(name=name, type=pycparser.c_ast.PtrDecl()):
+            # Named pointer
+            return ConvertedParam(name, "Any", original)
+        case pycparser.c_ast.Typename(name=name, type=pycparser.c_ast.PtrDecl()):
+            # Forwarded struct
+            return ConvertedParam(name or default_name, "Any", original)
+        case pycparser.c_ast.TypeDecl(type=pycparser.c_ast.IdentifierType(names=names)):
+            # Return type
+            return ConvertedParam(default_name, _type_from_names(names), original)
+        case pycparser.c_ast.PtrDecl():
+            # Return pointer
+            return ConvertedParam(default_name, "Any", original)
+        case pycparser.c_ast.EllipsisParam():
+            # C variable args
+            return ConvertedParam("*__args", "Any", original)
+        case _:
+            raise AssertionError
+
+
+class DefinitionCollector(pycparser.c_ast.NodeVisitor):  # type: ignore[misc]
+    """Gathers functions and names from C headers."""
+
+    def __init__(self) -> None:
+        """Initialize the object with empty values."""
+        self.functions: list[str] = []
+        """Indented Python function definitions."""
+        self.variables: set[str] = set()
+        """Python variable definitions."""
+
+    def parse_defines(self, string: str, /) -> None:
+        """Parse C define directives into hinted names."""
+        for match in re.finditer(r"#define\s+(\S+)\s+(\S+)\s*", string):
+            name, value = match.groups()
+            if value == "...":
+                self.variables.add(f"{name}: Final[int]")
+            else:
+                self.variables.add(f"{name}: Final[Literal[{value}]] = {value}")
+
+    def visit_Decl(self, node: pycparser.c_ast.Decl) -> None:  # noqa: N802
+        """Parse C FFI functions into type hinted Python functions."""
+        match node:
+            case pycparser.c_ast.Decl(
+                type=pycparser.c_ast.FuncDecl(),
+            ):
+                assert isinstance(node.type.args, pycparser.c_ast.ParamList), type(node.type.args)
+                arg_hints = [_param_as_hint(param, f"arg{i}") for i, param in enumerate(node.type.args.params)]
+                return_hint = _param_as_hint(node.type.type, "")
+                if len(arg_hints) == 1 and arg_hints[0].hint == "None":  # Remove void parameter
+                    arg_hints = []
+
+                python_params = [f"{p.name}: {p.hint}" for p in arg_hints]
+                if python_params:
+                    if arg_hints[-1].name.startswith("*"):
+                        python_params.insert(-1, "/")
+                    else:
+                        python_params.append("/")
+                c_def = pycparser.c_generator.CGenerator().visit(node)
+                python_def = f"""def {node.name}({", ".join(python_params)}) -> {return_hint.hint}:"""
+                self.functions.append(f'''    {python_def}\n        """{c_def}"""''')
+
+    def visit_Enumerator(self, node: pycparser.c_ast.Enumerator) -> None:  # noqa: N802
+        """Parse C enums into hinted names."""
+        name: str | None
+        value: str | int
+        match node:
+            case pycparser.c_ast.Enumerator(name=name, value=None):
+                self.variables.add(f"{name}: Final[int]")
+            case pycparser.c_ast.Enumerator(name=name, value=pycparser.c_ast.ID()):
+                self.variables.add(f"{name}: Final[int]")
+            case pycparser.c_ast.Enumerator(name=name, value=pycparser.c_ast.Constant(value=value)):
+                value = int(str(value).removesuffix("u"), base=0)
+                self.variables.add(f"{name}: Final[Literal[{value}]] = {value}")
+            case pycparser.c_ast.Enumerator(
+                name=name, value=pycparser.c_ast.UnaryOp(op="-", expr=pycparser.c_ast.Constant(value=value))
+            ):
+                value = -int(str(value).removesuffix("u"), base=0)
+                self.variables.add(f"{name}: Final[Literal[{value}]] = {value}")
+            case pycparser.c_ast.Enumerator(name=name):
+                self.variables.add(f"{name}: Final[int]")
+            case _:
+                raise AssertionError
+
+
+def write_hints() -> None:
+    """Write a custom _libtcod.pyi file from C definitions."""
+    function_collector = DefinitionCollector()
+    c = pycparser.CParser()
+
+    # Parse SDL headers
+    cdef = sdl_cdef
+    cdef = cdef.replace("int...", "int")
+    cdef = (
+        """
+typedef int int8_t;
+typedef int uint8_t;
+typedef int int16_t;
+typedef int uint16_t;
+typedef int int32_t;
+typedef int uint32_t;
+typedef int int64_t;
+typedef int uint64_t;
+typedef int wchar_t;
+typedef int intptr_t;
+"""
+        + cdef
+    )
+    cdef = re.sub(r"(typedef enum SDL_PixelFormat).*(SDL_PixelFormat;)", r"\1 \2", cdef, flags=re.DOTALL)
+    cdef = cdef.replace("padding[...]", "padding[]")
+    cdef = cdef.replace("...;} SDL_TouchFingerEvent;", "} SDL_TouchFingerEvent;")
+    function_collector.parse_defines(cdef)
+    cdef = re.sub(r"\n#define .*", "", cdef)
+    cdef = re.sub(r"""extern "Python" \{(.*?)\}""", r"\1", cdef, flags=re.DOTALL)
+    cdef = re.sub(r"//.*", "", cdef)
+    ast = c.parse(cdef)
+    function_collector.visit(ast)
+
+    # Parse libtcod headers
+    cdef = "\n".join(include.header for include in includes)
+    function_collector.parse_defines(cdef)
+    cdef = re.sub(r"\n?#define .*", "", cdef)
+    cdef = re.sub(r"//.*", "", cdef)
+    cdef = (
+        """
+typedef int int8_t;
+typedef int uint8_t;
+typedef int int16_t;
+typedef int uint16_t;
+typedef int int32_t;
+typedef int uint32_t;
+typedef int int64_t;
+typedef int uint64_t;
+typedef int wchar_t;
+typedef int intptr_t;
+typedef int ptrdiff_t;
+typedef int size_t;
+typedef unsigned char bool;
+typedef void* SDL_PropertiesID;
+"""
+        + cdef
+    )
+    cdef = re.sub(r"""extern "Python" \{(.*?)\}""", r"\1", cdef, flags=re.DOTALL)
+    function_collector.visit(c.parse(cdef))
+
+    # Write PYI file
+    out_functions = """\n\n    @staticmethod\n""".join(sorted(function_collector.functions))
+    out_variables = "\n    ".join(sorted(function_collector.variables))
+
+    pyi = f"""\
+# Autogenerated with build_libtcod.py
+from typing import Any, Final, Literal
+
+# pyi files for CFFI ports are not standard
+# ruff: noqa: A002, ANN401, D402, D403, D415, N801, N802, N803, N815, PLW0211, PYI021
+
+class _lib:
+    @staticmethod
+{out_functions}
+
+    {out_variables}
+
+lib: _lib
+ffi: Any
+"""
+    Path("tcod/_libtcod.pyi").write_text(pyi)
+
+
 if __name__ == "__main__":
+    write_hints()
     write_library_constants()

build_sdl.py

@@ -188,7 +188,7 @@ def _should_track_define(self, tokens: list[Any]) -> bool:
             return False  # Data type for printing, which is not needed.
         if tokens[0].value.startswith("SDL_PLATFORM_"):
             return False  # Ignore platform definitions
-        return bool(tokens[0].value.startswith("SDL_"))
+        return bool(str(tokens[0].value).startswith(("SDL_", "SDLK_")))
 
     def on_directive_handle(
         self,

pyproject.toml

@@ -10,6 +10,7 @@ requires = [
     "pycparser>=2.14",
     "pcpp==1.30",
     "requests>=2.28.1",
+    "attrs",
 ]
 build-backend = "setuptools.build_meta"