[josamhany]

Rationale for this change

Passing a negative value to Dataset.head() can result in unexpected behavior, including returning a table with a negative number of rows.

Since the head() API expects a non-negative number of rows, negative values should be rejected explicitly with a clear error message.

What changes are included in this PR?

• Added validation in AsyncScanner::Head() to reject negative num_rows values.
• Returns Status::Invalid("num_rows must be non-negative") when a negative value is provided.
• Added regression tests covering negative values passed to:
  • Dataset.head()
  • Scanner.head()
  • Fragment.head()

Are these changes tested?

Yes.

• Built PyArrow from source successfully.
• Targeted tests: 3 passed.
• Full python/pyarrow/tests/test_dataset.py test suite: 310 passed, 54 skipped.
• git diff --check passed.

Are there any user-facing changes?

Yes. Calling Dataset.head(), Scanner.head(), or Fragment.head() with a negative num_rows now raises pyarrow.ArrowInvalid with a clear error message instead of producing unexpected behavior.

Was AI used for this PR?

PR code and description written by:

• Human
• AI

Reviewed before submission by:

• Human
• AI
• Not reviewed

• GitHub Issue: [Python] Dataset.head(-1) returns a Table with negative num_rows #55295

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

[github-actions]

⚠️ GitHub issue #55295 has been automatically assigned in GitHub to PR creator.

[github-actions]

⚠️ GitHub issue #55295 has no components, please add labels for components.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.