[Bugfix] Caption constructor positional signature disagrees with its frozen docstring #320

New issue

Closed

opened 2026-06-21 14:50:21 +00:00 by john · 0 comments

john commented

2026-06-21 14:50:21 +00:00

Owner

Summary

mcrfpy.Caption's constructor accepts a different positional layout than its frozen (#314-locked) docstring advertises, and is the lone sibling constructor that rejects a 3rd positional argument.

Evidence

Frozen docstring (the public contract):

Caption(pos=None, font=None, text='', **kwargs)

This declares pos, font, text as positional-or-keyword (font is the 2nd positional, text the 3rd) — matching the sibling constructors:

Sprite(pos=None, texture=None, sprite_index=0, **kwargs) — accepts Sprite((100,150), None, 5)
Entity(grid_pos=None, texture=None, sprite_index=0, **kwargs) — accepts Entity((5,10), None, 3)

Actual implementation (src/UICaption.cpp UICaption::init, format "|Oz$...", kwlist {"pos","text",...}):

Only 2 positional slots, laid out as (pos, text), with font keyword-only.
Caption((50,100), None, "Hello") -> TypeError: function takes at most 2 positional arguments (3 given)
Caption((50,100), "hi") currently binds "hi" to text, contradicting the documented (pos, font, text) order.

So Caption is the only one of the three that (a) caps at 2 positional args and (b) has a different positional order than documented.

Impact

tests/unit/test_constructor_comprehensive.py fails at the Caption case (the only blocker; Entity/edge-cases already pass).
The public, frozen docstring lies about a constructor's positional arity and order — exactly the docstring-accuracy class as #317/#318/#319 (surfaced by the #314 verify pass).

Fix

Make the implementation match the frozen docstring and the Sprite/Entity convention: positional order (pos, font, text), with the rest keyword-only.

Behavior note (acceptable): Caption((x,y), "string") changes meaning from text="string" to font="string" (-> TypeError, since font must be a Font). Audited: zero live callers use the current (pos, text) 2-positional form; the legacy (text, x, y) callers in src/scripts/text_input_widget*.py already fail under the current impl and are out of scope.

Regression test + fix to follow.

Labels to apply (MCP label bug -> apply via web): Bugfix, system:python-binding, priority:tier1-active.

## Summary `mcrfpy.Caption`'s constructor accepts a different positional layout than its frozen (#314-locked) docstring advertises, and is the lone sibling constructor that rejects a 3rd positional argument. ## Evidence Frozen docstring (the public contract): ``` Caption(pos=None, font=None, text='', **kwargs) ``` This declares `pos`, `font`, `text` as positional-or-keyword (font is the 2nd positional, text the 3rd) — matching the sibling constructors: - `Sprite(pos=None, texture=None, sprite_index=0, **kwargs)` — accepts `Sprite((100,150), None, 5)` - `Entity(grid_pos=None, texture=None, sprite_index=0, **kwargs)` — accepts `Entity((5,10), None, 3)` Actual implementation (`src/UICaption.cpp` `UICaption::init`, format `"|Oz$..."`, kwlist `{"pos","text",...}`): - Only 2 positional slots, laid out as `(pos, text)`, with `font` **keyword-only**. - `Caption((50,100), None, "Hello")` -> `TypeError: function takes at most 2 positional arguments (3 given)` - `Caption((50,100), "hi")` currently binds "hi" to **text**, contradicting the documented `(pos, font, text)` order. So Caption is the only one of the three that (a) caps at 2 positional args and (b) has a different positional order than documented. ## Impact - `tests/unit/test_constructor_comprehensive.py` fails at the Caption case (the only blocker; Entity/edge-cases already pass). - The public, frozen docstring lies about a constructor's positional arity and order — exactly the docstring-accuracy class as #317/#318/#319 (surfaced by the #314 verify pass). ## Fix Make the implementation match the frozen docstring and the Sprite/Entity convention: positional order `(pos, font, text)`, with the rest keyword-only. Behavior note (acceptable): `Caption((x,y), "string")` changes meaning from `text="string"` to `font="string"` (-> TypeError, since font must be a Font). Audited: **zero live callers** use the current `(pos, text)` 2-positional form; the legacy `(text, x, y)` callers in `src/scripts/text_input_widget*.py` already fail under the current impl and are out of scope. Regression test + fix to follow. Labels to apply (MCP label bug -> apply via web): `Bugfix`, `system:python-binding`, `priority:tier1-active`.