ponkan-python 0.1.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.
- ponkan_python-0.1.0.dist-info/METADATA +157 -0
- ponkan_python-0.1.0.dist-info/RECORD +39 -0
- ponkan_python-0.1.0.dist-info/WHEEL +4 -0
- ponkan_python-0.1.0.dist-info/entry_points.txt +5 -0
- ponkan_python-0.1.0.dist-info/licenses/LICENSE +22 -0
- ponkan_python-0.1.0.dist-info/licenses/NOTICE.md +14 -0
- py3dscapture/__init__.py +36 -0
- py3dscapture/artifacts.py +66 -0
- py3dscapture/capture.py +599 -0
- py3dscapture/devices/__init__.py +1 -0
- py3dscapture/devices/n3dsxl_ftd3.py +238 -0
- py3dscapture/errors.py +120 -0
- py3dscapture/hardware_gate.py +143 -0
- py3dscapture/image/__init__.py +1 -0
- py3dscapture/image/frame.py +166 -0
- py3dscapture/protocol/__init__.py +1 -0
- py3dscapture/protocol/layout_3ds.py +60 -0
- py3dscapture/protocol/n3dsxl.py +249 -0
- py3dscapture/protocol/sizes.py +128 -0
- py3dscapture/py.typed +1 -0
- py3dscapture/streaming/__init__.py +1 -0
- py3dscapture/streaming/buffers.py +156 -0
- py3dscapture/streaming/engine.py +285 -0
- py3dscapture/streaming/policies.py +157 -0
- py3dscapture/streaming/stats.py +254 -0
- py3dscapture/tools/__init__.py +1 -0
- py3dscapture/tools/capture_raw.py +44 -0
- py3dscapture/tools/list_devices.py +68 -0
- py3dscapture/tools/raw_to_png.py +251 -0
- py3dscapture/tools/stream_n3dsxl.py +152 -0
- py3dscapture/transport/__init__.py +1 -0
- py3dscapture/transport/d3xx_backend.py +850 -0
- py3dscapture/transport/d3xx_native.py +268 -0
- py3dscapture/transport/d3xx_native_streaming.py +306 -0
- py3dscapture/transport/d3xx_streaming.py +202 -0
- py3dscapture/transport/ftd3_backend.py +275 -0
- py3dscapture/transport/ftd3_pipe.py +387 -0
- py3dscapture/transport/libusb_async.py +134 -0
- py3dscapture/transport/libusb_backend.py +357 -0
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: ponkan-python
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: A Python capture library focused on new 3DS XL capture board frame acquisition.
|
|
5
|
+
Project-URL: Documentation, https://github.com/niart120/ponkan-python/blob/master/docs/api.md
|
|
6
|
+
Project-URL: Homepage, https://github.com/niart120/ponkan-python
|
|
7
|
+
Project-URL: Issues, https://github.com/niart120/ponkan-python/issues
|
|
8
|
+
Project-URL: Repository, https://github.com/niart120/ponkan-python.git
|
|
9
|
+
Author-email: niart120 <38847256+niart120@users.noreply.github.com>
|
|
10
|
+
Maintainer-email: niart120 <38847256+niart120@users.noreply.github.com>
|
|
11
|
+
License-Expression: MIT
|
|
12
|
+
License-File: LICENSE
|
|
13
|
+
License-File: NOTICE.md
|
|
14
|
+
Keywords: 3ds,capture-card,n3dsxl,new-3ds-xl,usb,video-capture
|
|
15
|
+
Classifier: Development Status :: 2 - Pre-Alpha
|
|
16
|
+
Classifier: Intended Audience :: Developers
|
|
17
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
18
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
19
|
+
Classifier: Programming Language :: Python :: 3
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
22
|
+
Classifier: Topic :: Multimedia :: Video :: Capture
|
|
23
|
+
Classifier: Typing :: Typed
|
|
24
|
+
Requires-Python: <3.14,>=3.12
|
|
25
|
+
Requires-Dist: libusb1>=3.3.1
|
|
26
|
+
Requires-Dist: numpy>=2.0
|
|
27
|
+
Provides-Extra: d3xx
|
|
28
|
+
Requires-Dist: pyd3xx>=1.1.4; extra == 'd3xx'
|
|
29
|
+
Provides-Extra: image
|
|
30
|
+
Requires-Dist: pillow>=10.0; extra == 'image'
|
|
31
|
+
Provides-Extra: opencv
|
|
32
|
+
Requires-Dist: opencv-python>=4.10; extra == 'opencv'
|
|
33
|
+
Description-Content-Type: text/markdown
|
|
34
|
+
|
|
35
|
+
# ponkan-python
|
|
36
|
+
|
|
37
|
+
`ponkan-python` は、new 3DS XL capture board から USB 経由で映像フレームを取得するための Python ライブラリです。
|
|
38
|
+
|
|
39
|
+
このプロジェクトは [`cc3dsfs`](https://github.com/Lorenzooone/cc3dsfs) を参照しながら、個人用途で必要な N3DSXL 映像取得機能に絞って Python で再構成するものです。`cc3dsfs` 全体の代替や互換 API を提供することは目的にしていません。継続的なメンテナンスや対応 device の拡張は未定です。
|
|
40
|
+
|
|
41
|
+
## Current Scope
|
|
42
|
+
|
|
43
|
+
- new 3DS XL capture board の device 認識
|
|
44
|
+
- raw frame 取得
|
|
45
|
+
- raw frame の保存と metadata 記録
|
|
46
|
+
- RGB8 `numpy.ndarray` への変換
|
|
47
|
+
- Pillow 互換出力
|
|
48
|
+
- libusb async transfer による streaming MVP
|
|
49
|
+
|
|
50
|
+
詳細は次の仕様書を参照してください。
|
|
51
|
+
|
|
52
|
+
- `spec/initial/cc3dsfs_python_rebuild_spec.md`
|
|
53
|
+
- `spec/initial/cc3dsfs_python_n3dsxl_implementation_workflow.md`
|
|
54
|
+
|
|
55
|
+
## Installation
|
|
56
|
+
|
|
57
|
+
Python 3.12 / 3.13 を対象にしています。
|
|
58
|
+
|
|
59
|
+
```console
|
|
60
|
+
pip install ponkan-python
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
PNG 変換には Pillow extra、FTDI D3XX backend には D3XX extra を追加します。
|
|
64
|
+
|
|
65
|
+
```console
|
|
66
|
+
pip install "ponkan-python[image]"
|
|
67
|
+
pip install "ponkan-python[d3xx]"
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## Usage
|
|
71
|
+
|
|
72
|
+
高レベル API では、new 3DS XL capture board を開いて `read()` で RGB8 `numpy.ndarray` を取得できます。
|
|
73
|
+
|
|
74
|
+
```python
|
|
75
|
+
from py3dscapture import CaptureOutput, open_capture
|
|
76
|
+
|
|
77
|
+
with open_capture(output=CaptureOutput.BOTH_VERTICAL) as cap:
|
|
78
|
+
image = cap.read()
|
|
79
|
+
if image is not None:
|
|
80
|
+
print(image.shape)
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
上画面だけを読む場合は `CaptureOutput.TOP` を指定します。OpenCV へ渡す場合は `colorspace="BGR"` を指定できます。
|
|
84
|
+
|
|
85
|
+
```python
|
|
86
|
+
from py3dscapture import CaptureOutput, open_capture
|
|
87
|
+
|
|
88
|
+
with open_capture(output=CaptureOutput.TOP, colorspace="BGR") as cap:
|
|
89
|
+
top_bgr = cap.read()
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
3DS 固有の上画面・下画面・sequence などが必要な場合は `read_frame()` を使います。
|
|
93
|
+
|
|
94
|
+
```python
|
|
95
|
+
from py3dscapture import open_capture
|
|
96
|
+
|
|
97
|
+
with open_capture() as cap:
|
|
98
|
+
frame = cap.read_frame()
|
|
99
|
+
if frame is not None:
|
|
100
|
+
top = frame.top
|
|
101
|
+
bottom = frame.bottom
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
API の詳細は [API Reference](https://github.com/niart120/ponkan-python/blob/master/docs/api.md) を参照してください。
|
|
105
|
+
|
|
106
|
+
## Command Line Tools
|
|
107
|
+
|
|
108
|
+
インストール後は次の console scripts を利用できます。
|
|
109
|
+
|
|
110
|
+
```console
|
|
111
|
+
py3dscapture-list-devices
|
|
112
|
+
py3dscapture-capture-raw --out captures/n3dsxl/raw_2d_001.bin
|
|
113
|
+
py3dscapture-raw-to-png captures/n3dsxl/raw_2d_001.bin --metadata captures/n3dsxl/raw_2d_001.json --out captures/n3dsxl/png
|
|
114
|
+
py3dscapture-stream-n3dsxl --duration 10 --stats
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
実機へ N3DSXL command を送る操作は、事前に device identity と安全境界を確認してから実行してください。
|
|
118
|
+
|
|
119
|
+
## Development
|
|
120
|
+
|
|
121
|
+
Python 実行と依存管理は `uv` を使います。
|
|
122
|
+
|
|
123
|
+
```console
|
|
124
|
+
uv sync --dev
|
|
125
|
+
scripts/install-git-hooks.ps1
|
|
126
|
+
uv run ruff format --check .
|
|
127
|
+
uv run ruff check .
|
|
128
|
+
uv run ty check --no-progress
|
|
129
|
+
uv run pytest tests/unit
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
実機 new 3DS XL capture board を使うテストは通常 CI では実行しません。
|
|
133
|
+
|
|
134
|
+
```console
|
|
135
|
+
$env:PONKAN_RUN_N3DSXL = "1"
|
|
136
|
+
uv run pytest -m requires_n3dsxl tests/e2e
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
## Safety
|
|
140
|
+
|
|
141
|
+
N3DSXL command は、VID/PID と product string が仕様で許可された device にだけ送ります。未知の FTDI device を N3DSXL として扱わないでください。
|
|
142
|
+
|
|
143
|
+
Git hooks は `.githooks/` に配置しています。clone 後に `scripts/install-git-hooks.ps1` または `sh scripts/install-git-hooks.sh` を実行すると、`core.hooksPath` が `.githooks` に設定されます。
|
|
144
|
+
|
|
145
|
+
Codex project-local policy は `.codex/` に配置しています。Codex で有効にするには、この project layer を trust し、`/hooks` で hook を review/trust してください。
|
|
146
|
+
|
|
147
|
+
## License and Attribution
|
|
148
|
+
|
|
149
|
+
This project is licensed under the MIT License.
|
|
150
|
+
|
|
151
|
+
This project references `cc3dsfs` by Lorenzooone, which is also licensed under
|
|
152
|
+
the MIT License. The upstream copyright notice is preserved in `LICENSE` and
|
|
153
|
+
`NOTICE.md`.
|
|
154
|
+
|
|
155
|
+
- https://github.com/Lorenzooone/cc3dsfs
|
|
156
|
+
|
|
157
|
+
Release and publishing notes are kept in [Publishing](https://github.com/niart120/ponkan-python/blob/master/docs/publishing.md).
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
py3dscapture/__init__.py,sha256=1BdGPUhO7y--e5L2hqSnxhiHaRua_5aZ872T6vkEWz0,997
|
|
2
|
+
py3dscapture/artifacts.py,sha256=E5C63HfEnkQBeXH0E-oQ1_NhhzJYcYYNUrw5S-OtUL8,1961
|
|
3
|
+
py3dscapture/capture.py,sha256=L7wfW25safua22VRjDXfvjNduzwOW-jNP7j73LLzxNM,20262
|
|
4
|
+
py3dscapture/errors.py,sha256=S-f6yGSYaQH1y8X2loeRSiANwiDOzCRdnMt6441EQC0,3695
|
|
5
|
+
py3dscapture/hardware_gate.py,sha256=FClF7ckNH9kTXy833YgwDuKuGBkoAGFkDkf5IlBDsms,4834
|
|
6
|
+
py3dscapture/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
|
|
7
|
+
py3dscapture/devices/__init__.py,sha256=uYvgYIgcwciikPR23c_p674XuJDKTamUH0PKV3ECXiE,30
|
|
8
|
+
py3dscapture/devices/n3dsxl_ftd3.py,sha256=md6WyM9W1n-VY5L7uEhZbjWdTO044-oR4onkacJpwrM,8405
|
|
9
|
+
py3dscapture/image/__init__.py,sha256=-23f78dfqU2Q-WOIvYCqstSexYId_K3sP8pBn7tkUQU,38
|
|
10
|
+
py3dscapture/image/frame.py,sha256=yQ4gtMgFXv9DR72kgezi3oOKvaVYfXrNFCgpTc4h8Ok,5800
|
|
11
|
+
py3dscapture/protocol/__init__.py,sha256=lCr27_-ula3CtVd5nzTFbhEARAoiMecGEv8n8Q_xH6I,48
|
|
12
|
+
py3dscapture/protocol/layout_3ds.py,sha256=sqRbBqHe_VSkPp8zso5iVVk8Yc-sEH9CZLyD05ZiBXA,1968
|
|
13
|
+
py3dscapture/protocol/n3dsxl.py,sha256=_fpiWGoHle7qgtMk59o1YdM_HDldHxQZE2mgN_4F-b0,8454
|
|
14
|
+
py3dscapture/protocol/sizes.py,sha256=AlI9Ge-Dk6Rx8UI4eF2VVRpxcZ_pCEuC46TVc-qmJxQ,4129
|
|
15
|
+
py3dscapture/streaming/__init__.py,sha256=30b10h-HyMhyGW0emIJ1Cc_189kolDxuNoYMfft05Hc,35
|
|
16
|
+
py3dscapture/streaming/buffers.py,sha256=03ku6ZWkWwo4b6q9gnYaJmoee7zqur9WEkEUyHe6tI8,4727
|
|
17
|
+
py3dscapture/streaming/engine.py,sha256=wvuiF074n546FuzsQeYi9EYutcYPmNSjzrLoYE_-Yzg,10791
|
|
18
|
+
py3dscapture/streaming/policies.py,sha256=lXsNQJROi7IYZPJkLNvJn1xG8dqfE5-OiKb0RqFjiJE,4320
|
|
19
|
+
py3dscapture/streaming/stats.py,sha256=WT7q16CPtOel95xGn3uG6iXSzA15WOEMjlSWJ3hbzWY,8534
|
|
20
|
+
py3dscapture/tools/__init__.py,sha256=tMgzvLN5Tq0ia16r9UUMA6QOZ8NOHjwJRuS0KSk9LAg,28
|
|
21
|
+
py3dscapture/tools/capture_raw.py,sha256=mDL68bfAGD3nFI4rmAkvJ7QolE7X6ay3MN5u6XmaYuk,1508
|
|
22
|
+
py3dscapture/tools/list_devices.py,sha256=kVD1mHHcU0qtWf9pIwakP_j80b_Ar2tMofksioGEfMA,2325
|
|
23
|
+
py3dscapture/tools/raw_to_png.py,sha256=qnP-To6p4tg7-y4vDke07Oy0zPzv9Yk12fVHhuux-_I,8026
|
|
24
|
+
py3dscapture/tools/stream_n3dsxl.py,sha256=8A9vsiB5nsdLdSsuvmrXw6XPpIzgEex94-tmN5QHe2o,5347
|
|
25
|
+
py3dscapture/transport/__init__.py,sha256=zp3na4DRpaD2_RCvB5rGxdZW7xOahfhmJpdvvpPpBFI,29
|
|
26
|
+
py3dscapture/transport/d3xx_backend.py,sha256=EBg0dtaHxGak929h1JJuFxrOajr-ZgzCo_89qZQtqVs,26946
|
|
27
|
+
py3dscapture/transport/d3xx_native.py,sha256=3Njbl0GwEy_YXrfhAa3y67GZ3OdF87lL3twQNYueUYw,9019
|
|
28
|
+
py3dscapture/transport/d3xx_native_streaming.py,sha256=gwIqHEyX8XM4wj50n0qW6enupOzrBiaz9rhcRmI73w8,10914
|
|
29
|
+
py3dscapture/transport/d3xx_streaming.py,sha256=JvxfnF58Q6sVT9ZlnvRBfnydweeJDHZ_OTkUmbCkKug,6699
|
|
30
|
+
py3dscapture/transport/ftd3_backend.py,sha256=k8wceyVq8OYTILK7E8SYwOghmVd3TQCMt4W-xR5SxqQ,7795
|
|
31
|
+
py3dscapture/transport/ftd3_pipe.py,sha256=M8CCdkHvdIMKD2NePzIWcst9cD4_guf5kZ9T-YwuhTQ,12679
|
|
32
|
+
py3dscapture/transport/libusb_async.py,sha256=OHR1mBIrdCJP7n9RVj1WO8xjwMqC55UaKTdpT3J5BrE,4135
|
|
33
|
+
py3dscapture/transport/libusb_backend.py,sha256=DxUOsGgPPxiJtosf_KUbf1JpPeHAJxBcybRHeW1loBs,11037
|
|
34
|
+
ponkan_python-0.1.0.dist-info/METADATA,sha256=n7aJ3Ui81Kum0U-8e7Qegw9ysft61WkLqd2qFeYl5ZY,5746
|
|
35
|
+
ponkan_python-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
|
|
36
|
+
ponkan_python-0.1.0.dist-info/entry_points.txt,sha256=fX1my2fuKlmDn6T0PxrWSeXKmO5PsVpTfl7BYEqtYkc,274
|
|
37
|
+
ponkan_python-0.1.0.dist-info/licenses/LICENSE,sha256=ikr_NtR46ZO2hvTX0LtCeb9wbRb19pCcY97Hw_6VA6c,1096
|
|
38
|
+
ponkan_python-0.1.0.dist-info/licenses/NOTICE.md,sha256=KZPWtflkTM1GTH5e5UP7OvP7D8xYJotWUxgiePabylc,445
|
|
39
|
+
ponkan_python-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
[console_scripts]
|
|
2
|
+
py3dscapture-capture-raw = py3dscapture.tools.capture_raw:main
|
|
3
|
+
py3dscapture-list-devices = py3dscapture.tools.list_devices:main
|
|
4
|
+
py3dscapture-raw-to-png = py3dscapture.tools.raw_to_png:main
|
|
5
|
+
py3dscapture-stream-n3dsxl = py3dscapture.tools.stream_n3dsxl:main
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 niart120
|
|
4
|
+
Copyright (c) 2024 Lorenzooone
|
|
5
|
+
|
|
6
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
7
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
8
|
+
in the Software without restriction, including without limitation the rights
|
|
9
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
10
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
11
|
+
furnished to do so, subject to the following conditions:
|
|
12
|
+
|
|
13
|
+
The above copyright notice and this permission notice shall be included in all
|
|
14
|
+
copies or substantial portions of the Software.
|
|
15
|
+
|
|
16
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
17
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
18
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
19
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
20
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
21
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
22
|
+
SOFTWARE.
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
# Notices
|
|
2
|
+
|
|
3
|
+
`ponkan-python` is licensed under the MIT License.
|
|
4
|
+
|
|
5
|
+
This project references protocol behavior, constants, and implementation
|
|
6
|
+
structure from `cc3dsfs`:
|
|
7
|
+
|
|
8
|
+
- Project: https://github.com/Lorenzooone/cc3dsfs
|
|
9
|
+
- Author: Lorenzooone
|
|
10
|
+
- License: MIT License
|
|
11
|
+
- Copyright: Copyright (c) 2024 Lorenzooone
|
|
12
|
+
|
|
13
|
+
`ponkan-python` is a focused Python library for new 3DS XL capture board frame
|
|
14
|
+
acquisition. It is not a full compatibility port of `cc3dsfs`.
|
py3dscapture/__init__.py
ADDED
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
"""Python helpers for new 3DS XL capture board frame acquisition.
|
|
2
|
+
|
|
3
|
+
The package exposes the constants and size helpers needed to identify supported
|
|
4
|
+
N3DSXL capture boards and to reason about raw USB frame sizes. Higher-level
|
|
5
|
+
capture, decode, transport, and streaming APIs live in their dedicated
|
|
6
|
+
submodules.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from importlib.metadata import PackageNotFoundError, version
|
|
10
|
+
|
|
11
|
+
from py3dscapture.capture import CaptureConfig, CaptureOutput, CaptureReader, open_capture
|
|
12
|
+
from py3dscapture.protocol.sizes import (
|
|
13
|
+
ACCEPTED_N3DSXL_PRODUCT_IDS,
|
|
14
|
+
ACCEPTED_N3DSXL_PRODUCT_STRINGS,
|
|
15
|
+
N3DSXL_VENDOR_ID,
|
|
16
|
+
CaptureSizes,
|
|
17
|
+
capture_sizes,
|
|
18
|
+
)
|
|
19
|
+
|
|
20
|
+
try:
|
|
21
|
+
__version__ = version("ponkan-python")
|
|
22
|
+
except PackageNotFoundError:
|
|
23
|
+
__version__ = "0.0.0"
|
|
24
|
+
|
|
25
|
+
__all__ = [
|
|
26
|
+
"ACCEPTED_N3DSXL_PRODUCT_IDS",
|
|
27
|
+
"ACCEPTED_N3DSXL_PRODUCT_STRINGS",
|
|
28
|
+
"N3DSXL_VENDOR_ID",
|
|
29
|
+
"CaptureConfig",
|
|
30
|
+
"CaptureOutput",
|
|
31
|
+
"CaptureReader",
|
|
32
|
+
"CaptureSizes",
|
|
33
|
+
"__version__",
|
|
34
|
+
"capture_sizes",
|
|
35
|
+
"open_capture",
|
|
36
|
+
]
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
"""Artifact helpers for hardware-gated capture evidence."""
|
|
2
|
+
|
|
3
|
+
import json
|
|
4
|
+
from collections.abc import Mapping
|
|
5
|
+
from pathlib import Path
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
class ArtifactPathError(ValueError):
|
|
9
|
+
"""Raised when an artifact run id escapes the N3DSXL artifact root.
|
|
10
|
+
|
|
11
|
+
This prevents absolute paths and parent-directory traversal from being used
|
|
12
|
+
as hardware evidence run IDs.
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
def __init__(self) -> None:
|
|
16
|
+
"""Create an artifact path error with a stable user-facing message.
|
|
17
|
+
|
|
18
|
+
The message is intentionally short because path details can come from
|
|
19
|
+
user-controlled run IDs.
|
|
20
|
+
"""
|
|
21
|
+
super().__init__("invalid artifact run_id")
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def n3dsxl_artifact_dir(run_id: str, *, root: Path = Path("artifacts")) -> Path:
|
|
25
|
+
"""Return the artifact directory for one N3DSXL run.
|
|
26
|
+
|
|
27
|
+
Args:
|
|
28
|
+
run_id: Relative run identifier used below ``root / "n3dsxl"``.
|
|
29
|
+
root: Artifact root directory.
|
|
30
|
+
|
|
31
|
+
Returns:
|
|
32
|
+
Path where N3DSXL evidence for the run should be written.
|
|
33
|
+
|
|
34
|
+
Raises:
|
|
35
|
+
ArtifactPathError: ``run_id`` is absolute or contains ``..``.
|
|
36
|
+
"""
|
|
37
|
+
run_path = Path(run_id)
|
|
38
|
+
if run_path.is_absolute() or ".." in run_path.parts:
|
|
39
|
+
raise ArtifactPathError
|
|
40
|
+
return root / "n3dsxl" / run_path
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def write_json_artifact(
|
|
44
|
+
path: Path,
|
|
45
|
+
data: Mapping[str, object],
|
|
46
|
+
*,
|
|
47
|
+
force: bool = False,
|
|
48
|
+
) -> Path:
|
|
49
|
+
"""Write a JSON artifact, refusing overwrite unless force is set.
|
|
50
|
+
|
|
51
|
+
Args:
|
|
52
|
+
path: Destination JSON artifact path.
|
|
53
|
+
data: JSON-serializable mapping to write.
|
|
54
|
+
force: Overwrite an existing file when true.
|
|
55
|
+
|
|
56
|
+
Returns:
|
|
57
|
+
The path written by this call.
|
|
58
|
+
|
|
59
|
+
Raises:
|
|
60
|
+
FileExistsError: The artifact already exists and ``force`` is false.
|
|
61
|
+
"""
|
|
62
|
+
if path.exists() and not force:
|
|
63
|
+
raise FileExistsError(path)
|
|
64
|
+
path.parent.mkdir(parents=True, exist_ok=True)
|
|
65
|
+
path.write_text(json.dumps(data, indent=2, sort_keys=True), encoding="utf-8")
|
|
66
|
+
return path
|