💎 🐍 Crystal meets Python!
Crython is a tool that lets you use Python libraries in Crystal, a programming language. It provides seamless integration between Crystal and Python, allowing you to leverage Python's ecosystem while enjoying Crystal language.
- You need Python3. Python3.12 or later is recommended.
- Make sure
python3-config --ldflagsworks.
Add this to your dependencies:
dependencies:
crython:
github: kojix2/crythonTo find Python libraries, set the LD_LIBRARY_PATH:
export LD_LIBRARY_PATH=$(python3 -c \
"import sysconfig; print(sysconfig.get_config_var('LIBDIR'))"):$LD_LIBRARY_PATHThis command adds the Python library directory to LD_LIBRARY_PATH.
To use Crython in your Crystal project, add this line:
require "crython"For complex numbers, also add:
require "complex"Import a Python module
np = Crython.import("numpy")Use the module
array = np.array([1, 2, 3])
result = array * 2
puts result # [2 4 6]Crython.session do
# Write your Python code here
Crython.eval("print('Hello from Python!')")
# Import modules and use them
np = Crython.import("numpy")
array = np.array([1, 2, 3])
puts array
endConvert Crystal objects to Python objects using the to_py method:
42.to_py # Python int
3.14.to_py # Python float
"hello".to_py # Python str
[1, 2, 3].to_py # Python list
{"a" => 1, "b" => 2}.to_py # Python dict
true.to_py # Python bool
nil.to_py # Python None
Complex.new(1, 2).to_py # Python complexConvert Python objects to Crystal objects using the to_cr method:
py_int = 42.to_py
py_int.to_cr # Int64: 42py_float = 3.14.to_py
py_float.to_cr # Float64: 3.14py_str = "hello".to_py
py_str.to_cr # String: "hello"py_list = [1, 2, 3].to_py
py_list.to_cr # Array(PyObject)py_dict = {"a" => 1, "b" => 2}.to_py
py_dict.to_cr # Hash(PyObject, PyObject)py_bool = true.to_py
py_bool.to_cr # Bool: truepy_none = nil.to_py
py_none.to_cr # Nil: nilpy_complex = Complex.new(1, 2).to_py
py_complex.to_cr # Complex: 1+2iYou can also convert Python objects to specific Crystal types:
py_list = [1, 2, 3].to_py
Array(Int32).new(py_list) # Array(Int32): [1, 2, 3]py_dict = {"a" => 1, "b" => 2}.to_py
Hash(String, Int32).new(py_dict) # Hash(String, Int32): {"a" => 1, "b" => 2}Call methods on Python objects
py_str = "hello".to_py
py_str.upper.to_cr # "HELLO"Access attributes
np = Crython.import("numpy")
version = np.attr("__version__").to_cr
puts "NumPy version: #{version}"Call methods with arguments
math = Crython.import("math")
result = math.pow(2, 3).to_cr
puts "2^3 = #{result}" # 8.0Call methods with keyword arguments
plt = Crython.import("matplotlib.pyplot")
plt.plot([1, 2, 3], [4, 5, 6], color: "red", marker: "o")- Use
obj.call("Abc")to call a Python attribute whose name is not a valid Crystal method name. - Use
obj.call("Abc", arg1, arg2)to call it with positional arguments. - Use
"-".to_py.attr("join")to get a function attribute. - Use
Crython.slice_fullinstead of:.
Crython.session do
begin
# This will raise an error
Crython.eval("1/0")
rescue ex
puts "Python error: #{ex.message}"
end
endFor more examples, check the examples folder. To build all examples, use:
make examples
Then run:
./bin/hello
Crython.session do
np = Crython.import("numpy")
x1 = np.array([1, 2, 3])
x2 = np.array([4, 5, 6])
y = x1 + x2
puts "#{x1} + #{x2} = #{y}" # [1 2 3] + [4 5 6] = [5 7 9]
endCrython.session do
plt = Crython.import("matplotlib.pyplot")
# Create data
x = [1, 2, 3, 4, 5]
y = [1, 4, 9, 16, 25]
# Create plot
plt.plot(x, y, marker: "o", linestyle: "--")
plt.title("Square Numbers")
plt.xlabel("Number")
plt.ylabel("Square")
# Show plot
plt.show
end- Symbol conversion: Crystal cannot create Symbols at runtime, so Python strings cannot be converted to Crystal Symbols.
- Union types: Converting Python collections with mixed types to Crystal collections with union types is not fully supported.
python3-config usually provides the correct flags for linking. If it doesn't, you can manually set LDFLAGS to your environment's library path. For example, if using micromamba:
LDFLAGS="-L/Users/<your-username>/micromamba/envs/crython/lib -lpython3.13" make examplesReplace <your-username> with your actual username and adjust the path as necessary.
If you get an error like error while loading shared libraries: libpython3.13.so.1.0: cannot open shared object file: No such file or directory, make sure you've set the LD_LIBRARY_PATH correctly:
export LD_LIBRARY_PATH=$(python3 -c "import sysconfig; print(sysconfig.get_config_var('LIBDIR'))"):$LD_LIBRARY_PATHIf you encounter linking errors during compilation, check that python3-config --ldflags returns the correct flags for your Python installation.
Fork ➔ Edit ➔ Commit ➔ Pull Request
Romain Franceschini - The original creator of the Crython project
