feat: Implement item() for Series and Index #1792
Open
Conversation
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
This commit introduces the `item()` method to both `Series` and `Index` classes. The `item()` method allows you to extract the single value from a Series or Index. It calls `peek(2)` internally and raises a `ValueError` if the Series or Index does not contain exactly one element. This behavior is consistent with pandas. Unit tests have been added to verify the functionality for: - Single-item Series/Index - Multi-item Series/Index (ValueError expected) - Empty Series/Index (ValueError expected)
product-auto-label
bot
added
the
api: bigquery
tswast
commented
Jun 4, 2025
tswast
commented
Jun 4, 2025
This commit moves the docstrings for the `item()` method in `Series` and `Index` to their respective files in the `third_party/bigframes_vendored/pandas/core/` directory. The docstrings have been updated to match the pandas docstrings as closely as possible, while adhering to the existing style in the BigQuery DataFrames repository. This ensures that the BigQuery DataFrames API documentation remains consistent with pandas where applicable.
tswast
commented
Jun 4, 2025
tswast
commented
Jun 4, 2025
**Test: Update item() tests to match pandas behavior** This commit updates the tests for `Series.item()` and `Index.item()` to align more closely with pandas. The changes include: - Comparing the return value of `bigframes_series.item()` and `bigframes_index.item()` with their pandas counterparts. - Asserting that the ValueError messages for multi-item and empty Series/Index cases are identical to those raised by pandas. The expected message is "can only convert an array of size 1 to a Python scalar".
This commit modifies the implementation of `Series.item()` and `Index.item()`
to delegate the single-item check and ValueError raising to pandas.
Previously, `item()` used `peek(2)` and manually checked the length.
The new implementation changes:
- `Series.item()` to `self.peek(1).item()`
- `Index.item()` to `self.to_series().peek(1).item()`
This ensures that the ValueError message ("can only convert an array of size 1 to a Python scalar")
is identical to the one produced by pandas when the Series/Index does not
contain exactly one element.
Existing tests were verified to still pass and accurately cover these
conditions by comparing against `pandas.Series.item()` and `pandas.Index.item()`.
tswast
commented
Jun 6, 2025
This commit incorporates several fixes and improvements based on feedback:
1. **Docstring Style**:
* "Examples:" headings in `Series.item()` and `Index.item()`
docstrings (in `third_party/`) are now bold (`**Examples:**`).
2. **Implementation of `item()`**:
* `Series.item()` now uses `self.peek(2)` and then calls `.item()` on
the peeked pandas Series if length is 1, otherwise raises
`ValueError("can only convert an array of size 1 to a Python scalar")`.
* `Index.item()` now uses `self.to_series().peek(2)` and then calls
`.item()` on the peeked pandas Series if length is 1, otherwise
raises the same ValueError.
This change was made to allow tests to fail correctly when there is
more than 1 item, rather than relying on pandas' `peek(1).item()`
which would fetch only one item and not detect the multi-item error.
3. **Test Updates**:
* Tests for `Series.item()` and `Index.item()` now capture the
precise error message from the corresponding pandas method when
testing error conditions (multiple items, empty).
* The tests now assert that the BigQuery DataFrames methods raise
a `ValueError` with a message identical to the one from pandas.
4. **Doctest Fix**:
* The doctest for `Series.item()` in
`third_party/bigframes_vendored/pandas/core/series.py` has been
updated to expect `np.int64(1)` to match pandas behavior.
`import numpy as np` was added to the doctest.
5. **Mypy Fix**:
* A type annotation (`pd_idx_empty: pd.Index = ...`) was added in
`tests/system/small/test_index.py` to resolve a `var-annotated`
mypy error.
|
Test failure for test_read_gbq_with_configuration appears to be a flake. |
Genesis929
approved these changes
Jun 6, 2025
# for free
to join this conversation on GitHub.
Already have an account?
# to comment
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.
This commit introduces the
item()method to bothSeriesandIndexclasses.The
item()method allows you to extract the single value from a Series or Index. It callspeek(2)internally and raises aValueErrorif the Series or Index does not contain exactly one element. This behavior is consistent with pandas.Unit tests have been added to verify the functionality for:
Thank you for opening a Pull Request! Before submitting your PR, there are a few things you can do to make sure it goes smoothly:
Fixes internal issue b/422275127 🦕