TyJuliaCall

Calling Julia from Python for the real world.

Features:

1. Cross-platform support for both dynamically linked Python and statically linked Python.

2. Support Julia system images.

Installation

Prerequisites: Python (>=3.7), Julia (>=1.6)

Then install the tyjuliacall Python package and TyPython Julia package.

pip install -U tyjuliacall
julia -e "import Pkg; Pkg.add(\"TyPython\")"

Julia Initialization Options

Set TYPY_JL_EXTRA_OPTS before the first import of tyjuliacall to pass additional initialization options to Julia:

import os

os.environ["TYPY_JL_EXTRA_OPTS"] = "--quiet"

from tyjuliacall import Base

The value is parsed with shlex.split, combined with TyJuliaCall's required options, and passed to libjulia through its existing jl_parse_opts path. TyJuliaCall reserves --sysimage (-J) and --project; configure a custom system image with use_sysimage() instead. TYPY_JL_OPTS is an internal transport variable and should not be set directly.

This mechanism is for options handled during libjulia initialization. Julia driver actions such as -e, -L, and script arguments do not execute because an embedded Julia instance does not run the command-line driver's _start(). The standalone -- separator is not supported. Invalid or process-exiting options are handled by Julia itself and can make the Python import fail or terminate.

Shutting Down Julia

TyJuliaCall shuts down the embedded Julia runtime when Python exits normally. This runs Julia atexit hooks and pending finalizers.

Forced process termination, including os._exit(), does not run exit hooks.

Using System Images

from tyjuliasetup import use_sysimage  # CAUTIOUS: not 'tyjuliacall'!
use_sysimage(r"/path/to/sysimg")
# if your sysimage contains TyPython,
# you could call use_system_typython() to reduce the time cost of setting up julia.
from tyjuliacall import Base
print(
    "current sysimage in use",
    Base.unsafe_string(Base.JLOptions().image_file))
# out: /path/to/sysimg

受信赖的Python-Julia数据类型转换

虽然tyjuliacall允许在Python和Julia之间传递任意数据，但由于是两门不同的语言，数据转换的类型对应关系是复杂的。

为了保证代码的后向兼容性，使得规范的代码在不同版本的Syslab/tyjuliacall上都可以运行，建议只使用如下的数据类型转换。

Python数据传递到Julia

Python向Julia函数传参时，推荐只使用下表左边的数据类型，以保证代码的后向兼容。

对于Python传递给Julia的tuple，其各个元素按照以上规则依次转换。

TIPS: 如何传递bytearray或者bytes到Julia?

1. 向Julia函数传递bytes时，可以改为传递一个uint8的数组。

   无拷贝传参： np.array(memoryview(b'mybytes'), dtype=np.uint8) 拷贝传参： np.array(list(b'mybytes'), dtype=np.uint8)

2. 向Julia函数传递bytearray时，可以改为传递一个uint8的数组。

   无拷贝传参： np.asarray(bytearray(b'mybytes')))

Julia数据传递到Python

当获取Julia函数返回值，或导入Julia模块的非函数对象时，将发生Julia到Python的数据传递。

保证后向兼容的Julia到Python数据转换关系如下表所示：

一个Julia AbstrctArray能转换为numpy数组，当且仅当其元素类型T是以下类型之一

• Int8, Int16, Int32, Int64, UInt8, UInt16, UInt32, UInt64
• Float16, Float32, Float64
• ComplexF16, ComplexF32, ComplexF64
• Bool

注意，当类型为Vector{String}或者Array{String, 2}的Julia对象被返回给Python时，它被封装为一个tyjuliacall.JV类型。

其他说明

1. 不要对Julia包/模块使用from ... import *。
2. Vector{String}传到Python是一个tyjuliacall.JV，这是一个纯Julia对象的包装，因此下标索引是从1开始的。