RFC: `item()` to return scalar for arrays with exactly 1 element.

Open

#815 opened on Jun 20, 2024 8 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty: 4/5
Estimated time: 3-5 days
Newbie friendliness: 35/100

Issue type: Feature
Clarity: Mostly clear
Activity status: Stale
Tech stack: numpy, pandas, python, pytorch
Domain: api

Research direction

Start by reading the array API standard's current item() definition and comparing the linked NumPy, PyTorch, pandas, Polars, and xarray behavior. Use the demo pytest cases in the issue to verify empty and multi-element arrays raise ValueError and one-element arrays return a scalar; the RFC must reach an accepted standard decision before implementation can be considered done.

Written by the indexing model from the issue text.

Description

API extension Needs Discussion RFC

def item(self) -> Scalar:
     """If array contains exactly one element, retun it as a scalar, else raises ValueError."""

Examples:

Demo:

import pytest
import xarray as xr
import pandas as pd
import polars as pl
import numpy as np

@pytest.mark.parametrize("data", [[], [1, 2, 3]])
@pytest.mark.parametrize(
    "array_type", [torch.tensor, np.array, pd.Series, pd.Index, pl.Series, xr.DataArray]
)
def test_item_valueerror(data, array_type):
    array = array_type(data)
    with pytest.raises(ValueError):
        array.item()


@pytest.mark.parametrize(
    "array_type", [torch.tensor, np.array, pd.Series, pd.Index, pl.Series, xr.DataArray]
)
def test_item(array_type):
    array = array_type([1])
    array.item()

Currently, only torch fails, because it raises RuntimeError instead of ValueError.

Dominant language: Python
Stars: 281
Forks: 52
PR merge metrics: No merged PRs in 30d

Contributor guide

Open the contributing guide

First steps

Read the whole issue, then the project's contributing guide.
Comment on the issue to say you are picking it up — it saves two people doing the same work.
Fork the repository and make your change on a branch.
Open a pull request that references the issue number.

Similar issues

Add: hunch Open

Difficulty 2/5 1-3 hours Newbie friendliness 74/100

AbdelStark/awesome-typesafe#104 · Opened Sep 22, 2026
Add URL dialog: OK button should be labelled Add, and should validate required fields Open

enhancement

Difficulty 2/5 1-3 hours Newbie friendliness 72/100

translate/virtaal#3687 · Opened Sep 22, 2026
I15-1: Switch to use new fast shutter PV Open

Difficulty 2/5 1-3 hours Newbie friendliness 68/100

DiamondLightSource/dodal#2211 · Opened Sep 22, 2026
TEST Add sparse dataset inclusion coverage for row ID and ignore attributes. Open

Difficulty 2/5 1-3 hours Newbie friendliness 88/100

openml/openml-python#1749 · Opened Sep 22, 2026
pii_scan gate does not block on its two critical rules: an SSN or credit-card number passes Open

Difficulty 2/5 1-3 hours Newbie friendliness 88/100

sipyourdrink-ltd/bernstein#6191 · Opened Sep 22, 2026

More Python issues