OCaml-Python Bindings Generator

Generate Python bindings with pyml directly from OCaml value specifications.

While you could write all your Python bindings by hand, it can be tedious and it gets old real quick. While pyml_bindgen can't yet auto-generate all the bindings you may need, it can definitely take care of a lot of the tedious and repetitive work you need to do when writing bindings for a big Python library!! 💖

How to get started

Getting started with a new package or library and going through lots of docs can be frustrating. Here's the order I would suggest you look at these docs

Read the installing and quick start sections of this page.
Then read through the getting started tutorial. If you only read one page in the docs, make it this one! It explains most of what you need to know to get started with a simple example, while not getting bogged down in too much details.
Next, check out some working examples on GitHub.
Finally, there are some more (potentially) important details in the Rules and Miscellaneous sections of this site.

If you have any questions or issues, please let me know about it on GitHub!

Note: I try to keep this doc updated, but it may sometimes get out-of-sync with the latest pyml_bindgen. For the most up-to-date info, see the examples, tests, and dev tests, which are tested and kept up-to-date under CI.

Installing

Using Opam

pyml_bindgen is available on Opam. You can install it in the normal way:

$ opam install pyml_bindgen

Installing from sources

If you want to install from sources, e.g., to track the main branch or a development branch, but you do not want to install all the test and development packages, clone the repository, checkout the branch you want to follow and run opam install manually:

$ git clone https://github.com/mooreryan/ocaml_python_bindgen.git
$ git checkout dev
$ opam install .

This will save a lot of install time as it avoids some heavy packages.

Development

If instead, you want to work on pyml_bindgen development, will need to ensure you have the test dependencies, as well as a couple dependencies that are not included in the opam file (core, core_bench, and bisect_ppx.)

E.g.,

$ git clone https://github.com/mooreryan/ocaml_python_bindgen.git
$ opam install . --deps-only --with-doc --with-test
$ opam install core core_bench core_unix bisect_ppx
$ dune build

Quick start

Note: You can find full examples in the examples directory on GitHub. One neat thing about the examples there is that you can see how to write Dune rules to automatically generate your pyml bindings.

pyml_bindgen is a CLI program that generates OCaml modules that bind Python classes via pyml.

Here's a small example. Take a Python class, Thing. (Put it in a file called thing.py...this means the Python module will be called thing.)

class Thing:
    def __init__(self, x):
        self.x = x

    def add(self, y):
        return self.x + y

Now, look at your Python class and decide how you would like to use this class on the OCaml side.

For now, we will just do a direct translation, keeping in mind the rules for writing value specs that pyml_bindgen can process. Maybe something like this. (Put it in a file called val_specs.txt.)

val __init__ : x:int -> unit -> t

val x : t -> int

val add : t -> y:int -> unit -> int

Finally, to generate the OCaml code, run the pyml_bindgen program. There are a couple of options you can choose, but let's just keep it simple for now.

$ pyml_bindgen val_specs.txt thing Thing --caml-module=Thing > lib.ml

If you want nicer formatting than that which is generated by pyml_bindgen, you can use ocamlformat.

$ ocamlformat --enable-outside-detected-project lib.ml

Next steps

Check out the examples for more info about using and running pyml_bindgen. Then, check out the rules that you have to follow when writing value specifications that pyml_bindgen can read.

Additionally, you may want to check out this blog post introducing pyml_bindgen.

License

Software

Licensed under the Apache License, Version 2.0 or the MIT license, at your option. This program may not be copied, modified, or distributed except according to those terms.

Documentation

This documentation is licensed under a Creative Commons Attribution 4.0 International License.