[jryyangjy]

Fixes

Fixes #3683

Problem

surfarray.blit_array and surfarray.make_surface both silently accept NumPy float arrays:

if isinstance(array, numpy_ndarray) and array.dtype in numpy_floats:
    array = array.round(0).astype(numpy_uint32)

...even though both docstrings/reference docs state only integer, ASCII character, or record arrays are accepted. This is undocumented anywhere, and as the issue reporter found, it's a silent perf trap: passing a float array by mistake causes an implicit rounding-and-copy pass, defeating the whole point of these being the "fast path" functions.

Confirmed the current (2.5.7) behavior directly:

arr = np.zeros((4, 4), dtype=np.float64)
arr[:] = 123.7
surfarray.blit_array(surf, arr)   # succeeds silently, no warning
surf.get_at((0, 0))               # -> Color(0, 0, 124, 255), i.e. rounded

Fix

Doc-only change, no behavior change:

• Updated the blit_array and make_surface docstrings in src_py/surfarray.py to state that float arrays are accepted, rounded, and copied -- and that this defeats the performance benefit of blit_array.
• Mirrored the same wording in docs/reST/ref/surfarray.rst.

Test plan

• Verified current behavior against the installed 2.5.7 wheel (float array silently accepted and rounded, as shown above).
• Parsed the edited .rst with docutils to confirm no new syntax errors were introduced (pre-existing Sphinx-only directives like .. function::/:sl:/:mod: predictably show as "unknown" under bare docutils across the whole file, not just the edited sections -- this is expected without a full Sphinx build).
• ast.parse() on the edited surfarray.py to confirm valid Python syntax.
• I don't have a full local build of the pygame-ce C extensions on this machine, so I did not attempt dev.py docs --full; this change doesn't touch any C code or runtime behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: e00aae23-3bf2-49f9-93b1-902ffca50192

📥 Commits

Reviewing files that changed from the base of the PR and between d6540b0 and dc692a2.

📒 Files selected for processing (1)

• docs/reST/ref/surfarray.rst

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/reST/ref/surfarray.rst

---

📝 Walkthrough

Walkthrough

Clarifies that pygame.surfarray.blit_array and make_surface accept NumPy float arrays by rounding and copying them into integer arrays. The blit_array documentation also notes the performance cost.

Changes

Surfarray documentation

Layer / File(s)	Summary
Document float array conversion src_py/surfarray.py, docs/reST/ref/surfarray.rst	Docstrings and reference documentation describe float-array rounding and copying for blit_array and make_surface. The blit_array documentation includes an approximate 2x performance cost compared with integer arrays.

Estimated code review effort: 1 (Trivial) | ~2 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the documentation change for float array rounding in both APIs.
Description check	✅ Passed	The description explains the undocumented float-array behavior, performance impact, documentation fix, and validation steps.
Linked Issues check	✅ Passed	The changes document float-array acceptance, rounding, copying, and the performance impact required by issue #3683.
Out of Scope Changes check	✅ Passed	All changes update the two requested docstrings and reference documentation, with no unrelated code or API changes.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/reST/ref/surfarray.rst`:
- Around line 270-271: Update the blit_array documentation to explicitly state
that only NumPy float32, float64, and optionally float96 arrays are rounded and
copied; revise the preceding accepted-dtype statement so it no longer
contradicts float support. Apply the same correction to both referenced
documentation passages.

In `@src_py/surfarray.py`:
- Around line 105-108: Update the docstrings for blit_array and the related
array-copy function to explicitly list only float32, float64, and optional
float96 as supported NumPy float dtypes. Remove the broad “all NumPy float
arrays” wording and revise the preceding acceptance description so it includes
these supported float types alongside integer, ASCII character, and record
arrays without claiming unsupported dtypes are accepted.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: fe028c86-dbe4-4424-90f7-5ec44dfc6ad9

📥 Commits

Reviewing files that changed from the base of the PR and between 49e6804 and f87eb4b.

📒 Files selected for processing (2)

• docs/reST/ref/surfarray.rst
• src_py/surfarray.py

[Starbuck5]

Thanks for taking a look at this, I'm good to go with it.

However, I don't think it fully resolves #3683, just makes it better. Since it doesn't do a warning or decisively figure we don't need a warning. But that could make it more complicated, this is good.

I put a comment on the parent issue as well about going to "any numpy float array" instead of certain hardcoded values.

[oddbookworm]

LGTM with that quick fix in! 🎉