API¶
Utility functions¶
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 fromruntime
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
andFalse
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.
- init_julia (bool) –
-
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 isLibJulia.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 ofJulia
API (thus alsofrom 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/.
-
bindir
¶ Sys.BINDIR
ofjulia
. This is passed tojl_init_with_image
unless overridden by argumentoption
toinit_julia
.Type: str
-
sysimage
¶ Path to system image. This is passed to
jl_init_with_image
unless overridden by argumentoption
toinit_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 thejl_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
(orjl_init_with_image__threading
) but makes sure that it is called only once for each process.Parameters: options (sequence of str
orJuliaOptions
) –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 withJuliaInfo.load
.This classmethod runs
JuliaInfo.load
to retrieve information aboutjulia
runtime. This information is used to intializeLibJulia
.
-
-
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
-
is_compatible_python
()¶ Check if python used by PyCall.jl is compatible with
sys.executable
.
-
-
class
julia.api.
JuliaError
¶ Wrapper for Julia exceptions.