低级助手#

C Schema 工具#

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 Data 接口中定义的 ArrowSchema 字段。这些对象使用 nanoarrow.c_schema() 创建，该函数根据 Arrow PyCapsule 接口接受任何 schema 或数据类型类似的对象。

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

请注意，由 .child() 返回的 CSchema 对象持有对原始 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 Array 工具#

class ArrayBuilder(schema)#

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

此类及其子类旨在帮助将实际构建 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 Data 接口中定义的 ArrowArray 字段，并持有一个对 CSchema 的可选引用，该引用可用于安全地反序列化内容。

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

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

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

参数#

objarray-like: 支持 Arrow PyCapsule 接口、Python 缓冲区协议或 Python 对象可迭代对象的对象。
schemaschema-like or None: 由 c_schema() 清理的 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 包装器

给定一个 schema，按缓冲区构建一个 ArrowArray。这允许组装几乎任何数组；但是，需要一些关于 Arrow 列式规范的知识。此函数将尽力根据 validation_level 验证缓冲区的大小和内容；但是，目前并非所有类型的数组都能以这种方式构建时进行验证。

参数#

schemaschema-like: 由 c_schema() 清理的所需数组的数据类型。
lengthint: 输出数组的长度。
buffersIterable of buffer-like or None: 由 c_buffer() 清理的缓冲区可迭代对象。接受任何支持 Python 缓冲区协议的对象。不检查缓冲区数据类型。缓冲区值为 None 将跳过设置缓冲区（即，该缓冲区长度为零，其指针为 NULL）。
null_countint, optional: 空值数量，如果提前已知。如果为 -1（默认），则将根据有效位图计算空值数量。如果有效位图设置为 None，则计算出的空值数量将为零。
offsetint, optional: 从数组开头开始的逻辑偏移量。
childrenIterable of array-like: 用于设置数组子字段的数组可迭代对象。可以包含 c_array() 接受的任何对象。必须包含 schema 指定的所需子级的确切数量。
validation_level: None or str, optional: “none”（不检查）、“minimal”（检查不需要解除引用缓冲区内容的缓冲区大小）、“default”（检查所有缓冲区大小）或“full”（检查所有缓冲区大小和所有缓冲区内容）之一。默认值 None 将在可能的情况下在“default”级别进行验证。
movebool, optional: 使用 True 将任何输入缓冲区或子级的所有权转移到输出数组。
deviceDevice, optional: 构造此数组时要使用的显式设备。如果指定，此函数将构造一个 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 ArrayStream 工具#

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 Stream 接口中定义的 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

低级助手#

C Schema 工具#

示例#

示例#

示例#

C Array 工具#

示例#

参数#

示例#

参数#

示例#

示例#

C ArrayStream 工具#

示例#

示例#

本页