PyEus

Python library that builds Foreign Function Interface (what is called FFI between Python and Euslisp.

Ikezaki Shoya ikezaki@csg.ci.i.u-tokyo.ac.jp

PyEus supports Linux only. Though you can probably use PyEus library on your Mac OS X, it is not supported.

PyEus supports Python 2.7 and EusLisp 9.26 (1.2.1). (After Euslisp supports ROS2, Python 3.7 will also be supported.)

Since the library is still an experimental one, please be sure that the whole architecture of the library might be changed. Moreover, it has not yet packaged :)

If you just want to see how it works or just want to try it, please move on to the next step! If you want to see the explanation of each file in the directory first, go to the Description of each file section.

1. clone this package

git clone https://github.com/ikeshou/PyEus.git

2. place pyeus.py, pyeus_util.py, eus_server.l bugfixed_hash.l, inference_eusfunc.l and builtin_type_data.l inside the same directory that your main python program is placed.

3. You can call euslisp functions from your python program after import pyeus !

# Python user code
import pyeus

# some codes here

Suppose that you want to use originalVariable and my-awesome-eus-function in the "ROBOP" package written in Euslisp from Python.
The first thing you have to do is import pyeus library and load the euslisp file by using load_library function where originalVariable and my-awesome-eus-function is written.
Though the module_name argument is optional, please use the argument since it works as "include guard".

# Python user code
import pyeus

pyeus.load_library(src="/Users/ikezakishoya/PyEus/eus_script.l", module_name=":robop")

The next step you should do is making the euslisp package object inside the python by using make_eus_instance function. The keyword notation or quote notation or uppercase string notation is allowed as pkg argument.

# Python user code
robop = pyeus.make_eus_instance(pkg=":robop")

Now that you can use any Euslisp variables/functions/classes as you want! (Of course, you can use Euslisp built-in variables/functions/classes.) You can call Euslisp functions mostly as same as you use fucntions in a Python module.
Before moving on to the precise explanation, please remember there are some rules:

• Since using some symbols ("+-*/@$%^&=<>~.;") is prohibited in Python, these characters in a package/variable/function/class name is automatically translated to underscore("_").
• Because the namespace of the function is separated from other symbols in Euslisp, sometimes there are functions whose name is as same as the name of a variable or a class (e.g. vector). In that case, the prefix "func_" is automatically added to the name of the function in Python in order to tell one from the other. Conversely, you can access variables, functions and classes in Euslisp by completely the same name inside Python except for these cases.
• You can also access the functions of which name conflicts the name of a variable or a class in such way: robop.func.vector.
• All of the keyword argument in Python is automaticaly translated to &key argument.
• If the Euslisp function returns the object that is integer or float or null or t, the result is integer or float or None or True (Python built-in object)). (If you want to know other cases, see the next section!)

var = robop.originalVariable
result = robop.my_awesome_eus_function(*args, **kwargs)

• Importantly, symbols that is passed as an argument is evaluated as a Python object.
  For example,

;; suppose you want to use a ~~strange~~ Euslisp function below
(defun complicated~func (num1, num2, num3, &key param name)
  (if (string= name "py")
      (+ num1 num2 num3 param)))

# Python user code
a, b = 1, 10    # of course, these are python onject
n = robop.complicated_func(a, b, 100, param=1000, name="py")    # a and b are evaluated in Python!

Running the code above is as same as running the following code in Euslisp.

(robop::complicated~func 1 10 100 :param 1000 :name "py")

As a result, the n will be 1111 (Python built-in object "integer").

;; suppose you want to use an Euslisp function below
;; if a list is passed as an argument, Python raises EusError("irteus 0 error: array expected")
(defun zero-zero-elm-of-array (2d-arr)
  (if (= (length (array-dimensions 2d-arr)) 2)
      (aref 2d-arr 0 0)))

# Python user code
result = robop.zero_zero_elm_of_array(EusArray([[1,2],[3,4]]))
print(result)    # 1

# Python user code
result = robop.my_awesome_eus_function(*args, **kwargs)

# Python user code
print(result)    # <class 'pyeus.cons'>, Python proxy object to Euslisp list
L = result.to_python()    # list, Python built-in object
isinstance(L, list)    # True

# Python user code
arr = robop.make_array([2,2])    # arr is an EusArr object
robop.setf(robop.aref(arr, 0, 0), 100)    # assign directly
print(arr.to_python)    # [[100, None], [None, None]] (the 0-0 elment is changed)

You can access the user-defined class and built-in class in the same way.

(accessing the built-in class)

iv = robop.instantiate(robop.integer_vector, 4)    # integer-vector is the built-in class in Euslisp
iv.to_python()    # [0,0,0,0]

(accessing the user-defined class)

(defclass animal :super object :slots (name age))
(defmethod person
  (:print-hi ()
    (format nil "Hi,~A" name))
  (:get-name ()
    name)
  (:get-age ()
    age)
  (:set-name (str)
    (setq name str))
  (:set-age (num)
    (setq age num))
  (:incf-age ()
    (incf age))
  (:list-name-age ()
    (list name age)))

If you want to use the Euslisp user-defined class like above in Python, the code is like following:

murabito = robop.make_instance(robop.animal, name="Tanukichi", age=46)
murabito.get_name().to_python()    # "Tanukichi"
murabito.incf_age()
murabito.get_age()    # 47

L = robop.mapcar(lambda x: robop.cadr(x), [[1,2,3], [4,5,6], [7,8,9]])
L.to_python()    # [2,5,8]

# allowed
robop.mapcar(lambda x: x+1, [1,2,3])

# * NOT ALLOWED *
robop.mapcar(lambda x: x[1], [[1,2,3], [4,5,6], [7,8,9]])

proxy_func_object = robop.cadr    # <class pyeus.compiled_code>
robop.mapcar(proxy_func_object, [[1,2,3], [4,5,6], [7,8,9]])

(in-package "TEST")

(defun list-concatenate (&rest list-of-list)
  (mapcan #'append list-of-list))

TEST.list_concatenate([[1,2,3],[4,5,6],[7,8,9]]).to_python()
# [1,2,3,4,5,6,7,8,9]

TEST.list_concatenate([['a','b','c'],['d','e','f']]).to_python()
# ['a','b','c','d','e','f']

(in-package "TEST")

(defun sum-of-0-0-element (arr1 arr2)
  (+ (aref arr1 0 0) (aref arr2 0 0)))

TEST.sum_of_0_0_element(EusArray([[1,2],[3,4]]), EusArray([[5,6],[7,8]]))    # 6
TEST.sum_of_0_0_element(EusArray([[9,10],[11,12]]), EusArray([[13,14],[15,16]]))    # 22
TEST.sum_of_0_0_element(EusArray([[17,18],[19,20]]), EusArray([[21,22],[23,24]]))    # 38

set_params("sum-of-0-0-element", EusArray, EusArray)

TEST.sum_of_0_0_element([[1,2],[3,4]], [[5,6],[7,8]])    # 6
TEST.sum_of_0_0_element([[9,10],[11,12]], [[13,14],[15,16]])    # 22
TEST.sum_of_0_0_element([[17,18],[19,20]], [[21,22],[23,24]])    # 38