ponkan-python 0.1.0__tar.gz → 0.1.2__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.
Files changed (80) hide show
  1. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/PKG-INFO +12 -14
  2. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/README.md +9 -10
  3. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/docs/api.md +16 -16
  4. ponkan_python-0.1.2/docs/publishing.md +193 -0
  5. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/pyproject.toml +10 -12
  6. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/__init__.py +2 -2
  7. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/capture.py +12 -12
  8. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/devices/n3dsxl_ftd3.py +3 -3
  9. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/errors.py +25 -5
  10. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/hardware_gate.py +1 -1
  11. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/image/frame.py +2 -2
  12. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/protocol/layout_3ds.py +3 -3
  13. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/protocol/n3dsxl.py +5 -5
  14. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/streaming/engine.py +8 -8
  15. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/streaming/policies.py +2 -2
  16. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/tools/capture_raw.py +5 -5
  17. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/tools/list_devices.py +2 -2
  18. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/tools/raw_to_png.py +3 -3
  19. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/tools/stream_n3dsxl.py +5 -5
  20. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/transport/d3xx_backend.py +11 -11
  21. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/transport/d3xx_native.py +2 -2
  22. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/transport/d3xx_native_streaming.py +7 -7
  23. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/transport/d3xx_streaming.py +5 -5
  24. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/transport/ftd3_backend.py +4 -4
  25. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/transport/ftd3_pipe.py +3 -3
  26. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/transport/libusb_async.py +1 -1
  27. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/transport/libusb_backend.py +1 -1
  28. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/conftest.py +1 -1
  29. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/e2e/test_n3dsxl_connect.py +6 -6
  30. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/e2e/test_n3dsxl_d3xx_backend.py +9 -9
  31. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/e2e/test_n3dsxl_d3xx_native_streaming.py +8 -8
  32. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/e2e/test_n3dsxl_ftd3_pipe.py +5 -5
  33. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/e2e/test_n3dsxl_high_level_capture_read_api.py +3 -3
  34. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/e2e/test_n3dsxl_open_close.py +4 -4
  35. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/e2e/test_n3dsxl_raw_capture.py +7 -7
  36. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/e2e/test_n3dsxl_streaming.py +7 -7
  37. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/manual/test_n3dsxl_decoder_visual.py +3 -3
  38. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/performance/test_n3dsxl_d3xx_native_streaming_smoke.py +8 -8
  39. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/performance/test_n3dsxl_streaming_smoke.py +8 -8
  40. ponkan_python-0.1.2/tests/unit/test_codex_pre_tool_use_policy.py +53 -0
  41. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/unit/test_d3xx_backend.py +10 -6
  42. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/unit/test_d3xx_native_api.py +1 -1
  43. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/unit/test_d3xx_native_streaming_backend.py +4 -4
  44. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/unit/test_d3xx_streaming_backend.py +3 -3
  45. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/unit/test_ftd3_backend_selector.py +4 -4
  46. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/unit/test_ftd3_pipe_payloads.py +5 -5
  47. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/unit/test_hardware_gate.py +1 -1
  48. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/unit/test_high_level_capture_read_api.py +5 -5
  49. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/unit/test_layout_3ds_decoder.py +7 -7
  50. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/unit/test_libusb_backend.py +1 -1
  51. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/unit/test_n3dsxl_artifacts.py +1 -1
  52. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/unit/test_n3dsxl_connect_sequence.py +7 -7
  53. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/unit/test_n3dsxl_device_filter.py +2 -2
  54. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/unit/test_n3dsxl_list_devices_cli.py +3 -3
  55. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/unit/test_n3dsxl_session.py +3 -3
  56. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/unit/test_n3dsxl_sizes.py +1 -1
  57. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/unit/test_package.py +9 -9
  58. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/unit/test_raw_capture_metadata.py +3 -3
  59. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/unit/test_stream_n3dsxl_cli.py +2 -2
  60. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/unit/test_streaming_buffers.py +1 -1
  61. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/unit/test_streaming_engine_fake_async.py +5 -5
  62. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/unit/test_streaming_performance_stats.py +1 -1
  63. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/unit/test_streaming_policies.py +3 -3
  64. ponkan_python-0.1.0/docs/publishing.md +0 -84
  65. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/.gitignore +0 -0
  66. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/LICENSE +0 -0
  67. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/NOTICE.md +0 -0
  68. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/artifacts.py +0 -0
  69. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/devices/__init__.py +0 -0
  70. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/image/__init__.py +0 -0
  71. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/protocol/__init__.py +0 -0
  72. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/protocol/sizes.py +0 -0
  73. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/py.typed +0 -0
  74. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/streaming/__init__.py +0 -0
  75. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/streaming/buffers.py +0 -0
  76. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/streaming/stats.py +0 -0
  77. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/tools/__init__.py +0 -0
  78. {ponkan_python-0.1.0/src/py3dscapture → ponkan_python-0.1.2/src/ponkan}/transport/__init__.py +0 -0
  79. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/e2e/README.md +0 -0
  80. {ponkan_python-0.1.0 → ponkan_python-0.1.2}/tests/performance/README.md +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: ponkan-python
3
- Version: 0.1.0
3
+ Version: 0.1.2
4
4
  Summary: A Python capture library focused on new 3DS XL capture board frame acquisition.
5
5
  Project-URL: Documentation, https://github.com/niart120/ponkan-python/blob/master/docs/api.md
6
6
  Project-URL: Homepage, https://github.com/niart120/ponkan-python
@@ -21,11 +21,10 @@ Classifier: Programming Language :: Python :: 3.12
21
21
  Classifier: Programming Language :: Python :: 3.13
22
22
  Classifier: Topic :: Multimedia :: Video :: Capture
23
23
  Classifier: Typing :: Typed
24
- Requires-Python: <3.14,>=3.12
24
+ Requires-Python: >=3.12
25
25
  Requires-Dist: libusb1>=3.3.1
26
26
  Requires-Dist: numpy>=2.0
27
- Provides-Extra: d3xx
28
- Requires-Dist: pyd3xx>=1.1.4; extra == 'd3xx'
27
+ Requires-Dist: pyd3xx>=1.1.4; sys_platform == 'win32'
29
28
  Provides-Extra: image
30
29
  Requires-Dist: pillow>=10.0; extra == 'image'
31
30
  Provides-Extra: opencv
@@ -54,17 +53,16 @@ Description-Content-Type: text/markdown
54
53
 
55
54
  ## Installation
56
55
 
57
- Python 3.12 / 3.13 を対象にしています。
56
+ Python 3.12 以上を対象にしています。現在の検証基準は Python 3.12 / 3.13 です。
58
57
 
59
58
  ```console
60
59
  pip install ponkan-python
61
60
  ```
62
61
 
63
- PNG 変換には Pillow extra、FTDI D3XX backend には D3XX extra を追加します。
62
+ Windows の FTDI D3XX backend では、通常依存として PyD3XX を利用します。PNG 変換には Pillow extra を追加します。
64
63
 
65
64
  ```console
66
65
  pip install "ponkan-python[image]"
67
- pip install "ponkan-python[d3xx]"
68
66
  ```
69
67
 
70
68
  ## Usage
@@ -72,7 +70,7 @@ pip install "ponkan-python[d3xx]"
72
70
  高レベル API では、new 3DS XL capture board を開いて `read()` で RGB8 `numpy.ndarray` を取得できます。
73
71
 
74
72
  ```python
75
- from py3dscapture import CaptureOutput, open_capture
73
+ from ponkan import CaptureOutput, open_capture
76
74
 
77
75
  with open_capture(output=CaptureOutput.BOTH_VERTICAL) as cap:
78
76
  image = cap.read()
@@ -83,7 +81,7 @@ with open_capture(output=CaptureOutput.BOTH_VERTICAL) as cap:
83
81
  上画面だけを読む場合は `CaptureOutput.TOP` を指定します。OpenCV へ渡す場合は `colorspace="BGR"` を指定できます。
84
82
 
85
83
  ```python
86
- from py3dscapture import CaptureOutput, open_capture
84
+ from ponkan import CaptureOutput, open_capture
87
85
 
88
86
  with open_capture(output=CaptureOutput.TOP, colorspace="BGR") as cap:
89
87
  top_bgr = cap.read()
@@ -92,7 +90,7 @@ with open_capture(output=CaptureOutput.TOP, colorspace="BGR") as cap:
92
90
  3DS 固有の上画面・下画面・sequence などが必要な場合は `read_frame()` を使います。
93
91
 
94
92
  ```python
95
- from py3dscapture import open_capture
93
+ from ponkan import open_capture
96
94
 
97
95
  with open_capture() as cap:
98
96
  frame = cap.read_frame()
@@ -108,10 +106,10 @@ API の詳細は [API Reference](https://github.com/niart120/ponkan-python/blob/
108
106
  インストール後は次の console scripts を利用できます。
109
107
 
110
108
  ```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
109
+ ponkan-list-devices
110
+ ponkan-capture-raw --out captures/n3dsxl/raw_2d_001.bin
111
+ ponkan-raw-to-png captures/n3dsxl/raw_2d_001.bin --metadata captures/n3dsxl/raw_2d_001.json --out captures/n3dsxl/png
112
+ ponkan-stream-n3dsxl --duration 10 --stats
115
113
  ```
116
114
 
117
115
  実機へ N3DSXL command を送る操作は、事前に device identity と安全境界を確認してから実行してください。
@@ -20,17 +20,16 @@
20
20
 
21
21
  ## Installation
22
22
 
23
- Python 3.12 / 3.13 を対象にしています。
23
+ Python 3.12 以上を対象にしています。現在の検証基準は Python 3.12 / 3.13 です。
24
24
 
25
25
  ```console
26
26
  pip install ponkan-python
27
27
  ```
28
28
 
29
- PNG 変換には Pillow extra、FTDI D3XX backend には D3XX extra を追加します。
29
+ Windows の FTDI D3XX backend では、通常依存として PyD3XX を利用します。PNG 変換には Pillow extra を追加します。
30
30
 
31
31
  ```console
32
32
  pip install "ponkan-python[image]"
33
- pip install "ponkan-python[d3xx]"
34
33
  ```
35
34
 
36
35
  ## Usage
@@ -38,7 +37,7 @@ pip install "ponkan-python[d3xx]"
38
37
  高レベル API では、new 3DS XL capture board を開いて `read()` で RGB8 `numpy.ndarray` を取得できます。
39
38
 
40
39
  ```python
41
- from py3dscapture import CaptureOutput, open_capture
40
+ from ponkan import CaptureOutput, open_capture
42
41
 
43
42
  with open_capture(output=CaptureOutput.BOTH_VERTICAL) as cap:
44
43
  image = cap.read()
@@ -49,7 +48,7 @@ with open_capture(output=CaptureOutput.BOTH_VERTICAL) as cap:
49
48
  上画面だけを読む場合は `CaptureOutput.TOP` を指定します。OpenCV へ渡す場合は `colorspace="BGR"` を指定できます。
50
49
 
51
50
  ```python
52
- from py3dscapture import CaptureOutput, open_capture
51
+ from ponkan import CaptureOutput, open_capture
53
52
 
54
53
  with open_capture(output=CaptureOutput.TOP, colorspace="BGR") as cap:
55
54
  top_bgr = cap.read()
@@ -58,7 +57,7 @@ with open_capture(output=CaptureOutput.TOP, colorspace="BGR") as cap:
58
57
  3DS 固有の上画面・下画面・sequence などが必要な場合は `read_frame()` を使います。
59
58
 
60
59
  ```python
61
- from py3dscapture import open_capture
60
+ from ponkan import open_capture
62
61
 
63
62
  with open_capture() as cap:
64
63
  frame = cap.read_frame()
@@ -74,10 +73,10 @@ API の詳細は [API Reference](https://github.com/niart120/ponkan-python/blob/
74
73
  インストール後は次の console scripts を利用できます。
75
74
 
76
75
  ```console
77
- py3dscapture-list-devices
78
- py3dscapture-capture-raw --out captures/n3dsxl/raw_2d_001.bin
79
- py3dscapture-raw-to-png captures/n3dsxl/raw_2d_001.bin --metadata captures/n3dsxl/raw_2d_001.json --out captures/n3dsxl/png
80
- py3dscapture-stream-n3dsxl --duration 10 --stats
76
+ ponkan-list-devices
77
+ ponkan-capture-raw --out captures/n3dsxl/raw_2d_001.bin
78
+ ponkan-raw-to-png captures/n3dsxl/raw_2d_001.bin --metadata captures/n3dsxl/raw_2d_001.json --out captures/n3dsxl/png
79
+ ponkan-stream-n3dsxl --duration 10 --stats
81
80
  ```
82
81
 
83
82
  実機へ N3DSXL command を送る操作は、事前に device identity と安全境界を確認してから実行してください。
@@ -1,28 +1,27 @@
1
1
  # API Reference
2
2
 
3
- `py3dscapture` exposes a small public API for new 3DS XL capture board frame
3
+ `ponkan` exposes a small public API for new 3DS XL capture board frame
4
4
  acquisition. The current package is focused on 2D N3DSXL video capture and does
5
5
  not provide GUI, audio playback, recording, old DS, Optimize, Nisetro, or IS
6
6
  device support.
7
7
 
8
- ## Installation Extras
8
+ ## Installation
9
9
 
10
10
  ```console
11
11
  pip install ponkan-python
12
12
  pip install "ponkan-python[image]"
13
- pip install "ponkan-python[d3xx]"
14
13
  ```
15
14
 
16
15
  Use the `image` extra when calling `CaptureFrame.to_pillow()` or the
17
- `py3dscapture-raw-to-png` command. Use the `d3xx` extra when selecting the D3XX
18
- backend.
16
+ `ponkan-raw-to-png` command. On Windows, the D3XX backend uses PyD3XX as a
17
+ normal platform-gated dependency.
19
18
 
20
19
  ## Top-Level Imports
21
20
 
22
21
  The package root exports the high-level reader and size helpers:
23
22
 
24
23
  ```python
25
- from py3dscapture import (
24
+ from ponkan import (
26
25
  ACCEPTED_N3DSXL_PRODUCT_IDS,
27
26
  ACCEPTED_N3DSXL_PRODUCT_STRINGS,
28
27
  N3DSXL_VENDOR_ID,
@@ -45,7 +44,7 @@ tree without installed metadata it falls back to `"0.0.0"`.
45
44
  Open a high-level streaming reader for an accepted new 3DS XL capture board.
46
45
 
47
46
  ```python
48
- from py3dscapture import CaptureOutput, open_capture
47
+ from ponkan import CaptureOutput, open_capture
49
48
 
50
49
  with open_capture(output=CaptureOutput.BOTH_VERTICAL) as cap:
51
50
  image = cap.read()
@@ -151,7 +150,7 @@ Write a raw payload and metadata sidecar using the same stem:
151
150
 
152
151
  ```python
153
152
  from pathlib import Path
154
- from py3dscapture.capture import save_raw_capture
153
+ from ponkan.capture import save_raw_capture
155
154
 
156
155
  bin_path, metadata_path = save_raw_capture(capture, Path("captures/raw_2d_001.bin"))
157
156
  ```
@@ -162,8 +161,8 @@ unless `force=True` is provided.
162
161
  ## Device Discovery
163
162
 
164
163
  ```python
165
- from py3dscapture.devices.n3dsxl_ftd3 import list_n3dsxl_devices
166
- from py3dscapture.transport.libusb_backend import Usb1Backend
164
+ from ponkan.devices.n3dsxl_ftd3 import list_n3dsxl_devices
165
+ from ponkan.transport.libusb_backend import Usb1Backend
167
166
 
168
167
  listing = list_n3dsxl_devices(Usb1Backend())
169
168
  ```
@@ -183,7 +182,7 @@ Accepted device identity is constrained by `N3DSXL_VENDOR_ID`,
183
182
  ## Size Helpers
184
183
 
185
184
  ```python
186
- from py3dscapture import capture_sizes
185
+ from ponkan import capture_sizes
187
186
 
188
187
  sizes = capture_sizes(mode_3d=False)
189
188
  print(sizes.video_size, sizes.capture_size)
@@ -208,10 +207,10 @@ Installed console scripts:
208
207
 
209
208
  | Command | Purpose |
210
209
  | --- | --- |
211
- | `py3dscapture-list-devices` | Print accepted and rejected FTDI-family devices without sending N3DSXL commands. |
212
- | `py3dscapture-capture-raw --out <path>` | Capture one raw frame and metadata sidecar. |
213
- | `py3dscapture-raw-to-png <raw> --metadata <json> --out <dir>` | Decode raw video to top and bottom PNG files. |
214
- | `py3dscapture-stream-n3dsxl --duration 10 --stats` | Run a bounded streaming smoke loop and print counters. |
210
+ | `ponkan-list-devices` | Print accepted and rejected FTDI-family devices without sending N3DSXL commands. |
211
+ | `ponkan-capture-raw --out <path>` | Capture one raw frame and metadata sidecar. |
212
+ | `ponkan-raw-to-png <raw> --metadata <json> --out <dir>` | Decode raw video to top and bottom PNG files. |
213
+ | `ponkan-stream-n3dsxl --duration 10 --stats` | Run a bounded streaming smoke loop and print counters. |
215
214
 
216
215
  Hardware commands should only be run after confirming the device identity and
217
216
  the project hardware safety policy.
@@ -229,4 +228,5 @@ All package-level failures inherit from `CaptureError`.
229
228
  | `UnsupportedOperation` | Requested behavior is outside current MVP scope. |
230
229
  | `TransferOverflow` | Transfer length exceeds the accepted capture size. |
231
230
  | `DecodeError` | Raw bytes or decoded frame data cannot be interpreted. |
232
- | `OptionalDependencyError` | Optional dependency such as Pillow or PyD3XX is missing. |
231
+ | `DependencyUnavailableError` | A runtime dependency required by the selected backend is unavailable. |
232
+ | `OptionalDependencyError` | Optional dependency such as Pillow is missing. |
@@ -0,0 +1,193 @@
1
+ # Publishing
2
+
3
+ This project publishes `ponkan-python` to PyPI with local release checks and
4
+ GitHub Actions Trusted Publishing. Do not upload distributions from a local
5
+ machine with `twine upload`; production publishing is driven by a `v*` tag.
6
+
7
+ ## Package Metadata
8
+
9
+ - Distribution name: `ponkan-python`
10
+ - Import package: `ponkan`
11
+ - Python support: `>=3.12`
12
+ - License expression: `MIT`
13
+ - License files: `LICENSE`, `NOTICE.md`
14
+ - Repository: `https://github.com/niart120/ponkan-python`
15
+ - Publish workflow: `.github/workflows/publish.yml`
16
+ - Build backend: Hatchling
17
+
18
+ ## Release Flow
19
+
20
+ Use this order for normal releases:
21
+
22
+ 1. Confirm the current branch and `git status --short --branch`.
23
+ 2. Fetch tags and inspect the commits since the latest `v*` tag.
24
+ 3. Choose the next version and release type.
25
+ 4. Prepare a `release/vX.Y.Z` branch with the version bump and release docs.
26
+ 5. Run the local release checks.
27
+ 6. Merge the release PR through the normal PR workflow.
28
+ 7. Sync the default branch locally.
29
+ 8. Create and push an annotated `vX.Y.Z` tag.
30
+ 9. Confirm the `Publish` workflow and PyPI version.
31
+ 10. Run version-pinned smoke checks.
32
+ 11. Create a GitHub Release or record the final release report.
33
+
34
+ ## Version Policy
35
+
36
+ | Change type | Default release type |
37
+ | ----------- | -------------------- |
38
+ | Documentation, metadata cleanup, bug fix, dependency metadata cleanup | patch |
39
+ | Backward-compatible public API or CLI addition | minor |
40
+ | Breaking import package, public API, CLI, or dependency surface change | major or explicit pre-1.0 version |
41
+
42
+ If a patch release contains a `feat` commit, document why the change is still a
43
+ patch. Stop and ask before publishing a `minor` or `patch` release that contains
44
+ `BREAKING CHANGE` or `!` commit markers.
45
+
46
+ ## Release Preflight
47
+
48
+ Before creating a release tag:
49
+
50
+ - Confirm `pyproject.toml`, `uv.lock`, and this file agree on the project name,
51
+ version, Python support, and optional extras.
52
+ - Confirm the candidate PyPI version is not already published by checking the
53
+ version-specific JSON endpoint:
54
+ `https://pypi.org/pypi/ponkan-python/X.Y.Z/json`.
55
+ - Confirm neither local nor remote already has the `vX.Y.Z` tag.
56
+ - Confirm `.github/workflows/publish.yml` still builds distributions once and
57
+ publishes the stored artifact through `pypa/gh-action-pypi-publish@release/v1`.
58
+
59
+ Run these checks before creating the release PR or tag:
60
+
61
+ ```console
62
+ uv sync --dev
63
+ uv lock --check
64
+ uv run ruff format --check .
65
+ uv run ruff check .
66
+ uv run ty check --no-progress
67
+ uv run pytest tests/unit
68
+ uv build
69
+ uvx --from twine twine check dist\*
70
+ git diff --check
71
+ ```
72
+
73
+ The build should create both an sdist and a wheel under `dist/`. Check the wheel
74
+ contains the import package and typing marker:
75
+
76
+ ```console
77
+ uv run python -c "import pathlib, zipfile; wheel=next(pathlib.Path('dist').glob('*.whl')); names=set(zipfile.ZipFile(wheel).namelist()); assert 'ponkan/__init__.py' in names; assert 'ponkan/py.typed' in names"
78
+ ```
79
+
80
+ ## TestPyPI
81
+
82
+ Create a Trusted Publisher for TestPyPI with:
83
+
84
+ | Field | Value |
85
+ | --- | --- |
86
+ | Project name | `ponkan-python` |
87
+ | Owner | `niart120` |
88
+ | Repository name | `ponkan-python` |
89
+ | Workflow filename | `publish.yml` |
90
+ | Environment name | `testpypi` |
91
+
92
+ Run the `Publish` workflow manually from GitHub Actions when a staging publish is
93
+ needed. The manual workflow path publishes only to TestPyPI.
94
+
95
+ TestPyPI is optional for low-risk patch releases, but should be considered for
96
+ new package metadata, new dependencies, or packaging workflow changes.
97
+
98
+ ## PyPI
99
+
100
+ Create or configure the PyPI project and Trusted Publisher with:
101
+
102
+ | Field | Value |
103
+ | --- | --- |
104
+ | Project name | `ponkan-python` |
105
+ | Owner | `niart120` |
106
+ | Repository name | `ponkan-python` |
107
+ | Workflow filename | `publish.yml` |
108
+ | Environment name | `pypi` |
109
+
110
+ The `pypi` GitHub environment should require manual approval before deployment.
111
+ After the release PR is merged and the default branch is synchronized locally,
112
+ create and push an annotated release tag:
113
+
114
+ ```console
115
+ git tag -a vX.Y.Z -m "vX.Y.Z"
116
+ git push origin vX.Y.Z
117
+ ```
118
+
119
+ The tag push starts the PyPI publish job. The workflow builds the distribution
120
+ once, stores it as a workflow artifact, and publishes the same artifact to PyPI.
121
+
122
+ ## Stop Conditions
123
+
124
+ Stop before tag push when any of these are true:
125
+
126
+ - `git status --short` is not clean.
127
+ - The default branch is not synchronized with `origin/<default>`.
128
+ - The candidate version already exists on PyPI.
129
+ - The candidate `vX.Y.Z` tag already exists locally or remotely.
130
+ - `pyproject.toml`, `uv.lock`, and publishing docs disagree.
131
+ - A local release check, PR check, or publish workflow job failed.
132
+ - Production publish was not explicitly requested or confirmed.
133
+ - Hardware smoke is required but human approval is missing.
134
+
135
+ If the publish job fails after build and metadata checks already passed, inspect
136
+ the failed step before changing package metadata. Transient attestation or
137
+ network failures, such as `requests.exceptions.ChunkedEncodingError`, are rerun
138
+ candidates.
139
+
140
+ ## Post-Publish Smoke Check
141
+
142
+ Verify the exact published version first:
143
+
144
+ ```text
145
+ https://pypi.org/pypi/ponkan-python/X.Y.Z/json
146
+ ```
147
+
148
+ Then run version-pinned installation checks in clean `uvx` environments:
149
+
150
+ ```console
151
+ uvx --from ponkan-python==X.Y.Z python -c "import importlib.metadata, ponkan; print(importlib.metadata.version('ponkan-python')); print(ponkan.__version__)"
152
+ uvx --from ponkan-python==X.Y.Z ponkan-list-devices
153
+ ```
154
+
155
+ For the `image` extra:
156
+
157
+ ```console
158
+ uvx --from "ponkan-python[image]==X.Y.Z" ponkan-raw-to-png --help
159
+ ```
160
+
161
+ On Windows, the D3XX backend dependency is installed through normal platform
162
+ metadata. Use `uvx --from ponkan-python==X.Y.Z ponkan-list-devices` for the D3XX
163
+ dependency smoke check.
164
+
165
+ Only run the OpenCV extra smoke when a release changes OpenCV-facing behavior or
166
+ metadata:
167
+
168
+ ```console
169
+ uvx --from "ponkan-python[opencv]==X.Y.Z" python -c "import cv2; print(cv2.__version__)"
170
+ ```
171
+
172
+ Do not rely on the generic latest PyPI JSON endpoint immediately after a fresh
173
+ publish; it can lag. Prefer the version-specific endpoint.
174
+
175
+ ## Release Report
176
+
177
+ After a successful publish, create a GitHub Release or record a final release
178
+ report with:
179
+
180
+ ```text
181
+ - version:
182
+ - release type:
183
+ - release branch / PR:
184
+ - tag:
185
+ - merge commit:
186
+ - PyPI URL:
187
+ - publish workflow run:
188
+ - local gates:
189
+ - post-publish smoke:
190
+ - GitHub Release:
191
+ - hardware: used | not used | not run with reason
192
+ - follow-up:
193
+ ```
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "ponkan-python"
3
- version = "0.1.0"
3
+ version = "0.1.2"
4
4
  description = "A Python capture library focused on new 3DS XL capture board frame acquisition."
5
5
  readme = { file = "README.md", content-type = "text/markdown" }
6
6
  authors = [
@@ -9,7 +9,7 @@ authors = [
9
9
  maintainers = [
10
10
  { name = "niart120", email = "38847256+niart120@users.noreply.github.com" }
11
11
  ]
12
- requires-python = ">=3.12, <3.14"
12
+ requires-python = ">=3.12"
13
13
  license = "MIT"
14
14
  license-files = ["LICENSE", "NOTICE.md"]
15
15
  keywords = [
@@ -34,6 +34,7 @@ classifiers = [
34
34
  dependencies = [
35
35
  "libusb1>=3.3.1",
36
36
  "numpy>=2.0",
37
+ "pyd3xx>=1.1.4; sys_platform == 'win32'",
37
38
  ]
38
39
 
39
40
  [project.optional-dependencies]
@@ -43,9 +44,6 @@ image = [
43
44
  opencv = [
44
45
  "opencv-python>=4.10",
45
46
  ]
46
- d3xx = [
47
- "pyd3xx>=1.1.4",
48
- ]
49
47
 
50
48
  [project.urls]
51
49
  Documentation = "https://github.com/niart120/ponkan-python/blob/master/docs/api.md"
@@ -54,10 +52,10 @@ Issues = "https://github.com/niart120/ponkan-python/issues"
54
52
  Repository = "https://github.com/niart120/ponkan-python.git"
55
53
 
56
54
  [project.scripts]
57
- py3dscapture-capture-raw = "py3dscapture.tools.capture_raw:main"
58
- py3dscapture-list-devices = "py3dscapture.tools.list_devices:main"
59
- py3dscapture-raw-to-png = "py3dscapture.tools.raw_to_png:main"
60
- py3dscapture-stream-n3dsxl = "py3dscapture.tools.stream_n3dsxl:main"
55
+ ponkan-capture-raw = "ponkan.tools.capture_raw:main"
56
+ ponkan-list-devices = "ponkan.tools.list_devices:main"
57
+ ponkan-raw-to-png = "ponkan.tools.raw_to_png:main"
58
+ ponkan-stream-n3dsxl = "ponkan.tools.stream_n3dsxl:main"
61
59
 
62
60
  [dependency-groups]
63
61
  dev = [
@@ -76,7 +74,7 @@ build-backend = "hatchling.build"
76
74
  cache-dir = ".uv-cache"
77
75
 
78
76
  [tool.hatch.build.targets.wheel]
79
- packages = ["src/py3dscapture"]
77
+ packages = ["src/ponkan"]
80
78
 
81
79
  [tool.hatch.build.targets.sdist]
82
80
  include = [
@@ -133,7 +131,7 @@ select = [
133
131
  ]
134
132
 
135
133
  [tool.ruff.lint.per-file-ignores]
136
- "src/py3dscapture/tools/**/*.py" = ["T201"]
134
+ "src/ponkan/tools/**/*.py" = ["T201"]
137
135
  "tests/**/*.py" = ["D100", "D103", "S101"]
138
136
 
139
137
  [tool.ruff.lint.pydocstyle]
@@ -143,7 +141,7 @@ convention = "google"
143
141
  strict = true
144
142
 
145
143
  [tool.ruff.lint.isort]
146
- known-first-party = ["py3dscapture"]
144
+ known-first-party = ["ponkan"]
147
145
 
148
146
  [tool.ty.environment]
149
147
  python-version = "3.12"
@@ -8,8 +8,8 @@ submodules.
8
8
 
9
9
  from importlib.metadata import PackageNotFoundError, version
10
10
 
11
- from py3dscapture.capture import CaptureConfig, CaptureOutput, CaptureReader, open_capture
12
- from py3dscapture.protocol.sizes import (
11
+ from ponkan.capture import CaptureConfig, CaptureOutput, CaptureReader, open_capture
12
+ from ponkan.protocol.sizes import (
13
13
  ACCEPTED_N3DSXL_PRODUCT_IDS,
14
14
  ACCEPTED_N3DSXL_PRODUCT_STRINGS,
15
15
  N3DSXL_VENDOR_ID,
@@ -8,20 +8,20 @@ from enum import StrEnum
8
8
  from pathlib import Path
9
9
  from typing import TYPE_CHECKING, Literal, Protocol, cast, overload
10
10
 
11
- from py3dscapture.errors import (
11
+ from ponkan.errors import (
12
12
  DecodeError,
13
13
  DeviceNotFound,
14
14
  TransferOverflow,
15
15
  UnsupportedOperation,
16
16
  )
17
- from py3dscapture.image.frame import CaptureFrame, ColorSpace, RGB8Array
18
- from py3dscapture.streaming.policies import DropPolicy
19
- from py3dscapture.streaming.stats import StreamStats
17
+ from ponkan.image.frame import CaptureFrame, ColorSpace, RGB8Array
18
+ from ponkan.streaming.policies import DropPolicy
19
+ from ponkan.streaming.stats import StreamStats
20
20
 
21
21
  if TYPE_CHECKING:
22
- from py3dscapture.protocol.n3dsxl import N3DSXLPipe, N3DSXLSessionIdentity
23
- from py3dscapture.transport.d3xx_streaming import D3xxStreamHandle
24
- from py3dscapture.transport.libusb_async import AsyncTransferBackend
22
+ from ponkan.protocol.n3dsxl import N3DSXLPipe, N3DSXLSessionIdentity
23
+ from ponkan.transport.d3xx_streaming import D3xxStreamHandle
24
+ from ponkan.transport.libusb_async import AsyncTransferBackend
25
25
 
26
26
  CaptureSource = int | str
27
27
  CaptureBackend = Literal["auto", "libusb", "d3xx", "d3xx-native"]
@@ -373,13 +373,13 @@ def _open_d3xx_engine(config: CaptureConfig, *, native: bool) -> CaptureReaderEn
373
373
 
374
374
 
375
375
  def _new_d3xx_backend() -> _D3xxBackend:
376
- from py3dscapture.transport.d3xx_backend import D3xxBackend # noqa: PLC0415
376
+ from ponkan.transport.d3xx_backend import D3xxBackend # noqa: PLC0415
377
377
 
378
378
  return D3xxBackend()
379
379
 
380
380
 
381
381
  def _new_n3dsxl_protocol(handle: _D3xxHandle) -> _N3DSXLConnectProtocol:
382
- from py3dscapture.protocol.n3dsxl import N3DSXLProtocol # noqa: PLC0415
382
+ from ponkan.protocol.n3dsxl import N3DSXLProtocol # noqa: PLC0415
383
383
 
384
384
  return N3DSXLProtocol(
385
385
  cast("N3DSXLSessionIdentity", handle),
@@ -388,13 +388,13 @@ def _new_n3dsxl_protocol(handle: _D3xxHandle) -> _N3DSXLConnectProtocol:
388
388
 
389
389
 
390
390
  def _new_d3xx_backend_async(handle: _D3xxHandle) -> object:
391
- from py3dscapture.transport.d3xx_streaming import D3xxAsyncBackend # noqa: PLC0415
391
+ from ponkan.transport.d3xx_streaming import D3xxAsyncBackend # noqa: PLC0415
392
392
 
393
393
  return D3xxAsyncBackend(cast("D3xxStreamHandle", handle))
394
394
 
395
395
 
396
396
  def _new_d3xx_native_backend(handle: _D3xxHandle, config: CaptureConfig) -> object:
397
- from py3dscapture.transport.d3xx_native_streaming import ( # noqa: PLC0415
397
+ from ponkan.transport.d3xx_native_streaming import ( # noqa: PLC0415
398
398
  D3xxNativeFastPathBackend,
399
399
  )
400
400
 
@@ -402,7 +402,7 @@ def _new_d3xx_native_backend(handle: _D3xxHandle, config: CaptureConfig) -> obje
402
402
 
403
403
 
404
404
  def _new_streaming_engine(async_backend: object, config: CaptureConfig) -> CaptureReaderEngine:
405
- from py3dscapture.streaming.engine import StreamingEngine # noqa: PLC0415
405
+ from ponkan.streaming.engine import StreamingEngine # noqa: PLC0415
406
406
 
407
407
  return StreamingEngine(
408
408
  cast("AsyncTransferBackend", async_backend),
@@ -4,8 +4,8 @@ from contextlib import suppress
4
4
  from dataclasses import dataclass
5
5
  from typing import Literal, cast
6
6
 
7
- from py3dscapture.errors import DeviceOpenError, UnsupportedDevice
8
- from py3dscapture.protocol.sizes import (
7
+ from ponkan.errors import DeviceOpenError, UnsupportedDevice
8
+ from ponkan.protocol.sizes import (
9
9
  ACCEPTED_N3DSXL_PRODUCT_IDS,
10
10
  ACCEPTED_N3DSXL_PRODUCT_STRINGS,
11
11
  N3DSXL_BULK_INTERFACE,
@@ -13,7 +13,7 @@ from py3dscapture.protocol.sizes import (
13
13
  N3DSXL_DEFAULT_CONFIGURATION,
14
14
  N3DSXL_VENDOR_ID,
15
15
  )
16
- from py3dscapture.transport.libusb_backend import LibusbBackend, UsbDeviceInfo, UsbHandle
16
+ from ponkan.transport.libusb_backend import LibusbBackend, UsbDeviceInfo, UsbHandle
17
17
 
18
18
  AcceptedProductString = Literal["N3DSXL", "N3DSXL.2"]
19
19
  ProductStringStatus = Literal["accepted", "unreadable"]
@@ -4,7 +4,7 @@ from dataclasses import dataclass
4
4
 
5
5
 
6
6
  class CaptureError(Exception):
7
- """Base exception for py3dscapture failures.
7
+ """Base exception for ponkan failures.
8
8
 
9
9
  Catch this when callers want to handle package-level failures without
10
10
  matching individual USB, decode, or optional-dependency errors.
@@ -103,11 +103,31 @@ class DecodeError(CaptureError):
103
103
  """
104
104
 
105
105
 
106
- class OptionalDependencyError(CaptureError):
107
- """Raised when an optional adapter dependency is missing.
106
+ class DependencyUnavailableError(CaptureError):
107
+ """Raised when a runtime dependency required by a selected path is missing.
108
108
 
109
- Optional extras currently include image conversion dependencies and the D3XX
110
- backend dependency.
109
+ This covers platform-gated normal dependencies as well as more specific
110
+ optional-extra dependencies.
111
+ """
112
+
113
+ @classmethod
114
+ def for_backend_dependency(
115
+ cls,
116
+ dependency: str,
117
+ backend: str,
118
+ ) -> "DependencyUnavailableError":
119
+ """Create an error for a dependency required by one backend."""
120
+ return cls(
121
+ f"{dependency} is required for the {backend} backend. "
122
+ "Install ponkan-python with dependencies for this platform, or select a "
123
+ "backend supported by this environment."
124
+ )
125
+
126
+
127
+ class OptionalDependencyError(DependencyUnavailableError):
128
+ """Raised when a dependency provided by an optional extra is missing.
129
+
130
+ Optional extras currently include image conversion dependencies.
111
131
  """
112
132
 
113
133
  def __init__(self, dependency: str, extra: str) -> None:
@@ -5,7 +5,7 @@ from collections.abc import Mapping
5
5
  from dataclasses import dataclass
6
6
  from typing import Literal
7
7
 
8
- from py3dscapture.protocol.sizes import (
8
+ from ponkan.protocol.sizes import (
9
9
  ACCEPTED_N3DSXL_PRODUCT_IDS,
10
10
  ACCEPTED_N3DSXL_PRODUCT_STRINGS,
11
11
  N3DSXL_VENDOR_ID,
@@ -7,8 +7,8 @@ from typing import TYPE_CHECKING, Literal, Protocol, cast
7
7
  import numpy as np
8
8
  from numpy.typing import NDArray
9
9
 
10
- from py3dscapture.errors import DecodeError, OptionalDependencyError
11
- from py3dscapture.protocol.sizes import BOTTOM_WIDTH_3DS, HEIGHT_3DS, TOP_WIDTH_3DS
10
+ from ponkan.errors import DecodeError, OptionalDependencyError
11
+ from ponkan.protocol.sizes import BOTTOM_WIDTH_3DS, HEIGHT_3DS, TOP_WIDTH_3DS
12
12
 
13
13
  ColorSpace = Literal["RGB", "BGR"]
14
14
  ScreenName = Literal["top", "bottom", "top_right"]