Amalgam Language Python Bindings

29.0.1 verified Fri May 01 auth: no python

Python bindings for the Amalgam language runtime, providing a direct interface with the compiled Amalgam shared library (.dll, .dylib, .so). Version 29.0.1 supports Python >=3.10. The library is actively maintained with frequent releases.

pip install amalgam-lang==29.0.1

Common errors

error ImportError: cannot import name 'Amalgam' from 'amalgam' ↓

cause The package may not be installed correctly, or the wrong import path is used. The class Amalgam exists in the top-level __init__.py.

fix

Ensure the package is installed: pip install amalgam-lang==29.0.1. Then use: from amalgam import Amalgam

error RuntimeError: Unable to load Amalgam shared library ↓

cause The native Amalgam shared library is missing or not in the library search path.

fix

Set the environment variable AMALGAM_LIB_PATH to the directory containing the shared library, or install the library in a system path. For example: export AMALGAM_LIB_PATH=/usr/local/lib

error AttributeError: module 'amalgam' has no attribute 'DirectInterface' ↓

cause Importing from the wrong module; DirectInterface is in amalgam.direct, not amalgam directly.

fix

Use: from amalgam.direct import DirectInterface

error TypeError: Amalgam() takes no arguments ↓

cause Trying to pass arguments to Amalgam() constructor in version >=26.

fix

Amalgam() now takes no arguments. Set the library path via environment variable instead.

Warnings

breaking Version 26+ changed the initialization signature. Amalgam() no longer accepts arguments like 'lib_path' directly; the shared library path must be set via environment variable 'AMALGAM_LIB_PATH' or the platform-specific default search. ↓

fix Set the environment variable 'AMALGAM_LIB_PATH' before creating Amalgam instance, or ensure the library is in a default search path.

deprecated The method 'execute_query' is deprecated in favor of 'execute'. 'execute_query' may be removed in future versions. ↓

fix Use model.execute(...) instead of model.execute_query(...).

gotcha Amalgam library requires a valid Amalgam shared library (.dll/.dylib/.so). The Python package does not include the native runtime by default. Missing library leads to a vague ImportError or RuntimeError. ↓

fix Download the appropriate Amalgam shared library from the official Amalgam releases and place it in a directory included in the system's library search path, or set AMALGAM_LIB_PATH.

gotcha Thread safety is not guaranteed. Running multiple Amalgam instances from different threads may cause crashes. ↓

fix Use thread-local instances or serialize access to a single Amalgam object.

deprecated Python 3.9 support was dropped in version 28.0.0. ↓

fix Use Python 3.10 or later.

Imports

Amalgam
wrong
```
import amalgam Amalgam
```
correct
```
from amalgam import Amalgam
```
Module name is 'amalgam', not 'amalgam-lang'. The main class is Amalgam.
DirectInterface
wrong
```
from amalgam import DirectInterface
```
correct
```
from amalgam.direct import DirectInterface
```
DirectInterface is in a submodule 'direct'. Common mistake to import from top-level.

Quickstart

Initialize the Amalgam runtime, load a model, and execute a command.

from amalgam import Amalgam

# Initialize the library, providing path to amalgam shared library if needed
# If the library is in standard locations, leave blank.
amalgam = Amalgam()

# Load an Amalgam model
model = amalgam.load_model('path/to/model.amalgam')

# Run a simple query
result = model.execute("index")  # or any Amalgam command
print(result)