Conversion to Julia

Conversion Rules

The following table specifies the conversion rules used whenever converting a Python object to a Julia object. If the initial Python type matches the "From" column and the desired type T intersects with the "To" column, then that conversion is attempted. Conversions are tried in priority order, then in specificity order.

From Julia, one can convert Python objects to a desired type using pyconvert(T, x) for example.

From Python, the arguments to a Julia function will be converted according to these rules with T=Any.

FromTo
Top priority (wrapped values).
juliacall.AnyValueAny
juliacall.AsAny
Very high priority (arrays).
Objects satisfying the buffer or array interface (inc. bytes, bytearray, array.array, numpy.ndarray)PyArray
High priority (canonical conversions).
NoneNothing
boolBool
numbers.Integral (inc. int)Integer (prefers Int, or BigInt on overflow)
floatFloat64
complexComplex{Float64}
rangeStepRange
strString
tupleTuple
collections.abc.Mapping (inc. dict)PyDict
collections.abc.Sequence (inc. list)PyList
collections.abc.Set (inc. set, frozenset)PySet
io.IOBase (includes open files)PyIO
BaseExceptionPyException
datetime.date/datetime.time/datetime.datetimeDate/Time/DateTime
datetime.timedeltaMicrosecond (or Millisecond or Second on overflow)
numpy.intXX/numpy.uintXX/numpy.floatXXIntXX/UIntXX/FloatXX
Standard priority (other reasonable conversions).
NoneMissing
bytesVector{UInt8}, Vector{Int8}, String
strString, Symbol, Char, Vector{UInt8}, Vector{Int8}
rangeUnitRange
collections.abc.MappingDict
collections.abc.IterableVector, Set, Tuple, NamedTuple, Pair
datetime.timedeltaDates.CompoundPeriod
numbers.IntegralInteger, Rational, Real, Number
numbers.RealAbstractFloat, Number, Missing/Nothing (if NaN)
numbers.ComplexComplex, Number
ctypes.c_int and other integersInteger, Rational, Real, Number
ctypes.c_float/ctypes.c_doubleCfloat/Cdouble, AbstractFloat, Real, Number
ctypes.c_voidpPtr{Cvoid}, Ptr
ctypes.c_char_pCstring, Ptr{Cchar}, Ptr
ctypes.c_wchar_pCwstring, Ptr{Cwchar}, Ptr
numpy.intXX/numpy.uintXX/numpy.floatXXInteger, Rational, Real, Number
Objects satisfying the buffer or array interfaceArray, AbstractArray
Low priority (fallback to Py).
AnythingPy
Bottom priority (must be explicitly specified by excluding Py).
Objects satisfying the buffer interfacePyBuffer
AnythingPyRef

See below for an explanation of the Py* types (PyList, PyIO, etc).

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.PyList — Type
PyList{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.PySet — Type
PySet{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.PyDict — Type
PyDict{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.PyIterable — Type
PyIterable{T=Py}(x)

This object iterates over iterable Python object x, yielding values of type T.

PythonCall.PyArray — Type
PyArray{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. Equal to T for scalar numeric types.
PythonCall.PyIO — Type
PyIO(x; own=false, text=missing, 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.

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.PyTable — Type
PyTable

Abstract type for Python wrappers which may be interpretable as Tables.jl-compatible tables.

If pyconvert(PyTable, x::Py) is a table, then x is also a table.

PythonCall.PyPandasDataFrame — Type
PyPandasDataFrame(x; indexname=nothing, columntypes=Dict())

Wraps the pandas DataFrame x as a Tables.jl-compatible table.

indexname is the name of the column to contain the index. It may be nothing to exclude the index.

columntypes is a mapping of column names to column element types, in case automatic deduction does not work.

PythonCall.PyObjectArray — Type
PyObjectArray(undef, dims...)
PyObjectArray(array)

An array of Pys which supports the Python buffer protocol.

Internally, the objects are stored as an array of pointers.