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.
@@ -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,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -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,9 @@
1
+
2
+ [native]
3
+ packvium-native-rust==1.11.0
4
+
5
+ [test]
6
+ pytest
7
+
8
+ [test:python_version >= "3.10"]
9
+ packvium
@@ -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