Build a NumPy array from the passed buffer. Parameters ---------- buffer : Buffer Buffer to build a NumPy array from. dtype : tuple Data type of the buffer conforming protocol dtypes format. offset : int, default: 0 Number of elements to offset from
(
buffer: Buffer,
dtype: tuple[DtypeKind, int, str, str],
*,
length: int,
offset: int = 0,
)
| 464 | |
| 465 | |
| 466 | def buffer_to_ndarray( |
| 467 | buffer: Buffer, |
| 468 | dtype: tuple[DtypeKind, int, str, str], |
| 469 | *, |
| 470 | length: int, |
| 471 | offset: int = 0, |
| 472 | ) -> np.ndarray: |
| 473 | """ |
| 474 | Build a NumPy array from the passed buffer. |
| 475 | |
| 476 | Parameters |
| 477 | ---------- |
| 478 | buffer : Buffer |
| 479 | Buffer to build a NumPy array from. |
| 480 | dtype : tuple |
| 481 | Data type of the buffer conforming protocol dtypes format. |
| 482 | offset : int, default: 0 |
| 483 | Number of elements to offset from the start of the buffer. |
| 484 | length : int, optional |
| 485 | If the buffer is a bit-mask, specifies a number of bits to read |
| 486 | from the buffer. Has no effect otherwise. |
| 487 | |
| 488 | Returns |
| 489 | ------- |
| 490 | np.ndarray |
| 491 | |
| 492 | Notes |
| 493 | ----- |
| 494 | The returned array doesn't own the memory. The caller of this function is |
| 495 | responsible for keeping the memory owner object alive as long as |
| 496 | the returned NumPy array is being used. |
| 497 | """ |
| 498 | kind, bit_width, _, _ = dtype |
| 499 | |
| 500 | column_dtype = _NP_DTYPES.get(kind, {}).get(bit_width, None) |
| 501 | if column_dtype is None: |
| 502 | raise NotImplementedError(f"Conversion for {dtype} is not yet supported.") |
| 503 | |
| 504 | # TODO: No DLPack yet, so need to construct a new ndarray from the data pointer |
| 505 | # and size in the buffer plus the dtype on the column. Use DLPack as NumPy supports |
| 506 | # it since https://github.com/numpy/numpy/pull/19083 |
| 507 | ctypes_type = np.ctypeslib.as_ctypes_type(column_dtype) |
| 508 | |
| 509 | if bit_width == 1: |
| 510 | assert length is not None, "`length` must be specified for a bit-mask buffer." |
| 511 | pa = import_optional_dependency("pyarrow") |
| 512 | arr = pa.BooleanArray.from_buffers( |
| 513 | pa.bool_(), |
| 514 | length, |
| 515 | [None, pa.foreign_buffer(buffer.ptr, length)], |
| 516 | offset=offset, |
| 517 | ) |
| 518 | return np.asarray(arr) |
| 519 | else: |
| 520 | data_pointer = ctypes.cast( |
| 521 | buffer.ptr + (offset * bit_width // 8), ctypes.POINTER(ctypes_type) |
| 522 | ) |
| 523 | if length > 0: |
no test coverage detected