Function Repository Resource:

PythonObject (1.2.0) current version: 1.4.0 »

Create a Wolfram Language representation of a Python object

Contributed by: Igor Bakshee

ResourceFunction["PythonObject"][<|…|>]

represents a Python object defined in an ExternalSessionObject.

ResourceFunction["PythonObject"][session,"cmd"]

evaluates cmd in the specified running ExternalSessionObject and creates a reference to the resulting external object.

ResourceFunction["PythonObject"]["cmd"]

starts a new external session and evaluates cmd.

ResourceFunction["PythonObject"][…][prop]

gives the specified property of the ResourceFunction["PythonObject"][…].

ResourceFunction["PythonObject"][…][func[args,opts]]

calls the function func defined in the Python object with the specified arguments and options.

ResourceFunction["PythonObject"][…][All][args,opts]]

invokes the callable Python object with the specified arguments and options.

Details and Options

ResourceFunction["PythonObject"][…] is a Wolfram-Language representation of a Python-side object created with ExternalEvaluate.

ResourceFunction["PythonObject"][session,"cmd"] effectively executes ExternalEvaluate[session,"cmd"] and returns either its output, ResourceFunction["PythonObject"][…], or an expression containing one or more Python objects. The ResourceFunction["PythonObject"] is returned when the output contains ExternalObject[…], ExternalFunction[…] or certain Python-side objects.

ResourceFunction["PythonObject"][…] is also returned for some specific types of ExternalEvaluate failures, such as the ones resulting from an error in passing a valid object to the Wolfram Language.

ResourceFunction["PythonObject"][session,"cmd",True] returns ResourceFunction["PythonObject"][…] even for simplest objects, such as integers or strings, or a Failure object if the result of executing "cmd” does not represent a Python object.

ResourceFunction["PythonObject"][session,"cmd",False] returns the raw output of ExternalEvaluate.

ResourceFunction["PythonObject"][session,"cmd",…,Initialization→init] performs the specified initialization of the Python session prior to creating the Python object. With the default setting Initialization→Automatic, ResourceFunction["PythonObject"] attempts to detect, install, and import packages required for successful execution of"cmd". Other possible values of init are:

"cmd₁;cmd₂;…"

execute the specified commands

None

no initialization

The commands "cmd_i" typically include one or more import statements. If needed, the necessary packages are installed automatically using the resource function PythonEvaluateWithDependencies.

ResourceFunction["PythonObject"] takes the option "Configuration" that makes using Python objects more convenient. Configurations are typically provided by Wolfram Research or other developers. See Author Notes for details. Possible option values include:

ResourceFunction["f"]

resource function

"Custom"

interactively defined

Automatic

automatic

None

no configuration

Non-default configurations are identified by an icon specific to the configuration or the generic gear icon

Available properties of a Python object p can be queried with p["Properties"]. With a few exceptions, the list does not include "non-public" names that begin with an underscore "_".

Properties of a ResourceFunction["PythonObject"] include object-specific properties as well as the following properties:

"Session"

ExternalSessionObject

"PythonReference"

a reference to the Python-side object

"ReferenceValid"

whether the reference corresponds to an active Python session

"Information"

Python-side information

"FullInformation"

recursive information for modules

"RawInformation"

Python-side help

"Configuration"

configuration

Object-specific properties include:

"IsCallable"

callable object

"IsModule"

module

"IsClass"

class

"IsFunction"

function

"IsBuiltin"

built-in function

The default property is "PythonReference".

ResourceFunction["PythonObject"][…]["Information","obj"] gives information on function or class objects defined in the parent module or methods of the parent class.

For callable objects, "Information" also contains the expected call signature including:

"Arguments"

arguments

"Options"

options

Optional signature elements include:

“VarArgs"

whether the function accepts variable number of positional arguments

“KeywordOnlyArguments"

arguments that must be specified by name

“KeywordOnlyDefaults"

default values of named arguments

“KeywordArguments"

association of named arguments

In ResourceFunction["PythonObject"], both optional positional arguments and named arguments of functions and callable objects are given as Wolfram Language options.

For a ResourceFunction["PythonObject"] p that represents a Python module, p["FullInformation",type] gives a list of attributes of the specified type defined in the module itself and its submodules, recursively. The type can be one of the following:

"Functions"

functions

"Classes"

classes

"Modules"

modules

ResourceFunction["PythonObject"][session,{"cmd₁","cmd₂",…}] returns a list of objects.

ResourceFunction["PythonObject"][session,{"cmd₁","cmd₂",…},{policy₁,policy₂,…}] applies policy_i when creating an object from cmd_i. The policy_i values can be True, False or Automatic.

ResourceFunction["PythonObject"][{"cmd₁","cmd₂",…},…] starts a new ExternalSession and creates all obj_i in that session.

In ResourceFunction["PythonObject"][…][prop] and ResourceFunction["PythonObject"][…][func[args,opts]], prop, func and options names can be specified as a string or, as long as a name does not include underscores "_", a symbol.

When there is more than one function with the specified name in the Python object, the function name must be given as a string, in the fully qualified dot notation "module₁.module₂….name", or as a symbol in the corresponding nested context module₁`module₂`…`name.

Option names in opts can be given as strings or symbols in any context.

ResourceFunction["PythonObject"][…]["Assign"["var"→val]] sets the value of the ResourceFunction["PythonObject"] variable to the specified value.

For a ResourceFunction["PythonObject"] p representing a callable object, such as classes, callable instances, or functions, the Python-side object can be invoked with p[All][args,opts].

Arguments and options must be given as exportable Python expressions, ExternalFunction object or ResourceFunction["PythonObject"].

For a ResourceFunction["PythonObject"] p, Normal[p] gives an expression containing components of p.

ResourceFunction["PythonObject"][p,policy] recreates the ResourceFunction["PythonObject"] p with the specified policy.

ResourceFunction["PythonObject"][p,prop,policy] and ResourceFunction["PythonObject"][p,func[args,opts],policy] return the specified property prop and the result of calling the function func, using the specified policy.

ResourceFunction["PythonObject"][session,"TemporaryPackage"[assoc]] creates a Python object from a package specified by the association assoc deployed in a temporary directory.

DeleteObject[p] deletes the Python-side reference to the ResourceFunction["PythonObject"] p.

Deleting ResourceFunction["PythonObject"][…] is typically not necessary in short sessions or if the session is about to be closed anyway.

A ResourceFunction["PythonObject"][…] is specific to a particular ExternalSessionObject, which may not be persistent.

DeleteObject[p["Session"]] kills the Python session in which the ResourceFunction["PythonObject"] p is defined.

Examples

Basic Examples (2)

Create a Python object for a package:

In[1]:=

Out[1]=

Explore its contents:

In[2]:=

Out[2]=

Create an instance of a class in the package:

In[3]:=

Out[3]=

Examine its contents:

In[4]:=

Out[4]=

Get a the value of an instance variable:

In[5]:=

Out[5]=

Find the signature of a method:

In[6]:=

Out[6]=

Call the method:

In[7]:=

Out[7]=

Uninstall the package and close the session to clean up:

In[8]:=

Out[8]=

In[9]:=

Define a simple class in Python:

In[10]:=

Out[10]=

In[11]:=

ExternalEvaluate[session, "class MyClass:
cvar = 'myClassVariable'
def __init__(self, x):
self.x = x
print('instance initialized with '+str(x))
def __call__(self, x):
self.x = x
return 'instance called with '+str(x)
def f(self,x,y):
self.x = x
self.y = y
return 'f() fired with '+str(x)+', '+str(y)
"]

Out[11]=

Create a Python object referring to the class:

In[12]:=

Out[12]=

Get the value of a class variable from Python:

In[13]:=

Out[13]=

Create an instance of the class:

In[14]:=

Out[14]=

Check the instance variable:

In[15]:=

Out[15]=

Set the value of the variable and check the new value:

In[16]:=

Out[16]=

In[17]:=

Out[17]=

Call a method function of the instance:

In[18]:=

Out[18]=

Check the new instance variables:

In[19]:=

Out[19]=

Close the session:

In[20]:=

Scope (30)

Basic Usage (7)

A single Python object:

In[21]:=

Out[21]=

In[22]:=

Multiple objects:

In[23]:=

Out[23]=

In[24]:=

Components of a Python list:

In[25]:=

Out[25]=

In[26]:=

Python dictionaries containing objects:

In[27]:=

In[28]:=

Out[28]=

In[29]:=

Create a PythonObject[…] only for those objects that do not have a Wolfram Language representation:

In[30]:=

In[31]:=

In[32]:=

Out[32]=

Create Python objects for all objects, even the simplest:

In[33]:=

Out[33]=

In[34]:=

Get a list of of items in a Python tuple:

In[35]:=

In[36]:=

Out[36]=

In[37]:=

Out[37]=

Get the tuple as PythonObject:

In[38]:=

Out[38]=

Get the tuple components:

In[39]:=

Out[39]=

In[40]:=

Define an instance object in Python and access its Python-side property:

In[41]:=

In[42]:=

ExternalEvaluate[session, "class MyClass:
def __init__(self, x):
self.x = x*x
def f(self,y):
return y+100
"]

Out[42]=

In[43]:=

Out[43]=

In[44]:=

Out[44]=

Assign a new value to the property:

In[45]:=

Out[45]=

In[46]:=

Out[46]=

Call a method:

In[47]:=

Out[47]=

Alternatively, define a Python object referring to the class and construct an instance on the Wolfram-Language side:

In[48]:=

Out[48]=

In[49]:=

Out[49]=

The new value of the instance variable:

In[50]:=

Out[50]=

Call a member function:

In[51]:=

Out[51]=

In[52]:=

Object Types (7)

Interactively defined object:

In[53]:=

Out[53]=

In[54]:=

A module in Python’s standard library:

In[55]:=

Out[55]=

In[56]:=

A class in the standard library:

In[57]:=

Out[57]=

In[58]:=

An instance of a class in the standard library:

In[59]:=

Out[59]=

In[60]:=

A function in the standard library:

In[61]:=

Out[61]=

In[62]:=

A built-in function:

In[63]:=

Out[63]=

In[64]:=

An installable package, with its classes and functions:

In[65]:=

In[66]:=

Out[66]=

In[67]:=

Out[67]=

In[68]:=

Out[68]=

Uninstall when the package no longer needed:

In[69]:=

Out[69]=

In[70]:=

Argument Types (4)

Position arguments are supported. Define a function that takes positional arguments in a Python session:

In[71]:=

Out[71]=

In[72]:=

ExternalEvaluate[session, "def positional(x,y=10):
return {'x':x,'y':y}
"]

Out[72]=

The Python object representing the function:

In[73]:=

Out[73]=

Call the function with the mandatory positional argument:

In[74]:=

Out[74]=

Supply a value of the optional argument:

In[75]:=

Out[75]=

In[76]:=

Positional arguments can have variable lengths. Define a function that takes an arbitrary number of positional arguments in a Python session:

In[77]:=

Out[77]=

In[78]:=

ExternalEvaluate[session, "def vararg(x,*varargs):
return {'x':x,'varargs':varargs}
"]

Out[78]=

The Python object representing the function:

In[79]:=

Out[79]=

Call the function with one or more arguments:

In[80]:=

Out[80]=

In[81]:=

Out[81]=

In[82]:=

Named arguments are supported. Define a Python function that takes an arbitrary number of positional arguments as well as named arguments, with or without default values:

In[83]:=

Out[83]=

In[84]:=

ExternalEvaluate[session, "def kwarg(x,*varargs,y=10,z):
return {'x':x,'varargs':varargs,'y':y,'z':z}
None
"]

The Python object representing the function:

In[85]:=

Out[85]=

Call the function with one positional and one named argument:

In[86]:=

Out[86]=

Call the function with positional and named arguments:

In[87]:=

Out[87]=

In[88]:=

Arbitrary names can be used. Define a Python function that takes arbitrary named arguments:

In[89]:=

Out[89]=

In[90]:=

ExternalEvaluate[session, "def vrkw(**varkw):
return {**varkw}
None
"]

The Python object representing the function:

In[91]:=

Out[91]=

Call the function supplying a few arbitrary named arguments in an association:

In[92]:=

Out[92]=

In[93]:=

Callable Objects (3)

A class:

In[94]:=

In[95]:=

ExternalEvaluate[session, "class MyClass:
def __init__(self):
print('instance created')
"]

Out[95]=

In[96]:=

Out[96]=

Create an instance of the class:

In[97]:=

Out[97]=

In[98]:=

A callable instance of the class:

In[99]:=

In[100]:=

ExternalEvaluate[session, "class MyClass:
def __call__(self):
return 'instance called'
"]

Out[100]=

In[101]:=

Out[101]=

Call the instance:

In[102]:=

Out[102]=

In[103]:=

A function:

In[104]:=

In[105]:=

ExternalEvaluate[session, "def func():
return 'func() called'
"]

Out[105]=

In[106]:=

Out[106]=

Call the function:

In[107]:=

Out[107]=

In[108]:=

Calling Conventions (5)

Call a function defined in a module via the parent module object:

In[109]:=

In[110]:=

Out[110]=

In[111]:=

In[112]:=

Out[112]=

In[113]:=

Out[113]=

Alternatively, define a callable function object and call it directly:

In[114]:=

Out[114]=

In[115]:=

Out[115]=

In[116]:=

Out[116]=

Clean up:

In[117]:=

Out[117]=

In[118]:=

Define a Python class:

In[119]:=

In[120]:=

ExternalEvaluate[session, "class MyClass:
def __init__(self, x, y = 0, z=0):
self.x = x
self.y = y
self.z = z
"]

Out[120]=

Create a Python object referring to the class:

In[121]:=

Out[121]=

In PythonObject, optional arguments of a callable Python object become standard Wolfram Language options:

In[122]:=

Out[122]=

Create an instance and check its variables:

In[123]:=

Out[123]=

In[124]:=

Out[124]=

For comparison, specify the optional argument in the Python code and check the new instance variables:

In[125]:=

Out[125]=

In[126]:=

Define a Python class in which the constructor takes a function as an argument:

In[127]:=

In[128]:=

ExternalEvaluate[session, "class CallF:
cvar = 'myClassVariable'
def __init__(self, f):
self.f = f
def call(self):
return self.f()
"]

Out[128]=

Create a Python object referring to the class:

In[129]:=

Out[129]=

To create an an instance of the class, define a function on the Python side:

In[130]:=

ExternalEvaluate[session, "def my_func():
print('my_func() called')
"]

Out[130]=

Supply the ExternalFunction object to the class constructor::

In[131]:=

Out[131]=

Invoke a method of the class:

In[132]:=

Alternatively, initialize an instance with a PythonObject:

In[133]:=

Out[133]=

In[134]:=

Out[134]=

Invoke the method:

In[135]:=

In[136]:=

Define a Python function which expects a specific type of a Python object, for instance, the enum Color, as an option:

In[137]:=

In[138]:=

package = "TemporaryPackage"[<|"Name" -> "enumarg",
"__init__.py" -> "from . import mod
from . mod import *
",
"mod.py" -> "from enum import Enum
class Color(Enum):
RED = 1
GREEN = 2
BLUE = 3

def do_color(color=Color.BLUE):
if not isinstance(color, Color):
raise TypeError('color is not an instance of the Color Enum')
return color.value
"|>];

In[139]:=

Out[139]=

A Python object for the enum:

In[140]:=

Out[140]=

Supply an enum value to the function:

In[141]:=

Out[141]=

In[142]:=

Define a class in Python:

In[143]:=

In[144]:=

ExternalEvaluate[session, "class MyClass:
def f(self, x, y=0):
self.z = x + y
"];

Create a Python object referring to the class:

In[145]:=

Out[145]=

Call a method function and get the instance variable using strings as names:

In[146]:=

Out[141]=

Alternatively, use symbols as names:

In[147]:=

Out[133]=

In[148]:=

Class Methods (4)

Deploy a temporary package that defines a class with a class method:

In[149]:=

In[150]:=

package = "TemporaryPackage"[<|"Name" -> "clmethod",
"__init__.py" -> "from . import mod
from . mod import *
",
"mod.py" -> "class MyClass:
@classmethod
def classmethod(cls):
return 'class method called', cls
"|>];

In[151]:=

Out[151]=

Create a Python object referring to the class:

In[152]:=

Out[152]=

Create a Python object referring to the class method:

In[153]:=

Out[153]=

Call the method and notice that the class object is passed to the class method as the first argument:

In[154]:=

Out[154]=

In[155]:=

Options (5)

Initialization (3)

Without initialization, PythonObject fails for this command because the required package is not available in the current session:

In[156]:=

In[157]:=

Out[157]=

In fact, the package is not even installed:

In[158]:=

Out[158]=

With the default setting Initialization→Automatic, the package is automatically installed and imported:

In[159]:=

Out[159]=

The package is now installed:

In[160]:=

Out[160]=

Uninstall to clean up:

In[161]:=

Out[161]=

In[162]:=

Specify a custom initialization:

In[163]:=

Out[163]=

Use the new object:

In[164]:=

Out[164]=

Uninstall the package and close the session to clean up:

In[165]:=

Out[165]=

In[166]:=

Configuration (2)

Without configuration, the raw Python’s uuid4() function returns an instance of the UUID class:

In[167]:=

Out[167]=

In[168]:=

Out[168]=

In[169]:=

Out[169]=

In[170]:=

Specify a configuration defined in a resource function:

In[171]:=

Out[171]=

The custom configuration icon alerts you to the fact that the object has a non-default behavior. In this case, the return value of the Python object changes to a string:

In[172]:=

Out[172]=

In[173]:=

Out[173]=

In[174]:=

Applications (3)

Create a PythonObject to efficiently reuse data on the Python side, even when you do not have access to the Python code:

In[175]:=

Execute some code that defines a big object and keep a reference to that object:

In[176]:=

In[177]:=

Out[177]=

Use the object:

In[178]:=

Out[178]=

In[179]:=

Make a function defined in an external module available in your Wolfram Language session:

In[180]:=

Out[180]=

The function signature:

In[181]:=

Out[181]=

Call the function:

In[182]:=

Out[182]=

Information about the returned object:

In[183]:=

Out[183]=

The value of one of the available variables:

In[184]:=

Out[184]=

Another variable refers to a more complex object:

In[185]:=

Out[185]=

In[186]:=

Out[186]=

Get the signature of one of the methods of the new object:

In[187]:=

Out[187]=

Call the method several times:

In[188]:=

Out[188]=

Uninstall the package to clean up:

In[189]:=

Out[189]=

In[190]:=

Create a Python object for an external package, for instance, Topoly:

In[191]:=

Out[191]=

Explore its contents:

In[192]:=

Out[192]=

Find the signature of a function from the package:

In[193]:=

Out[193]=

Prepare and plot a list of coordinates that represent a 5₁knot:

In[194]:=

In[195]:=

Out[195]=

Call the Topoly function and display its result, in this case, a plot of the fingerprint matrix for the coordinates of the knot:

In[196]:=

In[197]:=

PrintTemporary["This may take a while..."];
topoly["conway"[coordinates51, "tries" -> 10, "matrix" -> True, "matrix_map" -> True, "map_filename" -> filename]];

In[198]:=

Out[198]=

In[199]:=

Properties and Relations (14)

Some common properties:

In[200]:=

Out[200]=

In[201]:=

Out[201]=

Curated properties:

In[202]:=

Out[202]=

In[203]:=

Contents of a package:

In[204]:=

Out[204]=

In[205]:=

Out[205]=

Recurse into submodules:

In[206]:=

Out[206]=

All modules in the package:

In[207]:=

Out[207]=

Contents of a module:

In[208]:=

Out[208]=

In[209]:=

Out[209]=

In[210]:=

Information on a class, including the class variable and the methods:

In[211]:=

In[212]:=

ExternalEvaluate[session, "class MyClass:
cvar = 'myClassVariable'
def __init__(self, x):
self.x = x
print('instance initialized with '+str(x))
def add_two(self,x,y):
return x+y
"]

Out[212]=

In[213]:=

Out[213]=

In[214]:=

Out[214]=

Information on a class instance, including the class and instance variables and the methods:

In[215]:=

Out[215]=

In[216]:=

Out[216]=

In[217]:=

Obtain the signature of a callable object:

In[218]:=

Out[218]=

In[219]:=

Out[219]=

In[220]:=

Access Python's "built-ins", mathematical functions defined by the C standard:

In[221]:=

Out[221]=

In[222]:=

Out[222]=

In[223]:=

Out[223]=

In[224]:=

Out[224]=

In[225]:=

Use the "PythonReference" property to access the object on the Python side with ExternalEvaluate:

In[226]:=

Out[226]=

In[227]:=

Out[227]=

The explicit "PythonReference" specification can be omitted since it is the default property:

In[228]:=

Out[228]=

In[229]:=

Out[229]=

In[230]:=

"PythonReference" becomes stale if you delete the Python object:

In[231]:=

Out[227]=

In[232]:=

Out[229]=

"PythonReference" also stales if you close the session in which it is defined:

In[233]:=

p = ResourceFunction["PythonObject"]["object()"];
DeleteObject[p["Session"]]
p["ReferenceValid"]

Out[217]=

Even if not listed in "Properties", native Python attributes are also accessible:

In[234]:=

In[235]:=

Out[235]=

In[236]:=

Out[236]=

In[237]:=

Get the Python-side help:

In[238]:=

In[239]:=

In[240]:=

Create a single PythonObject for a Python list:

In[241]:=

Out[241]=

Re-create the object using the default Automatic policy:

In[242]:=

Out[242]=

In[243]:=

Out[243]=

Get the raw output of ExternalEvaluate used to create the object:

In[244]:=

Out[244]=

In[245]:=

PythonObject is similar to ExternalObject returned by ExternalEvaluate:

In[246]:=

In[247]:=

Out[247]=

In[248]:=

Out[248]=

PythonObject is also similar to ExternalFunction object that can be defined to call a Python function:

In[249]:=

Out[249]=

In[250]:=

Out[250]=

In[251]:=

Out[251]=

Call the two functions:

In[252]:=

In[253]:=

Out[253]=

The major difference between the produced objects is that the contents of the latter are accessible directly in the Wolfram Language without any Python programming:

In[254]:=

Out[254]=

In[255]:=

Out[255]=

Uninstall the package to clean up:

In[256]:=

Out[256]=

In[257]:=

Create a PythonObject representing a Python-side list:

In[258]:=

Out[258]=

Get a list of components:

In[259]:=

Out[259]=

In[260]:=

For callable objects, PythonObject[…][All] is used only for calling the object and otherwise returns unevaluated:

In[261]:=

Out[261]=

In[262]:=

Out[262]=

In[263]:=

Out[263]=

In[264]:=

Create and deploy a Python package with one unique function name and two identically named functions in two modules:

In[265]:=

In[266]:=

$p = ResourceFunction["PythonObject"][session, "TemporaryPackage"[<|"Name" -> "fnames", "__init__.py" -> "from . import mod1, mod2", "mod1.py" -> "def unique(): print('in unique()')\ndef function(): print('in mod1.function()')", "mod2.py" -> "def function(): print('in mod2.function()')"|>]]$

Out[266]=

Call the unique function simply by its name, given as a string or a symbol:

In[267]:=

However, trying to use non-uniquely named functions the same way gives an error:

In[268]:=

Out[268]=

Use the qualified dot notation for strings, or use symbols in proper contexts:

In[269]:=

In[270]:=

Alternatively, create another PythonObject for one of the modules:

In[271]:=

Out[271]=

In that context, the function name is unique and the function can be called just by its name:

In[272]:=

In[273]:=

Possible Issues (5)

PythonObject cannot be created by Python statements that do not return an object, such as statements defining a function:

In[274]:=

In[275]:=

In[276]:=

Out[276]=

Define the function using ExternalEvaluate and give the function name to PythonObject:

In[277]:=

In[278]:=

Out[278]=

Use the object:

In[279]:=

In[280]:=

If "cmd" in PythonObject[session,"cmd"] contains multiple statements, all the statements are executed, but the PythonObject is currently created from the first statement:

In[281]:=

In[282]:=

Out[282]=

In[283]:=

Out[283]=

We plan to improve on that in a future update; in the meantime, use separate statements for each object you want to create:

In[284]:=

Out[284]=

In[285]:=

If a Python object cannot be created, PythonObject might return a syntax error:

In[286]:=

In[287]:=

Out[287]=

Use ExternalEvaluate if you want to import the package manually:

In[288]:=

In[289]:=

If a Python function does not specify default values for one or more named arguments, options that represent such arguments become mandatory:

In[290]:=

Out[290]=

In[291]:=

ExternalEvaluate[session, "def kwonly(*varargs,x):
return {'varargs':varargs,'x':x}
None
"]

In[292]:=

Out[292]=

The function fails if the mandatory argument is not supplied:

In[293]:=

Out[293]=

Specify the mandatory argument:

In[294]:=

Out[294]=

In[295]:=

Signatures of some callable objects can contain Missing elements:

In[296]:=

In[297]:=

Out[297]=

In[298]:=

Out[298]=

You can still use such objects, but need to obtain their signatures manually:

In[299]:=

In[300]:=

Out[300]=

Also, for such objects, you cannot use standard Wolfram Language options and should rather supply optional arguments:

In[301]:=

Out[301]=

In[302]:=

Out[302]=

Alternatively, you can remove missing elements using the PythonObject API function "Signatures":

In[303]:=

In[304]:=

Out[304]=

Now the "log" function works the standard way:

In[305]:=

Out[305]=

In[306]:=

Version History

1.4.0 – 07 February 2024
1.3.0 – 29 November 2022
1.2.0 – 23 June 2022
1.1.0 – 08 March 2022
1.0.0 – 23 November 2021

Related Resources

Author Notes

The current treatment of multiple statements in "cmd" is suboptimal. PythonObject should really be created from the last statement, not the first. This is a TODO item, see "Possible Issues".

PythonObject[session,"TemporaryPackage"[assoc]] created specifically to simplify examples in this documentation and is not recommended for any other use.

Developer Notes

Besides giving access to "raw" Python code, PythonObject is also the first step towards a full-fledged framework for creating Python package wrappers and developing Wolfram Language applications backed by Python code. To this end, it is possible to configure the wrappers to adhere closely to the Wolfram Language conventions. The framework also provides utility functions that make developing Python package wrappers simpler.

Configuration

Python package configurations can be defined interactively in the current Wolfram Language session or saved in a repository function and loaded on demand. In the future, saved configurations can be made discoverable automatically.

Configurations are defined through one or more of the PythonObject API functions including:

"WebInformation"

documentation and other links

"NumberOfOptionalArguments"

promote options to optional arguments

"Signatures"

set signatures of callable objects

"PostProcess"

apply post-processing to Python results

"PreProcess"

preprocess arguments before sending to Python

"Rename"

use Wolfram Language naming conventions in Python objects

"PreserveObjects"

keep specified Python-side objects as a single PythonObject

"Normal"

define Normal for objects

"Icon"

specify a custom icon

"Dependencies"

load configurations for specified modules

Currently, "Configuration"→Automatic uses the custom configuration, if defined, or the first non-custom configuration applied in the current Wolfram Language session.

Note: Although configurations can be loaded before or after a PythonObject is created, they do not apply retroactively.In most cases, to see the expected behavior, you have to create a new PythonObject instance after loading your configuration.

WebInformation (Experimental)

PythonObject["API","WebInformation"["package",<|key₁→val₁,…|>]]

defines URIs of the documention and other information for the package.

Possible keys include:

"DocumentationLink"

documentation URI

"DocumentationSearchTemplate"

URI template for documentation search

"DocumentationSearchTemplate" must give a StringTemplate expression to be applied to a search string.

Define the documentation link and the documentation search links for a package:

In[1]:=

PythonObject["API", "WebInformation"[
"uuid", <|
"DocumentationLink" -> "https://docs.python.org/3/library/uuid.html", "DocumentationSearchTemplate" -> StringTemplate[
"https://docs.python.org/3/library/uuid.html#uuid.``"]|>]]

In[2]:=

Open the web documentation link for a package in your default browser:

In[3]:=

In[4]:=

In[5]:=

NumberOfOptionalArguments

In general, the convention to represent Python’s optional arguments as Wolfram Language options works well, but occasionally the design can be improved by keeping optional arguments at the same level with required positional arguments.

PythonObject["API","NumberOfOptionalArguments"["package",<|target₁→n₁,…|>]]

promotes the first n Python’s optional arguments in target_i in the specified package to Wolfram Language arguments.

"package" must be the package name or the name of the top-level module. target_i can be:

"func"

function

{"class","method"}

method of the class

A sample package that implements an "add_two" function":

In[6]:=

package = "TemporaryPackage"[<|"Name" -> "addtwo",
"__init__.py" -> "from . import mod
from . mod import *
",
"mod.py" -> "def add_two(x,y=0):
return x+y
"|>];

Define a custom configuration in which the add_two function takes an optional argument, rather than an option:

In[7]:=

Create a Python object for the package using the custom configuration:

In[8]:=

In[9]:=

The signature of the add_two function:

In[10]:=

Call the function with one and two arguments:

In[11]:=

In[12]:=

For comparison, with no configuration, the second summand needs to be supplied as an option:

In[13]:=

In[14]:=

In[15]:=

A package that defines a class and a function:

In[16]:=

package = "TemporaryPackage"[<|"Name" -> "opargs",
"__init__.py" -> "from . import mod
from . mod import *
",
"mod.py" -> "class MyClass:
def __init__(self,x,y=0):
print('init done')
def __call__(self,t,u=0,v=1):
return 'call done'
def add_three(self,x,y,z=0):
return 'MyClass.add_three called'
def add_many(x,y=0,t=0,u=0):
return 'mod.add_many called'
"|>];

Set the number of optional arguments for the package function and all the methods in the class, using the "__init__" method to create an instance of the class and the "__call__" method to call it:

In[17]:=

$PythonObject["API", "NumberOfOptionalArguments"[ "opargs", <| "add_many" -> 2, {"MyClass", "__init__"} -> 1, {"MyClass", "__call__"} -> 1, {"MyClass", "add_three"} -> 1|>]]$

In[18]:=

Create a class instance with one argument:

In[19]:=

Create a second instance with an optional argument:

In[20]:=

Call the second instance with one or two arguments:

In[21]:=

In[22]:=

Call a method:

In[23]:=

In[24]:=

Call the add_many function in the module:

In[25]:=

In[26]:=

For this function, one optional argument is left as an option:

In[27]:=

In[28]:=

In[29]:=

Signatures

PythonObject["API","Signatures"["package",<|target₁→assoc₁,…|>]]

adds missing elements to signatures of the callable objects in the specified package.

target_i can be specified using the same conventions as for "NumberOfOptionalArguments".

Possible elements of assoc_i include:

"Arguments"

list of arguements

"Options"

list of options

"IsMethod"

whether the callable is a method

Signatures of some callable objects in this package contain missing elements:

In[30]:=

In[31]:=

In[32]:=

In[33]:=

In[34]:=

Supply the signature of the function "log":

In[35]:=

Now the function can be called as usual:

In[36]:=

In[37]:=

In[38]:=

In[39]:=

PostProcess

PythonObject["API","PostProcess"["package",func]]

applies the specified function to results received from the package.

The post-processor function func[e,{p,f},{farg₁,farg₂,…}]receives the result of the computation e; the caller object p, the name of the function or method f, and the list of arguments sent to f, including the arguments with default values.

For the module "uuid", define a post-processor function that converts the instances of the UUID class to their string values:

In[40]:=

post[p_PythonObject, __] := ExternalEvaluate[p["Session"], StringTemplate["str(``)"][p[]]] /; p["FullName"] === "uuid.UUID"
post[res_, __] := res

In[41]:=

The Python object for the uuid.uuid4() function from the package:

In[42]:=

Call the function:

In[43]:=

For comparison, with no configuration, the function returns an instance of the UUID class:

In[44]:=

In[45]:=

PreProcess

PythonObject["API","PreProcess"["package",func]]

applies the specified function to Wolfram Language values before sending them to the package.

The preprocessor function func[{p,f},{arg₁,arg₂,…}]receives the caller object p, the name of the function or method f, and the list of arguments arg_i to be sent to f.

A sample package with a function that expects an immutable Python object, a tuple:

In[46]:=

package = "TemporaryPackage"[<|"Name" -> "preprocess",
"__init__.py" -> "from . import mod
from . mod import *
",
"mod.py" -> "def do_tuple(t):
if not isinstance(t, tuple):
raise TypeError(str(t)+' is not a tuple')
print('do_tuple called')
"|>];

Define a custom configuration in which a Wolfram Language list is automatically converted to a tuple before sending it to the do_tuple function:

In[47]:=

In[48]:=

In[49]:=

$pre[{p_, "preprocess.do_tuple"}, {list_List}] := {tuple[p, list]} pre[_, args_] := args$

In[50]:=

The Python object for the package:

In[51]:=

In[52]:=

Call the function:

In[53]:=

$p["do_tuple"[{1, 2, 3}]]$

For comparison, with no configuration, the function does not accept a mutable array object:

In[54]:=

In[55]:=

$p1["do_tuple"[{1, 2, 3}]]$

In[56]:=

Rename

PythonObject["API","Rename"["package"]]

uses heuristic to rename function names, class names, methods and options in the package.

PythonObject["API","Rename"["package",{rules₁,…}]]

sets up the specified name replacement rules.

Name replacements help to use Wolfram Language naming conventions.

For option names, replacement rules apply to both optional positional arguments, specified as "Options", and named arguments, specified as "KeywordOnlyArguments" and "KeywordArguments", as well as to those association keys in "KeywordArguments" that are defined as "KeywordOnlyArguments".

rules_i are applied in the specified order and can be either in the form suitable for the use in StringReplace or Automatic.

Automatic removes underscores and converts names to CamelCase.

The replacement rules allow the use of curated names, but do not mandate them. The original Python names can be used as well.

A sample package with one function:

In[57]:=

package = "TemporaryPackage"[<|"Name" -> "onefunc",
"__init__.py" -> "from . import mod
from . mod import *
",
"mod.py" -> "def my_function(x):
return 'my_function called'
"|>];

Allow calling the function by its CamelCase name:

In[58]:=

Create a Python object and call the function by its new name:

In[59]:=

In[60]:=

In[61]:=

In[62]:=

In[63]:=

The native Python function name is still accessible:

In[64]:=

In[65]:=

Set up custom naming rules for the package:

In[66]:=

package = "TemporaryPackage"[<|"Name" -> "cnames",
"__init__.py" -> "from . import mod
from . mod import *
",
"mod.py" -> "mvar = 'module variable'
class MyClass:
clvar = 'class variable'
def __init__(self,x,asp_rat=0):
self.instvar = x
self.asp_rat = asp_rat
print('init done')
def my_plot(self,method='m'):
return 'MyClass.my_plot called with method = '+str(method)
def get_approx(iter=1):
return 'mod.get_approx called with iter = '+str(iter)
def positional(*varargs,my_argument=10):
return 'mod.get_approx called with varargs = '+str(varargs)+'positional = '+str(my_argument)
"|>];

In[67]:=

$PythonObject["API", "Rename"[ "cnames", {{"asp_rat" -> "AspectRatio", "get_approx" -> "Approximation", "iter" -> "Iterations"}, Automatic}]]$

In[68]:=

In[69]:=

Call the "get_approx" function using the new names:

In[70]:=

In[71]:=

In[72]:=

In[73]:=

Call the variable-arguments function with the new names:

In[74]:=

In[75]:=

Renaming rules for the package:

In[76]:=

The rule for a particular name:

In[77]:=

Convert to and from Python name:

In[78]:=

In[79]:=

In[80]:=

PreserveObjects

PythonObject["API","PreserveObjects"["package",{obj₁,obj₂,…}]]

prevents obj_i from automatically expanding into components.

Certain Python-side objects are normally expanded into components by default:

In[81]:=

In[82]:=

Create a package with two functions, one that returns a tuple and another that expects a tuple argument:

In[83]:=

package = "TemporaryPackage"[<|"Name" -> "tuples",
"__init__.py" -> "from . import mod
from . mod import *
",
"mod.py" -> "def return_tuple(n):
return tuple(range(n))
def use_tuple(t):
if not isinstance(t,tuple):
raise TypeError('expecting tuple')
return 'got tuple'
"|>];

Prevent tuples returned by the package from being automatically expanded:

In[84]:=

In[85]:=

In[86]:=

Supply the tuple as argument:

In[87]:=

In[88]:=

Normal

PythonObject["API","Normal"["package",f]]

specifies that the function f should be applied to package objects to convert them to normal expressions.

If the function f is intended to be applied only to a subset of objects in the package, it must return Failure["ConditionFailure",…] for other objects.

Set up a rule to convert sparse SciPy matrices to SparseArray objects:

In[89]:=