/
py_function_custom_scaffold.html
264 lines (221 loc) · 11.5 KB
/
py_function_custom_scaffold.html
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
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
<!-- Generated by pkgdown: do not edit by hand -->
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Custom Scaffolding of R Wrappers for Python Functions — py_function_custom_scaffold • reticulate</title>
<!-- jquery -->
<script src="https://code.jquery.com/jquery-3.1.0.min.js" integrity="sha384-nrOSfDHtoPMzJHjVTdCopGqIqeYETSXhZDFyniQ8ZHcVy08QesyHcnOUpMpqnmWq" crossorigin="anonymous"></script>
<!-- Bootstrap -->
<link href="https://maxcdn.bootstrapcdn.com/bootswatch/3.3.7/flatly/bootstrap.min.css" rel="stylesheet" crossorigin="anonymous">
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js" integrity="sha384-Tc5IQib027qvyjSMfHjOMaLkfuWVxZxUPnCJA7l2mCWNIpG9mGCD8wGNIcPD7Txa" crossorigin="anonymous"></script>
<!-- Font Awesome icons -->
<link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.6.3/css/font-awesome.min.css" rel="stylesheet" integrity="sha384-T8Gy5hrqNKT+hzMclPo118YTQO6cYprQmhrYwIiQ/3axmI1hQomh7Ud2hPOy8SP1" crossorigin="anonymous">
<!-- clipboard.js -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/1.7.1/clipboard.min.js" integrity="sha384-cV+rhyOuRHc9Ub/91rihWcGmMmCXDeksTtCihMupQHSsi8GIIRDG0ThDc3HGQFJ3" crossorigin="anonymous"></script>
<!-- pkgdown -->
<link href="../pkgdown.css" rel="stylesheet">
<script src="../jquery.sticky-kit.min.js"></script>
<script src="../pkgdown.js"></script>
<link href="../extra.css" rel="stylesheet">
<meta property="og:title" content="Custom Scaffolding of R Wrappers for Python Functions — py_function_custom_scaffold" />
<meta property="og:description" content="This function can be used to generate R wrapper for a specified
Python function while allowing to inject custom code for critical parts of
the wrapper generation, such as process the any part of the docs obtained
from py_function_docs() and append additional roxygen fields. The result
from execution of python_function is assigned to a variable called
python_function_result that can also be processed by postprocess_fn
before writing the closing curly braces for the generated wrapper function." />
<meta name="twitter:card" content="summary" />
<!-- mathjax -->
<script src='https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML'></script>
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/html5shiv/3.7.3/html5shiv.min.js"></script>
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
<![endif]-->
</head>
<body>
<div class="container template-reference-topic">
<header>
<div class="navbar navbar-inverse navbar-fixed-top" role="navigation">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<span class="navbar-brand">
<a class="navbar-link" href="../index.html">reticulate</a>
<span class="label label-default" data-toggle="tooltip" data-placement="bottom" title="Released package">1.9</span>
</span>
</div>
<div id="navbar" class="navbar-collapse collapse">
<ul class="nav navbar-nav">
<li>
<a href="../index.html">Home</a>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-expanded="false">
Articles
<span class="caret"></span>
</a>
<ul class="dropdown-menu" role="menu">
<li class="dropdown-header">Using</li>
<li>
<a href="../articles/calling_python.html">Calling Python from R</a>
</li>
<li>
<a href="../articles/r_markdown.html">R Markdown Python Engine</a>
</li>
<li>
<a href="../articles/versions.html">Python Version Configuration</a>
</li>
<li>
<a href="../articles/python_packages.html">Installing Python Packages</a>
</li>
<li class="divider"></li>
<li class="dropdown-header">Advanced</li>
<li>
<a href="../articles/arrays.html">Arrays in R and Python</a>
</li>
<li>
<a href="../articles/package.html">Using reticulate in an R Package</a>
</li>
<li class="divider"></li>
<li class="dropdown-header">Tools</li>
<li>
<a href="../articles/rstudio_ide.html">RStudio IDE Tools for reticulate</a>
</li>
</ul>
</li>
<li>
<a href="../reference/index.html">Reference</a>
</li>
<li>
<a href="../news/index.html">News</a>
</li>
</ul>
<ul class="nav navbar-nav navbar-right">
<li>
<a href="https://github.com/rstudio/reticulate">
<span class="fa fa-github"></span>
</a>
</li>
</ul>
</div><!--/.nav-collapse -->
</div><!--/.container -->
</div><!--/.navbar -->
</header>
<div class="row">
<div class="col-md-9 contents">
<div class="page-header">
<h1>Custom Scaffolding of R Wrappers for Python Functions</h1>
<small>Source: <a href='https://github.com/rstudio/reticulate/blob/master/R/wrapper.R'><code>R/wrapper.R</code></a></small>
</div>
<p>This function can be used to generate R wrapper for a specified
Python function while allowing to inject custom code for critical parts of
the wrapper generation, such as process the any part of the docs obtained
from <code><a href='py_function_wrapper.html'>py_function_docs()</a></code> and append additional roxygen fields. The result
from execution of <code>python_function</code> is assigned to a variable called
<code>python_function_result</code> that can also be processed by <code>postprocess_fn</code>
before writing the closing curly braces for the generated wrapper function.</p>
<pre class="usage"><span class='fu'>py_function_custom_scaffold</span>(<span class='no'>python_function</span>, <span class='kw'>r_function</span> <span class='kw'>=</span> <span class='kw'>NULL</span>,
<span class='kw'>additional_roxygen_fields</span> <span class='kw'>=</span> <span class='kw'>NULL</span>, <span class='kw'>process_docs_fn</span> <span class='kw'>=</span> <span class='kw'>function</span>(<span class='no'>docs</span>) <span class='no'>docs</span>,
<span class='kw'>process_param_fn</span> <span class='kw'>=</span> <span class='kw'>function</span>(<span class='no'>param</span>, <span class='no'>docs</span>) <span class='no'>param</span>,
<span class='kw'>process_param_doc_fn</span> <span class='kw'>=</span> <span class='kw'>function</span>(<span class='no'>param_doc</span>, <span class='no'>docs</span>) <span class='no'>param_doc</span>,
<span class='kw'>postprocess_fn</span> <span class='kw'>=</span> <span class='kw'>function</span>() { }, <span class='kw'>file_name</span> <span class='kw'>=</span> <span class='kw'>NULL</span>)</pre>
<h2 class="hasAnchor" id="arguments"><a class="anchor" href="#arguments"></a>Arguments</h2>
<table class="ref-arguments">
<colgroup><col class="name" /><col class="desc" /></colgroup>
<tr>
<th>python_function</th>
<td><p>Fully qualfied name of Python function or class
constructor (e.g. <code>tf$layers$average_pooling1d</code>)</p></td>
</tr>
<tr>
<th>r_function</th>
<td><p>Name of R function to generate (defaults to name of Python
function if not specified)</p></td>
</tr>
<tr>
<th>additional_roxygen_fields</th>
<td><p>A list of additional roxygen fields to write
to the roxygen docs, e.g. <code>list(export = "", rdname = "generated-wrappers")</code>.</p></td>
</tr>
<tr>
<th>process_docs_fn</th>
<td><p>A function to process docs obtained from
<code><a href='py_function_wrapper.html'>reticulate::py_function_docs(python_function)</a></code>.</p></td>
</tr>
<tr>
<th>process_param_fn</th>
<td><p>A function to process each parameter needed for
<code>python_funcion</code> before executing <code>python_funcion.</code></p></td>
</tr>
<tr>
<th>process_param_doc_fn</th>
<td><p>A function to process the roxygen docstring for
each parameter.</p></td>
</tr>
<tr>
<th>postprocess_fn</th>
<td><p>A function to inject any custom code in the form of a
string before writing the closing curly braces for the generated wrapper
function.</p></td>
</tr>
<tr>
<th>file_name</th>
<td><p>The file name to write the generated wrapper function to. If
<code>NULL</code>, the generated wrapper will only be printed out in the console.</p></td>
</tr>
</table>
<h2 class="hasAnchor" id="examples"><a class="anchor" href="#examples"></a>Examples</h2>
<pre class="examples"><span class='co'># NOT RUN {</span>
<span class='fu'>library</span>(<span class='no'>tensorflow</span>)
<span class='fu'>library</span>(<span class='no'>stringr</span>)
<span class='co'># Example of a `process_param_fn` to cast parameters with default values</span>
<span class='co'># that contains "L" to integers</span>
<span class='no'>process_int_param_fn</span> <span class='kw'><-</span> <span class='kw'>function</span>(<span class='no'>param</span>, <span class='no'>docs</span>) {
<span class='co'># Extract the list of parameters that have integer values as default</span>
<span class='no'>int_params</span> <span class='kw'><-</span> <span class='fu'>gsub</span>(
<span class='st'>" = [-]?[0-9]+L"</span>,
<span class='st'>""</span>,
<span class='fu'><a href='http://www.rdocumentation.org/packages/stringr/topics/str_extract'>str_extract_all</a></span>(<span class='no'>docs</span>$<span class='no'>signature</span>, <span class='st'>"[A-z]+ = [-]?[0-9]+L"</span>)<span class='kw'>[[</span><span class='fl'>1</span>]])
<span class='co'># Explicitly cast parameter in the list obtained above to integer</span>
<span class='kw'>if</span> (<span class='no'>param</span> <span class='kw'>%in%</span> <span class='no'>int_params</span>) {
<span class='no'>param</span> <span class='kw'><-</span> <span class='fu'>paste0</span>(<span class='st'>"as.integer("</span>, <span class='no'>param</span>, <span class='st'>")"</span>)
}
<span class='no'>param</span>
}
<span class='co'># Note that since the default value of parameter `k` is `1L`. It is wrapped</span>
<span class='co'># by `as.integer()` to ensure it's casted to integer before sending it to `tf$nn$top_k`</span>
<span class='co'># for execution. We then print out the python function result.</span>
<span class='fu'>py_function_custom_scaffold</span>(
<span class='st'>"tf$nn$top_k"</span>,
<span class='kw'>r_function</span> <span class='kw'>=</span> <span class='st'>"top_k"</span>,
<span class='kw'>process_param_fn</span> <span class='kw'>=</span> <span class='no'>process_int_param_fn</span>,
<span class='kw'>postprocess_fn</span> <span class='kw'>=</span> <span class='kw'>function</span>() { <span class='st'>"print(python_function_result)"</span> })
<span class='co'># }</span></pre>
</div>
<div class="col-md-3 hidden-xs hidden-sm" id="sidebar">
<h2>Contents</h2>
<ul class="nav nav-pills nav-stacked">
<li><a href="#arguments">Arguments</a></li>
<li><a href="#examples">Examples</a></li>
</ul>
</div>
</div>
<footer>
<div class="copyright">
<p>Developed by JJ Allaire, Kevin Ushey, <a href='https://www.rstudio.com'><img src='http://tidyverse.org/rstudio-logo.svg' alt='RStudio' height='24' /></a>, Yuan Tang.</p>
</div>
<div class="pkgdown">
<p>Site built with <a href="http://pkgdown.r-lib.org/">pkgdown</a>.</p>
</div>
</footer>
</div>
</body>
</html>