Add helpers to array that return the size and strides as a std::span

[dbs4261]

Description

Add convenience functions to pybind11::array to return the shape and strides as a std::span. These functions are hidden with macros unless PYBIND11_CPP20 is defined and the include has been found. By returning an iterable container, a new array could be created more simply with array(other.dtype(), other.size_span(), other.strides_span()).

Suggested changelog entry:

Add convenience functions to pybind11::array to return the shape and strides as a std::span.

[rwgk]

My prompt for Cursor was merely:

Unit tests for the two new member functions are missing, but appart from that the PR seems fine. However, I'm not familiar with std::span. Could you please review carefully?

Next thing I know, it had generated the missing unit tests.

This is the full response:

  Implementation review

  The implementation looks correct:
  1. Correct span usage:
    • Uses std::span<const ssize_t, std::dynamic_extent> (const, dynamic extent)
    • Constructs spans with std::span(pointer, count) (valid constructor)
    • Cast from ssize_t to std::size_t is safe since ndim() is non-negative for valid arrays
  2. Proper feature gating:
    • Guarded with #ifdef PYBIND11_HAS_SPAN
    • PYBIND11_HAS_SPAN is defined only when C++20 is available and <span> is found
  3. API consistency:
    • Mirrors shape() and strides() naming
    • Returns const spans, matching the const pointer returns
  4. Use case:
    • Spans can be passed to array constructors via any_container<ssize_t>, which accepts containers with iterators


  Unit tests added

  Added tests covering:
  • 0-dimensional arrays (scalars)
  • 1D, 2D, and 3D arrays
  • Comparison with regular shape()/strides() methods
  • Using spans to construct new arrays (main use case from PR description)
  • Tests are conditionally compiled only when PYBIND11_HAS_SPAN is defined


  Minor observations

  • The cast from ssize_t to std::size_t is safe but could theoretically wrap if ndim() were negative; that would indicate a corrupted array, which is outside this function's scope.

  The PR is ready to merge once the tests pass. The implementation follows pybind11 patterns and correctly uses std::span.

[Skylion007]

This isn't correct. Use the cpp feature label for this instead: https://en.cppreference.com/w/cpp/experimental/feature_test.html#cpp_lib_span this resolves the ambiguity of some pre CPP20 happen to having a global header called span somewhere

[rwgk]

@Skylion007 Does this look correct? — e9de405

[rwgk]

For easy reference, these were the failures before pushing more commits:

CI / 🐍 (windows-latest, 3.14, -DCMAKE_CXX_STANDARD=20) / 🧪 (pull_request) Failing after 4m

CI / 🐍 (windows-latest, 3.14t, -DCMAKE_CXX_STANDARD=23) / 🧪 (pull_request) Failing after 5m

CI / 🐍 3 • GCC 10 • C++20 • x64 (pull_request) Failing after 26s

CI / 🐍 3.10 • MSVC 2022 • x86 -DCMAKE_CXX_STANDARD=20 (pull_request) Failing after 3m

CI / 🐍 3.13 • windows-11-arm • clang-msvc (pull_request) Failing after 3m

CI / windows-11-arm • clang-msys2 (pull_request) Failing after 4m

[rwgk]

@seberg Could you please help reviewing this (very small) PR? It looks good to me, but it'd be great to get someone more closely associated with the numpy community to take a look, too.

(Please ignore the Manylinux 3.14t CI failure. It's definitely unrelated to this PR.)

[seberg]

Looks good to me. Seems like the only question would be if there is a nicer naming/API pattern. But I can't think of a nicer alternative.

(Not sure I quite follow the motivation, for creating a new array, I would different approaches are nicer, e.g. having an empty_like())

[dbs4261]

The actual motivation was to use them with ranges but it was easier to just describe the constructor. I would also like to see empty_like and others like it.