polarobi
Build gurobipy models from polars frames. Columns go from Arrow memory into the Gurobi C API in one call per variable or constraint family, while the model stays fully usable through gurobipy.
import gurobipy as gp
import polars as pl
from polarobi import GurobiFrame as grb
orders = pl.DataFrame(
{
"order": ["o1", "o1", "o2", "o2", "o3"],
"factory": ["f1", "f2", "f1", "f2", "f2"],
"quantity": [40, 40, 25, 25, 60],
"value": [120.0, 100.0, 100.0, 75.0, 120.0],
}
)
capacity = pl.DataFrame({"factory": ["f1", "f2"], "capacity": [50, 80]})
model = gp.Model()
model.ModelSense = gp.GRB.MAXIMIZE
# One binary variable per order and factory, worth the order's value.
x = grb(orders).add_vars(model, by=["order", "factory"], vtype="B", obj="value", name="x")
# Each order is made at most once, and no factory exceeds its capacity.
grb(x).add_constrs(model, by="order", sense="<=", rhs=1.0, name="assign")
grb(x).add_constrs(
model, capacity, by="factory", sense="<=", rhs="capacity", coef="quantity", name="cap"
)
model.optimize()
print(grb(x).get(model, "X").filter(pl.col("X") > 0.5))
grb(df) is the typed form of polars' df.grb namespace: both do the same, but type checkers only see the first.
See Type Checking for why.
How it works
Model._cmodelholds theGRBmodel*. The native module binds to the Gurobi library that gurobipy already loaded (never a second copy) and checks that both report the same version.- Numeric columns are passed without copying (one concatenation if a column has several chunks). Names are copied, since C needs NUL-terminated strings.
- New columns and rows are registered with gurobipy as
gp.Var(cmodel, i)/gp.Constr(cmodel, i)handles inModel._internal_vars/Model._constrs. That is what keepsgetVars,getVarByName, mixed expressions,remove,copyand friends working. The handles are created in Rust, at about half the cost of a Python loop over gurobipy's handle constructor. - Constraint and term order follow the input frames, so equal inputs build models with equal
Fingerprints.
This relies on private gurobipy attributes (_cmodel, _internal_vars, _livevars, _constrs,
_liveconstrs, _has_pending_deletions). Pin gurobipy to a minor version and keep
tests/test_compat.py in CI.
Contributing
polarobi is a mixed Rust and Python project. The Rust extension in src/ is compiled by
maturin into the module polarobi._native and packaged together with the Python sources in
python/polarobi/. uv drives the whole thing: maturin is the project's build backend,
so the usual uv commands compile the extension when needed.
Prerequisites
- Rust, stable, installed with rustup, with the
rustfmtandclippycomponents for the pre-commit hooks:rustup component add rustfmt clippy
On Windows, rustup's default toolchain needs the MSVC build tools (Visual Studio Build Tools, "Desktop development with C++"). On macOS, the Xcode command line tools. - uv, which also provides Python. polarobi supports Python 3.12 and up; CI runs 3.14.
- A Gurobi license that gurobipy finds. The size-limited license that ships with
gurobipyis enough for the tests.
You do not need a Gurobi installation or SDK to compile: the extension does not link against Gurobi. At import it binds to the Gurobi library that gurobipy has already loaded into the process.
Setting up
uv sync
uv run prek install
uv sync creates .venv, installs the dev dependencies and builds polarobi with maturin as an editable install: a
.pth file points at python/, and the compiled extension is placed next to the Python sources as
python/polarobi/_native.*.pyd (or .so). prek install sets up the pre-commit hooks below.
The build loop
- Python changes take effect immediately, the package is installed in editable mode.
- Rust changes are picked up by the next
uv syncoruv run:[tool.uv] cache-keysinpyproject.tomllistsCargo.tomlandsrc/**/*.rs, so uv rebuilds the extension when they change. This builds in release mode, which takes a while to compile. - For faster iterations on Rust code, build a debug extension in place and keep uv from rebuilding over it:
uv run --no-sync maturin develop --uv uv run --no-sync pytest
Debug builds compile quickly but run slowly, so usematurin develop --uv --release, or a plainuv sync, before benchmarking. cargo checkandcargo clippywork onsrc/directly and are the quickest way to see compile errors.
Configuration worth knowing:
| Where | What |
|---|---|
pyproject.toml, [build-system] |
maturin as the build backend |
pyproject.toml, [tool.maturin] |
python-source = "python", module-name = "polarobi._native" |
Cargo.toml, [lib] |
name = "_native", crate-type = ["cdylib"]; must match module-name |
Cargo.toml, version |
the package version, which maturin passes to Python (dynamic = ["version"]) |
Cargo.toml, pyo3 features |
abi3-py312: one wheel per platform for all supported Pythons |
Cargo.toml, arrow-* |
must stay on the arrow version pyo3-arrow is built on, or their types do not match |
Building wheels
uv build
builds an sdist and a wheel for the current platform into dist/. For a manylinux wheel from another platform, maturin
can cross-compile with zig:
uvx maturin build --release --zig --target x86_64-unknown-linux-gnu
Wheels use Python's stable ABI (pyo3's abi3-py312 feature), so one wheel per platform, tagged cp312-abi3, works on
every Python from 3.12 on.
Releasing
.github/workflows/release.yml builds an sdist and one wheel each for Linux x86_64 and aarch64 (manylinux), Windows
x64 and macOS (universal2, Intel and Apple silicon), the platforms gurobipy ships for. Every wheel is installed and
tested on Python 3.12 and 3.14 before anything is published. To release:
- Bump
versioninCargo.toml, which is the package version, and runuv lock. - Commit, then tag and push the tag:
git tag v0.1.2 git push origin v0.1.2
- The workflow publishes to PyPI once all wheels pass, if the tag matches the version in
Cargo.toml.
Publishing uses PyPI's trusted publishing, configured once on PyPI for the workflow release.yml and the GitHub
environment pypi; no API token is stored. Starting the workflow manually from the Actions tab builds and tests all
wheels without publishing, which is a safe way to try a release first.
Checks
The pre-commit hooks in prek.toml run on every commit. Run them on everything with:
uv run prek run --all-files
| Hook | Checks |
|---|---|
uv-lock |
uv.lock matches pyproject.toml |
ruff-format, ruff-check |
Python formatting and lints, fixed in place |
basedpyright |
strict type checking of the package and the tests |
cargo fmt |
Rust formatting, fixed in place |
cargo clippy |
Rust lints, with warnings as errors |
A hook that fixes files in place fails the commit; add the fixed files and commit again.
Tests
uv run pytest
Besides unit tests, tests/test_equivalence.py runs a Hypothesis state machine
that checks every model polarobi builds against the same model built with plain gurobipy, down to the MPS file and
Fingerprint. The default profile is quick; set HYPOTHESIS_PROFILE=ci for ten times the examples, or thorough for a
long search after changes to the native code or the namespace semantics:
HYPOTHESIS_PROFILE=thorough uv run pytest tests/test_equivalence.py
tests/harness/__init__.py explains how to extend the harness for a new feature, and
Equivalence with gurobipy what it guarantees.
Documentation
The documentation is built with Zensical from docs/, with the API reference generated from
the docstrings:
uv run zensical serve
uv run zensical build --clean --strict
serve rebuilds on changes and serves the site on http://localhost:8000.
Keep in Mind
- gurobipy's private attributes. polarobi registers its handles through
Model._cmodel,_internal_vars,_livevars,_constrs,_liveconstrsand_has_pending_deletions(), so gurobipy is pinned to one minor version. Raising the pin needs athoroughrun of the equivalence harness. - No numpy at runtime. numpy is a dev dependency only, because polars' type annotations refer to it.
tests/test_no_numpy.pyfails if polarobi ever imports it. - The Gurobi library is never loaded twice. The native module only ever binds to the copy gurobipy loaded.
Layout
polarobi/
├── src/ # Rust extension, built as polarobi._native
│ ├── lib.rs # Module definition
│ ├── gurobi.rs # Binding to gurobipy's Gurobi library, error handling
│ ├── columns.rs # Zero-copy views of Arrow columns as C arrays
│ ├── model.rs # Bulk adds, attribute reads and writes
│ └── handles.rs # gurobipy handle creation
├── python/polarobi/ # Python package
│ ├── _namespace.py # The df.grb namespace (GurobiFrame), the public API
│ ├── _api.py # Its implementation: inputs, names, constraint layout
│ ├── _handles.py # Registering handles with gurobipy
│ ├── _library.py # Finding and binding the Gurobi library
│ └── _native.pyi # Type stub of the extension
├── tests/
│ ├── harness/ # Equivalence harness: reference implementation, comparison
│ ├── test_equivalence.py # State machine against plain gurobipy
│ └── test_*.py # Compatibility, parity and edge cases
└── docs/ # Documentation (Zensical)
Metadata
Release files for polarobi 0.1.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| polarobi-0.1.3.tar.gz | 402.8 kB | With provenance | Details for polarobi-0.1.3.tar.gz |
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| polarobi-0.1.3-cp312-abi3-win_amd64.whl | CPython 3.12 | abi3 | Windows x86-64 | Details for polarobi-0.1.3-cp312-abi3-win_amd64.whl |
| polarobi-0.1.3-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl | CPython 3.12 | abi3 | Linux glibc 2.17+ x86-64 | Details for polarobi-0.1.3-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
| polarobi-0.1.3-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl | CPython 3.12 | abi3 | Linux glibc 2.17+ ARM64 | Details for polarobi-0.1.3-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
| polarobi-0.1.3-cp312-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl | CPython 3.12 | abi3 | macOS 10.12+ universal2 (ARM64, x86-64), macOS 10.12+ x86-64, macOS 11.0+ ARM64 | Details for polarobi-0.1.3-cp312-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl |
Total release size: 14.1 MB
Release files / polarobi-0.1.3.tar.gz
| Download URL | polarobi-0.1.3.tar.gz |
|---|---|
| Size | 402.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
985301621edc4bfa0ec85276ef7f9ccd9b67ae75e83f8c00f43138b77277928e
|
|
BLAKE2b-256 checksum How to use checksums |
50dead49426b8935c4fd4dc9f130d8b23ea699cb0574f566d3b3f723d480c5ff
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.
Transparency logRelease files / polarobi-0.1.3-cp312-abi3-win_amd64.whl
| Download URL | polarobi-0.1.3-cp312-abi3-win_amd64.whl |
|---|---|
| Size | 2.6 MB |
| Tags | CPython 3.12 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
847b24ceb4a4bc4ef73a3520a4db82152a99e7fc8925fa469be3317d04e7b127
|
|
BLAKE2b-256 checksum How to use checksums |
c677e4efcec453fb989d5c2b1f78a1e20484d0ed1f89074ae9cb5f31e6f8118c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.
Transparency logRelease files / polarobi-0.1.3-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | polarobi-0.1.3-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 3.0 MB |
| Tags | CPython 3.12 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
5a129c4d8523f08527e9d25352f05f8fee32b4b0b9779b8261039741ab279d31
|
|
BLAKE2b-256 checksum How to use checksums |
6e21212507d499f6363fc4c75bbb310b3a0b0bcc8c3ee8417161ce4d50767aa4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.
Transparency logRelease files / polarobi-0.1.3-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | polarobi-0.1.3-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 2.9 MB |
| Tags | CPython 3.12 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
562bb80149048a0da16eefb9a30350445e562f34a9b9679a549b917117956496
|
|
BLAKE2b-256 checksum How to use checksums |
ee095df482383d6cb8a23fd18bd2efbf59e1d856967b4ca300b1427e95dd6516
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.
Transparency logRelease files / polarobi-0.1.3-cp312-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
| Download URL | polarobi-0.1.3-cp312-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl |
|---|---|
| Size | 5.2 MB |
| Tags | CPython 3.12 abi3 macOS 10.12+ universal2 (ARM64, x86-64) macOS 10.12+ x86-64 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
c18cb1bdba71bc1e25ba91d489b65aab93e4ce40b839590afcb7047dbc5e81c4
|
|
BLAKE2b-256 checksum How to use checksums |
51ce3d7c7072697da609fe3408faa132fcd20e3e78084f80829912ca33086517
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.
Transparency logSecurity for polarobi 0.1.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 5 files in this release have been uploaded with provenance metadata.
Attestation for polarobi-0.1.3.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.