Apache Arrow PyArrowPython API 官方文档全解——从安装部署到数据模型与扩展接口【免费下载链接】arrowApache Arrow is the universal columnar format and multi-language toolbox for fast data interchange and in-memory analytics项目地址: https://gitcode.com/GitHub_Trending/arrow3/arrow本文基于 Apache Arrow 仓库中 Python 语言文档的入口页 docs/source/python/index.rst 展开系统梳理 PyArrowApache Arrow 的 Python 绑定的能力版图如何在 Windows / macOS / Linux 上正确安装、conda-forge 三个变体包的差异、核心的列式数据模型Array / Table / RecordBatch / Schema / DataType以及 IPC、Parquet、Dataset、Flight 等 20 余个文档主题各自对应哪些源码模块。读完后你可以独立完成 PyArrow 的选型安装并知道每个功能主题在仓库文档与源码中的具体位置。PyArrow 是什么基于 C 实现的 Python 绑定官方文档对 Python 部分的一句话定位是PyArrow - Apache Apache Arrow Python bindings即这是 Apache Arrow Python API 的文档。文档明确了三个关键事实Apache Arrow 本身是通用列式格式与多语言工具箱用于快速的数据交换和内存分析它包含一组让数据系统高效地存储、处理和移动数据的技术PyArrow 与 NumPy、pandas 及 Python 内置对象具有一等公民级别first-class的集成PyArrow 构建在 Arrow 的 C 实现之上——它不是纯 Python 重写而是 C 核心之上的绑定层。从源码结构可以印证第 3 点。python/pyarrow 目录下的模块呈现出清晰的Python 薄层 Cython/C 内核分层纯 Python 层types.py、compute.py、csv.py、json.py、feather.py、orc.py、dataset.py、ipc.py、flight.py、fs.py、acero.py、substrait.py等负责 API 组织、文档字符串与参数校验Cython 绑定层lib.pyx核心数据结构、_compute.pyx、_parquet.pyx、_dataset.pyx、_fs.pyx、_flight.pyx、_orc.pyx、_feather.pyx等.pyx文件直接封装 C Arrow 库C 源码层位于 python/pyarrow/src是 PyArrow 与 Arrow C 实现的真正衔接点。此外python/pyarrow/py.typed 的存在表明 PyArrow 提供了 PEP 561 类型标注支持可配合静态类型检查使用。文档地图22 个主题模块一览入口页通过 Sphinxtoctree列出了 Python 文档的完整目录这就是理解 PyArrow 能力版图最好的索引。按主题归类如下每节文档在仓库中的实际位置主题分组文档章节文档文件入门与安装安装Install、快速上手Getting Startedinstall.rst、getstarted.rst核心数据模型数据类型与内存数据模型、内存与 IO、计算Compute、时间戳data.rst、memory.rst、compute.rst、timestamps.rstIPC 与文件系统IPC 格式、文件系统ipc.rst、filesystems.rst数值生态集成NumPy、pandasnumpy.rst、pandas.rst文件格式Parquet、Dataset、CSV、ORC、Feather、JSONparquet/index、dataset.rst、csv.rst、orc.rst、feather.rst、json.rst网络与分布式Flightflight.rst扩展与互操作扩展类型、Table Interchange Protocol、DLPack、集成示例extending_types.rst、interchange_protocol.rst、dlpack.rst、integration.rst参考环境变量、API 参考、参与贡献env_vars.rst、api.rst、getting_involved.rst入口页末尾还列出了外部 Python Cookbook 作为示例参考与文档正文互补。值得注意的是这个目录与源码模块几乎一一对应形成文档 → 源码的可追溯链路例如parquet文档 → python/pyarrow/parquet 目录与 python/pyarrow/_parquet.pyxdataset文档 → python/pyarrow/dataset.py 与 python/pyarrow/_dataset.pyxdlpack文档 → python/pyarrow/_dlpack.pxiacero/ Substrait 相关 → python/pyarrow/acero.py、python/pyarrow/substrait.py。安装 PyArrow系统要求、包管理器与可选依赖install.rst 给出了完整的安装指引以下为核心内容。系统与 Python 版本兼容性系统兼容性PyArrow 定期在 Windows、macOS 和各类 Linux 发行版上构建和测试官方强烈建议使用64 位系统Python 兼容性当前版本兼容Python 3.11、3.12、3.13 和 3.14。Conda 与 Pip 两种安装方式使用 Condaconda-forge 渠道安装最新版conda install -c conda-forge pyarrow使用 Pip覆盖 Windows、Linux、macOSpip install pyarrow文档中附带的两个重要注意事项Windows若 pip 安装的 wheel 出现导入问题可能需要安装最新版 Visual C RedistributableLinux需要pip 19.0才能正确识别预编译二进制包。可选依赖依赖最低版本用途NumPy2.0 或更高与 NumPy 数组零拷贝互转pandas2.2.2 或更高与 DataFrame 互转cffi可选CFFI 绑定接口对应源码中的 python/pyarrow/cffi.py此外 PyArrow 还兼容fsspec文件系统抽象以及pytz / dateutil / tzdata时区支持。Windows 上的 tzdata 特别说明在 Linux 和 macOS 上Arrow 使用操作系统提供的时区数据库在 Windows 上若使用 MSVC 或较新 MinGW GCC13构建覆盖了大多数预编译包则使用 Windows 时区数据库无需额外配置。但当 PyArrow 以 Clang/libc 方式在 Windows 上构建时需要用户提供 IANA 时区数据库默认检测路径为%USERPROFILE%\Downloads\tzdata。文档还给出了一个常见排障方案pip 安装后向 ORC 文件写入 datetime 数据出错时可pip install tzdata并将环境变量TZDIR指向tzdata包目录可用import tzdata; print(tzdata.__file__)定位。conda-forge 三变体包pyarrow-core / pyarrow / pyarrow-all这是安装文档中信息密度最高的部分。与 PyPI 只提供单一pyarrow包不同conda-forge 将 PyArrow 拆分为三个功能层级递增的包目的是让大多数用户获得最小安装体积同时保留按需扩展能力pyarrow-core最小内核核心数据data、计算pyarrow.compute、IOio、IPCpyarrow.ipc、本地文件系统pyarrow.fs以及文件格式Feather、JSON、CSV、ORC不含 Parquetpyarrow在 core 之上额外提供Aceropyarrow.acero、Datasetpyarrow.dataset、Parquetpyarrow.parquet、Substraitpyarrow.substraitpyarrow-all完整包即历史上 conda-forge 的pyarrow再额外提供Flight 与 Flight SQLpyarrow.flight、Gandivapyarrow.gandiva。各组件与包的对应关系表组件对应 C 库pyarrow-corepyarrowpyarrow-allCorepyarrow-core✓✓✓Parquetlibparquet✓✓Datasetlibarrow-dataset✓✓Acerolibarrow-acero✓✓Substraitlibarrow-substrait✓✓Flightlibarrow-flight✓Flight SQLlibarrow-flight-sqlGandivalibarrow-gandiva✓自定义组合安装如果清楚自己需要哪些组件可以只装最小内核再按需叠加 C 库组件例如# 最小内核 Parquet 读写支持 conda install -c conda-forge pyarrow-core libparquet # 标准 pyarrow Flight RPC 支持 conda install -c conda-forge pyarrow libarrow-flight文档还注明未来计划把云文件系统S3、GCS 等移入pyarrow包但本地文件系统localfs将保留在pyarrow-core中——选型时可以把这一点纳入长期规划。核心数据模型Array 到 Table 的五层结构getstarted.rst 与 data.rst 共同定义了 PyArrow 的内存数据模型这是整套 Python API 的骨架pyarrow.DataType类型元数据描述数组类型并决定值如何被解释。Arrow 的类型分为四大类——定长基础类型数值、布尔、日期时间、定长二进制、Decimal 等、变长基础类型binary、string、嵌套类型list、map、struct、union以及字典类型编码的类别型。每种类型在 Python 中都有对应的工厂函数来创建类型对象pyarrow.Schema模式一组命名类型的集合即表格对象中各列的类型描述pyarrow.Array数组同构数据的集合是原子的、连续的列式数据结构由 Arrow Buffer 对象组合而成pyarrow.RecordBatch记录批一个具有特定 Schema 的 Array 集合pyarrow.Table表逻辑表结构每列由一个或多个同类型的pyarrow.Array组成对应源码 python/pyarrow/table.pxi 与array.pxi等 Cython 实现。这一分层与 getstarted.rst 的表述一致Arrow manages data in arrays, which can be grouped in tables to represent columns of data in tabular data同时文档指出 Arrow 提供多种格式用于把表格数据读写到磁盘和网络最常用的是 Parquet 与 IPC 格式——这也解释了文档目录中parquet与ipc两节的核心地位。用环境变量控制 PyArrow 行为env_vars.rst 列出了可以直接影响 PyArrow 运行行为的四个环境变量适合在生产部署与兼容性调试场景使用环境变量作用ARROW_HOME指定 PyArrow 安装的基础路径覆盖pyarrow.get_library_dirs等内省函数对库路径的默认计算ARROW_PRE_0_15_IPC_FORMAT设为非零整数时IPC 写器默认回退到 0.15 之前的旧 Arrow IPC 格式等价于IpcWriteOptions.use_legacy_formatARROW_PRE_1_0_METADATA_VERSION设为非零整数时IPC 写器写出 V4 元数据对应 1.0 之前、Union 布局不兼容的旧版本等价于IpcWriteOptions.metadata_versionPKG_CONFIG指定pkg-config可执行文件路径当系统 PATH 中找不到 pkg-config 时保证内省函数正常工作文档同时提醒由于 PyArrow 基于 Arrow C其行为还会受到Arrow C 环境变量的额外影响排查跨层问题时两个层面的变量都需纳入考量。深入学习的入口想先跑通最小示例从 getstarted.rst 的数组与建表示例入手想理解列式布局与 Buffer阅读 data.rst994 行覆盖类型、数组、表全部主题与 memory.rst想对接下游生态numpy、pandas、dlpack、interchange_protocol四节构成 PyArrow 与 Python 数值/ML 生态的互操作矩阵想参与开发getting_involved.rst 附有 PyArrow 架构总览图docs/source/python/images/py_arch_overview.svg并结合 python/pyarrow 源码树对照阅读效果最佳。【免费下载链接】arrowApache Arrow is the universal columnar format and multi-language toolbox for fast data interchange and in-memory analytics项目地址: https://gitcode.com/GitHub_Trending/arrow3/arrow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
