|
There are two ways to call Python from Codon:
|
||
|
|
|
||
|
|
- `from python import` allows importing and calling Python functions
|
||
|
|
from existing Python modules.
|
||
|
|
- `@python` allows writing Python code directly in Codon.
|
||
|
|
|
||
|
|
In order to use these features, the `CODON_PYTHON` environment variable
|
||
|
|
must be set to the appropriate Python shared library:
|
||
|
|
|
||
|
|
``` bash
|
||
|
|
export CODON_PYTHON=/path/to/libpython.X.Y.so
|
||
|
|
```
|
||
|
|
|
||
|
|
For example, with a Homebrew-installed Python 3.9 on macOS, this might be
|
||
|
|
|
||
|
|
```
|
||
|
|
/usr/local/opt/python@3.9/Frameworks/Python.framework/Versions/3.9/lib/libpython3.9.dylib
|
||
|
|
```
|
||
|
|
|
||
|
|
Note that only Python versions 3.6 and later are supported.
|
||
|
|
|
||
|
|
!!! tip "Tip: Finding `libpython`"
|
||
|
|
|
||
|
|
You can use
|
||
|
|
[this](https://raw.githubusercontent.com/exaloop/codon/refs/heads/develop/test/python/find-python-library.py)
|
||
|
|
script to locate the Python shared library for the `CODON_PYTHON` environment variable. Simply run it as
|
||
|
|
`python3 find-python-library.py` and it will print the library path.
|
||
|
|
|
||
|
|
!!! info "Info: Using virtual environments (`venv`)"
|
||
|
|
|
||
|
|
If you are using a virtual environment created with `venv`, set `PYTHON_PATH` to the `site-packages`
|
||
|
|
directory inside your virtual environment (e.g. `.venv/lib/python3.11/site-packages`).
|
||
|
|
|
||
|
|
!!! info "Info: Using virtual environments (`uv`)"
|
||
|
|
|
||
|
|
If you using a virtual environment created with `uv`, you can use the following steps to set up the necessary
|
||
|
|
environment variables. From the parent directory of your python project (where `pyproject.toml` is):
|
||
|
|
|
||
|
|
1. Run `uv python find --system` and set `PYTHON_HOME` to the result.
|
||
|
|
2. Set `CODON_PYTHON` to the `libpython.dylib` (or `.so`) file found in the folder from the previous
|
||
|
|
step (e.g. `lib/python3.11.dylib`) as an absolute path.
|
||
|
|
3. Set `PYTHON_PATH` to the `site-packages` folder inside your virtual environment (e.g `.venv/lib/python3.11/site-packages`).
|
||
|
|
|
||
|
|
## Import Python modules in Codon
|
||
|
|
|
||
|
|
Python modules can be imported and used in Codon-compiled programs through
|
||
|
|
a `from python import <module>` import statement. For example:
|
||
|
|
|
||
|
|
``` python
|
||
|
|
from python import sys # imports Python's 'sys' module
|
||
|
|
print(sys.version) # 3.11.12 (main, Apr 8 2025, 14:15:29) [Clang 17.0.0 (clang-1700.0.13.3)]
|
||
|
|
```
|
||
|
|
|
||
|
|
You can also import third-party libraries. Here is an example that imports
|
||
|
|
Matplotlib to create a simple plot:
|
||
|
|
|
||
|
|
``` python
|
||
|
|
from python import matplotlib.pyplot as plt
|
||
|
|
|
||
|
|
x = [1, 2, 3, 4, 5]
|
||
|
|
y = [2, 5, 3, 6, 4]
|
||
|
|
|
||
|
|
fig, ax = plt.subplots()
|
||
|
|
ax.plot(x, y)
|
||
|
|
plt.show()
|
||
|
|
```
|
||
|
|
|
||
|
|
Objects created from imported Python modules can be manipulated and operated on
|
||
|
|
from Codon. Internally, such operations are implemented by using CPython's C API.
|
||
|
|
For example, we can create a Pandas dataframe in Codon, and perform operations
|
||
|
|
on it:
|
||
|
|
|
||
|
|
``` python
|
||
|
|
from python import pandas as pd
|
||
|
|
df = pd.DataFrame({'A': [1, 2, 3], 'B': [4, 5, 6]}) # internally a Python object
|
||
|
|
print(df['B'].max()) # 6
|
||
|
|
```
|
||
|
|
|
||
|
|
## Run Python code directly in Codon
|
||
|
|
|
||
|
|
It is also possible to annotate functions with the `@python` decorator in order
|
||
|
|
to have them execute in Python, instead of being compiled by Codon:
|
||
|
|
|
||
|
|
``` python
|
||
|
|
@python
|
||
|
|
def version():
|
||
|
|
# the following runs in plain Python
|
||
|
|
import sys
|
||
|
|
print(sys.version)
|
||
|
|
|
||
|
|
version() # 3.11.12 (main, Apr 8 2025, 14:15:29) [Clang 17.0.0 (clang-1700.0.13.3)]
|
||
|
|
```
|
||
|
|
|
||
|
|
`@python` functions can specify return types, in which case returned values will
|
||
|
|
be checked and converted to native Codon types:
|
||
|
|
|
||
|
|
``` python
|
||
|
|
@python
|
||
|
|
def foo():
|
||
|
|
return 2 + 2
|
||
|
|
|
||
|
|
@python
|
||
|
|
def bar() -> int:
|
||
|
|
return 2 + 2
|
||
|
|
|
||
|
|
@python
|
||
|
|
def baz() -> int:
|
||
|
|
return 'abc'
|
||
|
|
|
||
|
|
|
||
|
|
print(foo()) # 4 (Python object)
|
||
|
|
print(bar()) # 4 (native Codon int)
|
||
|
|
print(baz()) # error: Python object did not have type 'int'
|
||
|
|
```
|
||
|
|
|
||
|
|
Similarly, arguments can be type-annotated as well:
|
||
|
|
|
||
|
|
``` python
|
||
|
|
@python
|
||
|
|
def square(n: int) -> int:
|
||
|
|
return n * n
|
||
|
|
|
||
|
|
print(square(4)) # 16
|
||
|
|
```
|
||
|
|
|
||
|
|
## Data conversions
|
||
|
|
|
||
|
|
Codon uses two new magic methods to transfer data to and from Python:
|
||
|
|
|
||
|
|
- `__to_py__`: Produces a Python object (`PyObject*` in C) given a Codon object.
|
||
|
|
- `__from_py__`: Produces a Codon object given a Python object.
|
||
|
|
|
||
|
|
For example:
|
||
|
|
|
||
|
|
``` python
|
||
|
|
import python # needed to initialize the Python runtime
|
||
|
|
|
||
|
|
o = (42).__to_py__() # type of 'o' is 'Ptr', equivalent to a pointer in C
|
||
|
|
print(o) # 0x100e00610
|
||
|
|
|
||
|
|
n = int.__from_py__(o) # converts Python object 'o' to native Codon integer
|
||
|
|
print(n) # 42
|
||
|
|
```
|
||
|
|
|
||
|
|
Codon stores the results of `__to_py__` calls by wrapping them in an instance of a new
|
||
|
|
class called `pyobj`, which correctly handles the underlying Python object's reference
|
||
|
|
count. All operations on `pyobj`s then go through CPython's API.
|