packvium-native 1.11.0__py3-none-any.whl
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.
|
@@ -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,6 @@
|
|
|
1
|
+
packvium_native/__init__.py,sha256=fbsSL7XI307Cx7EGgFZK1wxVSQCyzL9_RFZss_aBlhA,3803
|
|
2
|
+
packvium_native-1.11.0.dist-info/licenses/LICENSE,sha256=9fzq3vAiAqoOts5ZktCewiJPZlx1dCwmjv81UXP-U2w,1078
|
|
3
|
+
packvium_native-1.11.0.dist-info/METADATA,sha256=BkDV36ED2s5MpxId10pyMRibY1cmVdGUaSYuUF9HoEg,5884
|
|
4
|
+
packvium_native-1.11.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
5
|
+
packvium_native-1.11.0.dist-info/top_level.txt,sha256=XuhJmYJHLKlE9WeGdDWbrFoxR8IZR2vb_Hyyz2jSzuk,16
|
|
6
|
+
packvium_native-1.11.0.dist-info/RECORD,,
|
|
@@ -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 @@
|
|
|
1
|
+
packvium_native
|