binpacking

2.0.1 · active · verified Thu Apr 16

The `binpacking` library provides heuristic algorithms for distributing weighted items into bins. It supports scenarios with either a fixed number of bins or a fixed volume per bin, accepting data as lists, dictionaries, tuples, or CSV files. The current version is 2.0.1, and it has an active release cadence, with major updates and bug fixes released periodically.

Common errors

```
ERROR: Package 'binpacking' requires Python '>=3.10' but the running Python is X.Y.Z
```
cause Attempting to install or run binpacking v2.0.0+ on an unsupported Python version (older than 3.10).

fix Upgrade your Python environment to 3.10 or later. Alternatively, if unable to upgrade, install an older compatible version: `pip install binpacking==1.5.2`.
```
ModuleNotFoundError: No module named 'numpy'
```
cause Attempting to use advanced features that rely on NumPy acceleration without having installed the optional `[numpy]` extra.

fix Install `binpacking` with NumPy support: `pip install binpacking[numpy]`.
```
TypeError: 'type' object is not subscriptable
```
cause This error likely occurred in version 2.0.0 due to a compatibility issue with PEP 695 generic syntax on some Python 3.10/3.11 environments.

fix Upgrade `binpacking` to version 2.0.1 or newer: `pip install --upgrade binpacking`. This version fixed the generic syntax implementation.

Warnings

breaking Version 2.0.0 and above require Python 3.10 or newer. Older Python 3 versions (e.g., 3.8, 3.9) and Python 2.x are no longer supported.
Fix: Upgrade your Python environment to 3.10 or later. If unable to upgrade, you must use `binpacking` version < 2.0.0 (e.g., `pip install binpacking==1.5.2`).
breaking The packaging system transitioned from `setup.py`/`setup.cfg` to `pyproject.toml` in version 2.0.0. This primarily affects maintainers or developers building from source, but it's part of the modernization effort.
Fix: Ensure your build environment supports PEP 517/518 and `pyproject.toml` for packaging operations.
gotcha Version 2.0.0 had a bug related to PEP 695 generic syntax compatibility with certain Python 3.10/3.11 environments, which could lead to runtime errors.
Fix: Always upgrade to version 2.0.1 or later (`pip install --upgrade binpacking`) to resolve this compatibility issue. Version 2.0.1 replaced PEP 695 syntax with TypeVar-based generics for broader compatibility.
gotcha To leverage NumPy for accelerated performance, you must explicitly install `binpacking` with the `[numpy]` extra. Standard installation does not include NumPy, and any attempts to use NumPy-specific features will fail.
Fix: Install with `pip install binpacking[numpy]`.
deprecated The `pytest-runner` dependency was removed in v1.5.2 due to security concerns.
Fix: Ensure `pytest-runner` is not a direct or indirect dependency in your project to avoid potential security risks. Upgrade to `binpacking` v1.5.2 or newer.

Install

pip install binpacking Standard Installation
pip install binpacking[numpy] With NumPy Acceleration

Imports

to_constant_volume
```
import binpacking
bins = binpacking.to_constant_volume(items, volume)
```
This is one of the primary functions for bin packing with a fixed maximum volume per bin.
to_multiple_bins
```
import binpacking
bins = binpacking.to_multiple_bins(items, num_bins)
```
This is one of the primary functions for bin packing into a fixed number of bins.

Quickstart

This quickstart demonstrates the two primary bin packing functions: `to_constant_volume` for packing into bins with a maximum capacity, and `to_multiple_bins` for packing into a predefined number of bins. Items are provided as a dictionary where keys are item identifiers and values are their weights or sizes.

import binpacking

# Example 1: Pack items into bins with a constant volume limit
items_by_weight = {'itemA': 10, 'itemB': 20, 'itemC': 30, 'itemD': 40, 'itemE': 15}
max_bin_volume = 50
bins_constant_volume = binpacking.to_constant_volume(items_by_weight, max_bin_volume)
print(f"Bins (constant volume {max_bin_volume}): {bins_constant_volume}")

# Example 2: Pack items into a fixed number of bins
num_target_bins = 2
bins_multiple_bins = binpacking.to_multiple_bins(items_by_weight, num_target_bins)
print(f"Bins (fixed number {num_target_bins}): {bins_multiple_bins}")

# For NumPy accelerated functions, ensure it's installed via: pip install binpacking[numpy]
# from binpacking.matrices import to_constant_volume_numpy # (advanced usage)

view raw JSON →