fix: change CFFI writer default output extension from .py to .cdef.txt (#45)

* fix: change CFFI writer default output extension from .py to .cdef.txt

CFFI writer output is C declarations for ffi.cdef(), not Python code.
Using .py was misleading. Updated default_output_pattern and all docs
to use .cdef.txt, consistent with cffi_buildtool's read-sources mode.

* fix: use C-style comments in CFFI writer hash_comment_format

pycparser does not support shell-style # comments, so cache metadata
prepended to .cdef.txt output should use // instead.

* fix: use C89-compatible /* */ comments in CFFI hash_comment_format

pycparser may run in C89 mode where // is not supported.

Author: elijahr

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- CFFI writer default output extension changed from `.py` to `.cdef.txt` (output is C declarations, not Python)
+
 ## [0.18.0] - 2026-04-04
 
 ### Added

README.md

@@ -45,10 +45,10 @@ _lib.distance.restype = ctypes.c_int
 
 **CFFI -- declarations for `ffibuilder.cdef()`:**
 ```bash
-headerkit mylib.h -w cffi -o cffi:_defs.py
+headerkit mylib.h -w cffi -o cffi:_defs.cdef.txt
 ```
 ```c
-/* generated  _defs.py */
+/* generated  _defs.cdef.txt */
 typedef struct Point {
     int x;
     int y;
@@ -296,7 +296,7 @@ output = generate("mylib.h", "cffi")
 
 ```bash
 # CLI: generate with caching (on by default)
-headerkit mylib.h -w cffi -o cffi:bindings.py --store-dir .headerkit
+headerkit mylib.h -w cffi -o cffi:mylib.cdef.txt --store-dir .headerkit
 ```
 
 headerkit also ships a PEP 517 build backend. Consumer projects declare it in `pyproject.toml` and get bindings generated automatically during `pip install` or `python -m build`, with no libclang required when the cache is committed:

docs/guides/build-backend.md

@@ -48,7 +48,7 @@ include_dirs = ["/usr/local/include"]
 Run headerkit locally on a machine with libclang installed:
 
 ```bash
-headerkit include/mylib.h -w cffi -o cffi:bindings/mylib_cffi.py
+headerkit include/mylib.h -w cffi -o cffi:bindings/mylib.cdef.txt
 ```
 
 This writes cache entries to `.headerkit/`.
@@ -255,7 +255,7 @@ To fix a cache miss:
 headerkit install-libclang
 
 # Re-generate and populate cache
-headerkit include/mylib.h -w cffi -o cffi:bindings/mylib_cffi.py
+headerkit include/mylib.h -w cffi -o cffi:bindings/mylib.cdef.txt
 
 # Commit updated cache
 git add .headerkit/
@@ -328,7 +328,7 @@ If bindings are outdated after modifying a header:
 ```bash
 # Clear the cache and regenerate
 headerkit cache clear --store-dir .headerkit
-headerkit include/mylib.h -w cffi -o cffi:bindings/mylib_cffi.py
+headerkit include/mylib.h -w cffi -o cffi:bindings/mylib.cdef.txt
 git add .headerkit/
 git commit -m "cache: regenerate after header changes"
 ```
@@ -377,7 +377,7 @@ ensure `.headerkit/` is packaged.
 Verify the committed cache matches current sources:
 
 ```bash
-headerkit include/mylib.h -w cffi -o cffi:bindings/mylib_cffi.py
+headerkit include/mylib.h -w cffi -o cffi:bindings/mylib.cdef.txt
 git diff --exit-code .headerkit/ bindings/
 ```
 

docs/guides/cache.md

@@ -87,7 +87,7 @@ results = generate_all(
     "include/mylib.h",
     writers=["cffi", "ctypes", "json"],
     output_paths={
-        "cffi": "bindings/mylib_cffi.py",
+        "cffi": "bindings/mylib.cdef.txt",
         "ctypes": "bindings/mylib_ctypes.py",
         "json": "bindings/mylib_ir.json",
     },
@@ -114,13 +114,13 @@ output = generate(
 
 ```bash
 # Generate with caching (default behavior)
-headerkit include/mylib.h -w cffi -o cffi:bindings/mylib_cffi.py
+headerkit include/mylib.h -w cffi -o cffi:bindings/mylib.cdef.txt
 
 # Second run uses cache automatically
-headerkit include/mylib.h -w cffi -o cffi:bindings/mylib_cffi.py
+headerkit include/mylib.h -w cffi -o cffi:bindings/mylib.cdef.txt
 
 # Multiple writers in one pass
-headerkit include/mylib.h -w cffi -o cffi:bindings/cffi.py -w ctypes -o ctypes:bindings/ctypes.py
+headerkit include/mylib.h -w cffi -o cffi:bindings/cffi.cdef.txt -w ctypes -o ctypes:bindings/ctypes.py
 
 # Custom store directory
 headerkit include/mylib.h -w cffi --store-dir /tmp/headerkit-store
@@ -273,10 +273,10 @@ To verify the committed cache is up-to-date in CI:
 
 ```bash
 # Generate with current sources
-headerkit mylib.h -w cffi -o cffi:bindings.py
+headerkit mylib.h -w cffi -o cffi:mylib.cdef.txt
 
 # Check for uncommitted changes
-git diff --exit-code .headerkit/ bindings.py
+git diff --exit-code .headerkit/ mylib.cdef.txt
 ```
 
 If the diff is non-empty, the cache is stale and needs to be regenerated.
@@ -464,7 +464,7 @@ to select headers:
 
 ```bash
 # Process all .h files under include/
-headerkit 'include/**/*.h' -w cffi -o cffi:{dir}/{stem}_cffi.py
+headerkit 'include/**/*.h' -w cffi -o cffi:{dir}/{stem}.cdef.txt
 
 # Exclude internal headers
 headerkit 'include/**/*.h' --exclude 'include/internal/**' -w cffi
@@ -486,11 +486,11 @@ Templates support these variables:
 
 ```bash
 # Each header gets its own output file
-headerkit 'include/**/*.h' -w cffi -o cffi:{dir}/{stem}_cffi.py
+headerkit 'include/**/*.h' -w cffi -o cffi:{dir}/{stem}.cdef.txt
 
 # Multiple writers with different templates
 headerkit 'include/**/*.h' \
-    -w cffi -o cffi:{dir}/{stem}_cffi.py \
+    -w cffi -o cffi:{dir}/{stem}.cdef.txt \
     -w json -o json:{dir}/{stem}.json
 ```
 
@@ -510,7 +510,7 @@ pattern = "vendor/special.h"
 defines = ["VENDOR_MODE"]
 
 [tool.headerkit.output]
-cffi = "{dir}/{stem}_cffi.py"
+cffi = "{dir}/{stem}.cdef.txt"
 json = "{dir}/{stem}.json"
 ```
 

headerkit/writers/cffi.py

@@ -526,7 +526,7 @@ class CffiWriter:
         cdef_string = writer.write(header)
     """
 
-    default_output_pattern: str = "{dir}/{stem}_cffi.py"
+    default_output_pattern: str = "{dir}/{stem}.cdef.txt"
 
     def __init__(
         self,
@@ -564,8 +564,8 @@ def format_description(self) -> str:
         return "CFFI cdef declarations for ffibuilder.cdef()"
 
     def hash_comment_format(self) -> str:
-        """Return format string for wrapping TOML cache metadata in Python comments."""
-        return "# {line}"
+        """Return format string for wrapping cache metadata in C-style comments."""
+        return "/* {line} */"
 
 
 # Uses bottom-of-module self-registration. Unlike backends (which import

tests/test_cli_integration.py

@@ -415,8 +415,8 @@ def test_one_writer_explicit_one_writer_default(
 
         assert result == 0
         assert json_out.exists()
-        # cffi writer uses default pattern {dir}/{stem}_cffi.py
-        cffi_default = tmp_path / "test_cffi.py"
+        # cffi writer uses default pattern {dir}/{stem}.cdef.txt
+        cffi_default = tmp_path / "test.cdef.txt"
         assert cffi_default.exists()
         assert "multiply" in cffi_default.read_text(encoding="utf-8")
 
@@ -457,9 +457,9 @@ def test_two_files_declarations_both_present(
         result = main()
 
         assert result == 0
-        # Batch mode writes to default output pattern {dir}/{stem}_cffi.py
-        cffi_a = tmp_path / "a_cffi.py"
-        cffi_b = tmp_path / "b_cffi.py"
+        # Batch mode writes to default output pattern {dir}/{stem}.cdef.txt
+        cffi_a = tmp_path / "a.cdef.txt"
+        cffi_b = tmp_path / "b.cdef.txt"
         assert cffi_a.exists()
         assert cffi_b.exists()
         assert "func_a" in cffi_a.read_text(encoding="utf-8")