PyBase.jl

TL;DR

It takes just one line (per type) to define a Python interface:

using MyModule: MyType
using PyCall
using PyBase

PyCall.PyObject(self::MyType) = PyBase.UFCS.wrap(self)
# PyCall.PyObject(self::MyType) = PyBase.Plain.wrap(self)  # alternative

It defines an interface for MyType which can be imported from Python by from julia.MyModule import MyType via PyJulia.

Overview

Suppose you have a Julia type and want to expose its API to the Python world:

julia> mutable struct MyType
           x::Number
       end

julia> add1!(self::MyType) = self.x += 1;

julia> add2(self::MyType) = self.x + 2;

julia> add3(self::MyType) = self.x + 3
       add3!(self::MyType) = self.x += 3;

Using PyBase, it is just a one line to wrap it into a Python interface:

julia> using PyCall
       using PyBase

julia> PyCall.PyObject(self::MyType) = PyBase.UFCS.wrap(self);

Now MyType is usable from Python. Here, for a demonstration purpose, let's send it to Python namespace using PyCall's @py_str macro:

julia> py"""
       MyType = $MyType  # emulating "from julia.MyModule import MyType"
       """

Python users can now use MyType as if it is a Python function.

julia> py"""
       obj = MyType(0)
       assert obj.x == 0
       """

Since MyType uses PyBase.UFCS.wrap, Julia functions taking MyType as the first argument can be called as if it was a Python method of MyType:

julia> py"""
       obj.add1()
       assert obj.x == 1
       """

julia> py"""
       assert obj.add2() == 3
       assert obj.x == 1
       """

julia> py"""
       assert obj.add3(inplace=False) == 4
       assert obj.x == 1
       """

julia> py"""
       obj.add3()  # default to inplace=True
       assert obj.x == 4
       """

It may be useful to provide custom Python methods. This can be done by overloading PyBase.__getattr__:

julia> PyBase.__getattr__(self::MyType, ::Val{:explicit_method}) =
           (arg) -> "explicit method call with $arg"

julia> py"""
       assert obj.explicit_method(123) == "explicit method call with 123"
       """

Note that various Julia interfaces are automatically usable from Python. For example, indexing just works by translating indices as the offsets from Base.firstindex (which keeps 0-origin in Python side):

julia> Base.firstindex(obj::MyType) = 1;

julia> Base.getindex(obj::MyType, i::Integer) = i;

julia> py"""
       assert obj[0] == 1
       """

Pre-defined wrapper factories

"Uniform Function Call Syntax"

PyBase.UFCS — Module.

Uniform Function Call Syntax [UFCS] wrapper.

Usage:

PyCall.PyObject(self::MyModule.MyType) = PyBase.UFCS.wrap(self)

It then translates Python method call self.NAME(*args, **kwargs) to

MyModule.MyType.NAME(self, args...; kwargs...)  # or
MyModule.MyType.NAME!(self, args...; kwargs...)

in Julia where NAME is a placeholder (i.e., it can be a method named solve or plot). If both NAME and NAME! exist, NAME! is used unless False is passed to the special keyword argument inplace, i.e.,

# in Python:                               #    in Julia:
self.NAME(*args, **kwargs)                 # => NAME(self, args...; kwargs...)
                                           # or NAME!(self, args...; kwargs...)
self.NAME(*args, inplace=False, **kwargs)  # => NAME(self, args...; kwargs...)
self.NAME(*args, inplace=True, **kwargs)   # => NAME!(self, args...; kwargs...)

The modules in which method NAME is searched can be specified as a keyword argument to PyBase.UFCS.wrap:

using MyBase, MyModule
PyCall.PyObject(self::MyType) = PyBase.UFCS.wrap(self,
                                                 modules = [MyBase, MyModule])

The first match in the list of modules is used.

Usual method overloading of

PyBase.__getattr__(self::MyModule.MyType, name::Symbol)  # and/or
PyBase.__getattr__(self::MyModule.MyType, ::Val{name})

can still control the behavior of Python's __getattr__ if name is not already handled by the above UFCS mechanism.