package pyml
Install
Dune Dependency
Authors
Maintainers
Sources
sha512=79237ab56a2e439e785f4d873abd603fdaa51dbbb1258efb25102ca897826cf4d5d15e8467f324df85bba3c61995ceee8fb82d0808cda0da8010e024a78307aa
doc/pyml/Pycaml/index.html
Module PycamlSource
Embedding Python into OCaml.
(C) arty 2002
This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
A Derivative of Art Yerkes' 2002 Pycaml module.
Modifications (C) 2005 Dr. Thomas Fischbacher, Giuliano Bordignon, Dr. Hans Fangohr, SES, University of Southampton
More modifications are by Barry Schwartz. Copyright (C) 2009 Barry Schwartz.
Adapted for py.ml by Thierry Martinez. Copyright (C) 2016 Thierry Martinez.
Background Information
The original code is available in Debian as package "pycaml".
For various reasons, we hijacked it so that we can easily both fix bugs and extend it. This is permitted by the Pycaml license (the GNU LGPL).
Note: the layout and hierarchical structure of the documentation could need some more work.
OCaml Types, Python Types, and general issues of typing
Python objects are wrapped up within OCaml as entities of type pyobject.
The following types are slightly esoteric; normally, users of this module should not have any need to access them.
As Python is a dynamically typed language, pyobject values may represent entities of very different nature. The pytype function maps a pyobject to its type, or rather, a selection of types that have been made known to OCaml. The default for "unknown" values is OtherType.
Note (for advanced users only): This in particular holds for PyCObject values, which are used at present to wrap up OCaml values opaquely within Python values: at present, these appear to be of type OtherType, but there might be good reason to change this in the future.
type pyerror_type = | Pyerr_Exception| Pyerr_StandardError| Pyerr_ArithmeticError| Pyerr_LookupError| Pyerr_AssertionError| Pyerr_AttributeError| Pyerr_EOFError| Pyerr_EnvironmentError| Pyerr_FloatingPointError| Pyerr_IOError| Pyerr_ImportError| Pyerr_IndexError| Pyerr_KeyError| Pyerr_KeyboardInterrupt| Pyerr_MemoryError| Pyerr_NameError| Pyerr_NotImplementedError| Pyerr_OSError| Pyerr_OverflowError| Pyerr_ReferenceError| Pyerr_RuntimeError| Pyerr_SyntaxError| Pyerr_SystemExit| Pyerr_TypeError| Pyerr_ValueError| Pyerr_ZeroDivisionError
Also note the existence of pytype_name, which maps python types to human-readable strings.
Initialization
The Python interpreter has to be initialized, which is done via py_initialize. Note that this module does call this function automatically when it is initialized itself, so the end user does not have to worry about this.
Note that Python initialization seems to be idempotent, so there should not be any problems if one starts up a python interpreter first, and then loads a shared object via Python's foreign function interface which itself initializes OCaml and pycaml. (Note: However, this still needs more testing!)
Functions from the original Pycaml
There is a collection of functions from the original Pycaml module which are not-too-well-documented. For some of them, there are examples available, and often, one can guess what they are supposed to do from their name and type. (Admittedly, this is a quite unsatisfactory state of affairs, but on the other hand, as it turns out, we will have to use only very few of them. So for now, if there is a question, look at the source, or ask t.fischbacher\@soton.ac.uk.)
In order not to clutter the Pycaml documentation with a block of unreadable code, they have been moved to the last section.
On wrapping up Ocaml values for Python
The Pycaml functions pywrap_value and pyunwrap_value are elementary low-level primitives to make opaque Python values that hold OCaml values. As Python is a dynamically typed language, and OCaml is a statically typed language, and both achieve safety in a somewhat misaligned way, this interface may be considered as dangerous. In fact, it allows one to break OCaml type safety by mapping a statically typed value to a dynamically typed Python value and back.
This means that a Python user handing a wrapped-up ocaml value of a different type than expected over to an OCaml callback may crash the system.
This module provides an extension to the original Pycaml which will have added checks that prevent precisely such a situation and therefore is safer. Note however, that at the moment, it is only foolproof if one does not mix this up with other PyCObject Python values. (Presumably, it can be tightened up by introducing a new primitive Python type PyCamlObject. TODO.)
Genuine Extensions to the original Pycaml
Converting values and handling errors
Map an OCaml array of Python values to a Python list and vice versa. (This was just missing.)
While the functions in ocaml.* should not be made visible to end users directly, it may nevertheless be helpful to be able to set docstrings on them.
Return a name-string for an Ocaml Python-Object-Type value. Used mainly for debugging and in error messages.
Return the last value that was computed interactively at the Python prompt
A convenient function to make a collection of pyobject values (which usually will be OCaml callbacks) known to Python in one go. The strings give the names under which the corresponding values should appear in Python's "ocaml" module, which Pycaml will add to Python and automatically import on the Python side.
Note that as a convention, one must not register names that start with the string "example_" or "sys_", as those are reserved for internal use by Pycaml.
These functions provides a quick and convenient way to pass a simple array of numbers to Python. Note that neither on the OCaml nor on the Python side, the special data structure for efficient manipulation of large numerical arrays is used (OCaml: bigarray, Python: numarray). Rather, this just maps ordinary arrays.
This little helper creates a nested float array python structure that is supposed to represent a multi-indexed tensor, plus a function to set tensor entries.
val unpythonizing_function :
?name:string ->
?catch_weird_exceptions:bool ->
?extra_guards:(pyobject -> string option) array ->
?expect_tuple:bool ->
pyobject_type array ->
(pyobject array -> 'a) ->
pyobject ->
'aval python_interfaced_function :
?name:string ->
?catch_weird_exceptions:bool ->
?doc:string ->
?extra_guards:(pyobject -> string option) array ->
pyobject_type array ->
(pyobject array -> pyobject) ->
pyobjectThis helper simplifies the creation of OCaml callbacks that can be registered in Python's "ocaml" module.
First argument: An array of pyobject_type Python types.
Second argument: A "body" function B mapping an OCaml array of Python values to a Python return value.
Optional argument: An array of extra checks to be performed on the arguments, one by one, returning an optional error message.
The body function (as well as the optional checks) will be wrapped up in code that first checks for the correct number and the specified Python types of arguments, so B can rely on the n'th entry of its Python argument array being of the Python type specified in the n'th position of the type array.
XXX Note: we need examples in the documentation!
Sometimes, we want to manipulate complicated structures via Python which are implemented in OCaml, and about whose interna only OCaml should know and have to worry. So, all that one can do from Python is to place such values in containers (tuples, lists) and retrieve them back, pass them around, and hand them over to OCaml callbacks.
In order to ensure type safety, we have to extend OCaml by a primitive dynamic type system for Python-wrapped OCaml values. This is based on the following assumptions:
- The number of different OCaml types we might want to make visible to Python is quite limited. (In particular, we do not even try to properly support polymorphism.)
- Python should be allowed to take a peek at the type name of a wrapped OCaml value at runtime
Thus, before one can opaquely wrap up OCaml values in "ocamlpills" for Python, one has to register a type name with Pycaml. From the Python side, the function ocaml.sys_ocamlpill_type(x) will map the ocamlpill x to the registered type string.
py.ml: Pill types are not required to be registered. This function does nothing and is provided for compatibility only.
val pill_type_mismatch_exception :
?position:'a ->
?exn_name:string ->
string ->
string ->
exnGiven an ocamlpill type name (which was registered before using register_ocamlpill_type), as well as a witness of the type in question in form of a prototypical OCaml value, make a function that maps other OCaml values of the same type as the prototype to Python ocamlpills. This function is exported to python as ocaml.sys_ocamlpill_type.
Note: a simple type system hack is used to ensure that the wrapper function generated can only be applied to OCaml values of the proper type. One major drawback of this is that presumably, the prototypical object provided cannot be garbage collected until the wrapper function is. (A clever compiler might be able to figure out how to get rid of that, though.)
XXX Provide example code!
py.ml: the signature has been changed from string -> 'a -> ('a -> pyobject) * (pyobject -> 'b) to string -> 'a -> ('a -> pyobject) * (pyobject -> 'a). The second argument is ignored and the function calls Py.Capsule.make. Applying the function twice to the same type name raises a failure (Failure _).
py.ml: the signature has been changed from string -> 'a -> ('a -> pyobject) * (pyobject -> 'b) to string -> 'a -> ('a -> pyobject) * (pyobject -> 'a). The second argument is ignored and the function calls Py.Capsule.make. Applying the function twice to the same type name raises a failure (Failure _).
Also, we want to be able to pass optional arguments from python to OCaml. The convention which we use for now is as follows:
- Conceptually, an optional argument has to be a container monadic type.
- The only thing offered by python which looks like such a thing is the list.
- Hence, optional values are represented as 0-element or 1-element lists on the python side.
We then need ocaml functions that make it convenient to handle the automatic unpacking of such values. (XXX Note: we need examples in the documentation that show how to use this!)
This is semi-internal - It should only be used for writing other convenience type applicators that have their own way of doing the checking.
Running and evaluating Python from within OCaml
This function allows us to set Python's sys.argv
A convenience function for just letting the Python interpreter evaluate a block of Python code.
One may use python_eval "execfile(...)" to load Python code into the interpreter. This function provides a slightly nicer way to do the same.
Note 1: Internally, this uses python_eval. The int return value is ignored, however.
Note 2: As we do not bother to properly escape quotation marks, this will not work as supposed on filenames containing double quotes. (Yes, this is a bug and should better be fixed!)
Start the interactive python toplevel:
Start the ipython toplevel. Note: for still unknown reasons, this does not seem to be 100% reliable, and especially seems to fail in many situations where Pycaml.ipython() is called not from the OCaml toplevel. May be some crazy terminal handling bug.
Addition: 23/01/2006 fangohr:
On Mac OS X, one of the problems is that there are often several Python installations. (One is provided by Apple, but usually a fink or Darwinport installation is actually meant to use.) For fink-python (the binary installed in /sw/bin, it helps to set the shell environment variable PYTHONHOME=/sw .
Then the call to ipython works fine.
Python Functions
All functions which are made visible from OCaml to python by means of register_for_python go into the Python module ocaml. Usually, one wants to place low-level interface functions there and build higher levels of abstraction on the python side on top of it which are more convenient (maybe object-oriented) to the Python end user. So, the user of a Python library that uses OCaml callbacks internally should (ideally) never notice the existence of the ocaml Python module.
The following names are pre-registered in the ocaml module. Note that they all start with the reserved prefixes sys_ or example_.
sys_ocamlpill_type: Function that maps an OCaml pill to a type string, so that Python can find out what a given pill is supposed to be. (The OCaml function name isocamlpill_type_of.)
sys_python: Function that starts a recursive Python toplevel. This may seem strange at first, but actually is highly useful e.g. for providing some interactive control deep inside a contrived function during debugging. Return value is the value computed last on the recursive python command prompt.
example_test_interface: Function that just prints a test string.
example_the_answer: The number "42", put in theocamlmodule by OCaml.
example_make_powers: A function mapping an integernand a floatpto the array[|1.0**p,2.0**p,...,(float_of_int n)**p|]
.
example_hypotenuse: A function mapping two floatingpoint valuesx,ytosqrt(x**2+y**2).
It is instructive to have a look at the pycaml source providing the example_ entries to see how one can publish other constants and functions to Python.
Code Examples
The implementations of example_make_powers and example_hypotenuse demonstrate how to use python_interfaced_function:
let _py_make_powers =
python_interfaced_function
~extra_guards:
[|(fun py_len ->
let len = pyint_asint py_len in
if len < 0
then Some "Negative Length"
else None);
(fun _ -> None); (* This check never fails *)
|]
[|IntType;FloatType|]
(fun py_args ->
let len = pyint_asint py_args.(0)
and pow = pyfloat_asdouble py_args.(1)
in
float_array_to_python
(Array.init len (fun n -> let nn = float_of_int (n+1) in nn**pow)))
and
_py_hypotenuse_2d =
python_interfaced_function
[|FloatType;FloatType|]
(fun py_args ->
let x = pyfloat_asdouble py_args.(0)
and y = pyfloat_asdouble py_args.(1)
in pyfloat_fromdouble (sqrt(x*.x+.y*.y)))
in
register_for_python
[|("example_make_powers", _py_make_powers);
("example_hypotenuse", _py_hypotenuse_2d);
|]
;;Appendix: signatures of undocumented functions from the original Pycaml
py.ml: the result type has been changed from int to pyobject.
py.ml: the result type has been changed from int to pyobject.
py.ml: one of the two pyobject arguments has been removed.