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.
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/PKG-INFO +5 -7
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/README.md +2 -3
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/docs/api.md +5 -5
- ponkan_python-0.1.2/docs/publishing.md +193 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/pyproject.toml +3 -5
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/errors.py +24 -4
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/transport/d3xx_backend.py +8 -8
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_d3xx_backend.py +7 -3
- ponkan_python-0.1.1/docs/publishing.md +0 -84
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/.gitignore +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/LICENSE +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/NOTICE.md +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/__init__.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/artifacts.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/capture.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/devices/__init__.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/devices/n3dsxl_ftd3.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/hardware_gate.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/image/__init__.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/image/frame.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/protocol/__init__.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/protocol/layout_3ds.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/protocol/n3dsxl.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/protocol/sizes.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/py.typed +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/streaming/__init__.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/streaming/buffers.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/streaming/engine.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/streaming/policies.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/streaming/stats.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/tools/__init__.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/tools/capture_raw.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/tools/list_devices.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/tools/raw_to_png.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/tools/stream_n3dsxl.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/transport/__init__.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/transport/d3xx_native.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/transport/d3xx_native_streaming.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/transport/d3xx_streaming.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/transport/ftd3_backend.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/transport/ftd3_pipe.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/transport/libusb_async.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/src/ponkan/transport/libusb_backend.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/conftest.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/e2e/README.md +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/e2e/test_n3dsxl_connect.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/e2e/test_n3dsxl_d3xx_backend.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/e2e/test_n3dsxl_d3xx_native_streaming.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/e2e/test_n3dsxl_ftd3_pipe.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/e2e/test_n3dsxl_high_level_capture_read_api.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/e2e/test_n3dsxl_open_close.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/e2e/test_n3dsxl_raw_capture.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/e2e/test_n3dsxl_streaming.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/manual/test_n3dsxl_decoder_visual.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/performance/README.md +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/performance/test_n3dsxl_d3xx_native_streaming_smoke.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/performance/test_n3dsxl_streaming_smoke.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_codex_pre_tool_use_policy.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_d3xx_native_api.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_d3xx_native_streaming_backend.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_d3xx_streaming_backend.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_ftd3_backend_selector.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_ftd3_pipe_payloads.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_hardware_gate.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_high_level_capture_read_api.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_layout_3ds_decoder.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_libusb_backend.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_n3dsxl_artifacts.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_n3dsxl_connect_sequence.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_n3dsxl_device_filter.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_n3dsxl_list_devices_cli.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_n3dsxl_session.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_n3dsxl_sizes.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_package.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_raw_capture_metadata.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_stream_n3dsxl_cli.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_streaming_buffers.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_streaming_engine_fake_async.py +0 -0
- {ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_streaming_performance_stats.py +0 -0
- {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.
|
|
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:
|
|
24
|
+
Requires-Python: >=3.12
|
|
25
25
|
Requires-Dist: libusb1>=3.3.1
|
|
26
26
|
Requires-Dist: numpy>=2.0
|
|
27
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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.
|
|
18
|
-
|
|
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
|
-
| `
|
|
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.
|
|
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
|
|
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
|
|
107
|
-
"""Raised when
|
|
106
|
+
class DependencyUnavailableError(CaptureError):
|
|
107
|
+
"""Raised when a runtime dependency required by a selected path is missing.
|
|
108
108
|
|
|
109
|
-
|
|
110
|
-
|
|
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,
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
513
|
+
installed dependency is imported lazily.
|
|
514
514
|
|
|
515
515
|
Raises:
|
|
516
|
-
|
|
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
|
|
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
|
|
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(
|
|
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
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
{ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/e2e/test_n3dsxl_high_level_capture_read_api.py
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
{ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/performance/test_n3dsxl_streaming_smoke.py
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
{ponkan_python-0.1.1 → ponkan_python-0.1.2}/tests/unit/test_d3xx_native_streaming_backend.py
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|