/
pins-update.Rmd
156 lines (117 loc) · 4.83 KB
/
pins-update.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
---
title: "Upgrading to pins 1.0.0"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Upgrading to pins 1.0.0}
%\VignetteEncoding{UTF-8}
%\VignetteEngine{knitr::rmarkdown}
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
eval = rlang::is_installed("filelock")
)
```
pins 1.0.0 introduced a completely new API.
While the legacy API will continue to be supported for some time, it will not gain any new features, so it's good to plan to switch to the new interface.
This vignette shows a couple of examples of updating legacy code to the modern API, then provides a full set of equivalences between the legacy and modern function names.
```{r setup}
library(pins)
```
## Examples
A simple example of the legacy API looks something like this:
```{r}
# Legacy API
board_register_local("vignette", tempfile())
pin(head(mtcars), "mtcars", board = "vignette")
pin_get("mtcars", board = "vignette")
```
To convert to the modern API you need to make two major changes:
- Instead of registering a named board, you create an explicit board object.
- You use `pin_read()` and `pin_write()` instead of `pin_get()` and `pin()`.
```{r}
# Modern API
board <- board_local()
pin_write(board, head(mtcars), "mtcars")
pin_read(board, "mtcars")
```
Since the board object is always the first argument, you might also want to use the pipe:
```{r, echo=FALSE}
Sys.sleep(1)
```
```{r}
# Modern API
board <- board_local()
board %>% pin_write(head(mtcars), "mtcars")
board %>% pin_read("mtcars")
```
### Pinning files
Another way to use `pin()` is with a path to a file:
```{r}
# Legacy API
path <- tempfile()
writeLines(letters, path)
pin(path, "alphabet", board = "vignette")
pin_get("alphabet", board = "vignette")
```
pins 1.0.0 clearly separates the two cases of pin an object and pinning a file, so here instead of `pin_write()` and `pin_read()` you need to `pin_upload()` and `pin_download()`:
```{r}
# Modern API
board %>% pin_upload(path, "alphabet")
board %>% pin_download("alphabet")
```
### Pinning a url
Finally, you can `pin()` a url to automatically re-download it when it changes:
```{r}
# Legacy API
base <- "https://raw.githubusercontent.com/rstudio/pins-r/main/tests/testthat/"
(pin(paste0(base, "pin-files/first.txt"), board = "vignette"))
```
This now needs to be made explicit with the new `board_url()`, and since this returns a path, not a file, you need to use `pin_download()`:
```{r}
# Modern API
board_github <- board_url(c(
raw = paste0(base, "pin-files/first.txt")
))
board_github %>% pin_download("raw")
```
### Implicit board
It's also possible to use `pin()` and `pin_get()` without an explicit board argument, in which case it automatically uses a local board:
```{r}
# Legacy API
pin(data.frame(x = 1:3), "test-data")
pin_get("test-data")
```
To convert this code, you need to create an explicit `board_local()`:
```{r}
# Modern API
board <- board_local()
board %>% pin_write(data.frame(x = 1:3), "test-data")
board %>% pin_read("test-data")
```
## Equivalents
### Board functions
| Legacy API | Modern API |
|------------------------------|---------------------------------------------------------|
| `board_register_azure()` | `board_azure()` |
| `board_register_datatxt()` | Not currently implemented |
| `board_register_dospace()` | Not currently implemented |
| `board_register_gcloud()` | `board_gcs()` |
| `board_register_github()` | Use `board_folder()` together with `board_url()` |
| `board_register_local()` | `board_local()` |
| `board_register_kaggle()` | `board_kaggle_dataset()` / `board_kaggle_competition()` |
| `board_register_rsconnect()` | `board_connect()` |
| `board_register_s3()` | `board_s3()` |
| `pin()` with a URL | `board_url()` |
Future releases will add support for additional boards based on user feedback.
### Pin functions
| Legacy API | Modern API |
|------------------|---------------------------------------------------|
| `board_browse()` | `pin_browse()` |
| `pin()` | `pin_write()` / `pin_upload()` |
| `pin_get()` | `pin_read()` / `pin_download()` |
| `pin_find()` | `pin_search()` |
| `pin_info()` | `pin_meta()` |
| `pin_reactive()` | `pin_reactive_read()` / `pin_reactive_download()` |
| `pin_remove()` | `pin_delete()` |