Details

• ExternalEvaluate[sys,"cmd"] returns either the result of evaluating cmd using the external evaluator system or a Failure object.
• In ExternalEvaluate[sys,obj], the contents of the external object obj will be used as the command. The external object can be File[…], URL[…], CloudObject[…] or LocalObject[…].
• In ExternalEvaluate[sys,…], possible choices of sys include:
• "Python"Python "NodeJS"JavaScript running through Node.js "Julia"Julia "Ruby"Ruby "R"R "Java"Java "Octave"Octave "Shell"Bash, Sh, Zsh, ... "Jupyter"Jupyter kernel "SQL"SQL database "SQL-JDBC"SQL database using JDBC ExternalSessionObject[…]session object started by StartExternalSession
• In ExternalEvaluate[assoc,cmd], elements of assoc can include:
• "System"the external system or language to start "Evaluator"the specific evaluator to execute code "Name"the registered name of an evaluator "ReturnType"type of object to return ("String", "Expression", ...) "Prolog"code to run before the command "Epilog"code to run after the command "SessionProlog"code to run before the session "SessionEpilog"code to run after the session
• In ExternalEvaluate[assoc,cmd], elements of the association cmd can include:
• "Command"the command string to execute "ReturnType"type of object to return ("String", "Expression", ...) "Arguments"the arguments to call the command with "Constants"variables to set before executing the command "TemplateArguments"template arguments, if "Command" is a template
• Possible settings for "type" in ExternalEvaluate[sys->"type",…], or for "ReturnType", include:
• "Expression"attempt to convert to a Wolfram Language expression "String"give the raw string output by the external evaluator
• The possible settings for evaluator in ExternalEvaluate[{sys,"Evaluator"evaluator},…] depend on sys and include:
• "path"path to a language executable DatabaseReference[…]an SQL database connection SQLConnection[…]an SQL-JDBC database connection
• Typically, ExternalEvaluate uses the setting "ReturnType""Expression".
• In the form ExternalEvaluate[{"sys",opts},…], the possible options are the same as the keys for the association in ExternalEvaluate[assoc,…].
• The command "cmd" may contain an inline template expression <*expr*>. This evaluates expr before "cmd" is sent to the external evaluator.
• ExternalEvaluate[sys,cmd] launches the external evaluator, evaluates cmd, then exits the external session.
• ExternalEvaluate[session,cmd] sends the command to a running session and does not exit the session.
• When sys is specified as a string, the session options used are searched first for user-specified options specified using RegisterExternalEvaluator, then from built-in session options included with the system or automatically discovered.
• FindExternalEvaluators gives a dataset of evaluator systems that can be used.
• For most external evaluators, individual write operations to standard output are immediately printed to the notebook or terminal.

Examples

Basic Examples  (10)

Evaluate a simple arithmetic expression in Python:

Evaluate a basic math function in JavaScript using Node.js:

Import a library in Python and use a function:

Evaluate multiple lines of code in a Python session:

Use the File wrapper to execute code contained in a file:

Deploy code using CloudDeploy and then run the code directly from a CloudObject:

Use a URL wrapper to directly run code hosted online:

A Julia dictionary is returned as an Association:

Evaluate a function by name using a single Wolfram Language expression as the argument:

Evaluate a query in a database and return the result:

Use > at the beginning of a line to start an external code cell evaluated with ExternalEvaluate:

Evaluate code in a Python provisioned environment:

Scope  (26)

Compute powers of 10 using a range of numbers in Python:

Returning the result as a Python dict gives an Association:

Many types, like datetime, are natively mapped to Wolfram Language expressions:

Add two numbers in Python using an inline TemplateExpression:

Session Options  (13)

"ReturnType"  (4)

For most systems, the default return type is "Expression":

Numbers, strings, lists and associations are automatically imported for the "Expression" return type:

The return type of "String" returns a string of the result in the external language:

When using a database, the default return type is "Dataset":

"ReturnType" can be used to return data in a different form:

"Evaluator"  (3)

Evaluate code using a specified "Evaluator":

When using a File with the "SQL" evaluator, the evaluator can be a path to an SQLite file or a DatabaseReference specification:

An Association can be used to evaluate code in a Python provisioned environment:

"Name"  (1)

Register an evaluator using a name:

Use the registered evaluator by referring to it by name:

"SessionProlog"  (2)

Use "SessionProlog" to perform a side effect at the start of a session:

Start an external session and import a library at the beginning of the session:

Evaluate a function from the imported library:

Delete the session object:

"SessionEpilog"  (1)

Use "SessionEpilog" to perform a side effect at the end of a session:

"Prolog"  (1)

Use "Prolog" to perform a side effect before every evaluation:

"Epilog"  (1)

Use "Epilog" to perform a side effect after every evaluation:

Command Options  (10)

"Command"  (4)

When a string is provided, the command is directly executed:

The above is equivalent to writing the command using this form:

Use a File wrapper to run the code from a file:

The above is equivalent to writing the command using this form:

Use a URL wrapper to directly run code hosted online:

The above is equivalent to writing the command using this form:

Put code in a CloudObject:

Evaluate directly from the cloud:

The above is equivalent to writing the command using this form:

"ReturnType"  (1)

Specifying a "ReturnType" in the command overrides the "ReturnType" for the session:

"Arguments"  (2)

Use "Arguments" to call the command with arguments:

For a single argument, you do not need to use a list:

If you need to pass a list as first argument, you need to wrap it with an extra list explicitly:

You can define a function inside "Command" and directly call it with "Arguments":

The same result can be achieved by using a Rule:

An alternative method is to define an ExternalFunction:

"Constants"  (1)

Use "Constants" to permanently set global variables before the command runs:

"TemplateArguments"  (2)

When running a command, you can inline a TemplateExpression:

You can explicitly fill TemplateSlot using "TemplateArguments":

If you need to pass a list as first argument, you need to wrap it with an extra list explicitly:

You can name template slots and use an Association to pass named arguments to the template:

Applications  (1)

Evaluate a query in a database and return the result:

Properties & Relations  (4)

When an evaluation fails, a Failure object is returned:

The type of exception thrown is accessible inside the failure object:

External language cells implicitly call StartExternalSession:

A new session has been started:

By default, all cells of a given system use that session:

End the session so that subsequent evaluations start in a new session:

The same session is used when running a list of commands:

Separate sessions are used in a list of separate ExternalEvaluate calls:

The "String" and "Expression" return types can be related using import and export:

Use ImportString with "PythonExpression" to convert a Python string to an expression:

Conversely, use ExportString to convert an expression to its Python string:

Possible Issues  (1)

External language cells implicitly call StartExternalSession and use a single session:

Unless given an ExternalSessionObject, each ExternalEvaluate call uses a separate session:

For persistent evaluation, use StartExternalSession:

Each evaluation takes place in the same process:

Delete the session: