# Polyglot FFI
**Automatic FFI bindings generator for polyglot projects**
[](https://pypi.org/project/polyglot-ffi/)
[](https://www.python.org)
[](https://github.com/chizy7/polyglot-ffi/actions/workflows/ci.yml)
[](https://codecov.io/gh/chizy7/polyglot-ffi)
Stop writing FFI boilerplate. Start building amazing things.
---
## What is Polyglot FFI?
Polyglot FFI automatically generates complete Foreign Function Interface (FFI) bindings between programming languages. Write your OCaml interface once, and get type-safe, memory-safe bindings for Python (and soon Rust, Go, etc.) instantly.
### The Problem
Building multi-language projects requires writing:
- 50+ lines of OCaml ctypes boilerplate
- 30+ lines of C stubs with tricky memory management
- 20+ lines of Python ctypes configuration
- Plus: Dune configs, debugging, memory leaks...
### The Solution
```bash
polyglot-ffi generate crypto.mli
```
**Done!** All 100+ lines generated automatically.
---
## Quick Example
### Primitive Types
**1. Write OCaml interface:**
```ocaml
(* crypto.mli *)
val encrypt : string -> string
(** Encrypt a string *)
val hash : string -> int
(** Hash to integer *)
```
**2. Generate bindings:**
```bash
polyglot-ffi generate crypto.mli -o generated/ -n crypto
```
**3. Use from Python:**
```python
from generated.crypto_py import encrypt, hash
encrypted = encrypt("secret")
hash_val = hash("data")
```
### Complex Types
**1. Write OCaml interface with complex types:**
```ocaml
(* user.mli *)
type user = {
name: string;
age: int;
email: string option;
}
type result = Ok of user | Error of string
val find_user : string -> user option
val create_user : string -> int -> string -> result
val get_all_users : unit -> user list
val get_name_and_age : user -> string * int
```
**2. Generate bindings:**
```bash
polyglot-ffi generate user.mli
```
**3. Use from Python with full type hints:**
```python
from typing import Optional, List, Tuple
from generated.user_py import find_user, create_user, get_all_users
# Option type → Optional[User]
user = find_user("john") # Returns Optional[User]
# Variant type → Result
result = create_user("Jane", 25, "jane@example.com")
# List type → List[User]
all_users = get_all_users() # Returns List[User]
# Tuple type → Tuple[str, int]
name, age = get_name_and_age(user) # Returns Tuple[str, int]
```
---
## Installation
### From PyPI
```bash
pip install polyglot-ffi
```
### From Source
```bash
git clone https://github.com/chizy7/polyglot-ffi
cd polyglot-ffi
pip install -e ".[dev]"
```
### Verify
```bash
polyglot-ffi --version
# Output: polyglot_ffi, version 0.4.0
```
### Upgrading
To upgrade to the latest version:
```bash
pip install --upgrade polyglot-ffi
```
To upgrade to a specific version:
```bash
pip install --upgrade polyglot-ffi==0.5.0
```
See the [full installation guide](docs/installation.md) for detailed instructions including:
- Virtual environment setup
- Shell completion
- Troubleshooting
- Platform-specific notes
- **[Complete upgrade guide](docs/installation.md#upgrading)** with all options
---
## Features
- **Automatic Code Generation**: One command generates OCaml ctypes, C wrappers, Python modules, and build configs.
- **Plus Many More Features**: Check docs and roadmap!
### Some Future Features
- [ ] Rust target support
- [ ] Go target support
- [ ] Bidirectional bindings
- [ ] Plugin system
---
## Documentation
- **[Quickstart Guide](docs/quickstart.md)** - Get started in 5 minutes
- **[Architecture](docs/architecture.md)** - How it works
- **[Type Mapping](docs/type-mapping.md)** - Type system reference
- **[Contributing](docs/contributing.md)** - Join development
---
## Why Polyglot FFI?
### Zero Boilerplate
One command generates everything:
- OCaml ctypes declarations
- C wrapper functions
- Python wrapper module
- Build configuration
- Type conversions
- Error handling
### Type Safe
Preserves type information:
- Python type hints
- OCaml type constraints
- C type declarations
- Compile-time checking
### Memory Safe
Proper memory management:
- CAMLparam/CAMLreturn macros
- No memory leaks
- String ownership handled
- GC-safe conversions
---
## Use Cases
- **Cryptography**: OCaml for correctness, Python for integration
- **Data Processing**: OCaml for logic, Python for data science
- **Financial Systems**: OCaml for algorithms, Python for reporting
- **ML Infrastructure**: OCaml for pipelines, Python for training
---
## Quick Start
### Initialize a New Project
```bash
polyglot-ffi init my-crypto-lib
cd my-crypto-lib
```
### Edit Your Interface
```ocaml
(* src/my-crypto-lib.mli *)
val greet : string -> string
val add : int -> int -> int
```
### Generate Bindings
```bash
polyglot-ffi generate src/my-crypto-lib.mli
```
### Implement OCaml Functions
```ocaml
(* src/my-crypto-lib.ml *)
let greet name = "Hello, " ^ name ^ "!"
let add x y = x + y
let () =
Callback.register "greet" greet;
Callback.register "add" add
```
### Use from Python
```python
from generated.my_crypto_lib_py import greet, add
print(greet("World")) # Hello, World!
print(add(2, 3)) # 5
```
---
## CLI Reference
```bash
# Initialize project
polyglot-ffi init my-project
polyglot-ffi init --interactive # Interactive setup
# Generate bindings
polyglot-ffi generate src/module.mli
polyglot-ffi generate -o bindings/ -n mymodule
polyglot-ffi generate --dry-run # Preview only
polyglot-ffi generate --force # Force regeneration
# Watch mode (NEW in v0.3!)
polyglot-ffi watch # Watch files from config
polyglot-ffi watch src/*.mli # Watch specific files
polyglot-ffi watch --build # Auto-build after changes
# Validate project (NEW in v0.3!)
polyglot-ffi check # Check configuration
polyglot-ffi check --check-deps # Include dependency check
polyglot-ffi check --lang rust # Check specific language
# Clean generated files (NEW in v0.3!)
polyglot-ffi clean # Remove generated files
polyglot-ffi clean --dry-run # Preview what would be deleted
polyglot-ffi clean --all # Remove all including directories
# Get help
polyglot-ffi --help
```
All generation happens at build time. **Zero runtime overhead.**
---
## Contributing
We welcome contributions! See [CONTRIBUTING.md](docs/contributing.md) for:
- Development setup
- Code style guidelines
- Testing requirements
- PR process
**Good first issues:** Look for `good-first-issue` label
---
## Community
- **GitHub**: [chizy7/polyglot-ffi](https://github.com/chizy7/polyglot-ffi)
- **Issues**: [Report bugs](https://github.com/chizy7/polyglot-ffi/issues)
- **Discussions**: Coming soon
---
## License
MIT License - See [LICENSE](LICENSE) for details
---
## Acknowledgments
Built with inspiration from:
- [PyO3](https://github.com/PyO3/pyo3) - Rust ↔ Python bindings
- [Ctypes](https://github.com/ocamllabs/ocaml-ctypes) - OCaml FFI library
- [SWIG](http://www.swig.org/) - Multi-language wrapper generator
---
## Contact Me
For questions, feedback, or collaboration opportunities:
- **Email**: [chizy@chizyhub.com](mailto:chizy@chizyhub.com)
- **X(Twitter)**: [](https://x.com/Chizyization)
---
Stop writing FFI boilerplate. Start building amazing things.
```bash
pip install polyglot-ffi
```
Raw data
{
"_id": null,
"home_page": null,
"name": "polyglot-ffi",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "ffi, bindings, ocaml, python, rust, ctypes, polyglot",
"author": null,
"author_email": "Chizaram Chibueze <chizy@chizyhub.com>",
"download_url": "https://files.pythonhosted.org/packages/db/5c/5ef072a35abb4c5e01c0f734f44d469030ec084cfb8f003686198575baa6/polyglot_ffi-0.4.0.tar.gz",
"platform": null,
"description": "# Polyglot FFI\n\n**Automatic FFI bindings generator for polyglot projects**\n\n[](https://pypi.org/project/polyglot-ffi/)\n[](https://www.python.org)\n[](https://github.com/chizy7/polyglot-ffi/actions/workflows/ci.yml)\n[](https://codecov.io/gh/chizy7/polyglot-ffi)\n\nStop writing FFI boilerplate. Start building amazing things.\n\n---\n\n## What is Polyglot FFI?\n\nPolyglot FFI automatically generates complete Foreign Function Interface (FFI) bindings between programming languages. Write your OCaml interface once, and get type-safe, memory-safe bindings for Python (and soon Rust, Go, etc.) instantly.\n\n### The Problem\n\nBuilding multi-language projects requires writing:\n- 50+ lines of OCaml ctypes boilerplate\n- 30+ lines of C stubs with tricky memory management\n- 20+ lines of Python ctypes configuration\n- Plus: Dune configs, debugging, memory leaks...\n\n### The Solution\n\n```bash\npolyglot-ffi generate crypto.mli\n```\n\n**Done!** All 100+ lines generated automatically.\n\n---\n\n## Quick Example\n\n### Primitive Types\n\n**1. Write OCaml interface:**\n\n```ocaml\n(* crypto.mli *)\nval encrypt : string -> string\n(** Encrypt a string *)\n\nval hash : string -> int\n(** Hash to integer *)\n```\n\n**2. Generate bindings:**\n\n```bash\npolyglot-ffi generate crypto.mli -o generated/ -n crypto\n```\n\n**3. Use from Python:**\n\n```python\nfrom generated.crypto_py import encrypt, hash\n\nencrypted = encrypt(\"secret\")\nhash_val = hash(\"data\")\n```\n\n### Complex Types\n\n**1. Write OCaml interface with complex types:**\n\n```ocaml\n(* user.mli *)\ntype user = {\n name: string;\n age: int;\n email: string option;\n}\n\ntype result = Ok of user | Error of string\n\nval find_user : string -> user option\nval create_user : string -> int -> string -> result\nval get_all_users : unit -> user list\nval get_name_and_age : user -> string * int\n```\n\n**2. Generate bindings:**\n\n```bash\npolyglot-ffi generate user.mli\n```\n\n**3. Use from Python with full type hints:**\n\n```python\nfrom typing import Optional, List, Tuple\nfrom generated.user_py import find_user, create_user, get_all_users\n\n# Option type \u2192 Optional[User]\nuser = find_user(\"john\") # Returns Optional[User]\n\n# Variant type \u2192 Result\nresult = create_user(\"Jane\", 25, \"jane@example.com\")\n\n# List type \u2192 List[User]\nall_users = get_all_users() # Returns List[User]\n\n# Tuple type \u2192 Tuple[str, int]\nname, age = get_name_and_age(user) # Returns Tuple[str, int]\n```\n\n---\n\n## Installation\n\n### From PyPI\n\n```bash\npip install polyglot-ffi\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/chizy7/polyglot-ffi\ncd polyglot-ffi\npip install -e \".[dev]\"\n```\n\n### Verify\n\n```bash\npolyglot-ffi --version\n# Output: polyglot_ffi, version 0.4.0\n```\n\n### Upgrading\n\nTo upgrade to the latest version:\n\n```bash\npip install --upgrade polyglot-ffi\n```\n\nTo upgrade to a specific version:\n\n```bash\npip install --upgrade polyglot-ffi==0.5.0\n```\n\nSee the [full installation guide](docs/installation.md) for detailed instructions including:\n- Virtual environment setup\n- Shell completion\n- Troubleshooting\n- Platform-specific notes\n- **[Complete upgrade guide](docs/installation.md#upgrading)** with all options\n\n---\n\n## Features\n\n- **Automatic Code Generation**: One command generates OCaml ctypes, C wrappers, Python modules, and build configs.\n- **Plus Many More Features**: Check docs and roadmap!\n\n### Some Future Features\n\n- [ ] Rust target support\n- [ ] Go target support\n- [ ] Bidirectional bindings\n- [ ] Plugin system\n\n---\n\n## Documentation\n\n- **[Quickstart Guide](docs/quickstart.md)** - Get started in 5 minutes\n- **[Architecture](docs/architecture.md)** - How it works\n- **[Type Mapping](docs/type-mapping.md)** - Type system reference\n- **[Contributing](docs/contributing.md)** - Join development\n\n---\n\n## Why Polyglot FFI?\n\n### Zero Boilerplate\n\nOne command generates everything:\n- OCaml ctypes declarations\n- C wrapper functions\n- Python wrapper module\n- Build configuration\n- Type conversions\n- Error handling\n\n### Type Safe\n\nPreserves type information:\n- Python type hints\n- OCaml type constraints\n- C type declarations\n- Compile-time checking\n\n### Memory Safe\n\nProper memory management:\n- CAMLparam/CAMLreturn macros\n- No memory leaks\n- String ownership handled\n- GC-safe conversions\n\n---\n\n## Use Cases\n\n- **Cryptography**: OCaml for correctness, Python for integration\n- **Data Processing**: OCaml for logic, Python for data science\n- **Financial Systems**: OCaml for algorithms, Python for reporting\n- **ML Infrastructure**: OCaml for pipelines, Python for training\n\n---\n\n## Quick Start\n\n### Initialize a New Project\n\n```bash\npolyglot-ffi init my-crypto-lib\ncd my-crypto-lib\n```\n\n### Edit Your Interface\n\n```ocaml\n(* src/my-crypto-lib.mli *)\nval greet : string -> string\nval add : int -> int -> int\n```\n\n### Generate Bindings\n\n```bash\npolyglot-ffi generate src/my-crypto-lib.mli\n```\n\n### Implement OCaml Functions\n\n```ocaml\n(* src/my-crypto-lib.ml *)\nlet greet name = \"Hello, \" ^ name ^ \"!\"\nlet add x y = x + y\n\nlet () =\n Callback.register \"greet\" greet;\n Callback.register \"add\" add\n```\n\n### Use from Python\n\n```python\nfrom generated.my_crypto_lib_py import greet, add\n\nprint(greet(\"World\")) # Hello, World!\nprint(add(2, 3)) # 5\n```\n\n---\n\n## CLI Reference\n\n```bash\n# Initialize project\npolyglot-ffi init my-project\npolyglot-ffi init --interactive # Interactive setup\n\n# Generate bindings\npolyglot-ffi generate src/module.mli\npolyglot-ffi generate -o bindings/ -n mymodule\npolyglot-ffi generate --dry-run # Preview only\npolyglot-ffi generate --force # Force regeneration\n\n# Watch mode (NEW in v0.3!)\npolyglot-ffi watch # Watch files from config\npolyglot-ffi watch src/*.mli # Watch specific files\npolyglot-ffi watch --build # Auto-build after changes\n\n# Validate project (NEW in v0.3!)\npolyglot-ffi check # Check configuration\npolyglot-ffi check --check-deps # Include dependency check\npolyglot-ffi check --lang rust # Check specific language\n\n# Clean generated files (NEW in v0.3!)\npolyglot-ffi clean # Remove generated files\npolyglot-ffi clean --dry-run # Preview what would be deleted\npolyglot-ffi clean --all # Remove all including directories\n\n# Get help\npolyglot-ffi --help\n```\n\nAll generation happens at build time. **Zero runtime overhead.**\n\n---\n\n## Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](docs/contributing.md) for:\n- Development setup\n- Code style guidelines\n- Testing requirements\n- PR process\n\n**Good first issues:** Look for `good-first-issue` label\n\n---\n\n## Community\n\n- **GitHub**: [chizy7/polyglot-ffi](https://github.com/chizy7/polyglot-ffi)\n- **Issues**: [Report bugs](https://github.com/chizy7/polyglot-ffi/issues)\n- **Discussions**: Coming soon\n\n---\n\n## License\n\nMIT License - See [LICENSE](LICENSE) for details\n\n---\n\n## Acknowledgments\n\nBuilt with inspiration from:\n- [PyO3](https://github.com/PyO3/pyo3) - Rust \u2194 Python bindings\n- [Ctypes](https://github.com/ocamllabs/ocaml-ctypes) - OCaml FFI library\n- [SWIG](http://www.swig.org/) - Multi-language wrapper generator\n\n---\n## Contact Me\n\nFor questions, feedback, or collaboration opportunities:\n\n- **Email**: [chizy@chizyhub.com](mailto:chizy@chizyhub.com)\n- **X(Twitter)**: [](https://x.com/Chizyization)\n\n---\n\nStop writing FFI boilerplate. Start building amazing things.\n\n```bash\npip install polyglot-ffi\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Automatic FFI bindings generator for polyglot projects",
"version": "0.4.0",
"project_urls": {
"Changelog": "https://github.com/chizy7/polyglot-ffi/blob/master/CHANGELOG.md",
"Documentation": "https://chizy7.github.io/polyglot-ffi/",
"Homepage": "https://github.com/chizy7/polyglot-ffi",
"Issues": "https://github.com/chizy7/polyglot-ffi/issues",
"Repository": "https://github.com/chizy7/polyglot-ffi"
},
"split_keywords": [
"ffi",
" bindings",
" ocaml",
" python",
" rust",
" ctypes",
" polyglot"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c29f1434dd63b0793245faaa8b570f5d0aa41557c0ae2c8a878865ca4e7b816e",
"md5": "8c2296841a7b90d23f327fd107abc0fc",
"sha256": "72cd55a9b3ab7225a9e7feacc09f3f394df2059b21e362f7806c37f4b987dafc"
},
"downloads": -1,
"filename": "polyglot_ffi-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8c2296841a7b90d23f327fd107abc0fc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 40619,
"upload_time": "2025-10-26T03:20:46",
"upload_time_iso_8601": "2025-10-26T03:20:46.946868Z",
"url": "https://files.pythonhosted.org/packages/c2/9f/1434dd63b0793245faaa8b570f5d0aa41557c0ae2c8a878865ca4e7b816e/polyglot_ffi-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "db5c5ef072a35abb4c5e01c0f734f44d469030ec084cfb8f003686198575baa6",
"md5": "a65e88e8699173aad694cacf9bb53778",
"sha256": "d2384e4aa062e0d270387df6c56c892339b865514c971c20ff6d33ae9eda5091"
},
"downloads": -1,
"filename": "polyglot_ffi-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "a65e88e8699173aad694cacf9bb53778",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 35129,
"upload_time": "2025-10-26T03:20:48",
"upload_time_iso_8601": "2025-10-26T03:20:48.408523Z",
"url": "https://files.pythonhosted.org/packages/db/5c/5ef072a35abb4c5e01c0f734f44d469030ec084cfb8f003686198575baa6/polyglot_ffi-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-26 03:20:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "chizy7",
"github_project": "polyglot-ffi",
"github_not_found": true,
"lcname": "polyglot-ffi"
}
JSON
