Piton

Piton is a library which will help you to run your Python code.

You can implement your own Piton.Port and run your python code but I highly recommend to use Piton.Pool, a pool which will allow to run Python code in parallel, a way of avoiding the GIL, and it will protect you from python exceptions.

Requirements

• Elixir ~> 1.19
• Python 3.x
• Erlang/OTP 27

Installation

Add piton to your list of dependencies in mix.exs:

def deps do
  [{:piton, "~> 0.5.0"}]
end

How to use it

Define your own port

• The Easiest one

defmodule MySimplePort do
  use Piton.Port
end

• A port with some wrapper functions which will help you to call the python function: YOUR_MODULE.execute(pid, python_module, python_function, list_of_arguments)

defmodule MyCustomPort do
  use Piton.Port
  def start_link(), do: MyCustomPort.start_link([path: Path.expand("python_folder"), python: "python"], [name: __MODULE__])
  def fun(n), do: MyCustomPort.execute(__MODULE__, :functions, :fun, [n])
end

• A port prepared to be run by Piton.Pool They have to have a function start() and it has not to be linked.

defmodule MyPoolPort do
  use Piton.Port
  def start(), do: MyPoolPort.start([path: Path.expand("python_folder"), python: "python"], [])
  def fun(pid, n), do: MyPoolPort.execute(pid, :functions, :fun, [n])
end

Run a Pool

Pay attention to the number of Pythons you want to run in parallel. It does not exist an optimal number, maybe it is the number of cores, maybe half or maybe double. Test it with your application.

{:ok, pool} = Piton.Pool.start_link([module: MyPoolPort, pool_number: pool_number], [])

Call a Port (No pool)

iex> MyCustomPort.execute(pid_of_the_port, python_module, python_function, list_of_arguments_of_python_function)

Call a Pool

iex> Piton.Pool.execute(pid_of_the_pool, elixir_function, list_of_arguments_of_elixir_function)

Tasks

Some Mix.Tasks have been included in order to facilitate the integration of a python project

• Mix.Tasks.Piton.Venv: It creates a Python Virtual Environment.
• Mix.Tasks.Piton.Pip: It upgrades the Python pip.
• Mix.Tasks.Piton.Requirements: It gets the dependencies of the Python project.

Test

Before running tests, create a Python virtual environment:

python3 -m venv test/venv

Then run the tests:

mix test 

CI/CD

This project uses GitHub Actions for continuous integration and deployment:

Continuous Integration (CI)

Every push and pull request triggers automated tests.

Workflow: .github/workflows/ci.yml

The CI workflow:

• ✅ Runs on Elixir 1.19.2 and OTP 27.1
• ✅ Compiles code with warnings as errors
• ✅ Runs full test suite
• ✅ Checks code formatting
• ✅ Caches dependencies for faster builds

Triggers: All branches on push and all pull requests

Automatic Publishing to Hex.pm

When you create a new GitHub release, the package is automatically published to Hex.pm.

Workflow: .github/workflows/publish.yml

The workflow:

• ✅ Runs on Elixir 1.19.2 and OTP 27.1
• ✅ Installs dependencies with caching
• ✅ Runs tests before publishing
• ✅ Automatically publishes to Hex.pm on release

To publish a new version:

1. Update the version in mix.exs
2. Update CHANGELOG.md with changes
3. Commit and push changes
4. Create a new GitHub release (e.g., v0.5.0)
5. The package will be automatically published to Hex.pm

Required Secret: HEX_KEY - Your Hex.pm API key must be added to GitHub repository secrets.

Name

Pitón is only Python in Spanish :stuck_out_tongue_winking_eye: :snake: