packvium-native 1.11.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- packvium_native-1.11.0/LICENSE +21 -0
- packvium_native-1.11.0/PKG-INFO +138 -0
- packvium_native-1.11.0/README.md +117 -0
- packvium_native-1.11.0/pyproject.toml +37 -0
- packvium_native-1.11.0/setup.cfg +4 -0
- packvium_native-1.11.0/src/packvium_native/__init__.py +104 -0
- packvium_native-1.11.0/src/packvium_native.egg-info/PKG-INFO +138 -0
- packvium_native-1.11.0/src/packvium_native.egg-info/SOURCES.txt +10 -0
- packvium_native-1.11.0/src/packvium_native.egg-info/dependency_links.txt +1 -0
- packvium_native-1.11.0/src/packvium_native.egg-info/requires.txt +9 -0
- packvium_native-1.11.0/src/packvium_native.egg-info/top_level.txt +1 -0
- packvium_native-1.11.0/tests/test_adapter.py +160 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Packvium contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: packvium-native
|
|
3
|
+
Version: 1.11.0
|
|
4
|
+
Summary: Packvium backend selector: the native engine when a wheel is available, pure Python otherwise.
|
|
5
|
+
Author: Packvium contributors
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://packvium.com
|
|
8
|
+
Project-URL: Documentation, https://packvium.com/docs
|
|
9
|
+
Project-URL: Source, https://github.com/packvium/packvium-python-adapter
|
|
10
|
+
Project-URL: Issues, https://github.com/packvium/packvium-python-adapter/issues
|
|
11
|
+
Keywords: 3d-bin-packing,bin-packing,3d-packing,cartonization,container-loading,pallet-packing,truck-loading,packing-algorithm,logistics,deterministic,box-packing,load-planning
|
|
12
|
+
Requires-Python: >=3.9
|
|
13
|
+
Description-Content-Type: text/markdown
|
|
14
|
+
License-File: LICENSE
|
|
15
|
+
Provides-Extra: test
|
|
16
|
+
Requires-Dist: pytest; extra == "test"
|
|
17
|
+
Requires-Dist: packvium; python_version >= "3.10" and extra == "test"
|
|
18
|
+
Provides-Extra: native
|
|
19
|
+
Requires-Dist: packvium-native-rust==1.11.0; extra == "native"
|
|
20
|
+
Dynamic: license-file
|
|
21
|
+
|
|
22
|
+
# packvium-native
|
|
23
|
+
|
|
24
|
+
Optional native backend selector for [Packvium](https://pypi.org/project/packvium/).
|
|
25
|
+
It uses the compiled Rust wheel when available and otherwise delegates to the pure
|
|
26
|
+
Python package.
|
|
27
|
+
|
|
28
|
+
Full documentation, the constraint reference and benchmarks live at
|
|
29
|
+
[packvium.com](https://packvium.com).
|
|
30
|
+
|
|
31
|
+
## Install
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
pip install 'packvium-native[native]' packvium
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
The `native` extra installs the platform wheel. To use only the fallback, install
|
|
38
|
+
`packvium-native` together with `packvium`.
|
|
39
|
+
|
|
40
|
+
`packvium-native` is not on PyPI yet. Until the native wheels ship, install it from source:
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
pip install git+https://github.com/packvium/packvium-python-adapter packvium
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## Quick start
|
|
47
|
+
|
|
48
|
+
```python
|
|
49
|
+
from packvium_native import backend, pack
|
|
50
|
+
|
|
51
|
+
result = pack({
|
|
52
|
+
"items": [{
|
|
53
|
+
"id": "book", "quantity": 4,
|
|
54
|
+
"dimensions": {"length": "210", "width": "140", "height": "30"},
|
|
55
|
+
}],
|
|
56
|
+
"containers": [{
|
|
57
|
+
"id": "carton",
|
|
58
|
+
"inner_dimensions": {"length": "400", "width": "300", "height": "250"},
|
|
59
|
+
}],
|
|
60
|
+
})
|
|
61
|
+
|
|
62
|
+
print(backend()) # "rust" or "python"
|
|
63
|
+
print(result["status"]) # "feasible"
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
The adapter does not replace the `packvium` import. It is useful when an application
|
|
67
|
+
wants one stable call site with a native fast path and a pure-Python fallback.
|
|
68
|
+
|
|
69
|
+
`pack_json` takes and returns the same JSON string every other Packvium binding speaks —
|
|
70
|
+
useful when the request is already serialized, or being forwarded as-is:
|
|
71
|
+
|
|
72
|
+
```python
|
|
73
|
+
from packvium_native import pack_json
|
|
74
|
+
|
|
75
|
+
response = pack_json('{"items":[...],"containers":[...]}')
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
## Examples
|
|
79
|
+
|
|
80
|
+
Runnable, in [`examples/`](examples). Each one is a single file you can read top to bottom
|
|
81
|
+
and execute without a project around it.
|
|
82
|
+
|
|
83
|
+
| File | What it shows |
|
|
84
|
+
| --- | --- |
|
|
85
|
+
| [`basic.py`](examples/basic.py) | Pack through the adapter and report which backend answered. |
|
|
86
|
+
| [`shapes.py`](examples/shapes.py) | Items that are not their box: complementary wedges sharing one crate as `convex_hull`, two copies of one wedge that need the signed rotation `-L-W+H`, a cushion that compresses under load until the crush limit refuses it, and a gusseted bag that holds a layer more than a flat one — the same numbers whichever backend answered. |
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
python3 examples/basic.py
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## Platforms
|
|
93
|
+
|
|
94
|
+
Native wheels support Linux x86_64/aarch64, macOS Apple Silicon/Intel and Windows. The
|
|
95
|
+
wheel uses Python's stable ABI, so one wheel supports Python 3.9 and later on its
|
|
96
|
+
platform.
|
|
97
|
+
|
|
98
|
+
## The Packvium family
|
|
99
|
+
|
|
100
|
+
One request and result contract, implemented independently in four engines (Rust,
|
|
101
|
+
Python, PHP, JavaScript) and checked against each other on a shared fixture set. Python and
|
|
102
|
+
PHP are held to byte-identical canonical results; Rust and the JavaScript fallback are held
|
|
103
|
+
to independent validity and a per-fixture objective floor.
|
|
104
|
+
Pick the package for your stack; mixing them in one system is safe.
|
|
105
|
+
|
|
106
|
+
Documentation, the constraint reference and the benchmarks are at
|
|
107
|
+
[packvium.com](https://packvium.com).
|
|
108
|
+
|
|
109
|
+
| Package | Install | Source |
|
|
110
|
+
| --- | --- | --- |
|
|
111
|
+
| Python — [`packvium`](https://pypi.org/project/packvium/) | `pip install packvium` | [packvium-python](https://github.com/packvium/packvium-python) |
|
|
112
|
+
| PHP — [`packvium/packvium`](https://packagist.org/packages/packvium/packvium) | `composer require packvium/packvium` | [packvium-php](https://github.com/packvium/packvium-php) |
|
|
113
|
+
| Rust — [`packvium`](https://crates.io/crates/packvium) | `packvium = "1.11"` | [packvium-rust](https://github.com/packvium/packvium-rust) |
|
|
114
|
+
| Node.js — [`@packvium/engine`](https://www.npmjs.com/package/@packvium/engine) | `npm install @packvium/engine` | [packvium-node](https://github.com/packvium/packvium-node) |
|
|
115
|
+
| Browser / WebAssembly — [`@packvium/browser`](https://www.npmjs.com/package/@packvium/browser) | `npm install @packvium/browser` | [packvium-wasm](https://github.com/packvium/packvium-wasm) |
|
|
116
|
+
| PHP FFI bridge — [`packvium/native-bridge`](https://packagist.org/packages/packvium/native-bridge) | `composer require packvium/native-bridge` | [packvium-php-bridge](https://github.com/packvium/packvium-php-bridge) |
|
|
117
|
+
| Python native selector — `packvium-native` | from source until the native wheels ship | [packvium-python-adapter](https://github.com/packvium/packvium-python-adapter) |
|
|
118
|
+
|
|
119
|
+
## Citation
|
|
120
|
+
|
|
121
|
+
If Packvium supports your research, cite it as software. GitHub's **Cite this repository**
|
|
122
|
+
button reads [`CITATION.cff`](https://github.com/packvium/packvium-python-adapter/blob/main/CITATION.cff), and
|
|
123
|
+
[`codemeta.json`](https://github.com/packvium/packvium-python-adapter/blob/main/codemeta.json) carries the same record in
|
|
124
|
+
CodeMeta form.
|
|
125
|
+
|
|
126
|
+
```bibtex
|
|
127
|
+
@software{packvium_python_adapter,
|
|
128
|
+
author = {{Packvium contributors}},
|
|
129
|
+
title = {Packvium native backend selector for Python},
|
|
130
|
+
version = {1.11.0},
|
|
131
|
+
license = {MIT},
|
|
132
|
+
url = {https://packvium.com}
|
|
133
|
+
}
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
## License
|
|
137
|
+
|
|
138
|
+
MIT. See [LICENSE](LICENSE).
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
# packvium-native
|
|
2
|
+
|
|
3
|
+
Optional native backend selector for [Packvium](https://pypi.org/project/packvium/).
|
|
4
|
+
It uses the compiled Rust wheel when available and otherwise delegates to the pure
|
|
5
|
+
Python package.
|
|
6
|
+
|
|
7
|
+
Full documentation, the constraint reference and benchmarks live at
|
|
8
|
+
[packvium.com](https://packvium.com).
|
|
9
|
+
|
|
10
|
+
## Install
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
pip install 'packvium-native[native]' packvium
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
The `native` extra installs the platform wheel. To use only the fallback, install
|
|
17
|
+
`packvium-native` together with `packvium`.
|
|
18
|
+
|
|
19
|
+
`packvium-native` is not on PyPI yet. Until the native wheels ship, install it from source:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
pip install git+https://github.com/packvium/packvium-python-adapter packvium
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
## Quick start
|
|
26
|
+
|
|
27
|
+
```python
|
|
28
|
+
from packvium_native import backend, pack
|
|
29
|
+
|
|
30
|
+
result = pack({
|
|
31
|
+
"items": [{
|
|
32
|
+
"id": "book", "quantity": 4,
|
|
33
|
+
"dimensions": {"length": "210", "width": "140", "height": "30"},
|
|
34
|
+
}],
|
|
35
|
+
"containers": [{
|
|
36
|
+
"id": "carton",
|
|
37
|
+
"inner_dimensions": {"length": "400", "width": "300", "height": "250"},
|
|
38
|
+
}],
|
|
39
|
+
})
|
|
40
|
+
|
|
41
|
+
print(backend()) # "rust" or "python"
|
|
42
|
+
print(result["status"]) # "feasible"
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
The adapter does not replace the `packvium` import. It is useful when an application
|
|
46
|
+
wants one stable call site with a native fast path and a pure-Python fallback.
|
|
47
|
+
|
|
48
|
+
`pack_json` takes and returns the same JSON string every other Packvium binding speaks —
|
|
49
|
+
useful when the request is already serialized, or being forwarded as-is:
|
|
50
|
+
|
|
51
|
+
```python
|
|
52
|
+
from packvium_native import pack_json
|
|
53
|
+
|
|
54
|
+
response = pack_json('{"items":[...],"containers":[...]}')
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## Examples
|
|
58
|
+
|
|
59
|
+
Runnable, in [`examples/`](examples). Each one is a single file you can read top to bottom
|
|
60
|
+
and execute without a project around it.
|
|
61
|
+
|
|
62
|
+
| File | What it shows |
|
|
63
|
+
| --- | --- |
|
|
64
|
+
| [`basic.py`](examples/basic.py) | Pack through the adapter and report which backend answered. |
|
|
65
|
+
| [`shapes.py`](examples/shapes.py) | Items that are not their box: complementary wedges sharing one crate as `convex_hull`, two copies of one wedge that need the signed rotation `-L-W+H`, a cushion that compresses under load until the crush limit refuses it, and a gusseted bag that holds a layer more than a flat one — the same numbers whichever backend answered. |
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
python3 examples/basic.py
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## Platforms
|
|
72
|
+
|
|
73
|
+
Native wheels support Linux x86_64/aarch64, macOS Apple Silicon/Intel and Windows. The
|
|
74
|
+
wheel uses Python's stable ABI, so one wheel supports Python 3.9 and later on its
|
|
75
|
+
platform.
|
|
76
|
+
|
|
77
|
+
## The Packvium family
|
|
78
|
+
|
|
79
|
+
One request and result contract, implemented independently in four engines (Rust,
|
|
80
|
+
Python, PHP, JavaScript) and checked against each other on a shared fixture set. Python and
|
|
81
|
+
PHP are held to byte-identical canonical results; Rust and the JavaScript fallback are held
|
|
82
|
+
to independent validity and a per-fixture objective floor.
|
|
83
|
+
Pick the package for your stack; mixing them in one system is safe.
|
|
84
|
+
|
|
85
|
+
Documentation, the constraint reference and the benchmarks are at
|
|
86
|
+
[packvium.com](https://packvium.com).
|
|
87
|
+
|
|
88
|
+
| Package | Install | Source |
|
|
89
|
+
| --- | --- | --- |
|
|
90
|
+
| Python — [`packvium`](https://pypi.org/project/packvium/) | `pip install packvium` | [packvium-python](https://github.com/packvium/packvium-python) |
|
|
91
|
+
| PHP — [`packvium/packvium`](https://packagist.org/packages/packvium/packvium) | `composer require packvium/packvium` | [packvium-php](https://github.com/packvium/packvium-php) |
|
|
92
|
+
| Rust — [`packvium`](https://crates.io/crates/packvium) | `packvium = "1.11"` | [packvium-rust](https://github.com/packvium/packvium-rust) |
|
|
93
|
+
| Node.js — [`@packvium/engine`](https://www.npmjs.com/package/@packvium/engine) | `npm install @packvium/engine` | [packvium-node](https://github.com/packvium/packvium-node) |
|
|
94
|
+
| Browser / WebAssembly — [`@packvium/browser`](https://www.npmjs.com/package/@packvium/browser) | `npm install @packvium/browser` | [packvium-wasm](https://github.com/packvium/packvium-wasm) |
|
|
95
|
+
| PHP FFI bridge — [`packvium/native-bridge`](https://packagist.org/packages/packvium/native-bridge) | `composer require packvium/native-bridge` | [packvium-php-bridge](https://github.com/packvium/packvium-php-bridge) |
|
|
96
|
+
| Python native selector — `packvium-native` | from source until the native wheels ship | [packvium-python-adapter](https://github.com/packvium/packvium-python-adapter) |
|
|
97
|
+
|
|
98
|
+
## Citation
|
|
99
|
+
|
|
100
|
+
If Packvium supports your research, cite it as software. GitHub's **Cite this repository**
|
|
101
|
+
button reads [`CITATION.cff`](https://github.com/packvium/packvium-python-adapter/blob/main/CITATION.cff), and
|
|
102
|
+
[`codemeta.json`](https://github.com/packvium/packvium-python-adapter/blob/main/codemeta.json) carries the same record in
|
|
103
|
+
CodeMeta form.
|
|
104
|
+
|
|
105
|
+
```bibtex
|
|
106
|
+
@software{packvium_python_adapter,
|
|
107
|
+
author = {{Packvium contributors}},
|
|
108
|
+
title = {Packvium native backend selector for Python},
|
|
109
|
+
version = {1.11.0},
|
|
110
|
+
license = {MIT},
|
|
111
|
+
url = {https://packvium.com}
|
|
112
|
+
}
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
## License
|
|
116
|
+
|
|
117
|
+
MIT. See [LICENSE](LICENSE).
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "packvium-native"
|
|
7
|
+
version = "1.11.0"
|
|
8
|
+
requires-python = ">=3.9"
|
|
9
|
+
description = "Packvium backend selector: the native engine when a wheel is available, pure Python otherwise."
|
|
10
|
+
readme = "README.md"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
keywords = ["3d-bin-packing", "bin-packing", "3d-packing", "cartonization", "container-loading", "pallet-packing", "truck-loading", "packing-algorithm", "logistics", "deterministic", "box-packing", "load-planning"]
|
|
13
|
+
authors = [{name = "Packvium contributors"}]
|
|
14
|
+
dependencies = []
|
|
15
|
+
|
|
16
|
+
[project.urls]
|
|
17
|
+
Homepage = "https://packvium.com"
|
|
18
|
+
Documentation = "https://packvium.com/docs"
|
|
19
|
+
Source = "https://github.com/packvium/packvium-python-adapter"
|
|
20
|
+
Issues = "https://github.com/packvium/packvium-python-adapter/issues"
|
|
21
|
+
|
|
22
|
+
[project.optional-dependencies]
|
|
23
|
+
# `packvium` is deliberately not a hard dependency of the package itself (see
|
|
24
|
+
# README's "does not replace or shadow" note) -- it is only needed to exercise the
|
|
25
|
+
# fallback path in tests.
|
|
26
|
+
# The pure engine itself supports Python 3.10+, while this selector remains useful on
|
|
27
|
+
# Python 3.9 with the native wheel. Keep the public 3.9 CI lane installable instead of
|
|
28
|
+
# asking pip to satisfy an impossible test-only dependency there.
|
|
29
|
+
test = ["pytest", "packvium; python_version >= '3.10'"]
|
|
30
|
+
# Convenience extra: `pip install packvium-native[native]` pulls in the compiled Rust
|
|
31
|
+
# wheel too, rather than requiring a second, separate install command. Pinned to this
|
|
32
|
+
# release, which `scripts/suite_version.py` keeps in step: a wheel from another release
|
|
33
|
+
# answers with that release's rules while this selector claims its own.
|
|
34
|
+
native = ["packvium-native-rust==1.11.0"]
|
|
35
|
+
|
|
36
|
+
[tool.setuptools.packages.find]
|
|
37
|
+
where = ["src"]
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import json
|
|
4
|
+
from types import ModuleType
|
|
5
|
+
from typing import Any, Optional
|
|
6
|
+
|
|
7
|
+
__version__ = "1.11.0"
|
|
8
|
+
|
|
9
|
+
#: Each untyped model error's code and the prefix the core's `PackError` writes before its
|
|
10
|
+
#: detail (`packvium-core` `error.rs`). `packvium` reports a model it cannot build as reason
|
|
11
|
+
#: `invalid_value` with no field and the bare detail, and so does this adapter.
|
|
12
|
+
_MODEL_ERROR_PREFIXES = {
|
|
13
|
+
"invalid_input": "invalid input: ",
|
|
14
|
+
"invalid_number": "invalid numeric value: ",
|
|
15
|
+
"unsupported_unit": "unsupported unit: ",
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
def _native() -> Optional[ModuleType]:
|
|
20
|
+
try:
|
|
21
|
+
import packvium_native_rust # type: ignore
|
|
22
|
+
except ImportError:
|
|
23
|
+
return None
|
|
24
|
+
return packvium_native_rust
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
def backend() -> str:
|
|
28
|
+
return "rust" if _native() is not None else "python"
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def pack_json(payload: str) -> str:
|
|
32
|
+
native = _native()
|
|
33
|
+
if native is not None:
|
|
34
|
+
return _pack_natively(native, payload)
|
|
35
|
+
return _pack_in_python(payload)
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def _pack_natively(native: ModuleType, payload: str) -> str:
|
|
39
|
+
try:
|
|
40
|
+
return native.pack_json(payload)
|
|
41
|
+
except native.PackviumError as error:
|
|
42
|
+
refusal = _refusal_for(error)
|
|
43
|
+
if refusal is error:
|
|
44
|
+
raise
|
|
45
|
+
if refusal is not None:
|
|
46
|
+
raise refusal from error
|
|
47
|
+
# No refusal this adapter can name -- a panic caught at the boundary, a solution that
|
|
48
|
+
# failed the core's own validation -- is the library's failure, not the caller's, so the
|
|
49
|
+
# pure engine answers the same request (the PHP bridge's `refusalFor` rule).
|
|
50
|
+
return _pack_in_python(payload)
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def _pack_in_python(payload: str) -> str:
|
|
54
|
+
try:
|
|
55
|
+
from packvium.serialization import pack_from_dict
|
|
56
|
+
except ImportError as exc:
|
|
57
|
+
raise RuntimeError(
|
|
58
|
+
f"Install packvium=={__version__} or the packvium-native-rust wheel"
|
|
59
|
+
) from exc
|
|
60
|
+
# The canonical spelling the native engine writes (docs/SERIALIZATION.md): keys sorted,
|
|
61
|
+
# compact separators, UTF-8 left unescaped -- so the text does not depend on the backend.
|
|
62
|
+
return json.dumps(
|
|
63
|
+
pack_from_dict(json.loads(payload)),
|
|
64
|
+
ensure_ascii=False,
|
|
65
|
+
separators=(",", ":"),
|
|
66
|
+
sort_keys=True,
|
|
67
|
+
)
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
def _refusal_for(error: Exception) -> Optional[Exception]:
|
|
71
|
+
"""The `packvium` exception the pure engine raises for the request the core refused;
|
|
72
|
+
`error` itself when it carries a code but `packvium` is not installed to supply a class; or
|
|
73
|
+
None when it names no refusal `packvium` has a class for -- a missing or unmapped code,
|
|
74
|
+
which the caller treats as a native failure and answers from the pure engine."""
|
|
75
|
+
code = getattr(error, "code", None)
|
|
76
|
+
if not isinstance(code, str):
|
|
77
|
+
return None
|
|
78
|
+
try:
|
|
79
|
+
from packvium import FixedPlacementError, InvalidRequestError, UnsupportedFeatureError
|
|
80
|
+
except ImportError:
|
|
81
|
+
return error
|
|
82
|
+
message = str(error)
|
|
83
|
+
if code == "unsupported_feature":
|
|
84
|
+
return UnsupportedFeatureError(message)
|
|
85
|
+
prefix = _MODEL_ERROR_PREFIXES.get(code)
|
|
86
|
+
if prefix is not None:
|
|
87
|
+
detail = message[len(prefix):] if message.startswith(prefix) else message
|
|
88
|
+
return InvalidRequestError("invalid_value", "", detail)
|
|
89
|
+
named = [getattr(error, name, None) for name in ("reason", "field", "detail")]
|
|
90
|
+
if not all(isinstance(part, str) for part in named):
|
|
91
|
+
return None
|
|
92
|
+
reason, field, detail = named
|
|
93
|
+
if code == "invalid_request":
|
|
94
|
+
return InvalidRequestError(reason, field, detail)
|
|
95
|
+
if code == "invalid_fixed_placement":
|
|
96
|
+
return FixedPlacementError(detail, reason, field)
|
|
97
|
+
return None
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def pack(payload: dict[str, Any]) -> dict[str, Any]:
|
|
101
|
+
return json.loads(pack_json(json.dumps(payload, separators=(",", ":"))))
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
__all__ = ["pack", "pack_json", "backend", "__version__"]
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: packvium-native
|
|
3
|
+
Version: 1.11.0
|
|
4
|
+
Summary: Packvium backend selector: the native engine when a wheel is available, pure Python otherwise.
|
|
5
|
+
Author: Packvium contributors
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://packvium.com
|
|
8
|
+
Project-URL: Documentation, https://packvium.com/docs
|
|
9
|
+
Project-URL: Source, https://github.com/packvium/packvium-python-adapter
|
|
10
|
+
Project-URL: Issues, https://github.com/packvium/packvium-python-adapter/issues
|
|
11
|
+
Keywords: 3d-bin-packing,bin-packing,3d-packing,cartonization,container-loading,pallet-packing,truck-loading,packing-algorithm,logistics,deterministic,box-packing,load-planning
|
|
12
|
+
Requires-Python: >=3.9
|
|
13
|
+
Description-Content-Type: text/markdown
|
|
14
|
+
License-File: LICENSE
|
|
15
|
+
Provides-Extra: test
|
|
16
|
+
Requires-Dist: pytest; extra == "test"
|
|
17
|
+
Requires-Dist: packvium; python_version >= "3.10" and extra == "test"
|
|
18
|
+
Provides-Extra: native
|
|
19
|
+
Requires-Dist: packvium-native-rust==1.11.0; extra == "native"
|
|
20
|
+
Dynamic: license-file
|
|
21
|
+
|
|
22
|
+
# packvium-native
|
|
23
|
+
|
|
24
|
+
Optional native backend selector for [Packvium](https://pypi.org/project/packvium/).
|
|
25
|
+
It uses the compiled Rust wheel when available and otherwise delegates to the pure
|
|
26
|
+
Python package.
|
|
27
|
+
|
|
28
|
+
Full documentation, the constraint reference and benchmarks live at
|
|
29
|
+
[packvium.com](https://packvium.com).
|
|
30
|
+
|
|
31
|
+
## Install
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
pip install 'packvium-native[native]' packvium
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
The `native` extra installs the platform wheel. To use only the fallback, install
|
|
38
|
+
`packvium-native` together with `packvium`.
|
|
39
|
+
|
|
40
|
+
`packvium-native` is not on PyPI yet. Until the native wheels ship, install it from source:
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
pip install git+https://github.com/packvium/packvium-python-adapter packvium
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## Quick start
|
|
47
|
+
|
|
48
|
+
```python
|
|
49
|
+
from packvium_native import backend, pack
|
|
50
|
+
|
|
51
|
+
result = pack({
|
|
52
|
+
"items": [{
|
|
53
|
+
"id": "book", "quantity": 4,
|
|
54
|
+
"dimensions": {"length": "210", "width": "140", "height": "30"},
|
|
55
|
+
}],
|
|
56
|
+
"containers": [{
|
|
57
|
+
"id": "carton",
|
|
58
|
+
"inner_dimensions": {"length": "400", "width": "300", "height": "250"},
|
|
59
|
+
}],
|
|
60
|
+
})
|
|
61
|
+
|
|
62
|
+
print(backend()) # "rust" or "python"
|
|
63
|
+
print(result["status"]) # "feasible"
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
The adapter does not replace the `packvium` import. It is useful when an application
|
|
67
|
+
wants one stable call site with a native fast path and a pure-Python fallback.
|
|
68
|
+
|
|
69
|
+
`pack_json` takes and returns the same JSON string every other Packvium binding speaks —
|
|
70
|
+
useful when the request is already serialized, or being forwarded as-is:
|
|
71
|
+
|
|
72
|
+
```python
|
|
73
|
+
from packvium_native import pack_json
|
|
74
|
+
|
|
75
|
+
response = pack_json('{"items":[...],"containers":[...]}')
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
## Examples
|
|
79
|
+
|
|
80
|
+
Runnable, in [`examples/`](examples). Each one is a single file you can read top to bottom
|
|
81
|
+
and execute without a project around it.
|
|
82
|
+
|
|
83
|
+
| File | What it shows |
|
|
84
|
+
| --- | --- |
|
|
85
|
+
| [`basic.py`](examples/basic.py) | Pack through the adapter and report which backend answered. |
|
|
86
|
+
| [`shapes.py`](examples/shapes.py) | Items that are not their box: complementary wedges sharing one crate as `convex_hull`, two copies of one wedge that need the signed rotation `-L-W+H`, a cushion that compresses under load until the crush limit refuses it, and a gusseted bag that holds a layer more than a flat one — the same numbers whichever backend answered. |
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
python3 examples/basic.py
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## Platforms
|
|
93
|
+
|
|
94
|
+
Native wheels support Linux x86_64/aarch64, macOS Apple Silicon/Intel and Windows. The
|
|
95
|
+
wheel uses Python's stable ABI, so one wheel supports Python 3.9 and later on its
|
|
96
|
+
platform.
|
|
97
|
+
|
|
98
|
+
## The Packvium family
|
|
99
|
+
|
|
100
|
+
One request and result contract, implemented independently in four engines (Rust,
|
|
101
|
+
Python, PHP, JavaScript) and checked against each other on a shared fixture set. Python and
|
|
102
|
+
PHP are held to byte-identical canonical results; Rust and the JavaScript fallback are held
|
|
103
|
+
to independent validity and a per-fixture objective floor.
|
|
104
|
+
Pick the package for your stack; mixing them in one system is safe.
|
|
105
|
+
|
|
106
|
+
Documentation, the constraint reference and the benchmarks are at
|
|
107
|
+
[packvium.com](https://packvium.com).
|
|
108
|
+
|
|
109
|
+
| Package | Install | Source |
|
|
110
|
+
| --- | --- | --- |
|
|
111
|
+
| Python — [`packvium`](https://pypi.org/project/packvium/) | `pip install packvium` | [packvium-python](https://github.com/packvium/packvium-python) |
|
|
112
|
+
| PHP — [`packvium/packvium`](https://packagist.org/packages/packvium/packvium) | `composer require packvium/packvium` | [packvium-php](https://github.com/packvium/packvium-php) |
|
|
113
|
+
| Rust — [`packvium`](https://crates.io/crates/packvium) | `packvium = "1.11"` | [packvium-rust](https://github.com/packvium/packvium-rust) |
|
|
114
|
+
| Node.js — [`@packvium/engine`](https://www.npmjs.com/package/@packvium/engine) | `npm install @packvium/engine` | [packvium-node](https://github.com/packvium/packvium-node) |
|
|
115
|
+
| Browser / WebAssembly — [`@packvium/browser`](https://www.npmjs.com/package/@packvium/browser) | `npm install @packvium/browser` | [packvium-wasm](https://github.com/packvium/packvium-wasm) |
|
|
116
|
+
| PHP FFI bridge — [`packvium/native-bridge`](https://packagist.org/packages/packvium/native-bridge) | `composer require packvium/native-bridge` | [packvium-php-bridge](https://github.com/packvium/packvium-php-bridge) |
|
|
117
|
+
| Python native selector — `packvium-native` | from source until the native wheels ship | [packvium-python-adapter](https://github.com/packvium/packvium-python-adapter) |
|
|
118
|
+
|
|
119
|
+
## Citation
|
|
120
|
+
|
|
121
|
+
If Packvium supports your research, cite it as software. GitHub's **Cite this repository**
|
|
122
|
+
button reads [`CITATION.cff`](https://github.com/packvium/packvium-python-adapter/blob/main/CITATION.cff), and
|
|
123
|
+
[`codemeta.json`](https://github.com/packvium/packvium-python-adapter/blob/main/codemeta.json) carries the same record in
|
|
124
|
+
CodeMeta form.
|
|
125
|
+
|
|
126
|
+
```bibtex
|
|
127
|
+
@software{packvium_python_adapter,
|
|
128
|
+
author = {{Packvium contributors}},
|
|
129
|
+
title = {Packvium native backend selector for Python},
|
|
130
|
+
version = {1.11.0},
|
|
131
|
+
license = {MIT},
|
|
132
|
+
url = {https://packvium.com}
|
|
133
|
+
}
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
## License
|
|
137
|
+
|
|
138
|
+
MIT. See [LICENSE](LICENSE).
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
LICENSE
|
|
2
|
+
README.md
|
|
3
|
+
pyproject.toml
|
|
4
|
+
src/packvium_native/__init__.py
|
|
5
|
+
src/packvium_native.egg-info/PKG-INFO
|
|
6
|
+
src/packvium_native.egg-info/SOURCES.txt
|
|
7
|
+
src/packvium_native.egg-info/dependency_links.txt
|
|
8
|
+
src/packvium_native.egg-info/requires.txt
|
|
9
|
+
src/packvium_native.egg-info/top_level.txt
|
|
10
|
+
tests/test_adapter.py
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
packvium_native
|
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
import json
|
|
2
|
+
import sys
|
|
3
|
+
import types
|
|
4
|
+
from pathlib import Path
|
|
5
|
+
|
|
6
|
+
import pytest
|
|
7
|
+
|
|
8
|
+
import packvium_native
|
|
9
|
+
from packvium_native import pack
|
|
10
|
+
|
|
11
|
+
# A cross-language fixture kept several levels above this package; a published copy
|
|
12
|
+
# does not carry it.
|
|
13
|
+
ROOT = Path(__file__).parents[2] / "conformance" / "shared" / "fixtures"
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def test_fixtures() -> None:
|
|
17
|
+
if not ROOT.is_dir():
|
|
18
|
+
pytest.skip("the shared cross-language fixture corpus is not part of this package")
|
|
19
|
+
# A blanket `result["complete"]` assertion would be wrong — the group-atomicity
|
|
20
|
+
# regression fixture is deliberately unsatisfiable.
|
|
21
|
+
for path in ROOT.glob("*.json"):
|
|
22
|
+
result = pack(json.loads(path.read_text()))
|
|
23
|
+
expected_complete = len(result["unpacked_items"]) == 0
|
|
24
|
+
assert result["complete"] == expected_complete, (path.name, result)
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
# The native path raises what the pure engine raises, and both write one spelling.
|
|
28
|
+
# A stand-in module raises what the compiled wheel raises -- `PackviumError(ValueError)` with
|
|
29
|
+
# the core's refusal as attributes -- so this runs without a Rust build.
|
|
30
|
+
SIDE = {"length": "100", "width": "100", "height": "100"}
|
|
31
|
+
FIXED = {"item_type": "cube", "container_type": "box", "container_instance": 1,
|
|
32
|
+
"position": {"x": "0", "y": "0", "z": "0"}, "orientation": "LWH"}
|
|
33
|
+
REFUSED = {
|
|
34
|
+
"collision": {
|
|
35
|
+
"items": [{"id": "cube", "quantity": 2, "dimensions": SIDE}],
|
|
36
|
+
"containers": [{"id": "box", "inner_dimensions": {"length": "200", "width": "100", "height": "100"}}],
|
|
37
|
+
"fixed_placements": [FIXED, FIXED],
|
|
38
|
+
},
|
|
39
|
+
"unsupported": {
|
|
40
|
+
"items": [{"id": "cube", "quantity": 1, "dimensions": SIDE}],
|
|
41
|
+
"containers": [{"id": "box", "inner_dimensions": SIDE,
|
|
42
|
+
"pallet_overhang_limit": {"length": "1", "width": "1"}, "axles": []}],
|
|
43
|
+
},
|
|
44
|
+
"policy": {
|
|
45
|
+
"items": [{"id": "cube", "quantity": 1, "dimensions": SIDE}],
|
|
46
|
+
"containers": [{"id": "box", "inner_dimensions": SIDE}],
|
|
47
|
+
"policy": "x",
|
|
48
|
+
},
|
|
49
|
+
"quantity": {
|
|
50
|
+
"items": [{"id": "cube", "quantity": 0, "dimensions": SIDE}],
|
|
51
|
+
"containers": [{"id": "box", "inner_dimensions": SIDE}],
|
|
52
|
+
},
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
class StandInError(ValueError):
|
|
57
|
+
def __init__(self, message: str, **attributes: object) -> None:
|
|
58
|
+
super().__init__(message)
|
|
59
|
+
for name in ("code", "reason", "field", "detail"):
|
|
60
|
+
setattr(self, name, attributes.get(name))
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def stand_in(raised: Exception) -> types.ModuleType:
|
|
64
|
+
module = types.ModuleType("packvium_native_rust")
|
|
65
|
+
module.PackviumError = StandInError # type: ignore[attr-defined]
|
|
66
|
+
|
|
67
|
+
def pack_json(payload: str) -> str:
|
|
68
|
+
raise raised
|
|
69
|
+
|
|
70
|
+
module.pack_json = pack_json # type: ignore[attr-defined]
|
|
71
|
+
return module
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def describe(error: BaseException) -> tuple:
|
|
75
|
+
return (type(error), getattr(error, "code", None), getattr(error, "reason", None),
|
|
76
|
+
getattr(error, "field", None), getattr(error, "detail", None))
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def clock_free(value: object) -> object:
|
|
80
|
+
# Two solves of one request differ only in what the clock read: a loaded host reads 1 ms.
|
|
81
|
+
if isinstance(value, dict):
|
|
82
|
+
return {key: clock_free(item) for key, item in value.items() if "duration" not in key}
|
|
83
|
+
if isinstance(value, list):
|
|
84
|
+
return [clock_free(item) for item in value]
|
|
85
|
+
return value
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def python_refusal(request: dict) -> BaseException:
|
|
89
|
+
# The pure engine is a test extra only on Python 3.10+, where it is supported.
|
|
90
|
+
packvium = pytest.importorskip("packvium")
|
|
91
|
+
with pytest.raises(ValueError) as caught:
|
|
92
|
+
packvium.pack_from_dict(request)
|
|
93
|
+
return caught.value
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
NATIVE_ERRORS = {
|
|
97
|
+
"collision": StandInError("invalid_fixed_placement: collision: cube#1 with cube#2", code="invalid_fixed_placement",
|
|
98
|
+
reason="cannot_hold", field="/fixed_placements", detail="collision: cube#1 with cube#2"),
|
|
99
|
+
"unsupported": StandInError("unsupported_feature: the Rust core does not yet implement container.pallet_overhang_limit+axles; "
|
|
100
|
+
"the request was rejected instead of silently ignoring public fields",
|
|
101
|
+
code="unsupported_feature"),
|
|
102
|
+
"policy": StandInError("invalid input: policy must be an object", code="invalid_input"),
|
|
103
|
+
"quantity": StandInError("invalid_request: /items/0/quantity: must be at least 1", code="invalid_request",
|
|
104
|
+
reason="below_minimum", field="/items/0/quantity", detail="must be at least 1"),
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
@pytest.mark.parametrize("name", sorted(REFUSED))
|
|
109
|
+
def test_a_native_refusal_is_raised_as_the_pure_engines_class(monkeypatch: pytest.MonkeyPatch, name: str) -> None:
|
|
110
|
+
expected = python_refusal(REFUSED[name])
|
|
111
|
+
monkeypatch.setitem(sys.modules, "packvium_native_rust", stand_in(NATIVE_ERRORS[name]))
|
|
112
|
+
assert packvium_native.backend() == "rust"
|
|
113
|
+
with pytest.raises(ValueError) as caught:
|
|
114
|
+
packvium_native.pack(REFUSED[name])
|
|
115
|
+
assert describe(caught.value) == describe(expected)
|
|
116
|
+
if name != "unsupported": # that sentence names the engine that refused
|
|
117
|
+
assert str(caught.value) == str(expected)
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
@pytest.mark.parametrize("unnamed", [
|
|
121
|
+
StandInError("caught native panic"),
|
|
122
|
+
StandInError("solver result failed independent validation: overlap", code="solution_failed_validation"),
|
|
123
|
+
], ids=["missing code", "unmapped code"])
|
|
124
|
+
def test_a_native_error_with_no_refusal_to_name_falls_back_to_the_pure_engine(
|
|
125
|
+
monkeypatch: pytest.MonkeyPatch, unnamed: StandInError) -> None:
|
|
126
|
+
pytest.importorskip("packvium")
|
|
127
|
+
request = {"items": [{"id": "cube", "quantity": 1, "dimensions": SIDE}],
|
|
128
|
+
"containers": [{"id": "box", "inner_dimensions": SIDE}]}
|
|
129
|
+
monkeypatch.setitem(sys.modules, "packvium_native_rust", None)
|
|
130
|
+
expected = packvium_native.pack_json(json.dumps(request))
|
|
131
|
+
monkeypatch.setitem(sys.modules, "packvium_native_rust", stand_in(unnamed))
|
|
132
|
+
assert packvium_native.backend() == "rust"
|
|
133
|
+
assert clock_free(json.loads(packvium_native.pack_json(json.dumps(request)))) == clock_free(json.loads(expected))
|
|
134
|
+
assert json.loads(expected)["complete"] is True
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
def test_a_native_error_with_a_code_is_raised_as_it_came_when_packvium_is_absent(
|
|
138
|
+
monkeypatch: pytest.MonkeyPatch) -> None:
|
|
139
|
+
coded = NATIVE_ERRORS["quantity"]
|
|
140
|
+
monkeypatch.setitem(sys.modules, "packvium", None) # import fails: no class to raise
|
|
141
|
+
monkeypatch.setitem(sys.modules, "packvium_native_rust", stand_in(coded))
|
|
142
|
+
with pytest.raises(StandInError) as caught:
|
|
143
|
+
packvium_native.pack(REFUSED["quantity"])
|
|
144
|
+
assert caught.value is coded
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
def test_the_fallback_writes_the_canonical_spelling(monkeypatch: pytest.MonkeyPatch) -> None:
|
|
148
|
+
pytest.importorskip("packvium")
|
|
149
|
+
monkeypatch.setitem(sys.modules, "packvium_native_rust", None) # import fails: fallback
|
|
150
|
+
assert packvium_native.backend() == "python"
|
|
151
|
+
request = {"items": [{"id": "é", "quantity": 1, "dimensions": SIDE}],
|
|
152
|
+
"containers": [{"id": "box", "inner_dimensions": SIDE}]}
|
|
153
|
+
text = packvium_native.pack_json(json.dumps(request))
|
|
154
|
+
assert text == json.dumps(json.loads(text), ensure_ascii=False, separators=(",", ":"), sort_keys=True)
|
|
155
|
+
assert '"é' in text, "non-ASCII stays UTF-8, as the native engine writes it"
|
|
156
|
+
|
|
157
|
+
|
|
158
|
+
def test_the_native_extra_is_pinned_to_this_release() -> None:
|
|
159
|
+
pyproject = (Path(__file__).parents[1] / "pyproject.toml").read_text(encoding="utf-8")
|
|
160
|
+
assert f'"packvium-native-rust=={packvium_native.__version__}"' in pyproject
|