WOLFRAM

Wolfram Language & System Documentation Center
Wolfram Language Home Page »

ExternalObject   
✖
ExternalObject

Listing of External Evaluators »
Unsupported in Public CloudUpdated in 14.1[Experimental]

✖

represents an external object bound to an ExternalSessionObject.

Details

Examples

open allclose all

Basic Examples  (1)Summary of the most common use cases

Create an external object in Python:

In[1]:=1
✖
https://wolfram.com/xid/0eny092r2-006yhw
Out[1]=1

Scope  (7)Survey of the scope of standard use cases

The keys displayed for functions in Python differ between a built-in function and a user-defined function:

In[1]:=1
✖
https://wolfram.com/xid/0eny092r2-mgqemg
Out[1]=1

Define an object in Python and display it:

In[2]:=2
✖
https://wolfram.com/xid/0eny092r2-8x7mug
Out[2]=2

Delete the session:

In[3]:=3
✖
https://wolfram.com/xid/0eny092r2-izrruj

External Operations  (6)

"Eval"  (2)

Start a Python session to work with strings:

In[1]:=1
✖
https://wolfram.com/xid/0eny092r2-jjm2rl
Out[1]=1

Create an ExternalObject with a string that contains valid Python code:

In[2]:=2
✖
https://wolfram.com/xid/0eny092r2-swuxd6
Out[2]=2

Use the "Eval" operation to evaluate the string to Python code:

In[3]:=3
✖
https://wolfram.com/xid/0eny092r2-uu8arf
Out[3]=3

Close the session:

In[4]:=4
✖
https://wolfram.com/xid/0eny092r2-tzoug5

Start a Python session to work with strings:

In[1]:=1
✖
https://wolfram.com/xid/0eny092r2-x4l9wv
Out[1]=1

Create an ExternalObject with a string that contains valid Python code with variables:

In[2]:=2
✖
https://wolfram.com/xid/0eny092r2-e06xod
Out[2]=2

Use the "Eval" operation to evaluate the string to Python code, using an evaluation context:

In[3]:=3
✖
https://wolfram.com/xid/0eny092r2-829z99
Out[3]=3

Close the session:

In[4]:=4
✖
https://wolfram.com/xid/0eny092r2-0yq2q

"Call"  (1)

Start a Python session:

In[1]:=1
✖
https://wolfram.com/xid/0eny092r2-4219i
Out[1]=1

Define an ExternalObject that creates a function in Python:

In[2]:=2
✖
https://wolfram.com/xid/0eny092r2-9h6w6f
Out[2]=2

Call the function by running the ExternalOperation "Call":

In[3]:=3
✖
https://wolfram.com/xid/0eny092r2-thi0xa
Out[3]=3

Any argument of the "Call" operation can be an ExternalOperation:

In[4]:=4
✖
https://wolfram.com/xid/0eny092r2-bvf64x
Out[4]=4

ExternalObject can also be used as an argument:

In[5]:=5
✖
https://wolfram.com/xid/0eny092r2-zq8db7
Out[5]=5
In[6]:=6
✖
https://wolfram.com/xid/0eny092r2-s7pq8q
Out[6]=6

Arguments can also be passed directly in ExternalEvaluate by doing:

In[7]:=7
✖
https://wolfram.com/xid/0eny092r2-7rmkso
Out[7]=7

The result is equivalent to running the following Python code:

In[8]:=8
✖
https://wolfram.com/xid/0eny092r2-knfcqv
Out[8]=8

Close the session:

In[9]:=9
✖
https://wolfram.com/xid/0eny092r2-qkk4vh

"GetAttribute"  (1)

Start a Python session to work with dates:

In[1]:=1
✖
https://wolfram.com/xid/0eny092r2-d7wsz4

Return an ExternalObject for a datetime object:

In[2]:=2
✖
https://wolfram.com/xid/0eny092r2-zkk45a
Out[2]=2

Extract the year attribute by using "GetAttribute":

In[3]:=3
✖
https://wolfram.com/xid/0eny092r2-jfln28
Out[3]=3

The same can be done using an ExternalObject subvalue:

In[4]:=4
✖
https://wolfram.com/xid/0eny092r2-1rthe2
Out[4]=4

For the Python evaluator, "GetAttribute" is the default operation, and ExternalOperation can be omitted:

In[5]:=5
✖
https://wolfram.com/xid/0eny092r2-cotv78
Out[5]=5

The result is equivalent to running the following Python code:

In[6]:=6
✖
https://wolfram.com/xid/0eny092r2-b1282w
Out[6]=6

Delete the session:

In[7]:=7
✖
https://wolfram.com/xid/0eny092r2-u5uste

"SetAttribute"  (1)

Start a Python session to work with decimal numbers:

In[1]:=1
✖
https://wolfram.com/xid/0eny092r2-lf5zl4

Get the context for the decimal module:

In[2]:=2
✖
https://wolfram.com/xid/0eny092r2-ds819o
Out[2]=2

Set the precision to 6:

In[3]:=3
✖
https://wolfram.com/xid/0eny092r2-602p3t

Check that the precision was set to 6:

In[4]:=4
✖
https://wolfram.com/xid/0eny092r2-4c6pmi
Out[4]=4
In[5]:=5
✖
https://wolfram.com/xid/0eny092r2-cbzrou
Out[5]=5

The result is equivalent to running the following Python code:

In[6]:=6
✖
https://wolfram.com/xid/0eny092r2-by53sd

Delete the session:

In[7]:=7
✖
https://wolfram.com/xid/0eny092r2-c3tha6

"Cast"  (1)

Create an ExternalObject that represents the current date:

In[1]:=1
✖
https://wolfram.com/xid/0eny092r2-2ful7n
In[2]:=2
✖
https://wolfram.com/xid/0eny092r2-lh03sx
Out[2]=2

Use "Expression" to return the object as a Wolfram Language expression:

In[3]:=3
✖
https://wolfram.com/xid/0eny092r2-k0ehns
Out[3]=3

The Cast operation can also run in ExternalObject subvalues:

In[4]:=4
✖
https://wolfram.com/xid/0eny092r2-jeanm1
Out[4]=4

The symbol Expression is a shortcut for the same:

In[5]:=5
✖
https://wolfram.com/xid/0eny092r2-pdqz05
Out[5]=5

Return the object as a string:

In[6]:=6
✖
https://wolfram.com/xid/0eny092r2-gqmk1m
Out[6]=6

The symbol String is a shortcut for the same:

In[7]:=7
✖
https://wolfram.com/xid/0eny092r2-yg8hmp
Out[7]=7

Return the object as an ExternalObject:

In[8]:=8
✖
https://wolfram.com/xid/0eny092r2-yt1eew
Out[8]=8

The symbol ExternalObject is a shortcut for the same:

In[9]:=9
✖
https://wolfram.com/xid/0eny092r2-xiafcd
Out[9]=9

The same can be achieved by using "ReturnType" in ExternalEvaluate:

In[10]:=10
✖
https://wolfram.com/xid/0eny092r2-bnmhjm
Out[10]=10

Delete the session:

In[11]:=11
✖
https://wolfram.com/xid/0eny092r2-wdx7xb

Properties & Relations  (6)Properties of the function, and connections to other functions

ExternalOperation can be used to extract the operation from an ExternalObject:

In[1]:=1
✖
https://wolfram.com/xid/0eny092r2-p7tziq
Out[1]=1

The same can be done with an ExternalFunction:

In[2]:=2
✖
https://wolfram.com/xid/0eny092r2-dif7v0
Out[2]=2

ExternalOperation can be used as an argument to ExternalObject:

In[1]:=1
✖
https://wolfram.com/xid/0eny092r2-ixfzu5
Out[1]=1

The executed operation is identical to the following one:

In[2]:=2
✖
https://wolfram.com/xid/0eny092r2-mu3hbe
Out[2]=2

Which can be executed with ExternalEvaluate:

In[3]:=3
✖
https://wolfram.com/xid/0eny092r2-7b07hd
Out[3]=3

The result is equivalent to running the following Python code:

In[4]:=4
✖
https://wolfram.com/xid/0eny092r2-pzgu6c
Out[4]=4

Create an ExternalObject to work with the sys module:

In[1]:=1
✖
https://wolfram.com/xid/0eny092r2-tp546g
Out[1]=1

When a string is used, the "GetAttribute" operation is executed in most evaluators, including Python:

In[2]:=2
✖
https://wolfram.com/xid/0eny092r2-egqaxa
Out[2]=2

The result is equivalent to running an explicit "GetAttribute" operation:

In[3]:=3
✖
https://wolfram.com/xid/0eny092r2-9dppjt
Out[3]=3

Start a Python session:

In[1]:=1
✖
https://wolfram.com/xid/0eny092r2-k1043h
Out[1]=1

Create an ExternalObject:

In[2]:=2
✖
https://wolfram.com/xid/0eny092r2-3de5c9
Out[2]=2

Use ExternalFunction to run methods on the object:

In[3]:=3
✖
https://wolfram.com/xid/0eny092r2-nsaukm
Out[3]=3

Close the session:

In[4]:=4
✖
https://wolfram.com/xid/0eny092r2-vb2q92

Start a Python session:

In[1]:=1
✖
https://wolfram.com/xid/0eny092r2-bsyuoc
Out[1]=1

Create an ExternalObject for the datetime module:

In[2]:=2
✖
https://wolfram.com/xid/0eny092r2-zsnlru
Out[2]=2

Create an ExternalObject with the current date and another one with a timedelta:

In[3]:=3
✖
https://wolfram.com/xid/0eny092r2-s542nf
Out[3]=3

Send back the objects using an ExternalFunction:

In[4]:=4
✖
https://wolfram.com/xid/0eny092r2-cwcyon
Out[4]=4

The same can be done with an ExternalEvaluate call:

In[5]:=5
✖
https://wolfram.com/xid/0eny092r2-i9xnki
Out[5]=5

Use "ReturnType" to return a String:

In[6]:=6
✖
https://wolfram.com/xid/0eny092r2-3r3rxu
Out[6]=6

Close the session:

In[7]:=7
✖
https://wolfram.com/xid/0eny092r2-in0ms8

Multiple operations can be concatenated using multiple arguments in ExternalObject:

In[1]:=1
✖
https://wolfram.com/xid/0eny092r2-o4lbb2
Out[1]=1
In[2]:=2
✖
https://wolfram.com/xid/0eny092r2-oxalvx
Out[2]=2

Which can be written in a more compact way:

In[3]:=3
✖
https://wolfram.com/xid/0eny092r2-ey2dbb
Out[3]=3

Possible Issues  (1)Common pitfalls and unexpected behavior

Running successive operations using downvalues can lead to undefined behavior without checking the return value at every step:

In[1]:=1
✖
https://wolfram.com/xid/0eny092r2-4gjf7v
In[2]:=2
✖
https://wolfram.com/xid/0eny092r2-j4knlk
Out[2]=2
In[3]:=3
✖
https://wolfram.com/xid/0eny092r2-7s5qxn
Out[3]=3

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:

In[4]:=4
✖
https://wolfram.com/xid/0eny092r2-38hbg1
Out[4]=4

In order to safely chain operations without checking the return type at every step, run all operations at once:

In[5]:=5
✖
https://wolfram.com/xid/0eny092r2-rh80cu
Out[5]=5

A Failure object is returned as soon as any operation fails, preventing others from running:

In[6]:=6
✖
https://wolfram.com/xid/0eny092r2-zxk03r
Out[6]=6

Delete the session:

In[7]:=7
✖
https://wolfram.com/xid/0eny092r2-1u6vqw

Neat Examples  (1)Surprising or curious use cases

Start a Python session to play chess:

In[1]:=1
✖
https://wolfram.com/xid/0eny092r2-69y4m0
Out[1]=1

Create an ExternalObject to represent that state of the chess board:

In[2]:=2
✖
https://wolfram.com/xid/0eny092r2-5qubie
Out[2]=2

Define a function to plot the board:

In[3]:=3
✖
https://wolfram.com/xid/0eny092r2-lbo6yx

Use the function to plot the board:

In[4]:=4
✖
https://wolfram.com/xid/0eny092r2-yywky5
Out[4]=4

Extract the current move number by extracting an attribute from the object:

In[5]:=5
✖
https://wolfram.com/xid/0eny092r2-5snecj
Out[5]=5

Move a piece by running a function; it will change the state of the external object:

In[6]:=6
✖
https://wolfram.com/xid/0eny092r2-vf6glr
Out[6]=6

Plot the board again to display the new configuration:

In[7]:=7
✖
https://wolfram.com/xid/0eny092r2-xuhsa5
Out[7]=7

You can now compute all legal moves that can be done with the current configuration:

In[8]:=8
✖
https://wolfram.com/xid/0eny092r2-xnoclv

Create a method caller for the "UCI" property by chaining external operations:

In[9]:=9
✖
https://wolfram.com/xid/0eny092r2-dsdo7o
Out[9]=9

Compute the UCI string for one move:

In[10]:=10
✖
https://wolfram.com/xid/0eny092r2-oymcf9
Out[10]=10

You can now execute one random move:

In[11]:=11
✖
https://wolfram.com/xid/0eny092r2-lmxasj
Out[11]=11

You can use the plot function to show the board again:

In[12]:=12
✖
https://wolfram.com/xid/0eny092r2-yv9hcj
Out[12]=12

Create a function to play random moves:

In[13]:=13
✖
https://wolfram.com/xid/0eny092r2-qmr9xi

Play some random chess:

In[14]:=14
✖
https://wolfram.com/xid/0eny092r2-m6gati
Out[14]=14

Show the current move counter:

In[15]:=15
✖
https://wolfram.com/xid/0eny092r2-f4bygb
Out[15]=15

Delete the session:

In[16]:=16
✖
https://wolfram.com/xid/0eny092r2-wiubbv
Wolfram Research (2018), ExternalObject, Wolfram Language function, https://reference.wolfram.com/language/ref/ExternalObject.html (updated 2024).
✖
Wolfram Research (2018), ExternalObject, Wolfram Language function, https://reference.wolfram.com/language/ref/ExternalObject.html (updated 2024).

Text

Wolfram Research (2018), ExternalObject, Wolfram Language function, https://reference.wolfram.com/language/ref/ExternalObject.html (updated 2024).

✖
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.

✖
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

✖
Wolfram Language. (2018). ExternalObject. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/ExternalObject.html

BibTeX

@misc{reference.wolfram_2025_externalobject, author="Wolfram Research", title="{ExternalObject}", year="2024", howpublished="\url{https://reference.wolfram.com/language/ref/ExternalObject.html}", note=[Accessed: 25-March-2025 ]}

✖
@misc{reference.wolfram_2025_externalobject, author="Wolfram Research", title="{ExternalObject}", year="2024", howpublished="\url{https://reference.wolfram.com/language/ref/ExternalObject.html}", note=[Accessed: 25-March-2025 ]}

BibLaTeX

@online{reference.wolfram_2025_externalobject, organization={Wolfram Research}, title={ExternalObject}, year={2024}, url={https://reference.wolfram.com/language/ref/ExternalObject.html}, note=[Accessed: 25-March-2025 ]}

✖
@online{reference.wolfram_2025_externalobject, organization={Wolfram Research}, title={ExternalObject}, year={2024}, url={https://reference.wolfram.com/language/ref/ExternalObject.html}, note=[Accessed: 25-March-2025 ]}