Wolfram Client Library for Python

The Wolfram Client Library is organized into several specialized submodules:

• wolframclient.evaluation: Provides methods to evaluate Wolfram Language expressions (via local kernel, Wolfram Cloud, or deployed APIs).
• wolframclient.language: Provides a Python representation of Wolfram Language symbols and functions.
• wolframclient.serializers: Handles serialization of Python objects into Wolfram Language formats.
• wolframclient.deserializers: Contains parsers for deserializing Wolfram Language data (specifically WXF).
• wolframclient.exception: Contains the hierarchy of exceptions and errors raised by the library.

The Wolfram Client Library enables seamless integration between Python and the Wolfram Language. It allows developers to bridge the two environments by performing the following tasks:

• Code Evaluation: Execute arbitrary Wolfram Language code on a local kernel or on Wolfram Cloud (both public and private).
• API Interaction: Call deployed APIFunction instances.
• Function Building: Construct Python functions that wrap and leverage Wolfram Language functions.
• Data Representation: Represent Wolfram Language code as Python objects.
• Serialization:
  • Convert Python objects to Wolfram Language InputForm strings.
  • Serialize Python objects to WXF (Wolfram eXchange Format).
  • Extend serialization capabilities to custom Python classes.
• Parsing: Parse expressions encoded in WXF.

By default, the wolframclient.deserializers.binary_deserialize function maps Wolfram Language functions to the WLFunction class. You can extend this mapping by creating a subclass of WXFConsumer and overriding the build_function method. This allows you to map specific Wolfram Language symbols or functions directly to native Python classes (e.g., mapping Complex to Python's built-in complex type).

from wolframclient.deserializers import WXFConsumer
from wolframclient.language.expression import WLFunction

class ComplexFunctionConsumer(WXFConsumer):
    def build_function(self, name, args):
        if name == 'Complex':
            return complex
        return super().build_function(name, args)

The library provides two ways to represent Wolfram expressions:

• Object representation: Using wl constructs like wl.Quantity to create structured objects.
• String representation: Using wlexpr to define code as a string literal.

# Object representation
>>> wl.Quantity(12, "Hours")
Quantity[12, 'Hours']

# String representation
>>> wlexpr('f[x_] := x^2')
(f[x_] := x^2)

There are three ways to extend the serialization mechanism:

1. WLSerializable: Implement the WLSerializable interface in your custom class and override the to_wl method.
2. Normalizers: Pass a function to export(..., normalizer=func) to transform objects before serialization (see Normalizer guide).
3. Type Encoders: Declare a type encoder. The library uses encoders (generators of bytes) attached to specific Python types. Built-in encoders exist for types like PIL.Image, numpy.ndarray, and pandas.Series.

To build the documentation for the Wolfram Client Library for Python, you need the following requirements:

• uv: A fast Python package manager and project runner. Install it using:

  curl -LsSf https://astral.sh/uv/install.sh | sh

• Node.js (optional): Required for CSS compilation via npx sass.
  • On macOS: brew install node
  • Or download from https://nodejs.org/

Note: If Node.js is missing, CSS compilation will be skipped with a warning, but the documentation will still build.

When Wolfram Language returns symbolic exact values (like $\pi$ or symbolic eigenvalues) that you want to use as numerical values in Python, avoid writing complex custom WXFConsumer logic to reconstruct math objects. Instead, use the Wolfram Language function N (numerical approximation) within your client calls. This converts symbolic expressions into a mixture of reals and complex numbers that are easier to handle with standard Python types.

from wolframclient import WolframClient
from wolframclient.language import wl

client = WolframClient()
# Instead of handling symbolic results in Python, use N in the Wolfram Language
# to get numerical approximations directly.
result = client.evaluate(N(wl.Eigenvalues(wl.{{matrix}}))))

Install the library using pip to enable Python programs to integrate with the Wolfram Language via a local Wolfram Engine or the Wolfram Cloud.

$ pip install wolframclient

To begin interacting with the Wolfram Language, import WolframLanguageSession from wolframclient.evaluation and initialize it. You will also typically need wl and wlexpr from wolframclient.language to construct expressions.

>>> from wolframclient.evaluation import WolframLanguageSession
>>> from wolframclient.language import wl, wlexpr
>>> session = WolframLanguageSession()

For local development, use the build.sh script. This script utilizes uv to manage dependencies and builds the documentation in a single command.

./build.sh

If you are a developer and want to install the library along with the full source code, clone the repository and install it using pip.

$ git clone git://github.com/WolframResearch/WolframClientForPython
$ pip install .