低级辅助函数#

C 模式实用程序#

Arrow 和 nanoarrow C 结构包装器

这些类及其构造函数包装了 Arrow C 数据/流接口结构(即 ArrowArrayArrowSchemaArrowArrayStream)以及帮助反序列化其内容的 nanoarrow C 库结构(即 ArrowSchemaViewArrowArrayView)。这些包装器目前在 Cython 中实现,其作用范围仅限于生命周期管理和作为 Python 对象的成员访问。

allocate_c_schema() CSchema#

分配一个未初始化的 ArrowSchema 包装器

示例#

>>> import pyarrow as pa
>>> from nanoarrow.c_schema import allocate_c_schema
>>> schema = allocate_c_schema()
>>> pa.int32()._export_to_c(schema._addr())
c_schema(obj=None) CSchema#

ArrowSchema 包装器

CSchema 类提供了一个 Python 友好的接口来访问 Arrow C 数据接口中定义的 ArrowSchema 的字段。这些对象是使用 nanoarrow.c_schema() 创建的,它根据 Arrow PyCapsule 接口接受任何模式或类似数据类型的对象。

此 Python 包装器允许访问模式结构成员,但不会自动反序列化其内容:使用 c_schema_view() 来验证并将内容反序列化为更容易检查的对象。

请注意,CSchema 对象由 .child() 返回,并对原始 ArrowSchema 保持强引用,以避免在检查导入的结构时进行复制。

示例#

>>> import pyarrow as pa
>>> import nanoarrow as na
>>> schema = na.c_schema(pa.int32())
>>> schema.is_valid()
True
>>> schema.format
'i'
>>> schema.name
''
c_schema_view(obj) CSchemaView#

ArrowSchemaView 包装器

ArrowSchemaView 是 nanoarrow C 库结构,它有助于访问 ArrowSchema 的反序列化内容(例如,参数化类型的参数值)。此包装器将此功能扩展到 Python。

示例#

>>> import pyarrow as pa
>>> import nanoarrow as na
>>> from nanoarrow.c_schema import c_schema_view
>>> schema = na.c_schema(pa.decimal128(10, 3))
>>> schema_view = c_schema_view(schema)
>>> schema_view.type
'decimal128'
>>> schema_view.decimal_bitwidth
128
>>> schema_view.decimal_precision
10
>>> schema_view.decimal_scale
3

C 数组实用程序#

class ArrayBuilder(schema)#

用于从各种类型的输入构建 CArray 的内部实用程序

此类及其子类旨在帮助将实际构建 CArray 的代码与选择用于构建的策略的代码分开。

classmethod infer_schema(obj) Tuple[CSchema, Any]#

从目标对象推断 Arrow 数据类型

将类型作为 CSchema 返回,并返回一个对象,该对象可以在 append() 中以相同的方式使用,以防它必须修改以推断其类型(例如,对于可迭代对象,需要从原始迭代器中使用第一个元素)。

class ArrayFromIterableBuilder(schema)#

从标量对象的迭代器构建 CArray

此构建器使用一些启发式方法将可迭代对象转换为 CArray,以选择最快的可用方法转换为特定类型的数组。简而言之,这些方法是 (1) C 库中的 ArrowArrayAppendXXX() 函数(字符串、二进制)、(2) array.array()(整数/浮点数,除了 float16)、(3) CBufferBuilder.write_elements()(所有其他)。

classmethod infer_schema(obj) Tuple[CBuffer, CSchema]#

从目标对象推断 Arrow 数据类型

将类型作为 CSchema 返回,并返回一个对象,该对象可以在 append() 中以相同的方式使用,以防它必须修改以推断其类型(例如,对于可迭代对象,需要从原始迭代器中使用第一个元素)。

class ArrayFromPyBufferBuilder(schema)#

从 Python 缓冲区构建 CArray

此构建器将 Python 缓冲区(例如,NumPy 数组、字节、array.array)转换为 CArray(无需复制缓冲区的内容)。

classmethod infer_schema(obj) Tuple[CBuffer, CSchema]#

从目标对象推断 Arrow 数据类型

将类型作为 CSchema 返回,并返回一个对象,该对象可以在 append() 中以相同的方式使用,以防它必须修改以推断其类型(例如,对于可迭代对象,需要从原始迭代器中使用第一个元素)。

class EmptyArrayBuilder(schema)#

构建任何类型的空 CArray

此构建器接受任何空输入并生成有效的长度为零的数组作为输出。

classmethod infer_schema(obj) Tuple[Any, CSchema]#

从目标对象推断 Arrow 数据类型

将类型作为 CSchema 返回,并返回一个对象,该对象可以在 append() 中以相同的方式使用,以防它必须修改以推断其类型(例如,对于可迭代对象,需要从原始迭代器中使用第一个元素)。

allocate_c_array(schema=None) CArray#

分配一个未初始化的 ArrowArray

示例#

>>> import pyarrow as pa
>>> from nanoarrow.c_array import allocate_c_array
>>> array = allocate_c_array()
>>> pa.array([1, 2, 3])._export_to_c(array._addr())
c_array(obj, schema=None) CArray#

ArrowArray 包装器

此类提供了一个面向用户的接口来访问 Arrow C 数据接口中定义的 ArrowArray 的字段,并保存对可选的 CSchema 的引用,该引用可用于安全地反序列化内容。

这些对象是使用 c_array() 创建的,它根据 Arrow PyCapsule 接口、Python 缓冲区协议或 Python 对象的可迭代对象接受任何类似数组的对象。

此 Python 包装器允许访问数组字段,但不会自动反序列化其内容:使用 c_array_view() 来验证并将内容反序列化为更容易检查的对象。

请注意,CArray 对象由 .child() 返回,并对原始 ArrowArray 保持强引用,以避免在检查导入的结构时进行复制。

参数#

obj类似数组

支持 Arrow PyCapsule 接口、Python 缓冲区协议或 Python 对象的可迭代对象的任何对象。

schema类似模式或 None

c_schema() 规范化的类似模式的对象或 None。此值将用于从 obj 请求数据类型;但是,转换是尽力而为的(即,返回的 CArray 的数据类型可能与 schema 不同)。

示例#

>>> import nanoarrow as na
>>> # Create from iterable
>>> array = na.c_array([1, 2, 3], na.int32())
>>> # Create from Python buffer (e.g., numpy array)
>>> import numpy as np
>>> array = na.c_array(np.array([1, 2, 3]))
>>> # Create from Arrow PyCapsule (e.g., pyarrow array)
>>> import pyarrow as pa
>>> array = na.c_array(pa.array([1, 2, 3]))
>>> # Access array fields
>>> array.length
3
>>> array.null_count
0
c_array_from_buffers(schema, length: int, buffers: Iterable[Any], null_count: int = -1, offset: int = 0, children: Iterable[Any] = (), validation_level: Literal[None, 'full', 'default', 'minimal', 'none'] = None, move: bool = False, device: Device | None = None) CArray#

从组件创建 ArrowArray 包装器

给定一个模式,以缓冲区方式构建一个 ArrowArray。这允许组装几乎任何数组;但是,需要了解 Arrow 列式规范。此函数将尽最大努力根据 validation_level 验证缓冲区的大小和内容;但是,目前无法以这种方式构造所有类型的数组。

参数#

schema类似模式

c_schema() 规范化的所需数组的数据类型。

lengthint

输出数组的长度。

buffers缓冲区或 None 的可迭代对象

c_buffer() 规范化的缓冲区可迭代对象。接受任何支持 Python 缓冲区协议的对象。不检查缓冲区数据类型。缓冲区值为 None 将跳过设置缓冲区(即,该缓冲区的长度将为零,其指针将为 NULL)。

null_countint,可选

空值的数量,如果事先知道。如果为 -1(默认值),则将根据有效性位图计算空值计数。如果将有效性位图设置为 None,则计算出的空值计数将为零。

offsetint,可选

数组开头的逻辑偏移量。

children数组的迭代对象

用于设置数组子字段的可迭代数组。可以包含 c_array() 接受的任何对象。必须包含 schema 指定的所需子项的确切数量。

validation_level:None 或 str,可选

“none”(不检查),“minimal”(检查不需要取消引用缓冲区内容的缓冲区大小),“default”(检查所有缓冲区大小)或“full”(检查所有缓冲区大小和所有缓冲区内容)之一。默认值 None 将在可能的情况下在“default”级别进行验证。

movebool,可选

使用 True 将任何输入缓冲区或子项的所有权转移到输出数组。

deviceDevice,可选

构造此数组时要使用的显式设备。如果指定,此函数将构造一个 CDeviceArray;如果未指定,此函数将在 CPU 设备上构造一个 CArray

示例#

>>> import nanoarrow as na
>>> c_array = na.c_array_from_buffers(na.uint8(), 5, [None, b"12345"])
>>> na.Array(c_array).inspect()
<ArrowArray uint8>
- length: 5
- offset: 0
- null_count: 0
- buffers[2]:
  - validity <bool[0 b] >
  - data <uint8[5 b] 49 50 51 52 53>
- dictionary: NULL
- children[0]:
c_array_view(obj, schema=None) CArrayView#

ArrowArrayView 包装器

ArrowArrayView 是 nanoarrow C 库结构,提供对缓冲区地址、缓冲区大小和缓冲区数据类型的结构化访问。缓冲区数据通常从 ArrowArray 传播,但也可以从其他类型的对象(例如,序列化 IPC)传播。此视图的偏移量和长度与其父级无关(即,此对象也可以表示其父级的切片)。

示例#

>>> import pyarrow as pa
>>> import numpy as np
>>> import nanoarrow as na
>>> from nanoarrow.c_array import c_array_view
>>>
>>> array = na.c_array(pa.array(["one", "two", "three", None]))
>>> array_view = c_array_view(array)
>>> np.array(array_view.buffer(1))
array([ 0,  3,  6, 11, 11], dtype=int32)
>>> np.array(array_view.buffer(2))
array([b'o', b'n', b'e', b't', b'w', b'o', b't', b'h', b'r', b'e', b'e'],
      dtype='|S1')

C 数组流实用程序#

allocate_c_array_stream() CArrayStream#

分配一个未初始化的 ArrowArrayStream 包装器

示例#

>>> import pyarrow as pa
>>> from nanoarrow.c_array_stream import allocate_c_array_stream
>>> pa_column = pa.array([1, 2, 3], pa.int32())
>>> pa_batch = pa.record_batch([pa_column], names=["col1"])
>>> pa_reader = pa.RecordBatchReader.from_batches(pa_batch.schema, [pa_batch])
>>> array_stream = allocate_c_array_stream()
>>> pa_reader._export_to_c(array_stream._addr())
c_array_stream(obj=None, schema=None) CArrayStream#

ArrowArrayStream 包装器

此类提供了一个面向用户的接口来访问 Arrow C 流接口中定义的 ArrowArrayStream 的字段。这些对象通常使用 nanoarrow.c_array_stream() 创建。

示例#

>>> import pyarrow as pa
>>> import nanoarrow as na
>>> pa_column = pa.array([1, 2, 3], pa.int32())
>>> pa_batch = pa.record_batch([pa_column], names=["col1"])
>>> pa_reader = pa.RecordBatchReader.from_batches(pa_batch.schema, [pa_batch])
>>> array_stream = na.c_array_stream(pa_reader)
>>> array_stream.get_schema()
<nanoarrow.c_schema.CSchema struct>
- format: '+s'
- name: ''
- flags: 0
- metadata: NULL
- dictionary: NULL
- children[1]:
  'col1': <nanoarrow.c_schema.CSchema int32>
    - format: 'i'
    - name: 'col1'
    - flags: 2
    - metadata: NULL
    - dictionary: NULL
    - children[0]:
>>> array_stream.get_next().length
3
>>> array_stream.get_next() is None
Traceback (most recent call last):
  ...
StopIteration