Add fast paths for scalar element access - #599

…xpr.new()

Applies the Vector/Matrix.get recipe from the previous commit to three more
scalar access paths, calling GrB_*_extractElement or GrB_*_setElement
directly instead of building an extract expression, an Updater, and a Scalar.

Only exact-fit Python int, float, bool and complex values take the setitem
fast path, so dtype inference and cffi coercion match the Updater path
exactly.  Masks, accum, opts, UDTs and an active Recorder all fall back to
the full path.  TransposedMatrix has no __setitem__, so the setitem fast path
cannot be reached through a transposed view.

An out-of-range index falls through from the fast lane to the expression
path, so membership raises the same IndexError, with the same message, from
either lane.  Assignment likewise raises IndexError, in the fast lane as
before.

Measured on an Apple M5 Pro with timeit, best-of-7, warm, while other test
suites were running (load average about 5), so these are indicative rather
than clean-room:

    0 in v         3.95us -> 0.40us   (9.9x)
    (0, 0) in A    5.57us -> 0.53us   (10.4x)
    v[i] = 5       3.69us -> 0.50us   (7.3x)
    A[i, j] = 5    5.12us -> 0.62us   (8.2x)

The ScalarIndexExpr.new() path gains only the skipped per-argument
marshalling in the `call` wrapper.  That difference did not clear measurement
noise on a loaded machine, so no figure is quoted for it; the change stands
on doing strictly less work, not on a measured win.

A `typ is int` branch ahead of the np.issubdtype machinery skips two type
checks costing about 125ns each for the overwhelmingly common case of a plain
Python int index.  output_type maps only the exact `int` type to `int`, so
bool and numpy integer indices keep their existing handling.  Error messages,
negative wrapping, and the returned AxisIndex are unchanged, and a plain int
is always signed, so the negative branch matches the signedinteger branch it
bypasses.

Measured on an Apple M5 Pro with timeit, min of 15 runs of 20000 calls, warm,
while other test suites were running (load average about 5.7).  Before and
after were taken back to back with the same protocol:

    v[i] construction    1.85us -> 1.50us   (-19%)
    v[i].new()           3.48us -> 3.13us   (-10%)
    A[i, j].new()        5.04us -> 4.34us   (-14%)

These are small percentages, so the measurement is worth qualifying: min and
median differed by under 2% on every case, and each saving (0.35us, 0.35us,
0.70us) is many times that spread, in the direction the diff predicts and of
the size two skipped 125ns checks predict.  List, slice, and array extracts
are unchanged, since they never took the int branch.

The fast lanes for get, __contains__, integer __setitem__, scalar extract,
and plain-int index parsing were checked only by hand-run equivalence
scripts that CI never executes.  A fast lane that drifts from the
expression path it stands in for returns a wrong answer rather than a slow
one, so the comparison belongs in the suite where a refactor will trip over
it.

211 tests compare each fast path against the expression path across the
builtin dtypes (13 of them where complex is supported), hits and misses,
negative and out-of-range indices, exception type and message parity,
coercion and overflow edges, UDT and Recorder fallback, and
TransposedMatrix.  They run in the fast tier, in well under a second.

The TransposedMatrix case for Matrix.get was absent from this file and is
added here.  It is not the only guard: test_matrix.py::test_get already
asserts A.T.get(1, 0), and deleting the mirroring swap from the get fast
path fails that test as well as this one.  What the new case adds is shape
and breadth.  It uses a non-square 3x4 matrix, where equal dimensions cannot
hide a row/column swap, and it sweeps every cell against the expression path
rather than checking two positions.

The .value, __float__, __int__ and related accessors on an index-extract
expression (v[i], A[i, j]) resolved through automethods._get_value, which
called .new() to build a GrB_Scalar (extract number one) and then read
Scalar.value off it (extract number two, plus nvals).  For the nine
read-only scalar attrs that only need the raw element, resolve with a single
extractElement straight into a cscalar through a new private
ScalarIndexExpr._extract_fast hook.

_get_value consults the hook only for _fast_scalar_attrs and only when the
expression defines it, so every other expression type is unchanged and falls
to .new() as before.  UDT values, which need numpy conversion in
Scalar.value, and active Recorders fall back to .new().

Measured on an Apple M5 Pro with timeit, min of 15 runs of 20000 calls,
warm, before and after taken back to back while other test suites were
running (load average about 5):

    v[i].value      4.72us -> 3.14us   (1.50x)
    float(v[i])     4.88us -> 3.18us   (1.53x)
    A[i, j].value   5.93us -> 4.29us   (1.38x)

v[i].new() was measured alongside as a control and did not move, which is
what this diff predicts since it does not touch that path.  .get(i), at
about 0.38us, remains the fast API; this only helps the older v[i].value and
float(v[i]) idiom, whose floor is the cost of building the v[i] expression.

The hook region sits above the autogenerate markers, so regenerating
automethods.py leaves it in place.  Private surface only (_extract_fast,
_fast_scalar_attrs).

The fast lanes for Vector/Matrix get, __contains__, and integer-key
__setitem__ accepted any object implementing __index__, while the
expression path (IndexerResolver.parse_index) accepts only exact int
and np.integer scalars.  Anything else implementing __index__, such as
a 0-d ndarray, answered on the fast lane but raised on the slow path.
Reproduced at 5581edc8 (fast vs slow), where the slow-path error is
TypeError: Invalid number of dimensions for index: 0:

  Vector.get(np.array(5))         -> 2.5   vs TypeError
  np.array(5) in v                -> True  vs TypeError
  v[np.array(5)] = 1.0            -> sets  vs TypeError
  Matrix.get(np.array(1), np.array(2))  -> 20    vs TypeError
  (np.array(1), np.array(2)) in A       -> True  vs TypeError
  A[np.array(1), np.array(2)] = 1.0     -> sets  vs TypeError

A custom class implementing __index__ diverged the same way in all six
lanes; for it the slow path raises TypeError: Invalid type for index:
...; unable to convert to list.

Replace the duck-typed __index__ probe in all six lanes with the type
check parse_index applies: exact int or np.integer (bool has its own
exact type; np.bool_ is not an np.integer).  Anything else now falls
through to the expression path and gets its canonical error.  Bounds
checks and negative wrapping are unchanged for accepted types.

The remaining fast lanes on this branch cannot see such inputs: the
parse_index int lane already dispatches on exact type, and
ScalarIndexExpr.new / _extract_fast run only on indices that
parse_index has already validated.

Tests: add a 0-d ndarray and an __index__-implementing class to the
bad-input parity cases for get, __contains__, and __setitem__ on both
Vector and Matrix (17 new cases).  With the gate reverted, exactly
these 17 fail; with it, test_fastpath_parity.py goes 230 -> 247 passed
and the pinned suite 1034 -> 1051 passed, 141 skipped.

The fast path for v[i] = x and A[i, j] = x typed a Python int by itself,
so 2**63 was INT64 and raised OverflowError, while the full assign path
now types an int beyond INT64 as the destination's dtype and stores it
into UINT64 (#591). Such an int now takes the full path, as numpy values
and Scalars do.

test_fastpath_parity.py names a pair of UDT Vectors au and bu, and
codespell reads bu as a misspelling of by, but, bug and so on.

test_record_failed_call made a Recorder (gb.Recorder() starts one) and
test_record_repr_html started one (and called start() too), and neither
stopped it, so it kept running for the rest of the pytest session. Both
are on main: test_record_failed_call since #114 (2021), and
test_record_repr_html since #263 (2022). There that only means every
later call was recorded.

Here it matters: the scalar fast paths (get, in, integer-key setitem,
v[i].new() and value reads) step aside while a Recorder runs, so every
test that ran after test_recorder.py took the full path instead. In file
order that is test_scalar.py onward; under CI's random order it can be
any test, the fast-path parity tests included, which then compared the
full path with itself.

Both tests now record inside a with block. A new autouse fixture in
conftest.py fails a test that leaves a Recorder running (other than the
session's own one under --record) and stops it, so one leak cannot
change what the tests after it test. No other test trips it.

Behavior fix. When GrB_*_extractElement_<T> failed for a reason other
than a missing value, check_status built the error from the call's first
argument, the fresh empty C-scalar output, and asking it for its C value
raised EmptyObject ("Empty C scalar is invalid when passed as value
..."), which hid GraphBLAS's error. Extracting from an object whose data
was exported with give_ownership=True did this whenever the element went
to a C scalar.

The two cases differ in age. v[0].new(is_cscalar=True), and v[0].new()
under C-scalar defaults, raised EmptyObject on main too. v[0].value
raised NullPointer on main, which read the value through a GrB_Scalar;
this PR's single-extract fast path for value reads (_extract_fast) reads
every value into a C scalar, and so made .value raise EmptyObject. That
part is a regression from this PR, fixed here before it ships.

_extract_element now names the input as the object to report against,
through an optional exc_arg on _Pointer that check_status already honors
(as for _MatrixArray), so the error is GraphBLAS's, as with a GrB_Scalar
output and as in the fast paths. A TransposedMatrix reports against its
Matrix, since there is no GrB_TransposedMatrix_error. check_status is
unchanged. The new test extracts from a given-away Matrix, its transpose
and a Vector into both kinds of Scalar, and checks the same NullPointer
text for both; it fails before this with EmptyObject, and with the
"Unable to get the error string" text if a TransposedMatrix reports
against itself.

Behavior fix, the same as the previous commit's for the other calls that
write into a C scalar. Matrix.nrows, ncols and nvals, Vector.size and
nvals, Scalar.nvals and the GrB_Scalar read in Scalar.value pass their
count or value to GraphBLAS in a C scalar, and when the call failed,
check_status asked that empty C scalar for the error text, which raised
EmptyObject ("Empty C scalar is invalid when passed as value ...") and
hid GraphBLAS's error. Each now names its own object for the error,
through _Pointer's exc_arg; check_status is unchanged. A TransposedMatrix,
which shares Matrix's nrows, ncols and nvals, names its Matrix, as in the
previous commit, since there is no GrB_TransposedMatrix_error.

main has all of these. Of them, only the Matrix and Vector ones can be
reached through a public call: an object whose data was exported with
give_ownership=True has no GraphBLAS object left, and A.nvals, A.T.nvals
or v.size on it raised EmptyObject instead of NullPointer. Nothing leaves
a Scalar without its GraphBLAS object, and Scalar.value checks for
emptiness first, which already reported the error correctly, so the read
itself cannot fail; it changes for consistency only. The tests check that
a given-away Matrix, its transpose and a Vector, and a GrB_Scalar set to
NULL the way export leaves the others, raise NullPointer with the same
text as checking the object itself; they fail before this with
EmptyObject, and A.T with the "Unable to get the error string" text if it
reports against itself.

…th does

get, in, integer-key setitem and v[i].new() call GraphBLAS directly and
check its status themselves; get and in must also tell "no value" apart
from an error. Value reads extract through the full path's C-scalar
branch instead, which reports GraphBLAS's error since "Report
GraphBLAS's error when extracting an element into a C scalar". Nothing
reached those checks: Python validates every index and value first. An
object whose data was exported with give_ownership=True is left with no
GraphBLAS object, and every call on it fails, so the parity tests now use
one to check that each fast path, and each value read, raises the same
NullPointer as its reference, for a Vector and a Matrix, and for
v[i].new() into C scalars too. A get or in that read any error as a
missing value would return the default or False instead.

(0, slice(None)) in A and ([0, 1], 2) in A extract a row or a column,
not an element, so both the full path and _contains_matrix_slow raise
the TypeError that asks for a 2-tuple of ints; no case gave one.
_IndexLike.__index__ runs only if a fast lane accepts the object, which
the tests exist to catch, and __repr__ only in a failure message, so
both are marked "only on failure".

…a value read

A value read of v[i] (e.value, float(e), ...) extracts into a C scalar,
and the expression caches what it reads through. Its other attributes
then saw that C scalar: e.gb_obj was an int8_t * where a GrB_Scalar *
was, so a C call taking a GrB_Scalar refused it with TypeError, while
e.is_cscalar still said False. Main and the Recorder path gave a
GrB_Scalar (r599 R1).

Now an attribute other than a value read converts the cached C scalar
once into the kind of Scalar the expression reports, holding the same
value, so a value read is still a snapshot, as on main.