openghg_inversions.borrowed#

Experimental static markers for borrowed NumPy and xarray arrays.

The borrow() helper is an identity function at runtime. Its overloads cast supported arrays to phantom subclasses whose common mutation entry points are marked with PEP 702 deprecated diagnostics. The diagnostic means “mutation is unsupported through this borrowed reference”; the underlying object is neither copied nor made read-only.

This is an experimental module without a stability guarantee. Its deliberately narrow public surface consists only of BorrowedNDArray, BorrowedDataArray, and borrow().

It deliberately provides a warning aid rather than an immutability claim. Static diagnostics can be bypassed by an untyped alias, cast, Any, widening to an ordinary ndarray or DataArray parameter, mutating helper APIs (including NumPy out=), NumPy functions whose stubs erase subclasses, or xarray escape hatches such as coords, variables, data_vars, attrs, and loc. Mutation through aliases created before borrow() is also invisible. The DataArray.data marker preserves arbitrary duck-array use through __getattr__, so slices of that data are currently typed as Any and are another false negative. NumPy view-producing APIs are only protected when their existing annotations preserve Self; not every NumPy operation does. Conversely, values or to_numpy may materialize an independent buffer from a lazy backend, but the experiment conservatively retains the borrowed marker because the backend is not represented in the DataArray type. A deep DataArray.copy() relinquishes the marker as an explicit mutation-rights escape; for lazy and duck-array backends this says nothing about independent memory, graph isolation, or computation.

PEP 702 diagnostics are checker configuration, not runtime warnings. Pyright reports explicit calls through reportDeprecated, but version 1.1.408 does not report assignment syntax that implicitly calls a deprecated __setitem__. The mutation operands therefore also use Never to make direct assignments fail in both Pyright and Mypy. Mypy recognizes the PEP 702 annotations but requires the deprecated optional error code to be enabled. The project does not yet publish a package-wide PEP 561 py.typed marker; this experimental contract is enforced in the repository checker environment until its coverage and first production uses have been evaluated.

Bases: DataArray

Type-only xarray DataArray subtype marking common mutations.

values and to_numpy return BorrowedNDArray statically. data returns a narrow duck-array facade that marks direct indexed assignment without assuming a NumPy backend.

copy(deep: Literal[True] = True, data: Any = None) → DataArray#

copy(deep: Literal[False], data: Any = None) → BorrowedDataArray

copy(deep: bool, data: Any = None) → DataArray | BorrowedDataArray

Relinquish borrowing after a deep copy; retain it if shallow.

Parameters:

deep – Whether xarray should copy the wrapped data and coordinates.
data – Optional replacement data passed through to xarray.

Returns:

An ordinary mutable DataArray static type when deep is true, otherwise another borrowed static reference.

Note: A deep copy returns an ordinary mutable static type but does not promise backend-independent memory or graph isolation for lazy or duck arrays.

property data: _BorrowedArrayData#: Return the exact borrowed NumPy, Dask, or other duck-array backend.

item(*args)#

Copy an element of an array to a standard Python scalar and return it.

Parameters:

*args (Arguments (variable number and type)) –

none: in this case, the method only works for arrays with one element (a.size == 1), which element is copied into a standard Python scalar object and returned.
int_type: this argument is interpreted as a flat index into the array, specifying which element to copy and return.
tuple of int_types: functions as does a single int_type argument, except that the argument is interpreted as an nd-index into the array.

Returns:

z – A copy of the specified element of the array as a suitable Python scalar

Return type:

Standard Python scalar object

Notes

When the data type of a is longdouble or clongdouble, item() returns a scalar array object because there is no available Python scalar that would not lose information. Void arrays return a buffer object for item(), unless fields are defined, in which case a tuple is returned.

item is very similar to a[args], except, instead of an array scalar, a standard Python scalar is returned. This can be useful for speeding up access to elements of the array and doing arithmetic on elements of the array using Python’s optimized math.

Examples

>>> import numpy as np
>>> np.random.seed(123)
>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[2, 2, 6],
       [1, 3, 6],
       [1, 0, 1]])
>>> x.item(3)
1
>>> x.item(7)
0
>>> x.item((0, 1))
2
>>> x.item((2, 2))
1

For an array with object dtype, elements are returned as-is.

>>> a = np.array([np.int64(1)], dtype=object)
>>> a.item() #return np.int64
np.int64(1)

searchsorted(v, side='left', sorter=None)#

Find indices where elements of v should be inserted in a to maintain order.

For full documentation, see numpy.searchsorted.