ponkan-python 0.1.1__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.1 → ponkan_python-0.1.2}/PKG-INFO +5 -7
  2. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/README.md +2 -3
  3. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/docs/api.md +5 -5
  4. ponkan_python-0.1.2/docs/publishing.md +193 -0
  5. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/pyproject.toml +3 -5
  6. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/errors.py +24 -4
  7. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/transport/d3xx_backend.py +8 -8
  8. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_d3xx_backend.py +7 -3
  9. ponkan_python-0.1.1/docs/publishing.md +0 -84
  10. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/.gitignore +0 -0
  11. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/LICENSE +0 -0
  12. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/NOTICE.md +0 -0
  13. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/__init__.py +0 -0
  14. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/artifacts.py +0 -0
  15. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/capture.py +0 -0
  16. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/devices/__init__.py +0 -0
  17. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/devices/n3dsxl_ftd3.py +0 -0
  18. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/hardware_gate.py +0 -0
  19. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/image/__init__.py +0 -0
  20. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/image/frame.py +0 -0
  21. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/protocol/__init__.py +0 -0
  22. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/protocol/layout_3ds.py +0 -0
  23. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/protocol/n3dsxl.py +0 -0
  24. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/protocol/sizes.py +0 -0
  25. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/py.typed +0 -0
  26. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/streaming/__init__.py +0 -0
  27. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/streaming/buffers.py +0 -0
  28. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/streaming/engine.py +0 -0
  29. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/streaming/policies.py +0 -0
  30. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/streaming/stats.py +0 -0
  31. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/tools/__init__.py +0 -0
  32. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/tools/capture_raw.py +0 -0
  33. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/tools/list_devices.py +0 -0
  34. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/tools/raw_to_png.py +0 -0
  35. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/tools/stream_n3dsxl.py +0 -0
  36. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/transport/__init__.py +0 -0
  37. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/transport/d3xx_native.py +0 -0
  38. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/transport/d3xx_native_streaming.py +0 -0
  39. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/transport/d3xx_streaming.py +0 -0
  40. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/transport/ftd3_backend.py +0 -0
  41. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/transport/ftd3_pipe.py +0 -0
  42. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/transport/libusb_async.py +0 -0
  43. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/transport/libusb_backend.py +0 -0
  44. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/conftest.py +0 -0
  45. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/e2e/README.md +0 -0
  46. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/e2e/test_n3dsxl_connect.py +0 -0
  47. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/e2e/test_n3dsxl_d3xx_backend.py +0 -0
  48. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/e2e/test_n3dsxl_d3xx_native_streaming.py +0 -0
  49. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/e2e/test_n3dsxl_ftd3_pipe.py +0 -0
  50. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/e2e/test_n3dsxl_high_level_capture_read_api.py +0 -0
  51. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/e2e/test_n3dsxl_open_close.py +0 -0
  52. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/e2e/test_n3dsxl_raw_capture.py +0 -0
  53. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/e2e/test_n3dsxl_streaming.py +0 -0
  54. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/manual/test_n3dsxl_decoder_visual.py +0 -0
  55. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/performance/README.md +0 -0
  56. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/performance/test_n3dsxl_d3xx_native_streaming_smoke.py +0 -0
  57. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/performance/test_n3dsxl_streaming_smoke.py +0 -0
  58. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_codex_pre_tool_use_policy.py +0 -0
  59. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_d3xx_native_api.py +0 -0
  60. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_d3xx_native_streaming_backend.py +0 -0
  61. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_d3xx_streaming_backend.py +0 -0
  62. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_ftd3_backend_selector.py +0 -0
  63. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_ftd3_pipe_payloads.py +0 -0
  64. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_hardware_gate.py +0 -0
  65. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_high_level_capture_read_api.py +0 -0
  66. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_layout_3ds_decoder.py +0 -0
  67. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_libusb_backend.py +0 -0
  68. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_n3dsxl_artifacts.py +0 -0
  69. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_n3dsxl_connect_sequence.py +0 -0
  70. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_n3dsxl_device_filter.py +0 -0
  71. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_n3dsxl_list_devices_cli.py +0 -0
  72. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_n3dsxl_session.py +0 -0
  73. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_n3dsxl_sizes.py +0 -0
  74. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_package.py +0 -0
  75. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_raw_capture_metadata.py +0 -0
  76. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_stream_n3dsxl_cli.py +0 -0
  77. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_streaming_buffers.py +0 -0
  78. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_streaming_engine_fake_async.py +0 -0
  79. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_streaming_performance_stats.py +0 -0
  80. {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_streaming_policies.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: ponkan-python
3
- Version: 0.1.1
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
@@ -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
@@ -5,17 +5,16 @@ 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
- `ponkan-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
 
@@ -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.1"
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"
@@ -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:
@@ -10,7 +10,7 @@ from types import ModuleType
10
10
  from typing import Any, Literal, Protocol, cast
11
11
 
12
12
  from ponkan.devices.n3dsxl_ftd3 import DeviceCandidate, classify_n3dsxl_device
13
- from ponkan.errors import CaptureError, OptionalDependencyError
13
+ from ponkan.errors import CaptureError, DependencyUnavailableError
14
14
  from ponkan.protocol.sizes import N3DSXL_VENDOR_ID
15
15
  from ponkan.transport.libusb_backend import UsbDeviceInfo
16
16
 
@@ -481,13 +481,13 @@ class D3xxHandle:
481
481
 
482
482
 
483
483
  def load_pyd3xx_binding() -> D3xxBinding:
484
- """Import the optional PyD3XX module.
484
+ """Import the PyD3XX module used by the Windows D3XX backend.
485
485
 
486
486
  Returns:
487
487
  Imported module cast to the D3XX binding protocol.
488
488
 
489
489
  Raises:
490
- OptionalDependencyError: Neither supported PyD3XX module name can be
490
+ DependencyUnavailableError: Neither supported PyD3XX module name can be
491
491
  imported.
492
492
  """
493
493
  for module_name in PYD3XX_MODULE_NAMES:
@@ -495,7 +495,7 @@ def load_pyd3xx_binding() -> D3xxBinding:
495
495
  return cast("D3xxBinding", import_module(module_name))
496
496
  except ImportError:
497
497
  continue
498
- raise OptionalDependencyError("PyD3XX", "d3xx")
498
+ raise DependencyUnavailableError.for_backend_dependency("PyD3XX", "Windows D3XX")
499
499
 
500
500
 
501
501
  class D3xxBackend:
@@ -506,15 +506,15 @@ class D3xxBackend:
506
506
  """
507
507
 
508
508
  def __init__(self, binding: D3xxBinding | None = None) -> None:
509
- """Create a backend using an injected or optional PyD3XX binding.
509
+ """Create a backend using an injected or installed PyD3XX binding.
510
510
 
511
511
  Args:
512
512
  binding: Optional test or real PyD3XX binding. When omitted, the
513
- optional dependency is imported lazily.
513
+ installed dependency is imported lazily.
514
514
 
515
515
  Raises:
516
- OptionalDependencyError: ``binding`` is omitted and PyD3XX is not
517
- installed.
516
+ DependencyUnavailableError: ``binding`` is omitted and PyD3XX is not
517
+ installed or not supported in the current environment.
518
518
  """
519
519
  self._binding = binding or load_pyd3xx_binding()
520
520
 
@@ -5,7 +5,7 @@ import pytest
5
5
 
6
6
  import ponkan.transport.d3xx_backend as d3xx_backend
7
7
  from ponkan.devices.n3dsxl_ftd3 import DeviceCandidate
8
- from ponkan.errors import OptionalDependencyError
8
+ from ponkan.errors import DependencyUnavailableError
9
9
  from ponkan.transport.d3xx_backend import D3xxBackend
10
10
 
11
11
 
@@ -222,7 +222,7 @@ def test_d3xx_stream_pipe_read_uses_native_stream_read_api() -> None:
222
222
  assert read_data == b"stream"
223
223
 
224
224
 
225
- def test_pyd3xx_binding_missing_reports_optional_dependency(
225
+ def test_pyd3xx_binding_missing_reports_dependency_unavailable(
226
226
  monkeypatch: pytest.MonkeyPatch,
227
227
  ) -> None:
228
228
  def missing_module(module_name: str) -> object:
@@ -231,5 +231,9 @@ def test_pyd3xx_binding_missing_reports_optional_dependency(
231
231
 
232
232
  monkeypatch.setattr(d3xx_backend, "import_module", missing_module)
233
233
 
234
- with pytest.raises(OptionalDependencyError):
234
+ with pytest.raises(DependencyUnavailableError) as exc_info:
235
235
  d3xx_backend.load_pyd3xx_binding()
236
+
237
+ message = str(exc_info.value)
238
+ assert "PyD3XX is required for the Windows D3XX backend" in message
239
+ assert "d3xx extra" not in message
@@ -1,84 +0,0 @@
1
- # Publishing
2
-
3
- This project is prepared for PyPI publication with local builds and GitHub
4
- Actions Trusted Publishing. No PyPI API token is required when the PyPI project
5
- has a matching trusted publisher.
6
-
7
- ## Package Metadata
8
-
9
- - Distribution name: `ponkan-python`
10
- - Import package: `ponkan`
11
- - Python support: `>=3.12, <3.14`
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
-
17
- ## Local Release Check
18
-
19
- Run these checks before creating a release tag:
20
-
21
- ```console
22
- uv sync --dev
23
- uv run ruff format --check .
24
- uv run ruff check .
25
- uv run ty check --no-progress
26
- uv run pytest tests/unit
27
- uv build
28
- ```
29
-
30
- The build should create both an sdist and wheel under `dist/`.
31
-
32
- ## TestPyPI
33
-
34
- Create a Trusted Publisher for TestPyPI with:
35
-
36
- | Field | Value |
37
- | --- | --- |
38
- | Project name | `ponkan-python` |
39
- | Owner | `niart120` |
40
- | Repository name | `ponkan-python` |
41
- | Workflow filename | `publish.yml` |
42
- | Environment name | `testpypi` |
43
-
44
- Then run the `Publish` workflow manually from GitHub Actions. The manual
45
- workflow path publishes only to TestPyPI.
46
-
47
- ## PyPI
48
-
49
- Create or configure the PyPI project and Trusted Publisher with:
50
-
51
- | Field | Value |
52
- | --- | --- |
53
- | Project name | `ponkan-python` |
54
- | Owner | `niart120` |
55
- | Repository name | `ponkan-python` |
56
- | Workflow filename | `publish.yml` |
57
- | Environment name | `pypi` |
58
-
59
- The `pypi` GitHub environment should require manual approval before deployment.
60
- After the project and trusted publisher are ready, pushing a version tag starts
61
- the PyPI publish job:
62
-
63
- ```console
64
- git tag v0.1.1
65
- git push origin v0.1.1
66
- ```
67
-
68
- The workflow builds the distribution once, stores it as a workflow artifact, and
69
- publishes the same artifact to the selected package index.
70
-
71
- ## Post-Publish Smoke Check
72
-
73
- After upload, verify installation in a clean environment:
74
-
75
- ```console
76
- uvx --from ponkan-python ponkan-list-devices
77
- ```
78
-
79
- For optional features:
80
-
81
- ```console
82
- uvx --from "ponkan-python[image]" ponkan-raw-to-png --help
83
- uvx --from "ponkan-python[d3xx]" ponkan-list-devices
84
- ```
File without changes
File without changes
File without changes