Python Interoperability

Despite being a Lisp, Hy aims to be fully compatible with Python. That means every Python module or package can be imported in Hy code, and vice versa.

Mangling allows variable names to be spelled differently in Hy and Python. For example, Python’s str.format_map can be written str.format-map in Hy, and a Hy function named valid? would be called is_valid in Python. You can call hy.mangle and hy.unmangle from either language.

Using Python from Hy

To use a Python module from Hy, just import it. No additional ceremony is required.

You can embed Python code directly into a Hy program with the macros py and pys, and you can use standard Python tools like eval() or exec() to execute or manipulate Python code in strings.

Using Hy from Python

To use a Hy module from Python, you can just import it, provided that hy has already been imported first, whether in the current module or in some earlier module executed by the current Python process. The hy import is necessary to create the hooks that allow importing Hy modules. Note that you can always have a wrapper Python file (such as a package’s __init__.py) do the import hy for the user; this is a smart thing to do for a published package.

No way to import macros or reader macros into a Python module is implemented, since there’s no way to call them in Python anyway.

You can use hy2py to convert a Hy program to Python. The output will still import hy, and thus require Hy to be installed in order to run; see Implicit names for details and workarounds.

To execute Hy code from a string, use hy.read-many to convert it to models and then hy.eval to evaluate it:

>>> hy.eval(hy.read_many("(setv x 1) (+ x 1)"))
2

There is no Hy equivalent of exec() because hy.eval works even when the input isn’t equivalent to a single Python expression.

You can use hy.REPL.run() to launch the Hy REPL from Python, as in hy.REPL(locals = locals()).run().

Libraries that expect Python

There are various means by which Hy may interact poorly with a Python library

because the library doesn’t account for the possibility of Hy. For example, when you run hy, sys.executable will be set to this program rather than the original Python binary. This is helpful more often than not, but will lead to trouble if e.g. the library tries to call sys.executable with the -c option. In this case, you can try setting sys.executable back to hy.sys-executable, which is a saved copy of the original value. More generally, you can use hy2py, or you can put a simple Python wrapper script like import hy, my_hy_program in front of your code.