API

Utility functions

julia.install(*, julia="julia", color="auto")

Install Julia packages required by PyJulia in julia.

This function installs and/or re-builds PyCall if necessary. It also makes sure to build PyCall in a way compatible with this Python executable (if possible).

Keyword Arguments:
 
  • julia (str) – Julia executable (default: “julia”)
  • color ("auto", False or True) – Use colorful output if True. “auto” (default) to detect it automatically.

Low-level API

class julia.api.Julia(init_julia=True, jl_init_path=None, runtime=None, jl_runtime_path=None, debug=False, **julia_options)

Implements a bridge to the Julia runtime. This uses the Julia PyCall module to perform type conversions and allow full access to the entire Julia runtime.

__init__(init_julia=True, jl_init_path=None, runtime=None, jl_runtime_path=None, debug=False, **julia_options)

Create a Python object that represents a live Julia runtime.

Note: Use LibJulia to fully control the initialization of the Julia runtime.

Parameters:
  • init_julia (bool) –

    If True, try to initialize the Julia runtime. If this code is being called from inside an already running Julia, the flag should be passed as False so the interpreter isn’t re-initialized.

    Note that it is safe to call this class constructor twice in the same process with init_julia set to True, as a global reference is kept to avoid re-initializing it. The purpose of the flag is only to manage situations when Julia was initialized from outside this code.

  • runtime (str) – Custom Julia binary, e.g. “/usr/local/bin/julia” or “julia-1.0.0”.
  • debug (bool) – If True, print some debugging information to STDERR
  • bindir (str) – Set location of julia executable relative to which we find system image (sys.so). It is inferred from runtime if not given. Equivalent to --home of the Julia CLI.
  • check_bounds ({True, False, 'yes', 'no'}) – Emit bounds checks always or never (ignoring declarations). True and False are synonym of 'yes' and 'no', respectively. This applies to all other options.
  • compile ({True, False, 'yes', 'no', 'all', 'min'}) – Enable or disable JIT compiler, or request exhaustive compilation.
  • compiled_modules ({True, False, 'yes', 'no'}) – Enable or disable incremental precompilation of modules.
  • depwarn ({True, False, 'yes', 'no', 'error'}) – Enable or disable syntax and method deprecation warnings (“error” turns warnings into errors).
  • inline ({True, False, 'yes', 'no'}) – Control whether inlining is permitted, including overriding @inline declarations.
  • optimize ({0, 1, 2, 3}) – Set the optimization level (default level is 2 if unspecified or 3 if used without a level).
  • sysimage (str) – Start up with the given system image file.
  • warn_overwrite ({True, False, 'yes', 'no'}) – Enable or disable method overwrite warnings.
  • min_optlevel ({0, 1, 2, 3}) – Lower bound on the optimization level.
  • threads ({int, 'auto'}) – How many threads to use.
eval(src)

Execute code in Julia, then pull some results back to Python.

help(name)

Return help string for function by name.

using(module)

Load module in Julia by calling the using module command

class julia.api.LibJulia(libjulia_path, bindir, sysimage)

Low-level interface to libjulia C-API.

Examples

>>> from julia.api import LibJulia, JuliaInfo

An easy way to create a LibJulia object is LibJulia.load:

>>> api = LibJulia.load()                              # doctest: +SKIP

Or, equivalently,

>>> api = LibJulia.load(julia="julia")                 # doctest: +SKIP
>>> api = LibJulia.from_juliainfo(JuliaInfo.load())    # doctest: +SKIP

You can pass a path to the Julia executable using julia keyword argument:

>>> api = LibJulia.load(julia="PATH/TO/CUSTOM/julia")  # doctest: +SKIP

Path to the system image can be configured before initializing Julia:

>>> api.sysimage                                       # doctest: +SKIP
'/home/user/julia/lib/julia/sys.so'
>>> api.sysimage = "PATH/TO/CUSTOM/sys.so"             # doctest: +SKIP

Finally, the Julia runtime can be initialized using LibJulia.init_julia. Note that only the first call to this function in the current Python process takes effect.

>>> api.init_julia()

Any command-line options supported by Julia can be passed to init_julia:

>>> api.init_julia(["--compiled-modules=no", "--optimize=3"])

Once init_julia is called, any subsequent use of Julia API (thus also from julia import <JuliaModule> etc.) uses this initialized Julia runtime.

LibJulia can be used to access Julia’s C-API:

>>> ret = api.jl_eval_string(b"Int64(1 + 2)")
>>> int(api.jl_unbox_int64(ret))
3

However, a proper use of the C-API is more involved and presumably very challenging without C macros. See also: https://docs.julialang.org/en/v1/manual/embedding/.

libjulia_path

Path to libjulia.

Type:str
bindir

Sys.BINDIR of julia. This is passed to jl_init_with_image unless overridden by argument option to init_julia.

Type:str
sysimage

Path to system image. This is passed to jl_init_with_image unless overridden by argument option to init_julia.

If Custom Julia system image is a relative path, it is interpreted relative to the current directory (rather than relative to the Julia bindir as in the jl_init_with_image C API).

Type:str
init_julia(options=None)

Initialize libjulia. Calling this method twice is a no-op.

It calls jl_init_with_image (or jl_init_with_image__threading) but makes sure that it is called only once for each process.

Parameters:options (sequence of str or JuliaOptions) –

This is passed as command line options to the Julia runtime.

Warning

Any invalid command line option terminates the entire Python process.
classmethod load(**kwargs)

Create LibJulia based on information retrieved with JuliaInfo.load.

This classmethod runs JuliaInfo.load to retrieve information about julia runtime. This information is used to intialize LibJulia.

class julia.api.JuliaInfo(julia, version_raw, version_major, version_minor, version_patch, bindir=None, libjulia_path=None, sysimage=None, python=None, libpython_path=None)

Information required for initializing Julia runtime.

Examples

>>> from julia.api import JuliaInfo
>>> info = JuliaInfo.load()
>>> info = JuliaInfo.load(julia="julia")  # equivalent
>>> info = JuliaInfo.load(julia="PATH/TO/julia")       # doctest: +SKIP
>>> info.julia
'julia'
>>> info.sysimage                                      # doctest: +SKIP
'/home/user/julia/lib/julia/sys.so'
>>> info.python                                        # doctest: +SKIP
'/usr/bin/python3'
>>> info.is_compatible_python()                        # doctest: +SKIP
True
julia

Path to a Julia executable from which information was retrieved.

Type:str
bindir

Sys.BINDIR of julia.

Type:str
libjulia_path

Path to libjulia.

Type:str
sysimage

Path to system image.

Type:str
python

Python executable with which PyCall.jl is configured.

Type:str
libpython_path

libpython path used by PyCall.jl.

Type:str
is_compatible_python()

Check if python used by PyCall.jl is compatible with sys.executable.

classmethod load(julia='julia', **popen_kwargs)

Get basic information from julia.

class julia.api.JuliaError

Wrapper for Julia exceptions.