# Calling Python from Erlang ## rpc and erpc A Pyrlang node answers Erlang's remote procedure calls. The module is imported on the Python side if it is not yet, and the function is called with the arguments: ```erlang (erl@127.0.0.1)1> rpc:call('py@127.0.0.1', math, sqrt, [16.0]). 4.0 (erl@127.0.0.1)2> erpc:call('py@127.0.0.1', 'os.path', basename, [<<"/a/b.txt">>]). <<"b.txt">> ``` - Module and function are Python names written as atoms; a dotted module name needs quotes, `'os.path'`. - `rpc:cast` and `erpc:cast` run the function and discard the result. - If the function raises, or the module or function does not exist, the call *returns* the exception, as `{<<"ValueError">>, #{<<"traceback">> => "Traceback ..."}}`. Erlang does not get `{badrpc, _}` or an `erpc` exception (see [Known differences](known-differences.md)). - The call runs on the event loop of the node: a function that takes long holds up everything else on it. The result has to be something that can be sent to Erlang (see [Data types](data_types.md)). Many Python functions return objects that cannot; for those there are notebook calls. ## Notebook calls A {py:class}`~pyrlang.notebook.Notebook` is a process on the Python node that keeps the results of calls. Erlang gets a reference to each result and passes it as an argument of later calls, so intermediate values never cross the wire. The Erlang side is the module `py.erl/py.erl` of the repository. It has no dependencies: copy it into your project. ```{literalinclude} ../../examples/e06_notebook_calls.erl :language: erlang ``` `py:new_context(Node)`, `py:new_context(Node, Options)` : Starts a notebook on the node. `Options` is a map; `history` (default 50) is how many results the notebook keeps. `py:call(Context, Path, Args)`, `py:call(Context, Path, Args, KwArgs)`, `py:call(Context, Path, Args, KwArgs, Options)` : Calls a function. The first element of `Path` is a module name or a result reference; the rest are attribute names leading to the callable. Arguments and keyword values may be result references. `Options`: `timeout` in milliseconds (default 5000); `immediate` (default `false`), with `true` the value itself is returned and nothing is stored. `py:retrieve(Context, ValueRef)` : Fetches a stored result. `py:get_type(ValueRef)` : The name of the Python type of a stored result, known without asking. `py:destroy(Context)` : Ends the notebook and drops what it holds. ## Batches A batch is a list of such calls built in Erlang and run on the Python node in one round trip. The same batch can be run on several nodes. ```{literalinclude} ../../examples/e07_notebook_batch.erl :language: erlang ``` `py:batch_new()` : An empty batch. `py:batch_call(Batch, Path, Args)`, `py:batch_call(Batch, Path, Args, KwArgs)` : Appends a call; returns the new batch and a reference to the call's future result. `py:batch_run(Context, Batch)`, `py:batch_run(Context, Batch, Options)` : Runs the batch in a notebook. `Options` as for `py:call`, except that `immediate` defaults to `true`: the result of the last call is returned.