docs: add # Panics sections across the workspace - #10656
Open
emilk wants to merge 4 commits into
Open
Conversation
Sweep every crate for public functions that panic on bad arguments or
bad state and document them:
- arrow-buffer: `NullBuffer::{is_valid, is_null, slice, expand}`,
`BooleanBuffer::slice`, `ScalarBuffer::slice`, `OffsetBuffer`,
`Buffer::bit_slice`, `bit_util`, `bit_mask::set_bits`, bitmap builders,
`i256` division and logarithms
- arrow-array: `Array::{is_null, is_valid, slice}` and every inherent
`slice`, index accessors (`value_length`, `value_size`, `value_offset`,
`column`, `key`, `value_as_*`), `cast.rs` downcast helpers, builder
`finish`/`finish_cloned`, `make_builder`, deprecated `Date32Type`
interval helpers, `div_wrapping`/`mod_wrapping`
- arrow-data, arrow-schema: FFI schema accessors
- arrow-ord, arrow-row, arrow-cast: `compare_byte_view`,
`Rows::{push, row}`, `b64_encode`
- arrow: bench and test helpers that assert on their arguments
- parquet: `ByteArray` accessors, `Sbbf::new_with_num_of_bytes`,
`byte_range`, `with_range`, truncate-length setters, typed column
reader/writer casts, `schema::types` accessors
- parquet-variant: infallible constructors, `get`, `iter`, `get_entry`,
`ObjectBuilder::{new_object, new_list}`
Also normalize nine `# Panic` headers to `# Panics` so they are found by
a search, and convert loose "this will panic if ..." prose into proper
sections.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
github-actions
Bot
added
parquet
emilk
changed the title
# Panics sections across the workspace# Panics sections across the workspace
emilk
marked this pull request as ready for review
August 12, 2026 11:34
timsaucer
approved these changes
Aug 12, 2026
timsaucer
left a comment
timsaucer
left a comment
Member
There was a problem hiding this comment.
The only other thing I mentioned when we chatted was the inconsistent use of an extra line between the # Panics and the text about the panic, but I understand that it's trying to keep each file self consistent.
The issues below were flagged by an agent but I verified each one.
- Use concrete index expressions in the bitmap builders instead of prose - Drop two unreachable claims: `optimal_num_of_bytes` always returns a multiple of the block size, and a non-negative `i32` always fits `usize` - `from_iter_values` also panics on offset overflow - State the `is_null`/`is_valid` contract as `index >= self.len()` and mark the non-checking path as not guaranteed, so it stays fixable Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Jefffrey
reviewed
Aug 13, 2026
| { | ||
| let iter = iter.into_iter(); | ||
| let (_, data_len) = iter.size_hint(); | ||
| let data_len = data_len.expect("Iterator must be sized"); // panic if no upper bound. |
Contributor
There was a problem hiding this comment.
this is interesting; it might actually be a bug. i dont see why we should restrict to requiring an upper bound especially as its not guaranteed an iter will yield only up to upper bound
It is not enforced that an iterator implementation yields the declared number of elements. A buggy iterator may yield less than the lower bound or more than the upper bound of elements.
perhaps in a followup/separate PR we can remove this expect, to have one less panic in our codebase
Contributor
Author
There was a problem hiding this comment.
I agree - but I didn't want to change behavior in this PR
emilk
force-pushed
the
emilk/document-panics
branch
from
August 13, 2026 07:15
62b4823 to
5d1e2b1
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Which issue does this PR close?
Rationale for this change
As a user, I want to avoid panics, so panics should be documented.
In a future PR I will look at all functions with
# Panicsand make sure they have atry_variant that instead returns aResult.What changes are included in this PR?
Docs only, no code changes.
Adds
# Panicsto public functions that panic on bad arguments or bad state.Also normalizes
# Panicto# Panicsand converts loose "this will panic if ..." prose into proper sections.Are these changes tested?
No new tests; docs only.
Are there any user-facing changes?
Better docs!