低级辅助函数#
C 模式实用程序#
Arrow 和 nanoarrow C 结构包装器
这些类及其构造函数包装了 Arrow C 数据/流接口结构(即 ArrowArray
、ArrowSchema
和 ArrowArrayStream
)以及帮助反序列化其内容的 nanoarrow C 库结构(即 ArrowSchemaView
和 ArrowArrayView
)。这些包装器目前在 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