SWI-Prolog Python interface
All Application Manual Name SummaryHelp

4 library(janus): Call Python from Prolog

This library implements calling Python from Prolog. It is available directly from Prolog if the janus package is bundled, providing access to an embedded Python instance. If SWI-Prolog is embedded into Python using the Python package janus-swi, this library is provided either from Prolog or from the Python package.

Normally, the Prolog user can simply start calling Python using py_call/2 or friends. In special cases it may be needed to initialize Python with options using py_initialize/3 and optionally the Python search path may be extended using py_add_lib_dir/1.

[det]py_version
Print version info on the embedded Python installation based on Python sys.version. If a Python virtual environment (venv) is active, indicate this with the location of this environment found.
[det]py_call(+Call)
[det]py_call(+Call, -Return)
[det]py_call(+Call, -Return, +Options)
Call Python and return the result of the called function. Call has the shape‘[Target][:Action]*`, where Target is either a Python module name or a Python object reference. Each Action is either an atom to get the denoted attribute from current Target or it is a compound term where the first argument is the function or method name and the arguments provide the parameters to the Python function. On success, the returned Python object is translated to Prolog. Action without a Target denotes a buit-in function.

Arguments to Python functions use the Python conventions. Both positional and keyword arguments are supported. Keyword arguments are written as Name = Value and must appear after the positional arguments.

Below are some examples. 

% call a built-in
?- py_call(print("Hello World!\n")).
true.
% call a built-in (alternative)
?- py_call(builtins:print("Hello World!\n")).
true.
% call function in a module
?- py_call(sys:getsizeof([1,2,3]), Size).
Size = 80.
% call function on an attribute of a module
?- py_call(sys:path:append("/home/bob/janus")).
true
% get attribute from a module
?- py_call(sys:path, Path)
Path = ["dir1", "dir2", ...]

Given a class in a file dog.py such as the following example from the Python documentation 

class Dog:
    tricks = []

    def __init__(self, name):
        self.name = name

    def add_trick(self, trick):
        self.tricks.append(trick)

We can interact with this class as below. Note that $Doc in the SWI-Prolog toplevel refers to the last toplevel binding for the variable Dog. 

?- py_call(dog:'Dog'("Fido"), Dog).
Dog = <py_Dog>(0x7f095c9d02e0).
?- py_call($Dog:add_trick("roll_over")).
Dog = <py_Dog>(0x7f095c9d02e0).
?- py_call($Dog:tricks, Tricks).
Dog = <py_Dog>(0x7f095c9d02e0),
Tricks = ["roll_over"]

py_call/1 can also be used to set an attribute on a module or object using the syntax py_call(Obj:Attr = Value). For example: 

?- py_call(dog:'Dog'("Fido"), Dog),
   py_call(Dog:owner = "Bob"),
   py_call(Doc:owner, Owner).
Dog = <py_Dog>(0x7ffff7112170),
Owner = "Bob".

If the principal term of the first argument is not Target:Func, The argument is evaluated as the initial target, i.e., it must be an object reference or a module. For example: 

?- py_call(dog:'Dog'("Fido"), Dog),
   py_call(Dog, X).
   Dog = X, X = <py_Dog>(0x7fa8cbd12050).
?- py_call(sys, S).
   S = <py_module>(0x7fa8cd582390).

Options processed:

py_string_as(+Type)
If Type is atom (default), translate a Python String into a Prolog atom. If Type is string, translate into a Prolog string. Strings are more efficient if they are short lived.
py_object(Boolean)
If true (default false), translate the return as a Python object reference. Some objects are always translated to Prolog, regardless of this flag. These are the Python constants None, True and False as well as instances of the Python base classes long, float, string or tuple. Instances of sub classes of these base classes are controlled by this option.
[nondet]py_iter(+Iterator, -Value)
[nondet]py_iter(+Iterator, -Value, +Options)
True when Value is returned by the Python Iterator. Python iterators may be used to implement non-deterministic foreign predicates. The implementation uses these steps:

  1. Evaluate Iterator as py_call/2 evaluates its first argument, except the Obj:Attr = Value construct is not accepted.
  2. Call __iter__ on the result to get the iterator itself.
  3. Get the __next__ function of the iterator.
  4. Loop over the return values of the next function. If the Python return value unifies with Value, succeed with a choicepoint. Abort on Python or unification exceptions.
  5. Re-satisfaction continues at (4).

The example below uses the built-in iterator range(): 

?- py_iter(range(1,3), X).
X = 1 ;
X = 2.

Note that the implementation performs a look ahead, i.e., after successful unification it calls‘__next__()` again. On failure the Prolog predicate succeeds deterministically. On success, the next candidate is stored.

Note that a Python generator is a Python _iterator. Therefore, given the Python generator expression below, we can use py_iter(squares(1,5),X) to generate the squares on backtracking. 

def squares(start, stop):
     for i in range(start, stop):
         yield i * i
Options is processed as with py_call/3.
bug
Iterator may not depend on janus.Query()
[semidet]py_is_object(@Term)
True when Term is a Python object reference. Fails silently if @Term is any other Prolog term.
Errors
existence_error(py_object, Term) is raised of Term is a Python object, but it has been freed using py_free/1.
[det]py_free(+Obj)
Immediately free (decrement the reference count) for th Python object Obj. Further reference to Obj using py_call/1,2 or py_free/1 raises an existence_error. Note that by decrementing the reference count, we make the reference invalid from Prolog. This may not actually delete the object because the object may have references inside Python.

Prolog references to Python objects are subject to atom garbage collection and thus normally do not need to be freed explicitly.

[semidet]py_with_gil(:Goal)
Run Goal as once(Goal) while holding the Phyton GIL (Global Interpreter Lock). Note that py_call/1,2 also locks the GIL. This predicate is only required if we wish to make multiple calls to Python while keeping the GIL. The GIL is a recursive lock and thus calling py_call/1,2 while holding the GIL does not deadlock.
[det]py_func(+Module, +Function, -Return)
[det]py_func(+Module, +Function, -Return, +Options)
XSB compatible wrappers for py_call/2. Note that the wrapper supports more call patterns. Options
sizecheck(+Boolean)
Used by XSB for memory management. Ignored in SWI-Prolog.
py_object(+Boolean)
Passed to py_call/3.
[det]py_dot(+Module, +ObjRef, +MethAttr, -Ret)
[det]py_dot(+Module, +ObjRef, +MethAttr, -Ret, +Options)
XSB compatible wrappers for py_call/2.
Module is ignored (why do we need that if we have ObjRef?)
[semidet]values(+Dict, +Path, ?Val)
Get the value associated with Dict at Path. Path is either a single key or a list of keys.
[det]keys(+Dict, ?Keys)
True when Keys is a list of keys that appear in Dict.
[nondet]key(+Dict, ?Key)
True when Key is a key in Dict. Backtracking enumerates all known keys.
[det]items(+Dict, ?Items)
True when Items is a list of Key:Value that appear in Dict.
py_shell
Start an interactive Python REPL loop using the embedded Python interpreter. The interpreter first imports janus as below. 
from janus import *

So, we can do 

?- py_shell.
...
>>> once("writeln(X)", {"X":"Hello world"})
Hello world
{'truth': True}

If possible, we enable command line editing using the GNU readline library.

When used in an environment where Prolog does not use the file handles 0,1,2 for the standard streams, e.g., in swipl-win, Python's I/O is rebound to use Prolog's I/O. This includes Prolog's command line editor, resulting in a mixed history of Prolog and Pythin commands.

[det]py_pp(+Term)
[det]py_pp(+Term, +Options)
[det]py_pp(+Stream, +Term, +Options)
Pretty prints the Prolog translation of a Python data structure in Python syntax. This exploits pformat() from the Python module pprint to do the actual formatting. Options is translated into keyword arguments passed to pprint.pformat(). For example: 
?- py_pp(py{a:1, l:[1,2,3], size:1000000},
         [underscore_numbers(true)]).
{'a': 1, 'l': [1, 2, 3], 'size': 1_000_000}
[det]py_obj_dir(+ObjRef, -List)
[det]py_obj_dict(+ObjRef, -Dict)
Examine attributes of an object. The predicate py_obj_dir/2 fetches the names of all attributes, while py_obj_dict/2 gets a dict with all attributes and their values.
[det]py_initialize(+Program, +Argv, +Options)
Initialize and configure the embedded Python system. If this predicate is not called before any other call to Python such as py_call/2, it is called lazily, passing the Prolog executable as Program, the non-Prolog arguments as Argv and an empty Options list.

Calling this predicate while the Python is already initialized is a no-op. This predicate is thread-safe, where the first thread initializes Python.

In addition to initializing the Python system, it

  • Adds the directory holding janus.py to the Python module search path.
  • If Prolog I/O is not connected to the file handles 0,1,2, it rebinds Python I/O to use the Prolog I/O.
Options is currently ignored. It will be used to provide additional configuration options.
[det]py_lib_dirs(-Dirs)
True when Dirs is a list of directories searched for Python modules. The elements of Dirs are in Prolog canonical notation.
[det]py_add_lib_dir(+Dir)
[det]py_add_lib_dir(+Dir, +Where)
Add a directory to the Python module search path. In the second form, Where is one of first or last. py_add_lib_dir/1 adds the directory as last.

Dir is in Prolog notation. The added directory is converted to an absolute path using the OS notation.

A flexible way to add the directory holding the current Prolog file to the Python search path is in the template below. The here/0 predicate can be replaced by any predicate defined in the file, either above or below the initializing/1 directive. A simple name like here/0 is good style when this code is part of a Prolog module. 

here.
:- initialization
    (   source_file(here, File),
        file_directory_name(File, Dir),
        py_add_lib_dir(Dir, first)
    ).

4.1 Handling Python errors in Prolog

If py_call/2 or one of the other predicates that access Python causes Python to raise an exception, this exception is translated into a Prolog exception of the shape below. The library defines a rule for print_message/2 to render these errors in a human readable way.

error(python_error(ErrorType, Value, Stack), _)

Here, ErrorType is the name of the error type, as an atom, e.g., ’TypeError'. Value is the exception object represented by a Python object reference. Stack is either @none or an object that captures the Python stack. The library(janus) defines the message formatting, which makes us end up with a message like below. 

?- py_call(nomodule:noattr).
ERROR: Python 'ModuleNotFoundError':
ERROR:   No module named 'nomodule'
ERROR: In:
ERROR:   [10] janus:py_call(nomodule:noattr)

4.2 Janus and virtual environments (venv)

An embedded Python system does not automatically pick up Python virtual environments. It is supposed to setup its own environment. Janus is sensitive to Python venv environments. Running under such as environment is assumed if the environment variable VIRTUAL_ENV points at a directory that holds a file pyvenv.cfg. If the virtual environment is detected, the actions in the list below are taken.1This is based on observing how Python 3.10 on Linux responds to being used inside a virtual environment. We do not know whether this covers all platforms and versions.

ClioPatria (version V3.1.1-48-gf653ce4)