PythonCall.jl Documentation

When passing Julia objects to Python functions or using the explicit Py(x) constructor, PythonCall automatically converts Julia types to their Python equivalents.

Conversion Triggers:

• Explicit: Calling Py(x).
• Implicit: Passing a Julia object as an argument to a Python function.
• From Python: When a Julia function returns a value to Python.

To prevent automatic conversion and keep the object in its Julia form, use explicit conversion methods like pylist or pydict (depending on the desired structure) or wrap it in a way that avoids the default mapping.

If you are deciding between PythonCall.jl and the existing PyCall.jl, consider these architectural differences:

• Conversion & Extensibility: PythonCall supports a wider, more extensible range of conversions.
• Memory Management: PythonCall avoids copying mutable objects by default, instead wrapping them. Modifying a converted object modifies the original, which is faster and more memory-efficient.
• Type Stability & Pythonic Behavior: PythonCall typically leaves results as Python objects rather than automatically converting them to Julia values. This allows for easier method access on Python objects and better type stability.
• Dependency Management: PythonCall uses CondaPkg.jl to install dependencies into isolated Conda environments specific to each Julia project, preventing dependency conflicts between different projects.

Most Julia values are automatically converted into Python objects that wrap the original Julia value. These wrappers provide a Pythonic interface while maintaining a connection to the underlying Julia data.

• AnyValue: The base wrapper for most Julia objects. It supports standard Python protocols like len(), iteration, comparisons, and attribute access. Attribute access can also access Julia properties. To handle Julia's mutation syntax, _b at the end of an attribute is converted to ! and _bb to !!.
• RawValue: A stricter wrapper designed for generic programming. Unlike AnyValue, operations like indexing or calling on a RawValue always return another RawValue rather than converting to a Python type.
• ValueBase: The common parent class for all wrapper types.

When converting from Python to Julia, PythonCall often returns 'wrapper types' instead of raw Py objects. These wrappers provide Julia-native semantics for Python objects. For example, a PyList behaves like a Julia abstract vector.

# Common wrapper types returned during conversion:
# PyList, PySet, PyDict, PyIterable, PyArray, PyIO, PyTable, PyPandasDataFrame, PyObjectArray, PyException

As of v0.9.22, PythonCall and JuliaCall are thread-safe provided you handle the Global Interpreter Lock (GIL) correctly.

When starting a Julia REPL with multiple threads, you must ensure there is exactly one interactive thread to avoid segmentation faults during tab completion. You can configure this using the JULIA_NUM_THREADS environment variable in the format X,1 (where X is the number of worker threads) or via the --threads CLI flag.

julia --threads X,1

PythonCall handles conversions in two ways:

1. Implicit Conversion: When passing Julia objects as arguments to Python functions, they are automatically converted to Python objects.
2. Explicit Conversion:
   • Use Py(x) to wrap a Julia object as a Py object.
   • Use pyconvert(T, x) to convert a Python object x into a specific Julia type T.

Note on pyconvert(Any, x):

• For immutable scalars (like int or str), it returns the corresponding Julia object.
• For containers, it returns a wrapper type (like PyList{Py}) which is a no-copy view. Mutating the wrapper mutates the original Python object.

# Convert Python list to Julia Vector
x = pylist([3.4, 5.6])

# Specific type
vec = pyconvert(Vector{Float64}, x)

# No-copy wrapper (mutating 'any_vec' mutates 'x')
any_vec = pyconvert(Any, x)

PythonCall overloads Julia's standard arithmetic and logical operators to work with Py objects. This means you can use standard Julia syntax (e.g., +, -, *, <, ==) when interacting with Python objects, and it will correctly invoke the underlying Python operations.

# These are all equivalent:
# 1. Using overloaded Julia operators
result = Py(1) + Py(2)

# 2. Mixing Py objects and Julia numbers
result = Py(1) + 2

# 3. Using explicit PythonCall arithmetic functions
result = pyadd(Py(1), Py(2))

# Logic follows the same pattern:
# Py(1) < Py(2) is equivalent to pylt(Py(1), Py(2))

The exe preference (or JULIA_PYTHONCALL_EXE environment variable) allows you to point to specific Python environments using special tokens:

• @CondaPkg: Use Python from CondaPkg (the default).
• @PyCall: Use the same Python as PyCall.
• @venv: Use Python from a .venv virtual environment in the current active project.

Otherwise, the value is interpreted as an absolute path, a relative path (resolved relative to the current active project), or a command name to search for in PATH.

Wrapper types allow you to use Python objects with Julia semantics without copying the underlying data. Mutating a wrapper mutates the original Python object.

Common wrappers include:

• PyList{T}: Wraps Python sequences (lists, etc.) as a Julia AbstractVector.
• PyDict{K, V}: Wraps Python dictionaries.
• PySet{T}: Wraps Python sets.
• PyArray: Provides a high-performance Julia array view of Python arrays (e.g., numpy.ndarray or array.array) via the buffer protocol.
• PyIO: Wraps a Python file-like object as a Julia IO object.

# PyArray example
x = pyimport("array").array("i", [3, 4, 5])
y = PyArray(x)
sum(y) # 12

# PyIO example
x = pyimport("io").StringIO()
y = PyIO(x)
println(y, "Hello, world!")
flush(y)

You can install the juliacall module using pip or conda.

Using pip:

pip install juliacall

Using Conda:

conda install conda-forge::pyjuliacall

For Developers: If you are developing PythonCall.jl and want to use it in editable mode with juliacall, add "dev":true, "path":"../.." to pysrc/juliacall/juliapkg.json to ensure the development version is used.