Essays, Posts & Presentations

Announcing the Wolfram Client Library for Python

Dorian Birraux, Todd Gayley, Arnoud Buzing

Author

Dorian Birraux, Todd Gayley, Arnoud Buzing

Title

Announcing the Wolfram Client Library for Python

Description

Get Full Access to the Wolfram Language from Python

Announcing the Wolfram Client Library for Python

May 1, 2019

Dorian Birraux, Consultant, Engine Connectivity Engineering

Todd Gayley, Director, Engine Connectivity Engineering

Arnoud Buzing, Director, Product & Release Management

Get Full Access to the Wolfram Language from Python The Wolfram Language gives programmers an unparalleled technical computing system with an enormous array of sophisticated algorithms and built-in real-world knowledge. For many years people have asked us how to access all this wonderful technology from other software environments and programming languages. And over the years we have built many such connections, like the Wolfram CloudConnector for Excel, the Wolfram Symbolic Transfer Protocol (WSTP for short) for C/C++ programs, and of course J/Link which provides access to the Wolfram Language directly from Java.

So today we are happy to formally announce a new and often requested connection, which allows you to call the Wolfram Language directly and efficiently from Python: The Wolfram Client Library for Python! And, even better, this client library is fully open sourced as the WolframClientForPython git repository under the MIT License so you can clone it and use it any way you see fit! And if you see a way to improve it, please help us make it better by contributing pull requests to this repository.

“The Wolfram Client Library for Python is full open sourced.”

It’s Easy! The client library will make it super easy to integrate the large collection of Wolfram Language algorithms and knowledge directly into any Python code that you already have and will save you time and effort when developing new code. In this post we will show how to set up a connection from Python to the Wolfram Language and a few methods and examples you can use to do a computation in the Wolfram Language and use it in your Python session. For a complete introductory tutorial and full reference documentation you can visit the documentation homepage for the Wolfram Client Library for Python.

Evaluate Locally… We will start with a simple example which computes the mean and standard deviation of one million numbers drawn from a normal distribution. This example shows how to call a Wolfram Language function from Python and we compare the results from Python and the Wolfram Language to show that they a numerically close to one another.

Statistical Data Analysis

First, to connect to the Wolfram Language we need to create a new session with the Wolfram Engine:

〉

>>> from wolframclient.evaluation import WolframLanguageSession
>>> session = WolframLanguageSession()

To call Wolfram Language functions we need to import the `wl` factory:

〉

>>> from wolframclient.language import wl

Now we can evaluate any Wolfram Language code. Here we set the Python variable sample to a list of 1,000,000 random numbers drawn from the normal distribution with a mean of 0 and a standard deviation of 1:

〉

>>> sample = session.evaluate( wl.RandomVariate( wl.NormalDistribution(0,1), 1e6 ) )

We can take a look at the first five of them:

〉

>>> sample[:5]
[0.44767075774581,
0.9662810005828261,
-1.327910570542906,
-0.2383857558557122,
1.1826399551062043]

We can compute the mean value of this sample with the Wolfram Language. As expected it is close to zero:

〉

>>> session.evaluate( wl.Mean( sample ) )
0.0013371607703851515

We can also directly compute this in Python to verify we get a numerically similar result:

〉

>>> sum(sample)/len(sample)
0.0013371607703851474

Similarly we can compute the standard deviation of sample with the Wolfram Language:

〉

>>> session.evaluate( wl.StandardDeviation( sample ) )
1.0014296230797068

And run the following code in Python to verify that we get a similar result:

〉

>>> from statistics import stdev
>>> stdev(sample)
1.0014296230797068

It's good to see that these results are comparable, so now we know how to call some simple Wolfram Language functions from Python. Let’s continue with a more exciting example!

Using the Wolfram Knowledgebase

Now let's take a look at a built-in Wolfram Language function that is not readily available in Python:

〉

moons = session.evaluate( wl.WolframAlpha('moons of Saturn', 'Result') )

The

WolframAlpha

function is one the high level functions in the Wolfram Language which interacts with the Wolfram|Alpha servers via a Web API. You can use this API directly from Python, but doing it this way is much more powerful and convenient because you can all the data framework functions from the Wolfram Language directly. Let’s take a look at the the Python variable moons contains:

〉

>>> moons
EntityClass['PlanetaryMoon', 'SaturnMoon']

The output here is the Python representation of a Wolfram Language expression which can be re-used in any subsequent evaluation. For example, if we want to get the list of (the first four) moons explicitly we can do this:

〉

>>> session.evaluate( wl.EntityList(moons) )[:4]
[Entity['PlanetaryMoon', 'S2009S1'],
Entity['PlanetaryMoon', 'Pan'],
Entity['PlanetaryMoon', 'Daphnis'],
Entity['PlanetaryMoon', 'Atlas']]

Or we can easily get the four largest moons of Saturn by mass with this small snippet of code:

〉

>>> bigmoons = session.evaluate( wl.EntityList( wl.SortedEntityClass(moons, wl.Rule("Mass","Descending"),4 ) ) )
>>> bigmoons
[Entity['PlanetaryMoon', 'Titan'],
Entity['PlanetaryMoon', 'Rhea'],
Entity['PlanetaryMoon', 'Iapetus'],
Entity['PlanetaryMoon', 'Dione']]

And we can get a simple array of strings with the names of these moons like this:

〉

>>> session.evaluate( wl.Map( wl.Function( wl.Slot()("Name")), bigmoons))
['Titan', 'Rhea', 'Iapetus', 'Dione']

This is all pretty cool! Let take a look at another example, using the Wolfram Language’s built-in image processing and machine learning functions.

Image Processing & Machine Learning

First let’s switch over to another mode to do evaluations directly in the Wolfram Language. So far we have used the wl factory to build up Wolfram Language expressions in Python. But you can also evaluate Python strings containing Wolfram Language code and sometimes this is easier to read:

〉

>>> from wolframclient.language import wlexpr

For example, we can solve the quadratic equation by sending the Wolfram Language code as a string:

〉

>>> session.evaluate('1+1')
2

Using this method we can write a small snippet of Wolfram Language code which gets an image and uses the built-in face detection algorithm to find the location of the face in this image. Here the image we are using is the famous painting titled “Girl with a Pearl Earring” by the Dutch painter Johannes Vermeer (but it works on almost any image with recognizable faces!). Since the Python terminal interface does not support the display of image, we use a Jupyter notebook instead, together with the Python Image Library (PIL) package to help with displaying the result:

Quite easy and powerful! But what if you don’t have a local installation of the Wolfram Engine and want to use the Wolfram Client Library for Python? You can still use the Wolfram Language directly in the Wolfram Cloud.

To the Cloud! The Wolfram Cloud provides easy access to the Wolfram Language without needing to install it locally. The Wolfram Cloud provides various services, including a notebook web interface for Wolfram Language programming as well as the capability to deploy arbitrary Wolfram Language web APIs.

Here we will make use of the latter, deploying a Wolfram Language web API. This particular accepts the names of two countries (country1 and country2), find the capital city for each country and then computes the distance between them (in kilometers):

In[]:=

CloudDeploy[
APIFunction[{"country1""String","country2""String"},
QuantityMagnitude[
GeoDistance[
EntityValue[Entity["Country", #country1], "CapitalCity"],
EntityValue[Entity["Country", #country2], "CapitalCity"]
],
"Kilometers"
]&,
"WXF"
],
CloudObject["api/public/capital_distance"],
Permissions"Public"]

Out[]=

CloudObject[

https://www.wolframcloud.com/objects/user1/api/public/capital_dista

nce

]

After this deployment of this API we can start a new Wolfram Language session, but this time we connect to the Wolfram Cloud instead:

〉

>>> from wolframclient.evaluation WolframCloudSession
>>> cloud = WolframCloudSession()

To call the API we have to provide the username (user1) and the API endpoint (api/public/capital_distance). With that information, we can call the cloud:

〉

>>> api = ('user1', 'api/public/capital_distance')
>>> result = cloud.call(api, {'country1': 'Netherlands', 'country2': 'Spain'})

And get the result:

〉

>>> result.get()
1481.4538329484521

Pretty easy and useful!

If you want to keep your deploy Wolfram Language API private, so that only you can use it, you can deploy the API with Permissions->”Private”. Then, to authenticate yourself to the private API, you can generate (in the Wolfram Language) a secured authentication key:

In[]:=

key=GenerateSecuredAuthenticationKey["myapp"]

Out[]=

SecuredAuthenticationKey

Name: myapp

Authenticated : False



Copy the outputs from these two inputs:

key["ConsumerKey"]key["ConsumerSecret"]

Then paste them into your Python session:

〉

>>> from wolframclient.evaluation import SecuredAuthenticationKey
>>> sak = SecuredAuthenticationKey(
... '<<paste-consumer-key-here>>',
... '<<paste-consumer-secret-here>>')

And finally start a new authenticated cloud session:

〉

>>> cloud = WolframCloudSession(credentials=sak)
>>> cloud.start()
>>> cloud.authorized()
True

That it! At this point you (and only you) can use any privately deployed Wolfram Language API.

A bit about the underlying serialization To make everything very fast and efficient, the Wolfram Client Library for Python uses the open WXF format to exchange expressions between Python and the Wolfram Language. WXF is a binary format for faithfully serializing Wolfram Language expressions, in a form suitable for interchange with external programs. The library function export can serialize Python objects to string input form and WXF, and natively supports a set of Python built-in classes such as dict, list and strings:

〉

>>> from wolframclient.serializers import export
>>> export({
'list': [1,2,3],
'string': u'abc',
'etc': [0, None, -1.2]
})
b'<|"list" -> {1, 2, 3}, "string" -> "abc", "etc" -> {0, None, -1.2}|>'

WXF represents numeric arrays with packed data, allowing efficient support for NumPy arrays.

Create a new array of 255 unsigned 8 bit integers:

〉

>>> import numpy
>>> array=numpy.arange(255, dtype='uint8')

Serialize it to WXF bytes and compute the byte count:

〉

>>> wxf=export(array, target_format='wxf')
>>> len(wxf)
262

NumPy arrays are backing many Python libraries, therefore an efficient and compact serialization helps interfacing the Python ecosystem with the Wolfram Language. A direct consequence of supporting NumPy is that the serialization of PIL images is in general very efficient; most of the pixel data modes map to one of the numeric array types, specified by

NumericArrayType

. It’s also worth mentioning that Pandas Series and DataFrame are supported natively. The library also provides an extensible mechanism for serializing arbitrary classes.

Available Now! The latest version of the Wolfram Client Library for Python can be installed with pip:

pip install wolframclient

It requires Python 3.5.3 (or above) and Wolfram Language 11.3 (or above). The entire source code is hosted in the WolframClientForPython repository on the WolframResearch GitHub site. The full documentation is hosted on the Wolfram Language & System Documentation Center.

We are very excited about this release and hope you find it useful. Please let us know what you think by posting feedback on this blog or by making a post on the Wolfram Community.

Cite this as: Dorian Birraux, Todd Gayley, Arnoud Buzing, "Announcing the Wolfram Client Library for Python" from the Notebook Archive (2019), https://notebookarchive.org/2019-10-3ppx2n1