-
See Also
- StartExternalSession
- ExternalEvaluate
- ExternalSessionObject
- ExternalFunction
- ExternalOperation
-
- External Evaluation Systems
- Python
- NodeJS
- Ruby
- Related Guides
represents an external object bound to an ExternalSessionObject.
ExternalObject
Listing of External Evaluators »represents an external object bound to an ExternalSessionObject.
Details
- ExternalObject is a reference to external data that is returned by some ExternalEvaluate systems, such as "Python", "Ruby", "NodeJS".
- An ExternalObject[…] is specific to a particular ExternalSessionObject, which may not be persistent.
- ExternalObject[…]["name"] in most evaluators is identical to ExternalObject[…][ExternalOperation["GetAttribute", "name"]].
- ExternalObject[…][ExternalOperation[…]] is equivalent to ExternalEvaluate[session,ExternalOperation[…][ExternalObject[…]]], where session is implied by the ExternalObject[…].
- ExternalObject[…][op1,op2,…] is identical to ExternalEvaluate[session,RightComposition[op1,op2,…][ExternalObject[…]]].
- ExternalObject[…][{op1,op2,…}] is identical to ExternalEvaluate[session, {op1[ExternalObject[…]],op2[ExternalObject[…]],…}].
Examples
open all close allBasic Examples (1)
Scope (7)
The keys displayed for functions in Python differ between a built-in function and a user-defined function:
py = StartExternalSession["Python"]Define an object in Python and display it:
ExternalEvaluate[py, "class MyObject: pass"];
ExternalEvaluate[py, "MyObject()"]DeleteObject[py]External Operations (6)
"Eval" (2)
Start a Python session to work with strings:
session = StartExternalSession["Python"]Create an ExternalObject with a string that contains valid Python code:
obj = ExternalEvaluate[session, <|"Command" -> "'2+2'", "ReturnType" -> "ExternalObject"|>]Use the "Eval" operation to evaluate the string to Python code:
obj[ExternalOperation["Eval"]]DeleteObject[session]Start a Python session to work with strings:
session = StartExternalSession["Python"]Create an ExternalObject with a string that contains valid Python code with variables:
obj = ExternalEvaluate[session, <|"Command" -> "'a+b'", "ReturnType" -> "ExternalObject"|>]Use the "Eval" operation to evaluate the string to Python code, using an evaluation context:
obj[ExternalOperation["Eval", <|"a" -> 2, "b" -> 3|>]]DeleteObject[session]"Call" (1)
session = StartExternalSession["Python"]Define an ExternalObject that creates a function in Python:
obj = ExternalEvaluate[session, <|"Command" -> "max", "ReturnType" -> "ExternalObject"|>]Call the function by running the ExternalOperation "Call":
obj[ExternalOperation["Call", 1, 2]]Any argument of the "Call" operation can be an ExternalOperation:
obj[ExternalOperation["Call", 1, ExternalOperation["Eval", "2+2"]]]ExternalObject can also be used as an argument:
n = ExternalEvaluate[session, <|"Command" -> "2+2", "ReturnType" -> "ExternalObject"|>]obj[ExternalOperation["Call", 1, n]]Arguments can also be passed directly in ExternalEvaluate by doing:
ExternalEvaluate[session, obj -> {1, 2}]The result is equivalent to running the following Python code:
ExternalEvaluate[session, "max(1, 2)"]DeleteObject[session]"GetAttribute" (1)
Start a Python session to work with dates:
session = StartExternalSession[{"Python", "SessionProlog" -> "import datetime"}];Return an ExternalObject for a datetime object:
now = ExternalEvaluate[session, <|"Command" -> "datetime.datetime.now()", "ReturnType" -> "ExternalObject"|>]Extract the year attribute by using "GetAttribute":
ExternalEvaluate[session, ExternalOperation["GetAttribute", now, "year"]]The same can be done using an ExternalObject subvalue:
now[ExternalOperation["GetAttribute", "year"]]For the Python evaluator, "GetAttribute" is the default operation, and ExternalOperation can be omitted:
now["year"]The result is equivalent to running the following Python code:
ExternalEvaluate[session, "datetime.datetime.now().year"]DeleteObject[session]"SetAttribute" (1)
Start a Python session to work with decimal numbers:
session = StartExternalSession[{"Python", "SessionProlog" -> "from decimal import getcontext, Decimal"}];Get the context for the decimal module:
context = ExternalEvaluate[session, "getcontext()"]ExternalEvaluate[session, ExternalOperation["SetAttribute", context, "prec", 6]]Check that the precision was set to 6:
ExternalEvaluate[session, ExternalOperation["GetAttribute", context, "prec"]]ExternalEvaluate[session, "Decimal('0') + Decimal('0.123456789')"]The result is equivalent to running the following Python code:
ExternalEvaluate[session, "getcontext().prec = 6"]DeleteObject[session]"Cast" (1)
Create an ExternalObject that represents the current date:
session = StartExternalSession["Python"];now = ExternalEvaluate[session, <|"Command" -> "import datetime; datetime.datetime.now()", "ReturnType" -> "ExternalObject"|>]Use "Expression" to return the object as a Wolfram Language expression:
ExternalEvaluate[session, ExternalOperation["Cast", now, "Expression"]]The Cast operation can also run in ExternalObject subvalues:
now[ExternalOperation["Cast", "Expression"]]The symbol Expression is a shortcut for the same:
now[Expression]Return the object as a string:
now[ExternalOperation["Cast", "String"]]The symbol String is a shortcut for the same:
now[String]Return the object as an ExternalObject:
now[ExternalOperation["Cast", "ExternalObject"]]The symbol ExternalObject is a shortcut for the same:
now[ExternalObject]The same can be achieved by using "ReturnType" in ExternalEvaluate:
ExternalEvaluate[session, <|"Command" -> now, "ReturnType" -> "String"|>]DeleteObject[session]Properties & Relations (6)
ExternalOperation can be used to extract the operation from an ExternalObject:
ExternalOperation[ExternalObject["Python", "2+2"]]The same can be done with an ExternalFunction:
ExternalOperation[ExternalFunction["Python", "str"]]ExternalOperation can be used as an argument to ExternalObject:
ExternalObject["Python", "len"][ExternalOperation["Call", {1, 2, 3}]]The executed operation is identical to the following one:
op = ExternalOperation["Call", {1, 2, 3}][ExternalObject["Python", "len"]]Which can be executed with ExternalEvaluate:
ExternalEvaluate["Python", op]The result is equivalent to running the following Python code:
ExternalEvaluate["Python", "len((1, 2, 3))"]Create an ExternalObject to work with the sys module:
sys = ExternalObject["Python", ExternalOperation["Import", "sys"]]When a string is used, the "GetAttribute" operation is executed in most evaluators, including Python:
sys["maxsize"]The result is equivalent to running an explicit "GetAttribute" operation:
sys[ExternalOperation["GetAttribute", "maxsize"]]session = StartExternalSession["Python"]Create an ExternalObject:
module = ExternalEvaluate[session, ExternalOperation["Import", "datetime"]]Use ExternalFunction to run methods on the object:
ExternalFunction[module, "date"][2012, 10, 10]DeleteObject[session]session = StartExternalSession["Python"]Create an ExternalObject for the datetime module:
datetime = ExternalEvaluate[session, ExternalOperation["Import", "datetime"]]Create an ExternalObject with the current date and another one with a timedelta:
{now, tenhours} = {datetime["datetime", "now" -> {}, ExternalObject], datetime["timedelta" -> {"hours" -> 10}, ExternalObject]}Send back the objects using an ExternalFunction:
ExternalFunction[session, "lambda obj, n: obj + n"][now, tenhours]The same can be done with an ExternalEvaluate call:
ExternalEvaluate[session, "lambda obj, n: obj + n" -> {now, tenhours}]Use "ReturnType" to return a String:
ExternalEvaluate[session, <|"Command" -> "lambda obj, n: obj + n", "Arguments" -> {now, tenhours}, "ReturnType" -> "String"|>]DeleteObject[session]Multiple operations can be concatenated using multiple arguments in ExternalObject:
uuid = ExternalObject["Python", ExternalOperation["Import", "uuid"]]uuid[ExternalOperation["GetAttribute", "uuid4"], ExternalOperation["Call"], ExternalOperation["Cast", "String"]]Which can be written in a more compact way:
uuid["uuid4" -> {}, String]Possible Issues (1)
Running successive operations using downvalues can lead to undefined behavior without checking the return value at every step:
session = StartExternalSession[{"Python", "SessionProlog" -> "import datetime"}];obj = ExternalEvaluate[session, "datetime"]obj["date" ][ExternalOperation["Call", 2022, 10, 1]]This is happening because the first operation is returning an ExternalFunction (since date is a class that can be initialized) and you are passing an incomplete ExternalOperation to the date constructor:
obj["date" ]In order to safely chain operations without checking the return type at every step, run all operations at once:
obj["date", ExternalOperation["Call", 2022, 10, 1]]A Failure object is returned as soon as any operation fails, preventing others from running:
obj["not_a_valid_attribute", ExternalOperation["Call", 2022, 10, 1]]DeleteObject[session]Neat Examples (1)
Start a Python session to play chess:
session = StartExternalSession[{"Python", "Evaluator" -> <|"Dependencies" -> "chess"|>, "SessionProlog" -> "import chess, chess.svg"}]Create an ExternalObject to represent that state of the chess board:
board = ExternalEvaluate[session, "chess.Board()"]Define a function to plot the board:
PlotBoard[b_] := ImportString[ExternalFunction[session, "chess.svg.board"][b], "SVG"]Use the function to plot the board:
PlotBoard[board]Extract the current move number by extracting an attribute from the object:
board["fullmove_number"]Move a piece by running a function; it will change the state of the external object:
board["push_san" -> "e4"]Plot the board again to display the new configuration:
PlotBoard[board]You can now compute all legal moves that can be done with the current configuration:
moves = board["legal_moves"];Create a method caller for the "UCI" property by chaining external operations:
ucigetter = ExternalOperation["GetAttribute", "uci"] /* ExternalOperation["Call"]Compute the UCI string for one move:
ExternalEvaluate[session, ucigetter[RandomChoice[moves]]]You can now execute one random move:
board["push_san" -> ucigetter[RandomChoice[moves]]]You can use the plot function to show the board again:
PlotBoard[board]Create a function to play random moves:
RandomChessPlay[board_, n_Integer : 1, processor_ : Identity] := Table[board["push_san" -> ucigetter[RandomChoice[board["legal_moves"]]]];processor[board], n]Column[RandomChessPlay[board, 4, PlotBoard]]Show the current move counter:
board["fullmove_number"]DeleteObject[session]See Also
StartExternalSession ExternalEvaluate ExternalSessionObject ExternalFunction ExternalOperation
External Evaluation Systems: Python NodeJS Ruby
Function Repository: PythonObject
Related Guides
Text
Wolfram Research (2018), ExternalObject, Wolfram Language function, https://reference.wolfram.com/language/ref/ExternalObject.html (updated 2024).
CMS
Wolfram Language. 2018. "ExternalObject." Wolfram Language & System Documentation Center. Wolfram Research. Last Modified 2024. https://reference.wolfram.com/language/ref/ExternalObject.html.
APA
Wolfram Language. (2018). ExternalObject. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/ExternalObject.html
BibTeX
@misc{reference.wolfram_2026_externalobject, author="Wolfram Research", title="{ExternalObject}", year="2024", howpublished="\url{https://reference.wolfram.com/language/ref/ExternalObject.html}", note=[Accessed: 12-June-2026]}
BibLaTeX
@online{reference.wolfram_2026_externalobject, organization={Wolfram Research}, title={ExternalObject}, year={2024}, url={https://reference.wolfram.com/language/ref/ExternalObject.html}, note=[Accessed: 12-June-2026]}