ponkan-python 0.1.1__py3-none-any.whl → 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
ponkan/__init__.py CHANGED
@@ -1,14 +1,33 @@
1
1
  """Python helpers for new 3DS XL capture board frame acquisition.
2
2
 
3
- The package exposes the constants and size helpers needed to identify supported
4
- N3DSXL capture boards and to reason about raw USB frame sizes. Higher-level
5
- capture, decode, transport, and streaming APIs live in their dedicated
6
- submodules.
3
+ The package root exposes the high-level reader, supported profile/layout
4
+ metadata, safe device discovery helpers, and size constants needed by typical
5
+ callers. Lower-level decode, transport, and streaming APIs live in their
6
+ dedicated submodules.
7
7
  """
8
8
 
9
9
  from importlib.metadata import PackageNotFoundError, version
10
10
 
11
11
  from ponkan.capture import CaptureConfig, CaptureOutput, CaptureReader, open_capture
12
+ from ponkan.devices.discovery import (
13
+ CaptureDeviceDiscovery,
14
+ CaptureDeviceInfo,
15
+ list_capture_devices,
16
+ )
17
+ from ponkan.layouts import (
18
+ CaptureLayout,
19
+ CompositeOutputInfo,
20
+ ScreenInfo,
21
+ UnknownCaptureLayout,
22
+ get_capture_layout,
23
+ list_capture_layouts,
24
+ )
25
+ from ponkan.profiles import (
26
+ CaptureProfile,
27
+ UnknownCaptureProfile,
28
+ get_capture_profile,
29
+ list_capture_profiles,
30
+ )
12
31
  from ponkan.protocol.sizes import (
13
32
  ACCEPTED_N3DSXL_PRODUCT_IDS,
14
33
  ACCEPTED_N3DSXL_PRODUCT_STRINGS,
@@ -27,10 +46,23 @@ __all__ = [
27
46
  "ACCEPTED_N3DSXL_PRODUCT_STRINGS",
28
47
  "N3DSXL_VENDOR_ID",
29
48
  "CaptureConfig",
49
+ "CaptureDeviceDiscovery",
50
+ "CaptureDeviceInfo",
51
+ "CaptureLayout",
30
52
  "CaptureOutput",
53
+ "CaptureProfile",
31
54
  "CaptureReader",
32
55
  "CaptureSizes",
56
+ "CompositeOutputInfo",
57
+ "ScreenInfo",
58
+ "UnknownCaptureLayout",
59
+ "UnknownCaptureProfile",
33
60
  "__version__",
34
61
  "capture_sizes",
62
+ "get_capture_layout",
63
+ "get_capture_profile",
64
+ "list_capture_devices",
65
+ "list_capture_layouts",
66
+ "list_capture_profiles",
35
67
  "open_capture",
36
68
  ]
ponkan/capture.py CHANGED
@@ -8,6 +8,7 @@ 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 ponkan.devices.discovery import resolve_backend_preference
11
12
  from ponkan.errors import (
12
13
  DecodeError,
13
14
  DeviceNotFound,
@@ -15,6 +16,7 @@ from ponkan.errors import (
15
16
  UnsupportedOperation,
16
17
  )
17
18
  from ponkan.image.frame import CaptureFrame, ColorSpace, RGB8Array
19
+ from ponkan.layouts import get_capture_layout
18
20
  from ponkan.streaming.policies import DropPolicy
19
21
  from ponkan.streaming.stats import StreamStats
20
22
 
@@ -37,6 +39,7 @@ _OUTPUT_QUEUE_SIZE_CONFIG_ERROR = "output_queue_size must be positive"
37
39
  _POLL_INTERVAL_CONFIG_ERROR = "poll_interval must be positive"
38
40
  _RAW_SLOTS_CONFIG_ERROR = "raw_slots must be positive"
39
41
  _READ_TIMEOUT_CONFIG_ERROR = "read_timeout must be non-negative or None"
42
+ _N3DSXL_LAYOUT_ID = "3ds_dual_screen"
40
43
 
41
44
 
42
45
  class _ReadTimeoutUnset:
@@ -336,9 +339,11 @@ def _validate_config(config: CaptureConfig) -> None:
336
339
 
337
340
 
338
341
  def _coerce_output(output: CaptureOutput | str) -> CaptureOutput:
339
- if isinstance(output, CaptureOutput):
340
- return output
341
- return CaptureOutput(output)
342
+ selected = output if isinstance(output, CaptureOutput) else CaptureOutput(output)
343
+ supported_outputs = {item.id for item in get_capture_layout(_N3DSXL_LAYOUT_ID).outputs}
344
+ if selected.value not in supported_outputs:
345
+ raise ValueError
346
+ return selected
342
347
 
343
348
 
344
349
  def _validate_colorspace(colorspace: str) -> None:
@@ -347,17 +352,27 @@ def _validate_colorspace(colorspace: str) -> None:
347
352
 
348
353
 
349
354
  def _open_hardware_engine(config: CaptureConfig) -> CaptureReaderEngine:
350
- if config.backend == "libusb":
351
- raise UnsupportedOperation
352
- native = config.backend == "d3xx-native"
353
- return _open_d3xx_engine(config, native=native)
355
+ resolved_backend = resolve_backend_preference(config.backend)
356
+ if resolved_backend == "libusb":
357
+ raise UnsupportedOperation(
358
+ profile="n3dsxl",
359
+ backend=resolved_backend,
360
+ reason="unsupported_backend",
361
+ )
362
+ native = resolved_backend == "d3xx-native"
363
+ return _open_d3xx_engine(config, native=native, resolved_backend=resolved_backend)
354
364
 
355
365
 
356
- def _open_d3xx_engine(config: CaptureConfig, *, native: bool) -> CaptureReaderEngine:
366
+ def _open_d3xx_engine(
367
+ config: CaptureConfig,
368
+ *,
369
+ native: bool,
370
+ resolved_backend: str,
371
+ ) -> CaptureReaderEngine:
357
372
  backend = _new_d3xx_backend()
358
373
  candidates = backend.iter_device_candidates()
359
374
  if not candidates:
360
- raise DeviceNotFound
375
+ raise DeviceNotFound(profile="n3dsxl", backend=resolved_backend)
361
376
  d3xx_candidate = candidates[0]
362
377
  handle = backend.open(d3xx_candidate)
363
378
  try:
@@ -0,0 +1,397 @@
1
+ """Public capture device discovery model."""
2
+
3
+ import sys
4
+ from dataclasses import dataclass
5
+ from typing import TYPE_CHECKING, Literal, Protocol, cast
6
+
7
+ from ponkan.errors import CaptureReason, DependencyUnavailableError
8
+ from ponkan.profiles import UnknownCaptureProfile, get_capture_profile
9
+
10
+ if TYPE_CHECKING:
11
+ from ponkan.transport.libusb_backend import LibusbBackend, UsbDeviceInfo
12
+
13
+ BackendPreference = Literal["auto", "d3xx", "d3xx-native", "libusb"]
14
+ BackendStatus = Literal["available", "unavailable", "unsupported"]
15
+ ConnectionStatus = Literal["available", "rejected", "unsupported", "unknown"]
16
+ IdStability = Literal["stable", "session", "unknown"]
17
+ ProductStringStatus = Literal["accepted", "unreadable", "rejected", "unknown"]
18
+
19
+ _VALID_BACKENDS = frozenset(("auto", "d3xx", "d3xx-native", "libusb"))
20
+
21
+
22
+ class _LibusbDiscoveryBackend(Protocol):
23
+ def iter_devices(self) -> tuple["_UsbInfo", ...]:
24
+ """Return descriptor-like USB device records without opening them."""
25
+ ...
26
+
27
+
28
+ class _D3xxDiscoveryBackend(Protocol):
29
+ def iter_devices(self) -> tuple[object, ...]:
30
+ """Return D3XX descriptor-like device records without opening them."""
31
+ ...
32
+
33
+
34
+ class _UsbInfo(Protocol):
35
+ bus_number: int | None
36
+ address: int | None
37
+ vendor_id: int | None
38
+ product_id: int | None
39
+ product_string: str | None
40
+ serial_number: str | None
41
+
42
+
43
+ class _CandidateInfo(Protocol):
44
+ info: _UsbInfo
45
+ product_string: str | None
46
+ product_string_status: ProductStringStatus
47
+ model: str
48
+
49
+
50
+ class _RejectedInfo(Protocol):
51
+ info: _UsbInfo
52
+ reason: str
53
+
54
+
55
+ class _D3xxDeviceInfo(Protocol):
56
+ usb_info: _UsbInfo
57
+
58
+
59
+ @dataclass(frozen=True, slots=True)
60
+ class CaptureDeviceInfo:
61
+ """Public descriptor and classification state for one visible device."""
62
+
63
+ id: str
64
+ display_name: str
65
+ profile_id: str
66
+ model: str
67
+ backend: str
68
+ backend_preference: BackendPreference
69
+ vendor_id: int | None
70
+ product_id: int | None
71
+ serial_number: str | None
72
+ product_string: str | None
73
+ product_string_status: ProductStringStatus
74
+ connection_status: ConnectionStatus
75
+ id_stability: IdStability
76
+ reason: CaptureReason = "available"
77
+ remediation: str | None = None
78
+
79
+
80
+ @dataclass(frozen=True, slots=True)
81
+ class CaptureDeviceDiscovery:
82
+ """Public discovery result for one profile/backend request."""
83
+
84
+ profile_id: str
85
+ backend_preference: BackendPreference
86
+ resolved_backend: str
87
+ backend_status: BackendStatus
88
+ reason: CaptureReason = "available"
89
+ remediation: str | None = None
90
+ devices: tuple[CaptureDeviceInfo, ...] = ()
91
+
92
+
93
+ def resolve_backend_preference(
94
+ backend: BackendPreference,
95
+ *,
96
+ sys_platform: str | None = None,
97
+ ) -> str:
98
+ """Resolve the concrete backend used by discovery and high-level open."""
99
+ if backend != "auto":
100
+ return backend
101
+ platform = sys.platform if sys_platform is None else sys_platform
102
+ if platform == "win32":
103
+ return "d3xx-native"
104
+ return "d3xx"
105
+
106
+
107
+ def list_capture_devices(
108
+ *,
109
+ profile: str = "n3dsxl",
110
+ backend: BackendPreference | str = "auto",
111
+ include_rejected: bool = False,
112
+ _libusb_backend: object | None = None,
113
+ _d3xx_backend: object | None = None,
114
+ _sys_platform: str | None = None,
115
+ ) -> CaptureDeviceDiscovery:
116
+ """Return structured capture device discovery state without opening devices."""
117
+ backend_preference = cast("BackendPreference", backend)
118
+ if backend not in _VALID_BACKENDS:
119
+ return CaptureDeviceDiscovery(
120
+ profile_id=profile,
121
+ backend_preference=backend_preference,
122
+ resolved_backend=str(backend),
123
+ backend_status="unsupported",
124
+ reason="unsupported_backend",
125
+ )
126
+ try:
127
+ profile_metadata = get_capture_profile(profile)
128
+ except UnknownCaptureProfile:
129
+ return CaptureDeviceDiscovery(
130
+ profile_id=profile,
131
+ backend_preference=backend_preference,
132
+ resolved_backend=resolve_backend_preference(
133
+ backend_preference,
134
+ sys_platform=_sys_platform,
135
+ ),
136
+ backend_status="unsupported",
137
+ reason="unsupported_profile",
138
+ )
139
+
140
+ resolved_backend = resolve_backend_preference(
141
+ backend_preference,
142
+ sys_platform=_sys_platform,
143
+ )
144
+ if profile_metadata.id != "n3dsxl":
145
+ return CaptureDeviceDiscovery(
146
+ profile_id=profile_metadata.id,
147
+ backend_preference=backend_preference,
148
+ resolved_backend=resolved_backend,
149
+ backend_status="unsupported",
150
+ reason="unsupported_profile",
151
+ )
152
+ if resolved_backend == "libusb":
153
+ return _discover_libusb(
154
+ profile_id=profile_metadata.id,
155
+ backend_preference=backend_preference,
156
+ resolved_backend=resolved_backend,
157
+ include_rejected=include_rejected,
158
+ backend=_libusb_backend,
159
+ )
160
+ if resolved_backend in ("d3xx", "d3xx-native"):
161
+ return _discover_d3xx(
162
+ profile_id=profile_metadata.id,
163
+ backend_preference=backend_preference,
164
+ resolved_backend=resolved_backend,
165
+ include_rejected=include_rejected,
166
+ backend=_d3xx_backend,
167
+ )
168
+ return CaptureDeviceDiscovery(
169
+ profile_id=profile_metadata.id,
170
+ backend_preference=backend_preference,
171
+ resolved_backend=resolved_backend,
172
+ backend_status="unsupported",
173
+ reason="unsupported_backend",
174
+ )
175
+
176
+
177
+ def _discover_libusb(
178
+ *,
179
+ profile_id: str,
180
+ backend_preference: BackendPreference,
181
+ resolved_backend: str,
182
+ include_rejected: bool,
183
+ backend: object | None,
184
+ ) -> CaptureDeviceDiscovery:
185
+ from ponkan.devices.n3dsxl_ftd3 import ( # noqa: PLC0415
186
+ DeviceCandidate,
187
+ RejectedDevice,
188
+ list_n3dsxl_devices,
189
+ )
190
+
191
+ actual_backend = _new_libusb_backend() if backend is None else backend
192
+ listing = list_n3dsxl_devices(cast("LibusbBackend", actual_backend))
193
+ devices: list[CaptureDeviceInfo] = [
194
+ _info_from_candidate(
195
+ cast("_CandidateInfo", candidate),
196
+ profile_id=profile_id,
197
+ backend_preference=backend_preference,
198
+ resolved_backend=resolved_backend,
199
+ )
200
+ for candidate in listing.candidates
201
+ if isinstance(candidate, DeviceCandidate)
202
+ ]
203
+ if include_rejected:
204
+ devices.extend(
205
+ _info_from_rejected(
206
+ cast("_RejectedInfo", rejected),
207
+ profile_id=profile_id,
208
+ backend_preference=backend_preference,
209
+ resolved_backend=resolved_backend,
210
+ )
211
+ for rejected in listing.rejected
212
+ if isinstance(rejected, RejectedDevice)
213
+ )
214
+ return _available_result(
215
+ profile_id=profile_id,
216
+ backend_preference=backend_preference,
217
+ resolved_backend=resolved_backend,
218
+ devices=tuple(devices),
219
+ accepted_count=len(listing.candidates),
220
+ )
221
+
222
+
223
+ def _discover_d3xx(
224
+ *,
225
+ profile_id: str,
226
+ backend_preference: BackendPreference,
227
+ resolved_backend: str,
228
+ include_rejected: bool,
229
+ backend: object | None,
230
+ ) -> CaptureDeviceDiscovery:
231
+ from ponkan.devices.n3dsxl_ftd3 import ( # noqa: PLC0415
232
+ DeviceCandidate,
233
+ RejectedDevice,
234
+ classify_n3dsxl_device,
235
+ )
236
+
237
+ try:
238
+ actual_backend = cast(
239
+ "_D3xxDiscoveryBackend",
240
+ _new_d3xx_backend() if backend is None else backend,
241
+ )
242
+ d3xx_devices = actual_backend.iter_devices()
243
+ except DependencyUnavailableError as exc:
244
+ return CaptureDeviceDiscovery(
245
+ profile_id=profile_id,
246
+ backend_preference=backend_preference,
247
+ resolved_backend=resolved_backend,
248
+ backend_status="unavailable",
249
+ reason=exc.reason or "unknown",
250
+ remediation=exc.remediation,
251
+ )
252
+
253
+ devices: list[CaptureDeviceInfo] = []
254
+ accepted_count = 0
255
+ for d3xx_device in d3xx_devices:
256
+ usb_info = cast("_D3xxDeviceInfo", d3xx_device).usb_info
257
+ classified = classify_n3dsxl_device(cast("UsbDeviceInfo", usb_info))
258
+ if isinstance(classified, DeviceCandidate):
259
+ accepted_count += 1
260
+ devices.append(
261
+ _info_from_candidate(
262
+ cast("_CandidateInfo", classified),
263
+ profile_id=profile_id,
264
+ backend_preference=backend_preference,
265
+ resolved_backend=resolved_backend,
266
+ )
267
+ )
268
+ elif include_rejected and isinstance(classified, RejectedDevice):
269
+ devices.append(
270
+ _info_from_rejected(
271
+ cast("_RejectedInfo", classified),
272
+ profile_id=profile_id,
273
+ backend_preference=backend_preference,
274
+ resolved_backend=resolved_backend,
275
+ )
276
+ )
277
+ return _available_result(
278
+ profile_id=profile_id,
279
+ backend_preference=backend_preference,
280
+ resolved_backend=resolved_backend,
281
+ devices=tuple(devices),
282
+ accepted_count=accepted_count,
283
+ )
284
+
285
+
286
+ def _available_result(
287
+ *,
288
+ profile_id: str,
289
+ backend_preference: BackendPreference,
290
+ resolved_backend: str,
291
+ devices: tuple[CaptureDeviceInfo, ...],
292
+ accepted_count: int,
293
+ ) -> CaptureDeviceDiscovery:
294
+ reason: CaptureReason = "available" if accepted_count else "device_not_found"
295
+ return CaptureDeviceDiscovery(
296
+ profile_id=profile_id,
297
+ backend_preference=backend_preference,
298
+ resolved_backend=resolved_backend,
299
+ backend_status="available",
300
+ reason=reason,
301
+ devices=devices,
302
+ )
303
+
304
+
305
+ def _info_from_candidate(
306
+ candidate: _CandidateInfo,
307
+ *,
308
+ profile_id: str,
309
+ backend_preference: BackendPreference,
310
+ resolved_backend: str,
311
+ ) -> CaptureDeviceInfo:
312
+ info = candidate.info
313
+ return CaptureDeviceInfo(
314
+ id=_device_id(resolved_backend, info),
315
+ display_name=candidate.product_string or "new 3DS XL",
316
+ profile_id=profile_id,
317
+ model=candidate.model,
318
+ backend=resolved_backend,
319
+ backend_preference=backend_preference,
320
+ vendor_id=info.vendor_id,
321
+ product_id=info.product_id,
322
+ serial_number=info.serial_number,
323
+ product_string=candidate.product_string,
324
+ product_string_status=candidate.product_string_status,
325
+ connection_status="available",
326
+ id_stability=_id_stability(info),
327
+ )
328
+
329
+
330
+ def _info_from_rejected(
331
+ rejected: _RejectedInfo,
332
+ *,
333
+ profile_id: str,
334
+ backend_preference: BackendPreference,
335
+ resolved_backend: str,
336
+ ) -> CaptureDeviceInfo:
337
+ info = rejected.info
338
+ return CaptureDeviceInfo(
339
+ id=_device_id(resolved_backend, info),
340
+ display_name=info.product_string or "Rejected FTDI device",
341
+ profile_id=profile_id,
342
+ model="unknown",
343
+ backend=resolved_backend,
344
+ backend_preference=backend_preference,
345
+ vendor_id=info.vendor_id,
346
+ product_id=info.product_id,
347
+ serial_number=info.serial_number,
348
+ product_string=info.product_string,
349
+ product_string_status="rejected" if info.product_string else "unknown",
350
+ connection_status="rejected",
351
+ id_stability=_id_stability(info),
352
+ reason="device_rejected",
353
+ remediation=rejected.reason,
354
+ )
355
+
356
+
357
+ def _device_id(backend: str, info: _UsbInfo) -> str:
358
+ if info.serial_number:
359
+ return f"{backend}:{info.serial_number}"
360
+ if info.bus_number is not None and info.address is not None:
361
+ return f"{backend}:bus{info.bus_number}:address{info.address}"
362
+ if info.vendor_id is not None and info.product_id is not None:
363
+ return f"{backend}:vid{info.vendor_id:04x}:pid{info.product_id:04x}"
364
+ return f"{backend}:unknown"
365
+
366
+
367
+ def _id_stability(info: _UsbInfo) -> IdStability:
368
+ if info.serial_number:
369
+ return "stable"
370
+ if info.bus_number is not None and info.address is not None:
371
+ return "session"
372
+ return "unknown"
373
+
374
+
375
+ def _new_libusb_backend() -> object:
376
+ from ponkan.transport.libusb_backend import Usb1Backend # noqa: PLC0415
377
+
378
+ return Usb1Backend()
379
+
380
+
381
+ def _new_d3xx_backend() -> _D3xxDiscoveryBackend:
382
+ from ponkan.transport.d3xx_backend import D3xxBackend # noqa: PLC0415
383
+
384
+ return D3xxBackend()
385
+
386
+
387
+ __all__ = [
388
+ "BackendPreference",
389
+ "BackendStatus",
390
+ "CaptureDeviceDiscovery",
391
+ "CaptureDeviceInfo",
392
+ "ConnectionStatus",
393
+ "IdStability",
394
+ "ProductStringStatus",
395
+ "list_capture_devices",
396
+ "resolve_backend_preference",
397
+ ]
@@ -162,7 +162,7 @@ class N3DSXLDevice:
162
162
  final close fails through the backend.
163
163
  """
164
164
  if not isinstance(candidate, DeviceCandidate):
165
- raise UnsupportedDevice
165
+ raise UnsupportedDevice(profile="n3dsxl")
166
166
  handle = backend.open(candidate.info)
167
167
  claimed_interfaces: list[int] = []
168
168
  try: