"Python" (External Evaluation System)

Details

ExternalEvaluate Usage

  • ExternalEvaluate["Python",code] executes a code string in a Python REPL and returns the results as a Wolfram Language expression.
  • ExternalEvaluate["Python""String",code] executes the code string in a Python REPL and does not interpret the results.

Data Types

  • Not all Python built-in types are supported. The supported Python types are:
  • boolTrue|FalseBoolean values
    arrayNumericArrayarrays (from the NumPy library)
    bytearrayByteArraysequence of integers 0-255
    bytesByteArrayimmutable sequence of integers 0-255
    complexComplexcomplex number
    dateDateObjectspecific calendar date
    datetimeDateObjectspecific date with time granularity
    DecimalRealarbitrary-precision real number
    dictionaryAssociationassociation of keys and values
    floatRealreal-valued number
    FractionRationalfraction object from the fractions module
    frozensetListunordered immutable set of unique values
    ImageImageimage (from Python PIL library)
    intIntegerarbitrary-sized integer
    listListsequence of values
    longIntegerarbitrary-sized integer
    NoneNullnull value
    setListunordered set of unique values
    strStringsequence of character values
    tupleListordered sequence of values
  • The precision of a Real returned from a Decimal object is maintained when returned from ExternalEvaluate.
  • Python complex types are required to be real, and so any Complex expression returned from ExternalEvaluate will have real-valued components.

Usage Notes

  • String templates (<*…*>) can be used to evaluate and insert Wolfram Language expressions into the Python code string.

Examples

open allclose all

Basic Examples  (2)

Evaluate in Python and return the result:

Create a list in Python and return the result:

Type > to get a Python code cell that uses ExternalEvaluate to evaluate:

import math [math.sqrt(i) for i in range(10)]

Create a list with exponentials and logarithms:

[[i,math.exp(i),math.log(i)] for i in range(1,10)]

Create a list with the days of the week:

import calendar [calendar.day_name[i] for i in range(7)]

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:

Scope  (30)

Evaluate a Boolean statement in Python and return the result:

Create a byte array in Python and return its equivalent in the Wolfram Language:

Another way to work with a byte array in Python:

Python list, tuple, set and frozenset are converted to List:

Python dict are converted to Association:

When using a Python higher than 3.7, dictionary keys are ordered, just like Association:

Create a Complex number in Python and return the result:

Fractions are automatically converted to Rational:

Decimals are converted to Real:

Date-time objects are automatically converted:

Numpy arrays are automatically converted to NumericArray:

Pandas DataFrames are automatically converted to Dataset:

PIL images are automatically converted to Image:

Generators are automatically converted to List:

Any Python object that is iterable will be automatically converted to a List unless an explicit conversion method is implemented:

String templates can be used to insert Wolfram Language expressions into Python code. Set two variables:

The expression x^2+y^2 is evaluated in the Wolfram Language, and the result is converted and inserted into the Python code string:

Session Options  (9)

"ReturnType"  (3)

For the Python evaluation system, 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 by calling the Python function repr:

"Version"  (1)

You can use "Version" to make sure only a particular Python version is used:

You can specify a minor or patch version:

"Target"  (1)

Evaluate Python code using a specified "Target":

"SessionProlog"  (1)

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

"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  (11)

"Command"  (4)

When only a string of Python code 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 in 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)

By default, the command is executed using the "ReturnType" specified during the session creation:

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

"Arguments"  (2)

Use "Arguments" to call a Python function with arguments:

When a non-list argument is provided, a single argument is passed to the function:

If you need to pass a list as the first argument, you must 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:

You can also pass arguments by creating an ExternalFunction:

"Constants"  (1)

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

"TemplateArguments"  (3)

When running a command, you can inline a TemplateExpression:

You can explicitly fill TemplateSlot using "TemplateArguments":

When a non-list argument is provided, a single template argument is passed to the template:

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

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

Applications  (3)

Expose the Python range function in Wolfram Language:

Use the function:

Create a function that returns AST for a string of Python code using an AST module:

Use the function:

Use Pygments to create a function that is doing syntax highlighting of a block of code:

Use the function:

Properties & Relations  (1)

You can use to return expressions from Python:

Expressions automatically evaluate after they are transferred in a kernel.

Use Hold to control evaluation:

Close the session:

Possible Issues  (1)

Generators are automatically converted to List:

Returning an infinite generator will block your kernel forever: