低级辅助函数#

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 数据类型

class ArrayFromPyBufferBuilder(schema)#

从 Python 缓冲区构建 CArray

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

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

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

class EmptyArrayBuilder(schema)#

构建任何类型的空 CArray

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

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

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

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