Python 教程

在本教程中，我们将按照指南中的 快速参考 部分以及更详细的 创建第一个 PR 的步骤 部分中指定的步骤，对 Arrow 进行实际的功能贡献。如果这里缺少一些信息，请随时浏览这些部分。

功能贡献将添加到 PyArrow 的计算模块中。但如果您是修复错误或添加绑定，也可以遵循这些步骤。

本教程与 创建第一个 PR 的步骤 不同，因为我们将处理一个特定的案例。本教程并非旨在作为一步一步的指南。

让我们开始吧！

设置

让我们设置 Arrow 代码库。我们假设您已经安装了 Git。否则，请参阅 设置 部分。

完成 Apache Arrow 代码库 的 fork 后，我们将克隆它并将主代码库的链接添加到我们的上游。

$ git clone https://github.com/<your username>/arrow.git
$ cd arrow
$ git remote add upstream https://github.com/apache/arrow

构建 PyArrow

构建 PyArrow 的脚本因您使用的操作系统而异。因此，在本教程中，我们只介绍构建过程的说明。

另请参阅

有关构建过程的 介绍，请参阅 构建 Arrow 库 🏋🏿‍♀️ 部分。

有关如何构建 PyArrow 的 说明，请参阅 在 Linux 和 macOS 上构建 部分。

为新功能创建 GitHub Issue

我们将添加一个新功能，它模仿 arrow.compute 模块中的现有函数 min_max，但在两个方向上将间隔增大 1。请注意，这是一个为了本指南而编造的函数。

查看 此链接 中的 pc.min_max 示例。

首先，我们需要创建一个 GitHub Issue，因为该 Issue 还不存在。创建 GitHub 帐户后，我们将导航到 GitHub Issue 仪表板 并单击 新建 Issue 按钮。

我们应该确保将自己分配给该 Issue，以便让其他人知道我们正在处理它。您可以通过在创建的 Issue 中添加评论 take 来实现这一点。

另请参阅

有关 GitHub Issue 的更多信息，请访问指南的 查找适合新手的 Issue 🔎 部分。

开始在新分支上工作

在开始添加功能之前，我们应该从更新后的主分支创建一个新分支。

$ git checkout main
$ git fetch upstream
$ git pull --ff-only upstream main
$ git checkout -b ARROW-14977

让我们研究 Arrow 库，看看 pc.min_max 函数在何处定义/与 C++ 连接，并了解我们可以在哪里实现新功能。

我们可以尝试在 GitHub Apache Arrow 代码库中搜索函数引用。

并搜索 pyarrow 文件夹中的 test_compute.py 文件。

从搜索结果可以看出，该函数在 python/pyarrow/tests/test_compute.py 文件中进行测试，这意味着该函数是在 compute.py 文件中定义的。

检查 compute.py 文件后，我们可以看到它与 _compute.pyx 一起将来自 C++ 的函数包装到 Python 中。我们将在 compute.py 文件的末尾定义新功能。

让我们从 arrow/python 目录中的 shell 运行一些 Python 控制台代码，以了解更多有关 pc.min_max 的信息。

$ cd python
$ python

Python 3.9.7 (default, Oct 22 2021, 13:24:00)
[Clang 13.0.0 (clang-1300.0.29.3)] on darwin
Type "help", "copyright", "credits" or "license" for more information.

我们已从 shell 进入 Python 控制台，现在可以进行一些研究。

>>> import pyarrow.compute as pc
>>> data = [4, 5, 6, None, 1]
>>> data
[4, 5, 6, None, 1]
>>> pc.min_max(data)
<pyarrow.StructScalar: [('min', 1), ('max', 6)]>
>>> pc.min_max(data, skip_nulls=False)
<pyarrow.StructScalar: [('min', None), ('max', None)]>

我们将把新功能称为 pc.tutorial_min_max。我们希望从接受相同输入数据的函数中获得的结果为 [('min-', 0), ('max+', 7)]。如果指定应包含空值，则结果应等于 pc.min_max，即 [('min', None), ('max', None)]。

让我们将第一个试验代码添加到 arrow/python/pyarrow/compute.py 中，我们首先测试对来自 C++ 的“min_max”函数的调用。

def tutorial_min_max(values, skip_nulls=True):
    """
    Add docstrings

    Parameters
    ----------
    values : Array

    Returns
    -------
    result : TODO

    Examples
    --------
    >>> import pyarrow.compute as pc
    >>> data = [4, 5, 6, None, 1]
    >>> pc.tutorial_min_max(data)
    <pyarrow.StructScalar: [('min-', 0), ('max+', 7)]>
    """

    options = ScalarAggregateOptions(skip_nulls=skip_nulls)
    return call_function("min_max", [values], options)

要查看它是否有效，我们需要再次导入 pyarrow.compute 并尝试

>>> import pyarrow.compute as pc
>>> data = [4, 5, 6, None, 1]
>>> pc.tutorial_min_max(data)
<pyarrow.StructScalar: [('min', 1), ('max', 6)]>

它正在运行。现在我们必须更正限制以获得更正的间隔。为此，我们必须对 pyarrow.StructScalar 进行一些研究。在 test_scalars.py 中的 test_struct_duplicate_fields 下，我们可以看到 StructScalar 的创建示例。我们还可以再次运行 Python 控制台并尝试自己创建一个。

>>> import pyarrow as pa
>>> ty = pa.struct([
...      pa.field('min-', pa.int64()),
...      pa.field('max+', pa.int64()),
...    ])
>>> pa.scalar([('min-', 3), ('max+', 9)], type=ty)
<pyarrow.StructScalar: [('min-', 3), ('max+', 9)]>

注意

在我们还没有完善的文档的情况下，单元测试可能是寻找代码示例的好地方。

利用我们新获得的有关 StructScalar 和 pc.min_max 函数的附加选项的知识，我们可以完成工作。

def tutorial_min_max(values, skip_nulls=True):

   """
   Compute the minimum-1 and maximum+1 values of a numeric array.

   This is a made-up feature for the tutorial purposes.

   Parameters
   ----------
   values : Array
   skip_nulls : bool, default True
       If True, ignore nulls in the input.

   Returns
   -------
   result : StructScalar of min-1 and max+1

   Examples
   --------
   >>> import pyarrow.compute as pc
   >>> data = [4, 5, 6, None, 1]
   >>> pc.tutorial_min_max(data)
   <pyarrow.StructScalar: [('min-', 0), ('max+', 7)]>
   """

   options = ScalarAggregateOptions(skip_nulls=skip_nulls)
   min_max = call_function("min_max", [values], options)

   if min_max[0].as_py() is not None:
     min_t = min_max[0].as_py()-1
     max_t = min_max[1].as_py()+1
   else:
     min_t = min_max[0].as_py()
     max_t = min_max[1].as_py()

   ty = pa.struct([
     pa.field('min-', pa.int64()),
     pa.field('max+', pa.int64()),
   ])
   return pa.scalar([('min-', min_t), ('max+', max_t)], type=ty)

添加测试

现在，我们应该在 python/pyarrow/tests/test_compute.py 中添加一个单元测试，并运行 pytest。

def test_tutorial_min_max():
    arr = [4, 5, 6, None, 1]
    l1 = {'min-': 0, 'max+': 7}
    l2 = {'min-': None, 'max+': None}
    assert pc.tutorial_min_max(arr).as_py() == l1
    assert pc.tutorial_min_max(arr,
                               skip_nulls=False).as_py() == l2

添加单元测试后，我们可以从 shell 运行 pytest。要运行特定的单元测试，请将测试名称传递给 -k 参数。

$ cd python
$ python -m pytest pyarrow/tests/test_compute.py -k test_tutorial_min_max
======================== test session starts ==========================
platform darwin -- Python 3.9.7, pytest-6.2.5, py-1.10.0, pluggy-1.0.0
rootdir: /Users/alenkafrim/repos/arrow/python, configfile: setup.cfg
plugins: hypothesis-6.24.1, lazy-fixture-0.6.3
collected 204 items / 203 deselected / 1 selected

pyarrow/tests/test_compute.py .                                  [100%]

======================== 1 passed, 203 deselected in 0.16s ============


$ python -m pytest pyarrow/tests/test_compute.py
======================== test session starts ===========================
platform darwin -- Python 3.9.7, pytest-6.2.5, py-1.10.0, pluggy-1.0.0
rootdir: /Users/alenkafrim/repos/arrow/python, configfile: setup.cfg
plugins: hypothesis-6.24.1, lazy-fixture-0.6.3
collected 204 items

pyarrow/tests/test_compute.py ................................... [ 46%]
.................................................                 [100%]

========================= 204 passed in 0.49s ==========================

另请参阅

有关测试的更多信息，请参阅 测试 🧪 部分。

检查样式

最后，我们还需要检查样式。在 Arrow 中，我们使用一个名为 Archery 的实用程序来检查代码是否符合 PEP 8 样式指南。

$ archery lint --python --fix
INFO:archery:Running Python formatter (autopep8)
INFO:archery:Running Python linter (flake8)
/Users/alenkafrim/repos/arrow/python/pyarrow/tests/test_compute.py:2288:80: E501 line too long (88 > 79 characters)

使用 --fix 命令，Archery 将尝试修复样式问题，但有些问题（如行长）无法自动修复。我们应该自己进行必要的更正并再次运行 Archery。

$ archery lint --python --fix
INFO:archery:Running Python formatter (autopep8)
INFO:archery:Running Python linter (flake8)

完成。现在让我们创建 Pull Request！

创建 Pull Request

首先，让我们使用 shell 中的 git status 查看我们的更改，看看哪些文件已更改，并只提交我们正在处理的文件。

$ git status
On branch ARROW-14977
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
   modified:   python/pyarrow/compute.py
   modified:   python/pyarrow/tests/test_compute.py

no changes added to commit (use "git add" and/or "git commit -a")

以及 git diff，查看文件中的更改，以便发现可能出现的任何错误。

$ git diff
diff --git a/python/pyarrow/compute.py b/python/pyarrow/compute.py
index 9dac606c3..e8fc775d8 100644
--- a/python/pyarrow/compute.py
+++ b/python/pyarrow/compute.py
@@ -774,3 +774,45 @@ def bottom_k_unstable(values, k, sort_keys=None, *, memory_pool=None):
         sort_keys = map(lambda key_name: (key_name, "ascending"), sort_keys)
     options = SelectKOptions(k, sort_keys)
     return call_function("select_k_unstable", [values], options, memory_pool)
+
+
+def tutorial_min_max(values, skip_nulls=True):
+    """
+    Compute the minimum-1 and maximum-1 values of a numeric array.
+
+    This is a made-up feature for the tutorial purposes.
+
+    Parameters
+    ----------
+    values : Array
+    skip_nulls : bool, default True
+        If True, ignore nulls in the input.
+
+    Returns
+    -------
+    result : StructScalar of min-1 and max+1
+
+    Examples
+    --------
+    >>> import pyarrow.compute as pc
+    >>> data = [4, 5, 6, None, 1]
+    >>> pc.tutorial_min_max(data)
+    <pyarrow.StructScalar: [('min-', 0), ('max+', 7)]>
+    """
+
+    options = ScalarAggregateOptions(skip_nulls=skip_nulls)
+    min_max = call_function("min_max", [values], options)
+
...

一切看起来都很好。现在我们可以进行提交（将更改保存到分支历史记录中）

$ git commit -am "Adding a new compute feature for tutorial purposes"
[ARROW-14977 170ef85be] Adding a new compute feature for tutorial purposes
 2 files changed, 51 insertions(+)

我们可以使用 git log 检查提交历史记录

$ git log
commit 170ef85beb8ee629be651e3f93bcc4a69e29cfb8 (HEAD -> ARROW-14977)
Author: Alenka Frim <[email protected]>
Date:   Tue Dec 7 13:45:06 2021 +0100

    Adding a new compute feature for tutorial purposes

commit 8cebc4948ab5c5792c20a3f463e2043e01c49828 (main)
Author: Sutou Kouhei <[email protected]>
Date:   Sun Dec 5 15:19:46 2021 +0900

    ARROW-14981: [CI][Docs] Upload built documents

    We can use this in release process instead of building on release
    manager's local environment.

    Closes #11856 from kou/ci-docs-upload

    Authored-by: Sutou Kouhei <[email protected]>
    Signed-off-by: Sutou Kouhei <[email protected]>
...

如果我们是在一段时间前开始分支的，我们可能需要重新设置基线到上游主分支，以确保不存在合并冲突。

$ git pull upstream main --rebase

现在，我们可以将工作推送到 GitHub 上名为 origin 的 fork 的 Arrow 代码库中。

$ git push origin ARROW-14977
Enumerating objects: 13, done.
Counting objects: 100% (13/13), done.
Delta compression using up to 8 threads
Compressing objects: 100% (7/7), done.
Writing objects: 100% (7/7), 1.19 KiB | 1.19 MiB/s, done.
Total 7 (delta 6), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (6/6), completed with 6 local objects.
remote:
remote: Create a pull request for 'ARROW-14977' on GitHub by visiting:
remote:      https://github.com/AlenkaF/arrow/pull/new/ARROW-14977
remote:
To https://github.com/AlenkaF/arrow.git
 * [new branch]          ARROW-14977 -> ARROW-14977

现在，我们必须转到 GitHub 上的 Arrow 代码库 创建 Pull Request。在 GitHub Arrow 页面（主分支或 fork 分支）上，我们将看到一个黄色的通知栏，上面有一条消息，指出我们对分支 ARROW-14977 进行了最近的推送。太棒了，现在我们可以通过单击 比较并发起 Pull Request 来发起 Pull Request。

Apache Arrow 代码库上的通知栏。

首先，我们需要将标题更改为 ARROW-14977: [Python] 为指南教程添加一个“编造的”功能，使其与 Issue 相匹配。请注意，添加了一个标点符号！

额外说明：创建本教程时，我们使用的是 Jira Issue 跟踪器。由于我们目前使用 GitHub Issue，因此标题将以 GH-14977: [Python] 为指南教程添加一个“编造的”功能 开头。.

我们还将添加一个描述，以清楚地向其他人说明我们想要做什么。

单击 创建 Pull Request 后，我们的代码就可以在 Apache Arrow 代码库中作为 Pull Request 进行审查。

这是我们的 Pull Request！

Pull Request 与 Issue 相连，CI 正在运行。一段时间后，我们收到审查后，可以更正代码、添加评论、解决对话等等。我们发起的 Pull Request 可以从 这里 查看。

另请参阅

有关 Pull Request 工作流的更多信息，请参阅 Pull Request 生命周期。