［翻訳］reticulate vignette: RからPythonへのインターフェース

この文書は，RStudio他によるRパッケージ[`reticulate`](https://cran.r-project.org/package=reticulate) (Version 0.7) のビネット["R interface to Python"](https://cran.r-project.org/package=reticulate/vignettes/introduction.html)の翻訳です．

License: [Apache License 2.0](https://choosealicense.com/licenses/apache-2.0/)

----

<!-- ## Overview -->

## 概要

<!-- The **reticulate** package provides an R interface to Python modules, classes, and functions. For example, this code imports the Python `os` module and calls some functions within it: -->

**reticulate** パッケージはPythonのモジュール，クラス，関数へのRインターフェースを提供します．たとえば次のコードでは，Pythonの`os`モジュールをインポートして，その中の関数を呼び出しています．


```r
library(reticulate)
os <- import("os")
os$chdir("tests")
os$getcwd()
```

<!-- Functions and other data within Python modules and classes can be accessed via the `$` operator (analogous to the way you would interact with an R list, environment, or reference class). -->

Pythonのモジュールやクラスの中の関数やその他のデータには，`$`演算子によってアクセスできます（Rのリストや環境，参照クラスを操作するやり方と同様です）．

<!-- When calling into Python, R data types are automatically converted to their equivalent Python types. When values are returned from Python to R they are converted back to R types. Types are converted as follows: -->

Pythonを呼び出すときに，Rのデータ型はPythonの同等な型に自動的に変換されます．PythonからRに値が返されるときには，逆にRの型に変換されます．型は以下のように変換されます．

<!-- | R  | Python | Examples | -->
<!-- |---|---|---| -->
<!-- | Single-element vector   | Scalar |  `1`, `1L`, `TRUE`, `"foo"` | -->
<!-- | Multi-element vector | List  |  `c(1.0, 2.0, 3.0)`, `c(1L, 2L, 3L)` | -->
<!-- | List of multiple types  | Tuple  |  `list(1L, TRUE, "foo")` -->
<!-- | Named list | Dict  |  `list(a = 1L, b = 2.0)`, `dict(x = x_data)` -->
<!-- | Matrix/Array | NumPy ndarray  | `matrix(c(1,2,3,4), nrow = 2, ncol = 2)` -->
<!-- | Function | Python function | `function(x) x + 1` -->
<!-- | NULL, TRUE, FALSE  | None, True, False  |  `NULL`, `TRUE`, `FALSE` -->

| R  | Python | 例 |
|---|---|---|
| 一要素のベクトル   | スカラー |  `1`, `1L`, `TRUE`, `"foo"` |
| 多要素のベクトル | リスト |  `c(1.0, 2.0, 3.0)`, `c(1L, 2L, 3L)` |
| 複数の型を含むリスト  | タプル |  `list(1L, TRUE, "foo")`
| 名前付きリスト | 辞書 |  `list(a = 1L, b = 2.0)`, `dict(x = x_data)`
| 行列/配列 | NumPyの配列(ndarray)  | `matrix(c(1,2,3,4), nrow = 2, ncol = 2)`
| 関数| Pythonの関数 | `function(x) x + 1`
| NULL, TRUE, FALSE  | None, True, False  |  `NULL`, `TRUE`, `FALSE`

<!-- If a Python object of a custom class is returned then an R reference to that object is returned. You can call methods and access properties of the object just as if it was an instance of an R reference class. -->

カスタムクラスのPythonオブジェクトが返ってくる場合には，Rからそのオブジェクトへの参照が返されます．このオブジェクトに対しては，まるでRの参照クラスのインスタンスであるかのようにして，メソッドを呼び出したり，プロパティにアクセスしたりできます．

<!-- The **reticulate** package is compatible with all versions of Python >= 2.7. Integration with NumPy is optional and requires NumPy >= 1.6. -->

**reticulate** パッケージは，バージョン2.7以降のすべてのPythonで動作します．オプションとしてNumpyが統合できますが，Numpy 1.6以上が必要です．

<!-- ## Installation -->

## インストール

<!-- You can install reticulate from CRAN as follows: -->

**reticulate**はCRANから以下のようにしてインストールできます．


```r
install.packages("reticulate")
```

<!-- ### Locating Python -->

### Pythonの場所の特定

<!-- If the version of Python you want to use is located on the system `PATH` then it will be automatically discovered (via `Sys.which`) and used.  -->

使用したいバージョンのPythonがシステムの`PATH`にある場合には，（`Sys.which`によって）自動的にそのPythonが見つかり，使用されます

<!-- Alternatively, you can use one of the following functions to specify alternate versions of Python: -->

あるいは，以下の関数のどれかを用いて，他のバージョンのPythonを指定することもできます．

<!-- | Function  | Description |  -->
<!-- |----------------|------------------------------------------------------------------| -->
<!-- | use_python | Specify the path a specific Python binary. |  -->
<!-- | use_virtualenv | Specify the directory containing a Python virtualenv. |  -->
<!-- | use_condaenv | Specify the name of a Conda environment. |  -->

| 関数  | 説明 |
|----------------|------------------------------------------------------------------|
| use_python | 特定のPythonバイナリへのパスを指定する． | 
| use_virtualenv | Pythonのvirtualenvを含むディレクトリを指定する． | 
| use_condaenv | condaの環境を指定する． | 

<!-- For example: -->

例：


```r
library(reticulate)
use_python("/usr/local/bin/python")
use_virtualenv("~/myenv")
use_condaenv("myenv")
```

<!-- Note that the NumPy features of **reticulate** require NumPy &gt;= 1.6 so versions of Python that satisfy this requirement will be preferred over ones that don't. -->

**reticulate** でNumpyの機能を使うにはNumpy 1.6以上が必要になるので，この要件を満たすバージョンのPythonの方が望ましいです．

<!-- Also note that the `use` functions are by default considered only hints as to where to find Python (i.e. they don't produce errors if the specified version doesn't exist). You can add the `required` parameter to ensure that the specified version of Python actually exists: -->

また，デフォルトでは`use`系関数はPythonがどこで見つかるかのヒントにすぎないということに注意してください（つまり，指定されたバージョンのPythonが存在しなくてもエラーは出ません）．指定されたバージョンのPythonが実際に存在することを保証するには，`required`引数を追加します．


```r
use_virtualenv("~/myenv", required = TRUE)
```

<!-- The order in which versions of Python will be discovered and used is as follows: -->

Pythonは以下の順序で探索されて見つかった場所にあるバージョンが使用されます．

<!-- 1.  If specified, at the locations referenced by calls to `use_python`, `use_virtualenv`, and `use_condaenv`. -->

<!-- 2.  If specified, at the location referenced by the `RETICULATE_PYTHON` environment variable. -->

<!-- 3.  At the location of the Python binary discovered on the system `PATH` (via the `Sys.which` function). -->

<!-- 4.  At other customary locations for Python including `/usr/local/bin/python`, `/opt/local/bin/python`, etc. -->

1. `use_python`，`use_virtualenv`，`use_condaenv`を呼び出して指定した場所

2. `RETICULATE_PYTHON`環境変数で指定した場所

3. （`Sys.which`関数によって）システムの`PATH`で見つかるPythonの場所

4. その他の慣習的にPythonが配置される場所．`/usr/local/bin/python`，`/opt/local/bin/python`等．

<!-- The scanning for and binding to a version of Python typically occurs at the time of the first call to `import` within an R session. As a result, priority will be given to versions of Python that include the module specified within the call to `import` (i.e. versions that don't include it will be skipped). -->

典型的な用途では，Rセッションで最初に`import`を呼んだときにPythonの探索とバインディングが実行されます．その結果，`import`の呼び出しで指定したモジュールを含むバージョンのPythonが優先的に使用されます（すなわち，指定のモジュールを含まないバージョンのPythonはスキップされます）．

<!-- You can use the `py_config` function to query for information about the specific version of Python in use as well as a list of other Python versions discovered on the system: -->

`py_config`関数を使うと，使用しているバージョンのPythonや，システムで見つかる他のバージョンのPythonに関する情報を問い合わせることができます．


```r
py_config()
```


<!-- ## Importing Modules -->

## モジュールのインポート

<!-- The `import` function can be used to import any Python module. For example: -->

`import`関数を使って任意のPythonモジュールをインポートすることができます．例を示します．


```r
difflib <- import("difflib")
difflib$ndiff(foo, bar)

filecmp <- import("filecmp")
filecmp$cmp(dir1, dir2)
```

<!-- The `import_main` and `import_builtins` functions give you access to the main module where code is executed by default and the collection of built in Python functions. For example: -->

`import_main`関数と`import_builtins`関数によって，デフォルトでコードが実行される場所であるmainモジュールと，組み込みのPython関数群にアクセスすることができます．例を示します．


```r
main <- import_main()

py <- import_builtins()
py$print('foo')
```

<!-- The main module is generally useful if you have executed Python code from a file or string and want to get access to it's results (see the section below for more details). -->

一般的に，ファイルや文字列からPythonコードを実行して，その結果にアクセスしたい場合にmainモジュールが役立ちます（さらなる詳細は以下の節を見てください）．

<!-- ### Object Conversion -->

### オブジェクトの変換

<!-- By default when Python objects are returned to R they are converted to their equivalent R types. However, if you'd rather make conversion from Python to R explicit and deal in native Python objects by default you can pass `convert = FALSE` to the `import` function. In this case Python to R conversion will be disabled for the module returned from `import`. For example: -->

PythonのオブジェクトがRに返されるとき，デフォルトではRの同等な型に変換されます．ですが，もしPythonからRへの変換を明示的にし，ネイティブなPythonのオブジェクトを扱うのをデフォルトの設定にしたいのであれば，`import`関数に`convert=FALSE`を渡せばよいです．


```r
# numpyをインポートし，PythonからRへの自動変換を禁止する
np <- import("numpy", convert = FALSE)

# NumPyで配列を操作する
a <- np$array(c(1:4))
sum <- a$cumsum()

# 最後に明示的にRに変換する
py_to_r(sum)
```

<!-- # import numpy and speicfy no automatic Python to R conversion -->
<!-- # do some array manipulations with NumPy -->
<!-- # convert to R explicitly at the end -->

<!-- As illustrated above, if you need access to an R object at end of your computations you can call the `py_to_r` function explicitly. -->

上で示したように，計算の最後にRのオブジェクトへのアクセスが必要であれば，`py_to_r`関数を明示的に呼び出せばよいです．


<!-- ## Executing Code -->

## コードの実行

<!-- You can execute Python code within the main module using the `py_run_file` and `py_run_string` functions. These functions both return a reference to the main Python module so you can access the results of their execution. For example: -->

`py_run_file`関数と`py_run_string`関数を使って，mainモジュールの中でPythonコードを実行できます．これらの関数は両方ともPythonのmainモジュールへの参照を返すので，実行結果にアクセスすることができます．例を示します．


```r
py_run_file("script.py")

main <- py_run_string("x = 10")
main$x
```

<!-- ## Lists, Tuples, and Dictionaries -->

## リスト，タプル，辞書

<!-- The automatic conversion of R types to Python types works well in most cases, but occasionally you will need to be more explicit on the R side to provide Python the type it expects. -->

Rの型からPythonの型への自動変換は大抵の場合にうまくいきますが，Python側が期待している型を与えるためには，R側でより明示的な操作が必要な場合もあります．

<!-- For example, if a Python API requires a list and you pass a single element R vector it will be converted to a Python scalar. To overcome this simply use the R `list` function explicitly: -->

たとえば，PythonのAPIがリストを要求しているのにRの一要素のベクトルを渡すと，これはPythonのスカラーに変換されてしまいます．これを克服するには，たんにRの`list`関数を明示的に使えばよいです．

```r
foo$bar(indexes = list(42L))
```

<!-- Similarly, a Python API might require a `tuple` rather than a list. In that case you can use the `tuple` function: -->

同様に，PythonのAPIがリストではなくタプルを要求することがあるかもしれませんが，その場合には`tuple`関数が使えます．

```r
tuple("a", "b", "c")
```

<!-- R named lists are converted to Python dictionaries however you can also explicitly create a Python dictionary using the `dict` function: -->

Rの名前付きリストはPythonの辞書に変換されますが．`dict`関数を使って明示的にPythonの辞書を作成することもできます．

```r
dict(foo = "bar", index = 42L)
```

<!-- This might be useful if you need to pass a dictionary that uses a more complex object (as opposed to a string) as it's key. -->

これは，（文字列ではない）より複雑なオブジェクトをキーに持つ辞書を渡す必要がある場合に有用かもしれません．


<!-- ## With Contexts -->

## コンテキスト

<!-- The R `with` generic function can be used to interact with Python context manager objects (in Python you use the `with` keyword to do the same). For example: -->

Rの`with`総称関数を使って，Pythonのコンテキストマネージャオブジェクトを操作できます（Pythonでは`with`キーワードを使って同じことができます）．例を示します．


```r
py <- import_builtins()
with(py$open("output.txt", "w") %as% file, {
  file$write("Hello, there!")
})
```

<!-- This example opens a file and ensures that it is automatically closed at the end of the with block. Note the use of the `%as%` operator to alias the object created by the context manager. -->

この例では，ファイルを開いて，そのファイルがwithブロックの最後に自動的に閉じられることを保証しています．`%as%`演算子を使って，コンテキストマネージャが作成したオブジェクトに別名を与えていることに注目してください．

<!-- ## Iterators -->

## イテレータ

<!-- If a Python API returns an [iterator or generator](http://anandology.com/python-practice-book/iterators.html) you can interact with it using the `iterate` function. The `iterate` function can be used to apply an R function to each item yielded by the iterator: -->

もしPythonのAPIが[イテレータやジェネレータ](http://anandology.com/python-practice-book/iterators.html)を返す場合には，`iterate`関数を使ってこれを操作することができます．`iterate`関数を使うと，イテレータが返す各要素に対してRの関数を適用できます．


```r
iterate(iter, print)
```

<!-- If you don't pass a function to `iterate` the results will be collected into an R vector: -->

`iterate`に関数を渡さないと，結果が集められてRのベクトルになります．


```r
results <- iterate(iter)
```

<!-- Note that the `Iterators` will be drained of their values by `iterate()`: -->

`iterate`関数によってイテレータの値は消費されてしまうことに注意してください．


```r
a <- iterate(iter) # 結果は空でない
b <- iterate(iter) # 要素はすでに消費されてしまったので，結果は空になる
```

<!-- # results are not empty -->
<!-- # results are empty since items have already been drained -->

<!-- ## Callable Objects -->

## 呼び出し可能オブジェクト

<!-- In addition to accessing their methods and properties, some Python objects are also callable (meaning they can be invoked with parameters just like an ordinary function). Callable Python objects are returned to R as objects rather than functions, however, you can still execute the callable function via the `$call()` method, for example: -->

Pythonのオブジェクトの中には，メソッドやプロパティへのアクセスだけでなく，呼び出し可能な（つまり普通の関数のように引数を与えて呼び出すことができる）ものがあります．呼び出し可能なPythonオブジェクトは，関数ではなくオブジェクトとしてRに返ってくるものの，`$call()`メソッドによって呼び出し可能な関数を実行できます．例を示します．


```r
# 呼び出し可能オブジェクトを取得
parser <- spacy$English()
# オブジェクトを関数として呼び出す
parser$call(spacy)
```

<!-- # get a callable object -->
<!-- # call the object as a function -->

<!-- ## Advanced Functions -->

## 高度な関数

<!-- There are several more advanced functions available that are useful principally when creating high level R interfaces for Python libraries. -->

主にPythonライブラリに対して高水準のRインターフェースを作成するときに役立つ，より高度な関数も利用可能です．

<!-- ### Python Objects -->

### Pythonオブジェクト

<!-- Typically interacting with Python objects from R involves using the `$` operator to access whatever properties for functions of the object you need. When using the `$`, Python objects are automatically converted to their R equivalents when possible. The following functions enable you to interact with Python objects at a lower level (e.g. no conversion to R is done unless you explicitly call the `py_to_r` function): -->

RからPythonのオブジェクトを操作するには，通常は`$`演算子を使って必要なオブジェクトの機能にアクセスします．`$`を使うと，Pythonのオブジェクトは可能であれば自動的にRの同等なオブジェクトに変換されますが，以下の関数を用いればPythonのオブジェクトをより低水準で操作できます（たとえば，明示的に`py_to_r`を呼ばない限りRのオブジェクトへの変換は行われません）．

<!-- | Functions | Description |  -->
<!-- |----------------|------------------------------------------------------------------| -->
<!-- | py_has_attr | Check if an object has a specified attribute.  |  -->
<!-- | py_get_attr | Get an attribute of a Python object.  |  -->
<!-- | py_set_attr | Set an attribute of a Python object.  |  -->
<!-- | py_list_attributes | List all attributes of a Python object. | -->
<!-- | py_call | Call a Python callable object with the specified arguments.  |  -->
<!-- | py_to_r | Convert a Python object to it's R equivalent | -->
<!-- | r_to_py | Convert an R object to it's Python equivalent | -->

| 関数 | 説明 | 
|----------------|------------------------------------------------------------------|
| py_has_attr | オブジェクトが指定した属性を持つか確認する． | 
| py_get_attr | Pythonオブジェクトの属性を取得する． | 
| py_set_attr | Pythonオブジェクトの属性を設定する． | 
| py_list_attributes | Pythonオブジェクトの全属性の一覧を取得する． |
| py_call | 指定した引数でPythonの呼び出し可能オブジェクトを呼び出す． | 
| py_to_r | PythonオブジェクトをRの同等なオブジェクトに変換する． |
| r_to_py | RのオブジェクトをPythonの同等なオブジェクトに変換する． |


<!-- ### Configuration -->

### 設定

<!-- The following functions enable you to query for information about the Python configuration available on the current system. -->

以下の関数を用いると，現在のシステムで利用可能なPythonの設定に関する情報を問い合わせることができます．

<!-- | Function  | Description |  -->
<!-- |----------------|------------------------------------------------------------------| -->
<!-- | py_available | Check whether a Python interface is available on this system. | -->
<!-- | py_numpy_available | Check whether the R interface to NumPy is available (requires NumPy >= 1.6) | -->
<!-- | py_module_available | Check whether a Python module is available on this system. | -->
<!-- | py_config | Get information on the location and version of Python in use.  |  -->

| 関数 | 説明 | 
|----------------|------------------------------------------------------------------|
| py_available | Pythonへのインターフェースがこのシステムで利用可能か確認する． |
| py_numpy_available | NumPyへのRインターフェースが利用可能か確認する（要NumPy 1.6以上）． |
| py_module_available | Pythonのモジュールがこのシステムで利用可能か確認する． |
| py_config | 使用中のPythonの場所とバージョンの情報を取得する． | 

<!-- ### Output Control -->

### 出力の制御

<!-- These functions enable you to capture or suppress output from Python: -->

以下の関数を用いるとPythonからの出力を捕捉したり抑制したりできます．

<!-- | Function  | Description |  -->
<!-- |----------------|------------------------------------------------------------------| -->
<!-- | py_capture_output | Capture Python output for the specified expression and return it as an R character vector. |  -->
<!-- | py_suppress_warnings | Execute the specified expression, suppressing the display Python warnings.   |  -->

| 関数 | 説明 |
|----------------|------------------------------------------------------------------|
| py_capture_output | 指定した式に対するPythonの出力を捕捉してRの文字ベクトルとして返す． | 
| py_suppress_warnings | 指定した式を実行するが，Pythonの警告の表示は抑制する． | 


<!-- ### Miscellaneous -->

### その他

<!-- The functions provide miscellaneous other lower-level capabilities: -->

以下の関数は，その他の様々な低水準の機能を提供します．

<!-- | Function  | Description |  -->
<!-- |----------------|------------------------------------------------------------------| -->
<!-- | py_unicode | Convert a string to a Python unicode object. | -->
<!-- | py_str | Get the string representation of Python object. | -->
<!-- | py_is_null_xptr | Check whether a Python object is a null externalptr. | -->
<!-- | py_validate_xptr | Check whether a Python object is a null externalptr and throw an error if it is. | -->

| 関数 | 説明 |
|----------------|------------------------------------------------------------------|
| py_unicode | 文字列をPythonのユニコードオブジェクトに変換する． |
| py_str | Pythonオブジェクトの文字列表現を取得する． |
| py_is_null_xptr | Pythonオブジェクトがnullなexternalptrであるか確認する． |
| py_validate_xptr | Pythonオブジェクトがnullなexternalptrであるか確認し，そうであればエラーを投げる． |

<!-- ## Using in a Package -->

## パッケージでの使用

<!-- ### Checking and Testing on CRAN -->

### CRANでチェックとテスト

<!-- If you use **reticulate** in another R package you need to account for the fact that when your package is submitted to CRAN, the CRAN test servers may not have Python, NumPy, or whatever other Python modules you are wrapping in your package. If you don't do this then your package may fail to load and/or pass it's tests when run on CRAN. -->

**reticulate**を他のRパッケージで使うのであれば，次のことを考慮する必要があります．それは，パッケージがCRANに提出される際に，CRANのテスト用サーバにはPythonもNumPyも，あなたがパッケージでラップしようとしている他のPythonモジュールも存在しないかもしれないということです．

<!-- There are two things you should do to ensure your package is well behaved on CRAN: -->

あなたのパッケージがCRANでうまく動作することを保証するには，以下の2つのことをやってておくべきです．

<!-- 1. When importing Python modules for use inside your package you should use the `delay_load` option to ensure that the module (and Python) is loaded only on it's first use. For example: -->

1. パッケージの中で使うPythonモジュールをインポートする際には，モジュール（とPython）がそれらを最初に使うときにだけロードされることを保証するために，`delay_load`オプションを使うべきです．

    
    ```r
    # 自分のパッケージで使用したいpythonの'foo'モジュール
    foo <- NULL
    
    .onLoad <- function(libname, pkgname) {
      # fooモジュールを遅延ロードする（$でアクセスするときにのみロードされる)
      foo <<- import("foo", delay_load = TRUE)
    }
    ```

<!-- # python 'foo' module I want to use in my package -->
<!-- # delay load foo module (will only be loaded when accessed via $) -->


<!-- 2. When writing tests, check to see if your module is available and if it isn't then skip the test. For example, if you are using the **testthat** package, you might do this: -->

2. テストを書く際には，モジュールが利用可能かどうか確認し，利用不可能であればテストをスキップするようにします．たとえば**testthat**パッケージを使っているのであれば，以下のようになるでしょう．

    
    ```r
    # 'foo'モジュールがなければテストをスキップするためのヘルパ関数
    skip_if_no_foo <- function() {
      have_foo <- py_module_available("foo")
      if (!have_foo)
        skip("テストにfooが利用できません！")
    }
    
    # このヘルパ関数をすべてのテストで呼ぶようにする
    test_that("期待通りに動く", {
      skip_if_no_foo()
      # ここにテストコードを書く
    })
    ```

<!-- # helper function to skip tests if we don't have the 'foo' module -->
<!-- skip("foo not available for testing") -->
<!-- # then call this function from all of your tests -->
<!-- test_that("Things work as expected", { -->
<!-- # test code here... -->

<!-- ### S3 Methods -->

### S3メソッド

<!-- Python objects exposed by **reticulate** carry their Python classes into R, so it's possible to write S3 methods to customize e.g. the `str` or `print` behavior for a given class (note that it's not typically necessary that you do this since the default `str` and `print` methods call `PyObject_Str`, which typically provides an acceptable default behavior). -->

**reticulate** によってR側に露出しているPythonオブジェクトのクラスはRにも持ち越されるので，クラスに対してS3メソッドを書いて，たとえば`str`や`print`の動作をカスタマイズすることができます（ただし通常はそうする必要はありません．デフォルトの`str`メソッドや`print`メソッドは`PyObject_Str`を呼び出しますが，これが普通は許容可能なデフォルトの動作を提供するからです．

<!-- If you do decide to implement custom S3 methods for a Python class it's important to keep in mind that when an R session ends the connection to Python objects is lost, so when the .RData saved from one R session is restored in a subsequent R session the Python objects are effectively lost (technically they become `NULL` R `externalptr` objects). -->

もし本当にPythonのクラス向けにカスタマイズしたS3メソッドを実装すると決めたのであれば，次のことに留意するのが大切です．すなわち，Rセッションの終了時にはPythonオブジェクトへのコネクションが失われるので，あるRセッションで保存した.RDataを後続のRセッションでリストアすると，Pythonオブジェクトが実質的に失われてしまうということです（正確に言うと，Rの`NULL`な`externalptr`オブジェクトになってしまいます）．

<!-- This means that you should always use the `py_is_null_xptr` function on objects before interacting with them in an S3 method. For example: -->

これが意味するところは，S3メソッドでPythonオブジェクトを操作する前には，常に`py_is_null_xptr`を使うべきだということです．例を示します．


```r
#' @export
summary.MyPythonClass <- function(object, ...) {
  if (py_is_null_xptr(object))
    stop("Object is NULL")
  else
    # オブジェクトを操作してサマリを生成する
}
```

<!-- # interact with the object to generate the summary -->

<!-- There are a couple of shortcut methods you can use to make this more straightforward. The `py_validate_xptr` function will do the check and automatically throw an error if it fails. So the example above could be re-written as: -->

これをより簡単に行うために，いくつかショートカット用メソッドが用意されています．`py_validate_xptr`関数は必要な確認を行い，失敗したら自動的にエラーを投げます．したがって上の例は次のように書き直すことができるでしょう．


```r
#' @export
summary.MyPythonClass <- function(object, ...) {
  py_validate_xptr(object)
  # オブジェクトを操作してサマリを生成する
}
```

<!-- Finally, the **reticulate** package exports a `py_str` generic method which is called from the `str` method only after doing appropriate validation (if the object is NULL then `<pointer: 0x0>` is returned). You can implement the `py_str` method as follows: -->

最後になりますが，**reticulate**パッケージは`py_str`総称関数をエクスポートしており，そのメソッドは`str`メソッドから適切な検証（オブジェクトがNULLなら`<pointer: 0x0>`を返す）を経た後にのみ呼び出されます[^tr1]．以下のようにして`py_str`のメソッドを実装できます．


```r
#' @importFrom reticulate py_str
#' @export 
py_str.MyPythonClass <- function(object, ...) {
  # オブジェクトを操作して文字列を生成する
}
```

<!-- # interact with the object to generate the string -->

<!-- So in short, to provide custom `str` and `print` methods, just implement `py_str`. For other S3 methods be sure to call either `py_validate_xptr` or `py_is_null_xptr` before interacting with the object. -->

要するに，カスタムの`str`メソッドや`print`メソッドを提供するには`py_str`を実装してください．その他のS3メソッドについては，オブジェクトを操作する前に必ず`py_validate_xptr`や`py_is_null_xptr`を呼ぶようにしてください．


[^tr1]: ［訳注］若干わかりにくいように思うので補足する．まずreticulateによって，任意のPythonオブジェクトはR側では`python.builtin.object`クラスを継承したオブジェクトとして見える．`python.builtin.object`に対しては`str`メソッドが定義されており，このメソッドが`py_str`総称関数を呼び出す．そして`py_str`総称関数は引数のチェックをした後にメソッドを呼ぶという構造になっている．
    
    
    ```r
    reticulate:::str.python.builtin.object
    ```
    
    ```
    ## function (object, ...) 
    ## {
    ##     cat(py_str(object), "\n", sep = "")
    ## }
    ## <environment: namespace:reticulate>
    ```
    
    ```r
    reticulate::py_str
    ```
    
    ```
    ## function (object, ...) 
    ## {
    ##     if (!inherits(object, "python.builtin.object")) 
    ##         py_str.default(object)
    ##     else if (py_is_null_xptr(object) || !py_available()) 
    ##         "<pointer: 0x0>"
    ##     else UseMethod("py_str")
    ## }
    ## <environment: namespace:reticulate>
    ```