PythonCall API Reference
Py
objects
PythonCall.Core.Py
— TypePy(x)
Convert x
to a Python object, of type Py
.
Conversion happens according to these rules.
Such an object supports attribute access (obj.attr
), indexing (obj[idx]
), calling (obj(arg1, arg2)
), iteration (for x in obj
), arithmetic (obj + obj2
) and comparison (obj > obj2
), among other things. These operations convert all their arguments to Py
and return Py
.
PythonCall.Core.pybuiltins
— Modulepybuiltins
An object whose fields are the Python builtins, of type Py
.
For example pybuiltins.None
, pybuiltins.int
, pybuiltins.ValueError
.
Constructors
These functions construct Python objects of builtin types from Julia values.
PythonCall.Core.pybool
— Functionpybool(x)
Convert x
to a Python bool
.
PythonCall.Core.pycollist
— Functionpycollist(x::AbstractArray)
Create a nested Python list
-of-list
s from the elements of x
. For matrices, this is a list of columns.
PythonCall.Core.pybytes
— Functionpybytes(x)
Convert x
to a Python bytes
.
PythonCall.Core.pycomplex
— Functionpycomplex(x=0.0)
pycomplex(re, im)
Convert x
to a Python complex
, or create one from given real and imaginary parts.
PythonCall.Core.pydict
— Functionpydict(x)
pydict(; x...)
Convert x
to a Python dict
. In the second form, the keys are strings.
If x
is a Python object, this is equivalent to dict(x)
in Python. Otherwise x
must iterate over key-value pairs.
PythonCall.Core.pyfloat
— Functionpyfloat(x=0.0)
Convert x
to a Python float
.
PythonCall.Core.pyfrozenset
— Functionpyfrozenset(x=())
Convert x
to a Python frozenset
.
If x
is a Python object, this is equivalent to frozenset(x)
in Python. Otherwise x
must be iterable.
PythonCall.Core.pyint
— Functionpyint(x=0)
Convert x
to a Python int
.
PythonCall.Core.pylist
— Functionpylist(x=())
Convert x
to a Python list
.
If x
is a Python object, this is equivalent to list(x)
in Python. Otherwise x
must be iterable.
PythonCall.Core.pyrange
— Functionpyrange([[start], [stop]], [step])
Construct a Python range
. Unspecified arguments default to None
.
PythonCall.Core.pyrowlist
— Functionpyrowlist(x::AbstractArray)
Create a nested Python list
-of-list
s from the elements of x
. For matrices, this is a list of rows.
PythonCall.Core.pyset
— Functionpyset(x=())
Convert x
to a Python set
.
If x
is a Python object, this is equivalent to set(x)
in Python. Otherwise x
must be iterable.
PythonCall.Core.pyslice
— Functionpyslice([start], stop, [step])
Construct a Python slice
. Unspecified arguments default to None
.
PythonCall.Core.pystr
— Functionpystr(x)
Convert x
to a Python str
.
PythonCall.Core.pytuple
— Functionpytuple(x=())
Convert x
to a Python tuple
.
If x
is a Python object, this is equivalent to tuple(x)
in Python. Otherwise x
must be iterable.
Builtins
These functions mimic the Python builtin functions or keywords of the same name.
PythonCall.Core.pyall
— Functionpyall(x)
Equivalent to all(x)
in Python.
PythonCall.Core.pyany
— Functionpyany(x)
Equivalent to any(x)
in Python.
PythonCall.Core.pyascii
— Functionpyascii(x)
Equivalent to ascii(x)
in Python.
PythonCall.Core.pycall
— Functionpycall(f, args...; kwargs...)
Call the Python object f
with the given arguments.
PythonCall.Core.pycallable
— Functionpycallable(x)
Equivalent to callable(x)
in Python.
PythonCall.Core.pycompile
— Functionpycompile(...)
Equivalent to compile(...)
in Python.
PythonCall.Core.pycontains
— Functionpycontains(x, v)
Equivalent to v in x
in Python.
PythonCall.Core.pydelattr
— Functionpydelattr(x, k)
Equivalent to delattr(x, k)
or del x.k
in Python.
PythonCall.Core.pydelitem
— Functionpydelitem(x, k)
Equivalent to delitem(x, k)
or del x[k]
in Python.
PythonCall.Core.pydir
— Functionpydir(x)
Equivalent to dir(x)
in Python.
PythonCall.Core.pyeval
— Functionpyeval([T=Py], code, globals, locals=nothing)
Evaluate the given Python code
, returning the result as a T
.
If globals
is a Module
, then a persistent dict
unique to that module is used.
By default the code runs in global scope (i.e. locals===globals
). To use a temporary local scope, set locals
to ()
, or to a NamedTuple
of variables to include in the scope.
See also @pyeval
.
Examples
The following computes 1.1+2.2
in the Main
module as a Float64
:
pyeval(Float64, "x+y", Main, (x=1.1, y=2.2)) # returns 3.3
PythonCall.Core.@pyeval
— Macro@pyeval [inputs =>] code [=> T]
Evaluate the given code
in a new local scope and return the answer as a T
.
The global scope is persistent and unique to the current module.
The code
must be a literal string or command.
The inputs
is a tuple of inputs of the form v=expr
to be included in the local scope. Only v
is required, expr
defaults to v
.
Examples
The following computes 1.1+2.2
and returns a Float64
:
@pyeval (x=1.1, y=2.2) => `x+y` => Float64 # returns 3.3
PythonCall.Core.pyexec
— Functionpyexec([T=Nothing], code, globals, locals=nothing)
Execute the given Python code
.
If globals
is a Module
, then a persistent dict
unique to that module is used.
By default the code runs in global scope (i.e. locals===globals
). To use a temporary local scope, set locals
to ()
, or to a NamedTuple
of variables to include in the scope.
If T==Nothing
then returns nothing
. Otherwise T
must be a concrete NamedTuple
type and the corresponding items from locals
are extracted and returned.
See also @pyexec
.
Examples
The following computes 1.1+2.2
in the Main
module as a Float64
:
pyexec(@NamedTuple{ans::Float64}, "ans=x+y", Main, (x=1.1, y=2.2)) # returns (ans = 3.3,)
Marking variables as global
saves them into the module scope, so that they are available in subsequent invocations:
pyexec("global x; x=12", Main)
pyeval(Int, "x", Main) # returns 12
PythonCall.Core.@pyexec
— Macro@pyexec [inputs =>] code [=> outputs]
Execute the given code
in a new local scope.
The global scope is persistent and unique to the current module.
The code
must be a literal string or command.
The inputs
is a tuple of inputs of the form v=expr
to be included in the local scope. Only v
is required, expr
defaults to v
.
The outputs
is a tuple of outputs of the form x::T=v
, meaning that v
is extracted from locals, converted to T
and assigned to x
. Only x
is required: T
defaults to Py
and v
defaults to x
.
Examples
The following computes 1.1+2.2
and assigns its value to ans
as a Float64
:
@pyexec (x=1.1, y=2.2) => `ans=x+y` => ans::Float64 # returns 3.3
Marking variables as global
saves them into the module scope, so that they are available in subsequent invocations:
@pyexec `global x; x=12`
@pyeval `x` => Int # returns 12
PythonCall.Core.pygetattr
— Functionpygetattr(x, k, [d])
Equivalent to getattr(x, k)
or x.k
in Python.
If d
is specified, it is returned if the attribute does not exist.
PythonCall.Core.pygetitem
— Functionpygetitem(x, k, [d])
Equivalent x[k]
in Python.
If d
is specified, it is returned if the item does not exist (i.e. if x[k]
raises a KeyError
or IndexError
).
PythonCall.Core.pyhasattr
— Functionpyhasattr(x, k)
Equivalent to hasattr(x, k)
in Python.
Tests if getattr(x, k)
raises an AttributeError
.
PythonCall.Core.pyhasitem
— Functionpyhasitem(x, k)
Test if pygetitem(x, k)
raises a KeyError
or AttributeError
.
PythonCall.Core.pyhash
— Functionpyhash(x)
Equivalent to hash(x)
in Python, converted to an Integer
.
PythonCall.Core.pyhelp
— Functionpyhelp([x])
Equivalent to help(x)
in Python.
PythonCall.Core.pyimport
— Functionpyimport(m)
pyimport(m => k)
pyimport(m => (k1, k2, ...))
pyimport(m1, m2, ...)
Import a module m
, or an attribute k
, or a tuple of attributes.
If several arguments are given, return the results of importing each one in a tuple.
PythonCall.Core.pyin
— Functionpyin(v, x)
Equivalent to v in x
in Python.
PythonCall.Core.pyis
— Functionpyis(x, y)
True if x
and y
are the same Python object. Equivalent to x is y
in Python.
PythonCall.Core.pyisinstance
— Functionpyisinstance(x, t)
Test if x
is of type t
. Equivalent to isinstance(x, t)
in Python.
PythonCall.Core.pyissubclass
— Functionpyissubclass(s, t)
Test if s
is a subclass of t
. Equivalent to issubclass(s, t)
in Python.
PythonCall.Core.pyiter
— Functionpyiter(x)
Equivalent to iter(x)
in Python.
PythonCall.Core.pylen
— Functionpylen(x)
The length of x
. Equivalent to len(x)
in Python, converted to an Integer
.
PythonCall.Core.pynext
— Functionpynext(x)
Equivalent to next(x)
in Python.
PythonCall.Core.pyprint
— Functionpyprint(...)
Equivalent to print(...)
in Python.
PythonCall.Core.pyrepr
— Functionpyrepr(x)
Equivalent to repr(x)
in Python.
PythonCall.Core.pysetattr
— Functionpysetattr(x, k, v)
Equivalent to setattr(x, k, v)
or x.k = v
in Python.
PythonCall.Core.pysetitem
— Functionpysetitem(x, k, v)
Equivalent to setitem(x, k, v)
or x[k] = v
in Python.
PythonCall.Core.pytype
— Methodpytype(x)
The Python type
of x
.
PythonCall.Core.pywith
— Functionpywith(f, o, d=nothing)
Equivalent to with o as x: f(x)
in Python, where x
is a Py
.
On success, the value of f(x)
is returned.
If an exception occurs but is suppressed then d
is returned.
Conversion to Julia
These functions convert Python values to Julia values, using the rules documented here.
PythonCall.Core.pyconvert
— Functionpyconvert(T, x, [d])
Convert the Python object x
to a T
.
If d
is specified, it is returned on failure instead of throwing an error.
PythonCall.Convert.@pyconvert
— Macro@pyconvert(T, x, [onfail])
Convert the Python object x
to a T
.
On failure, evaluates to onfail
, which defaults to return pyconvert_unconverted()
(mainly useful for writing conversion rules).
Wrap Julia values
These functions explicitly wrap Julia values into Python objects, documented here.
As documented here, Julia values are wrapped like this automatically on conversion to Python, unless the value is immutable and has a corresponding Python type.
PythonCall.JlWrap.pyjl
— Functionpyjl([t=pyjltype(x)], x)
Create a Python object wrapping the Julia object x
.
If x
is mutable, then mutating the returned object also mutates x
, and vice versa.
Its Python type is normally inferred from the type of x
, but can be specified with t
.
For example if x
is an AbstractVector
then the object will have type juliacall.VectorValue
. This object will satisfy the Python sequence interface, so for example uses 0-up indexing.
To define a custom conversion for your type T
, overload pyjltype(::T)
.
PythonCall.JlWrap.pyjlraw
— Functionpyjlraw(v)
Create a Python object wrapping the Julia object x
.
It has type juliacall.RawValue
. This has a much more rigid "Julian" interface than pyjl(v)
. For example, accessing attributes or calling this object will always return a RawValue
.
PythonCall.JlWrap.pyisjl
— Functionpyisjl(x)
Test whether x
is a wrapped Julia value, namely an instance of juliacall.ValueBase
.
PythonCall.JlWrap.pyjlvalue
— Functionpyjlvalue(x)
Extract the value from the wrapped Julia value x
.
PythonCall.JlWrap.pybinaryio
— Functionpybinaryio(io::IO)
Wrap io
as a Python binary IO object.
This is the default behaviour of Py(io)
.
PythonCall.JlWrap.pytextio
— Functionpytextio(io::IO)
Wrap io
as a Python text IO object.
Arithmetic
These functions are equivalent to the corresponding Python arithmetic operators.
Note that the equivalent Julia operators are overloaded to call these when all arguments are Py
(or Number
). Hence the following are equivalent: Py(1)+Py(2)
, Py(1)+2
, pyadd(1, 2)
, pyadd(Py(1), Py(2))
, etc.
PythonCall.Core.pyneg
— Functionpyneg(x)
Equivalent to -x
in Python.
PythonCall.Core.pypos
— Functionpypos(x)
Equivalent to +x
in Python.
PythonCall.Core.pyabs
— Functionpyabs(x)
Equivalent to abs(x)
in Python.
PythonCall.Core.pyinv
— Functionpyinv(x)
Equivalent to ~x
in Python.
PythonCall.Core.pyindex
— Functionpyindex(x)
Convert x
losslessly to an int
.
PythonCall.Core.pyadd
— Functionpyadd(x, y)
Equivalent to x + y
in Python.
PythonCall.Core.pysub
— Functionpysub(x, y)
Equivalent to x - y
in Python.
PythonCall.Core.pymul
— Functionpymul(x, y)
Equivalent to x * y
in Python.
PythonCall.Core.pymatmul
— Functionpymatmul(x, y)
Equivalent to x @ y
in Python.
PythonCall.Core.pypow
— Functionpypow(x, y, z=None)
Equivalent to x ** y
or pow(x, y, z)
in Python.
PythonCall.Core.pyfloordiv
— Functionpyfloordiv(x, y)
Equivalent to x // y
in Python.
PythonCall.Core.pytruediv
— Functionpytruediv(x, y)
Equivalent to x / y
in Python.
PythonCall.Core.pymod
— Functionpymod(x, y)
Equivalent to x % y
in Python.
PythonCall.Core.pydivmod
— Functionpydivmod(x, y)
Equivalent to divmod(x, y)
in Python.
PythonCall.Core.pylshift
— Functionpylshift(x, y)
Equivalent to x << y
in Python.
PythonCall.Core.pyrshift
— Functionpyrshift(x, y)
Equivalent to x >> y
in Python.
PythonCall.Core.pyand
— Functionpyand(x, y)
Equivalent to x & y
in Python.
PythonCall.Core.pyxor
— Functionpyxor(x, y)
Equivalent to x ^ y
in Python.
PythonCall.Core.pyor
— Functionpyor(x, y)
Equivalent to x | y
in Python.
PythonCall.Core.pyiadd
— Functionpyiadd(x, y)
In-place add. x = pyiadd(x, y)
is equivalent to x += y
in Python.
PythonCall.Core.pyisub
— Functionpyisub(x, y)
In-place subtract. x = pyisub(x, y)
is equivalent to x -= y
in Python.
PythonCall.Core.pyimul
— Functionpyimul(x, y)
In-place multiply. x = pyimul(x, y)
is equivalent to x *= y
in Python.
PythonCall.Core.pyimatmul
— Functionpyimatmul(x, y)
In-place matrix multiply. x = pyimatmul(x, y)
is equivalent to x @= y
in Python.
PythonCall.Core.pyipow
— Functionpyipow(x, y, z=None)
In-place power. x = pyipow(x, y)
is equivalent to x **= y
in Python.
PythonCall.Core.pyifloordiv
— Functionpyifloordiv(x, y)
In-place floor divide. x = pyifloordiv(x, y)
is equivalent to x //= y
in Python.
PythonCall.Core.pyitruediv
— Functionpyitruediv(x, y)
In-place true division. x = pyitruediv(x, y)
is equivalent to x /= y
in Python.
PythonCall.Core.pyimod
— Functionpyimod(x, y)
In-place subtraction. x = pyimod(x, y)
is equivalent to x %= y
in Python.
PythonCall.Core.pyilshift
— Functionpyilshift(x, y)
In-place left shift. x = pyilshift(x, y)
is equivalent to x <<= y
in Python.
PythonCall.Core.pyirshift
— Functionpyirshift(x, y)
In-place right shift. x = pyirshift(x, y)
is equivalent to x >>= y
in Python.
PythonCall.Core.pyiand
— Functionpyiand(x, y)
In-place and. x = pyiand(x, y)
is equivalent to x &= y
in Python.
PythonCall.Core.pyixor
— Functionpyixor(x, y)
In-place xor. x = pyixor(x, y)
is equivalent to x ^= y
in Python.
PythonCall.Core.pyior
— Functionpyior(x, y)
In-place or. x = pyior(x, y)
is equivalent to x |= y
in Python.
Logic
These functions are equivalent to the corresponding Python logical operators.
Note that the equivalent Julia operators are overloaded to call these when all arguments are Py
(or Number
). Hence the following are equivalent: Py(1) < Py(2)
, Py(1) < 2
, pylt(1, 2)
, pylt(Py(1), Py(2))
, etc.
Note that the binary operators by default return Py
(not Bool
) since comparisons in Python do not necessarily return bool
.
PythonCall.Core.pytruth
— Functionpytruth(x)
The truthyness of x
. Equivalent to bool(x)
in Python, converted to a Bool
.
PythonCall.Core.pynot
— Functionpynot(x)
The falsyness of x
. Equivalent to not x
in Python, converted to a Bool
.
PythonCall.Core.pyeq
— Functionpyeq(x, y)
pyeq(Bool, x, y)
Equivalent to x == y
in Python. The second form converts to Bool
.
PythonCall.Core.pyne
— Functionpyne(x, y)
pyne(Bool, x, y)
Equivalent to x != y
in Python. The second form converts to Bool
.
PythonCall.Core.pyle
— Functionpyle(x, y)
pyle(Bool, x, y)
Equivalent to x <= y
in Python. The second form converts to Bool
.
PythonCall.Core.pylt
— Functionpylt(x, y)
pylt(Bool, x, y)
Equivalent to x < y
in Python. The second form converts to Bool
.
PythonCall.Core.pyge
— Functionpyge(x, y)
pyge(Bool, x, y)
Equivalent to x >= y
in Python. The second form converts to Bool
.
PythonCall.Core.pygt
— Functionpygt(x, y)
pygt(Bool, x, y)
Equivalent to x > y
in Python. The second form converts to Bool
.
Create classes
These functions can be used to create new Python classes where the functions are implemented in Julia. You can instead use @pyeval
etc. to create pure-Python classes.
PythonCall.Core.pytype
— Methodpytype(name, bases, dict)
Create a new type. Equivalent to type(name, bases, dict)
in Python.
If bases
is not a Python object, it is converted to one using pytuple
.
The dict
may either by a Python object or a Julia iterable. In the latter case, each item may either be a name => value
pair or a Python object with a __name__
attribute.
In order to use a Julia Function
as an instance method, it must be wrapped into a Python function with pyfunc
. Similarly, see also pyclassmethod
, pystaticmethod
or pyproperty
. In all these cases, the arguments passed to the function always have type Py
. See the example below.
Example
Foo = pytype("Foo", (), [
"__module__" => "__main__",
pyfunc(
name = "__init__",
doc = """
Specify x and y to store in the Foo.
If omitted, y defaults to None.
""",
function (self, x, y = nothing)
self.x = x
self.y = y
return
end,
),
pyfunc(
name = "__repr__",
self -> "Foo($(self.x), $(self.y))",
),
pyclassmethod(
name = "frompair",
doc = "Construct a Foo from a tuple of length two.",
(cls, xy) -> cls(xy...),
),
pystaticmethod(
name = "hello",
doc = "Prints a friendly greeting.",
(name) -> println("Hello, $name"),
),
"xy" => pyproperty(
doc = "A tuple of x and y.",
get = (self) -> (self.x, self.y),
set = function (self, xy)
(x, y) = xy
self.x = x
self.y = y
nothing
end,
),
])
PythonCall.JlWrap.pyfunc
— Functionpyfunc(f; [name], [qualname], [doc], [signature])
Wrap the callable f
as an ordinary Python function.
The name, qualname, docstring or signature can optionally be set with name
, qualname
, doc
or signature
.
Unlike Py(f)
(or pyjl(f)
), the arguments passed to f
are always of type Py
, i.e. they are never converted.
PythonCall.JlWrap.pyclassmethod
— Functionpyclassmethod(f; ...)
Convert callable f
to a Python class method.
If f
is not a Python object (e.g. if f
is a Function
) then it is converted to one with pyfunc
. In particular this means the arguments passed to f
are always of type Py
. Keyword arguments are passed to pyfunc
.
PythonCall.JlWrap.pystaticmethod
— Functionpystaticmethod(f; ...)
Convert callable f
to a Python static method.
If f
is not a Python object (e.g. if f
is a Function
) then it is converted to one with pyfunc
. In particular this means the arguments passed to f
are always of type Py
. Any keyword arguments are passed to pyfunc
.
PythonCall.JlWrap.pyproperty
— Functionpyproperty(; get=nothing, set=nothing, del=nothing, doc=nothing)
pyproperty(get)
Create a Python property
with the given getter, setter and deleter.
If get
, set
or del
is not a Python object (e.g. if it is a Function
) then it is converted to one with pyfunc
. In particular this means the arguments passed to it are always of type Py
.
Wrapper types
The following types wrap a Python object, giving it the semantics of a Julia object. For example PyList(x)
interprets the Python sequence x
as a Julia abstract vector.
Apart from a few fundamental immutable types, conversion from Python to Julia Any
will return a wrapper type such as one of these, or simply Py
if no wrapper type is suitable.
PythonCall.Wrap.PyList
— TypePyList{T=Py}([x])
Wraps the Python list x
(or anything satisfying the sequence interface) as an AbstractVector{T}
.
If x
is not a Python object, it is converted to one using pylist
.
PythonCall.Wrap.PySet
— TypePySet{T=Py}([x])
Wraps the Python set x
(or anything satisfying the set interface) as an AbstractSet{T}
.
If x
is not a Python object, it is converted to one using pyset
.
PythonCall.Wrap.PyDict
— TypePyDict{K=Py,V=Py}([x])
Wraps the Python dict x
(or anything satisfying the mapping interface) as an AbstractDict{K,V}
.
If x
is not a Python object, it is converted to one using pydict
.
PythonCall.Wrap.PyIterable
— TypePyIterable{T=Py}(x)
This object iterates over iterable Python object x
, yielding values of type T
.
PythonCall.Wrap.PyArray
— TypePyArray{T,N,M,L,R}(x; copy=true, array=true, buffer=true)
Wrap the Python array x
as a Julia AbstractArray{T,N}
.
The input x
can be bytes
, bytearray
, array.array
, numpy.ndarray
or anything satisfying the buffer protocol (if buffer=true
) or the numpy array interface (if array=true
).
If copy=false
then the resulting array is guaranteed to directly wrap the data in x
. If copy=true
then a copy is taken if necessary to produce an array.
The type parameters are all optional, and are:
T
: The element type.N
: The number of dimensions.M
: True if the array is mutable.L
: True if the array supports fast linear indexing.R
: The element type of the underlying buffer. Often equal toT
.
PythonCall.Wrap.PyIO
— TypePyIO(x; own=false, text=missing, line_buffering=false, buflen=4096)
Wrap the Python IO stream x
as a Julia IO stream.
When this goes out of scope and is finalized, it is automatically flushed. If own=true
then it is also closed.
If text=false
then x
must be a binary stream and arbitrary binary I/O is possible. If text=true
then x
must be a text stream and only UTF-8 must be written (i.e. use print
not write
). If text
is not specified then it is chosen automatically. If x
is a text stream and you really need a binary stream, then often PyIO(x.buffer)
will work.
If line_buffering=true
then output is flushed at each line.
For efficiency, reads and writes are buffered before being sent to x
. The size of the buffers is buflen
. The buffers are cleared using flush
.
PythonCall.Wrap.PyTable
— TypePyTable(x)
Wrap x
as a Tables.jl-compatible table.
PyTable
is an abstract type. See PyPandasDataFrame
for a concrete example.
PythonCall.Wrap.PyPandasDataFrame
— TypePyPandasDataFrame(x; [indexname::Union{Nothing,Symbol}], [columnnames::Function], [columntypes::Function])
Wraps the pandas DataFrame x
as a Tables.jl-compatible table.
indexname
: The name of the column including the index. The default isnothing
, meaning to exclude the index.columnnames
: A function mapping the Python column name (aPy
) to the Julia one (aSymbol
). The default isx -> Symbol(x)
.columntypes
: A function taking the column name (aSymbol
) and returning either the desired element type of the column, ornothing
to indicate automatic inference.
PythonCall.JlWrap.PyObjectArray
— TypePyObjectArray(undef, dims...)
PyObjectArray(array)
An array of Py
s which supports the Python buffer protocol.
Internally, the objects are stored as an array of pointers.
PythonCall.Core.PyException
— TypePyException(x)
Wraps the Python exception x
as a Julia Exception
.
Custom wrappers
Here is a minimal example of defining a wrapper type. You may add methods, fields and a supertype to the type to specialise its behaviour. See any of the above wrapper types for examples.
# The new type with a field for the Python object being wrapped.
struct MyType
py::Py
end
# Says that the object is a wrapper.
ispy(x::MyType) = true
# Says how to access the underlying Python object.
Py(x::MyType) = x.py
@py
and @pyconst
PythonCall.PyMacro.@py
— Macro@py expr
Evaluate the given expression using Pythonic semantics.
For example:
f(x, y)
is translated topycall(f, x, y)
x + y
is translated topyadd(x, y)
x === y
is translated topyis(x, y)
(x is y
in Python)x.foo
is translated topygetattr(x, "foo")
import x: f as g
is translated tog = pyimport("x" => "f")
(from x import f as g
in Python)
Compound statements such as begin
, if
, while
and for
are supported.
See the online documentation for more details.
This macro is experimental. It may be modified or removed in a future release.
PythonCall.Core.@pyconst
— Macro@pyconst ex
Equivalent to Py(ex)
but always returns the exact same Julia object.
That is, if foo() = @pyconst ex
then foo() === foo()
.
The expression ex
is evaluated the first time the code is run.
If ex
is a string literal, the string is interned.
Do not use this macro at the top level of a module. Instead, use pynew()
and pycopy!()
.
Multi-threading
These functions are not exported. They support multi-threading of Python and/or Julia. See also juliacall.AnyValue._jl_call_nogil
.
PythonCall.GIL.lock
— Functionlock(f)
Lock the GIL, compute f()
, unlock the GIL, then return the result of f()
.
Use this to run Python code from threads that do not currently hold the GIL, such as new threads. Since the main Julia thread holds the GIL by default, you will need to unlock
the GIL before using this function.
See @lock
for the macro form.
PythonCall.GIL.@lock
— Macro@lock expr
Lock the GIL, compute expr
, unlock the GIL, then return the result of expr
.
Use this to run Python code from threads that do not currently hold the GIL, such as new threads. Since the main Julia thread holds the GIL by default, you will need to @unlock
the GIL before using this function.
The macro equivalent of lock
.
PythonCall.GIL.unlock
— Functionunlock(f)
Unlock the GIL, compute f()
, re-lock the GIL, then return the result of f()
.
Use this to run non-Python code with the GIL unlocked, so allowing another thread to run Python code. That other thread can be a Julia thread, which must lock the GIL using lock
.
See @unlock
for the macro form.
PythonCall.GIL.@unlock
— Macro@unlock expr
Unlock the GIL, compute expr
, re-lock the GIL, then return the result of expr
.
Use this to run non-Python code with the GIL unlocked, so allowing another thread to run Python code. That other thread can be a Julia thread, which must lock the GIL using @lock
.
The macro equivalent of unlock
.
PythonCall.GC.gc
— FunctionPythonCall.GC.gc()
Free any Python objects waiting to be freed.
These are objects that were finalized from a thread that was not holding the Python GIL at the time.
Like most PythonCall functions, this must only be called from the main thread (i.e. the thread currently holding the Python GIL.)
The Python interpreter
These functions are not exported. They give information about which Python interpreter is being used.
PythonCall.C.python_version
— Functionpython_version()
The version of Python, or missing
if not known.
PythonCall.C.python_executable_path
— Functionpython_executable_path()
Path to the Python interpreter, or missing
if not known.
PythonCall.C.python_library_path
— Functionpython_library_path()
Path to libpython, or missing
if not known.
PythonCall.C.python_library_handle
— Functionpython_library_handle()
Handle to the open libpython, or C_NULL
if not known.
Low-level API
The functions here are not exported. They are mostly unsafe in the sense that you can crash Julia by using them incorrectly.
PythonCall.Core.pynew
— Functionpynew([ptr])
A new Py
representing the Python object at ptr
(NULL by default).
If ptr
is given and non-NULL, this function steals a reference to the Python object it points at, i.e. the new Py
object owns a reference.
Note that NULL Python objects are not safe in the sense that most API functions will probably crash your Julia session if you pass a NULL argument.
PythonCall.Core.pyisnull
— Functionpyisnull(x)
True if the Python object x
is NULL.
PythonCall.Core.pycopy!
— Functionpycopy!(dst::Py, src)
Copy the Python object src
into dst
, so that they both represent the same object.
This function exists to support module-level constant Python objects. It is illegal to call most PythonCall API functions at the top level of a module (i.e. before __init__()
has run) so you cannot do const x = pything()
at the top level. Instead do const x = pynew()
at the top level then pycopy!(x, pything())
inside __init__()
.
Assumes dst
is NULL, otherwise a memory leak will occur.
PythonCall.Core.getptr
— Functiongetptr(x)
Get the underlying pointer from the Python object x
.
PythonCall.Core.pydel!
— Functionpydel!(x::Py)
Delete the Python object x
.
DANGER! Use this function ONLY IF the Julia object x
could have been garbage-collected anyway, i.e. was about to become unreachable. This means you MUST KNOW that no other part of the program has the Julia object x
.
This decrements the reference count, sets the pointer to NULL and appends x
to a cache of unused objects (PYNULL_CACHE
).
This is an optimization to avoid excessive allocation and deallocation in Julia, which can be a significant source of slow-down in code which uses a lot of Python objects. It allows pynew()
to pop an item from PYNULL_CACHE
instead of allocating one, and avoids calling the relatively slow finalizer on x
.
PythonCall.Core.unsafe_pynext
— Functionunsafe_pynext(x)
Return the next item in the iterator x
. When there are no more items, return NULL.