R 教程#

在 Arrow R 包中添加 lubridate 绑定教程#

在本教程中，我们将记录对 Arrow R 包的绑定贡献，遵循指南中指定的步骤快速参考部分和更详细的创建第一个 PR 的步骤部分。如果发现这里缺少某些信息，请随时导航到这些部分。

该绑定将被添加到 R 包中的expression.R文件中。但即使您添加的绑定位于其他地方，您也可以遵循这些步骤。

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

让我们开始吧！

设置#

让我们设置 Arrow 存储库。我们假设您已安装 Git。否则，请参阅设置部分。

完成Apache Arrow 存储库的 fork 后（请参阅Fork 存储库），我们将克隆它并将主存储库的链接添加到我们的上游。

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

构建 R 包#

构建 R 包的步骤取决于您使用的操作系统。因此，在本教程中，我们只针对构建过程的说明进行参考。

另请参阅

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

有关如何构建 R 包的说明，请参阅R 开发者文档。

问题#

在本教程中，我们将解决一个问题，即实现一个简单的mday()函数绑定，它将与来自lubridate的现有 R 函数匹配。

注意

如果您没有问题并且需要帮助找到问题，请参阅指南的寻找好的第一个问题 🔎部分。

一旦您选择并为自己分配了一个问题，就可以继续下一步。

在新的分支上开始工作#

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

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

现在我们可以开始研究我们想要公开或连接到的 R 函数和 C++ Arrow 计算函数。

检查 lubridate mday() 函数

通过lubridate 文档，我们可以看到mday()接受一个日期对象并返回一个数字对象，表示月份中的日期。

我们可以在 R 控制台中运行一些示例，以帮助我们更好地理解该函数

> library(lubridate)
> mday(as.Date("2000-12-31"))
[1] 31
> mday(ymd(080306))
[1] 6

检查 Arrow C++ day() 函数

从计算函数文档中，我们可以看到day是一个一元函数，这意味着它接受单个数据输入。数据输入必须是Temporal class，返回值为Integer/numeric类型。

Temporal class被指定为：日期类型（Date32、Date64）、时间类型（Time32、Time64）、时间戳、持续时间、间隔。

我们可以使用call_function从 R 控制台中调用 Arrow C++ 函数，以查看它的工作原理

> call_function("day", Scalar$create(lubridate::ymd("2000-12-31")))
Scalar
31

我们可以看到 lubridate 和 Arrow 函数在操作和返回方面，使用了等效的数据类型。lubridate 的mday()函数没有其他参数，并且 Arrow C++ 函数day()也没有关联的选项类。

查看expressions.R中的代码，我们可以看到 day 函数已经在 R 包方面被指定/映射了：apache/arrow

我们只需要将mday()添加到表达式列表中，将其连接到 C++ day函数。

# second is defined in dplyr-functions.R
# wday is defined in dplyr-functions.R
"mday" = "day",
"yday" = "day_of_year",
"year" = "year",

添加测试#

现在我们需要添加一个测试，以检查一切是否正常。如果有其他选项或边缘情况，我们需要添加更多测试。查看类似函数的测试（例如yday()或day())，我们可以看到在test-dplyr-funcs-datetime.R中添加两个测试是一个好地方

test_that("extract mday from timestamp", {
  compare_dplyr_binding(
    .input %>%
      mutate(x = mday(datetime)) %>%
      collect(),
    test_df
  )
})

以及

test_that("extract mday from date", {
  compare_dplyr_binding(
    .input %>%
      mutate(x = mday(date)) %>%
      collect(),
    test_df
  )
})

现在我们需要查看测试是否通过，或者是否需要进行更多研究和代码修正。

devtools::test(filter="datetime")

> devtools::test(filter="datetime")
ℹ Loading arrow
See arrow_info() for available features
ℹ Testing arrow
See arrow_info() for available features
✔ | F W S  OK | Context
✖ | 1     230 | dplyr-funcs-datetime [1.4s]
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Failure (test-dplyr-funcs-datetime.R:187:3): strftime
``%>%`(...)` did not throw the expected error.
Backtrace:
 1. testthat::expect_error(...) test-dplyr-funcs-datetime.R:187:2
 2. testthat:::expect_condition_matching(...)
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

══ Results ═════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════
Duration: 1.4 s

[ FAIL 1 | WARN 0 | SKIP 0 | PASS 230 ]

我们为strftime函数获得了一个错误，但查看代码后发现它与我们的工作无关。我们可以继续，也许可以询问其他人，看看他们是否在运行测试时也遇到了类似的错误。我们可能只需要重新构建库即可。

检查样式#

我们还应该运行 linter 以检查代码样式是否遵循tidyverse 样式。为此，我们在 shell 中运行以下命令

$ make style
R -s -e 'setwd(".."); if (requireNamespace("styler")) styler::style_file(setdiff(system("git diff --name-only | grep r/.*R$", intern = TRUE), file.path("r", source("r/.styler_excludes.R")$value)))'
Loading required namespace: styler
Styling  2  files:
 r/R/expression.R                             ✔
 r/tests/testthat/test-dplyr-funcs-datetime.R ℹ
────────────────────────────────────────────
Status   Count Legend
✔  1  File unchanged.
ℹ  1  File changed.
✖  0  Styling threw an error.
────────────────────────────────────────────
Please review the changes carefully!

创建拉取请求#

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

$ git status
On branch ARROW-14816
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:   R/expression.R
   modified:   tests/testthat/test-dplyr-funcs-datetime.R

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

$ git diff
diff --git a/r/R/expression.R b/r/R/expression.R
index 37fc21c25..0e71803ec 100644
--- a/r/R/expression.R
+++ b/r/R/expression.R
@@ -70,6 +70,7 @@
   "quarter" = "quarter",
   # second is defined in dplyr-functions.R
   # wday is defined in dplyr-functions.R
+  "mday" = "day",
   "yday" = "day_of_year",
   "year" = "year",

diff --git a/r/tests/testthat/test-dplyr-funcs-datetime.R b/r/tests/testthat/test-dplyr-funcs-datetime.R
index 359a5403a..228eca56a 100644
--- a/r/tests/testthat/test-dplyr-funcs-datetime.R
+++ b/r/tests/testthat/test-dplyr-funcs-datetime.R
@@ -444,6 +444,15 @@ test_that("extract wday from timestamp", {
   )
 })

+test_that("extract mday from timestamp", {
+  compare_dplyr_binding(
+    .input %>%
+      mutate(x = mday(datetime)) %>%
+      collect(),
+    test_df
+  )
+})
+
 test_that("extract yday from timestamp", {
   compare_dplyr_binding(
     .input %>%
@@ -626,6 +635,15 @@ test_that("extract wday from date", {
   )
 })

+test_that("extract mday from date", {
+  compare_dplyr_binding(
+    .input %>%
+      mutate(x = mday(date)) %>%
+      collect(),
+    test_df
+  )
+})
+
 test_that("extract yday from date", {
   compare_dplyr_binding(
     .input %>%

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

$ git commit -am "Adding a binding and a test for mday() lubridate"
[ARROW-14816 ed37d3a3b] Adding a binding and a test for mday() lubridate
 2 files changed, 19 insertions(+)

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

$ git log
commit ed37d3a3b3eef76b696532f10562fea85f809fab (HEAD -> ARROW-14816)
Author: Alenka Frim <[email protected]>
Date:   Fri Jan 21 09:15:31 2022 +0100

    Adding a binding and a test for mday() lubridate

commit c5358787ee8f7b80f067292f49e5f032854041b9 (upstream/main, upstream/HEAD, main, ARROW-15346, ARROW-10643)
Author: Krisztián Szűcs <[email protected]>
Date:   Thu Jan 20 09:45:59 2022 +0900

    ARROW-15372: [C++][Gandiva] Gandiva now depends on boost/crc.hpp which is missing from the trimmed boost archive

    See build error https://github.com/ursacomputing/crossbow/runs/4871392838?check_suite_focus=true#step:5:11762

    Closes #12190 from kszucs/ARROW-15372

    Authored-by: Krisztián Szűcs <[email protected]>
    Signed-off-by: Sutou Kouhei <[email protected]>

如果我们在一段时间之前开始了分支，我们可能需要重新绑定到上游主分支，以确保没有合并冲突

$ git pull upstream main --rebase

现在我们可以将我们的工作推送到 GitHub 上名为 origin 的 Forked Arrow 存储库。

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

现在，我们必须转到GitHub 上的 Arrow 存储库以创建一个拉取请求。在 GitHub Arrow 页面（主分支或 Forked 分支）上，我们会看到一个黄色的通知栏，上面有一条消息，表明我们对 ARROW-14816 分支进行了最新的推送。非常好，现在我们可以通过点击比较并创建拉取请求来创建拉取请求。

GitHub page of the Apache Arrow repository showing a notice bar indicating change has been made in our branch and a Pull Request can be created.

Apache Arrow 存储库上的通知栏。#

首先，我们需要将标题更改为ARROW-14816: [R] Implement bindings for lubridate::mday()，以使其与问题相匹配。请注意，添加了一个标点符号！

额外说明：在创建本教程时，我们一直使用 Jira 问题跟踪器。由于我们目前使用 GitHub 问题，因此标题将以 GH-14816: [R] Implement bindings for lubridate::mday() 为前缀.

我们还将添加一个描述，以便其他人清楚地了解我们正在尝试做的事情。

GitHub page of the Pull Request showing the editor for the title and a description.

编辑拉取请求的标题和描述。#

单击创建拉取请求后，我们的代码将作为拉取请求在 Apache Arrow 存储库中进行审查。

GitHub page of the Pull Request showing the title and a description.

我们的拉取请求！#

拉取请求与问题连接，并且 CI 正在运行。一段时间后，我们会收到审查，然后可以修正代码、添加评论、解决对话等等。

另请参阅

有关拉取请求工作流程的更多信息，请参阅拉取请求的生命周期。

我们创建的拉取请求可以在这里查看。

本页内容
在 GitHub 上编辑