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,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -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