ponkan-python 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. ponkan_python-0.1.0.dist-info/METADATA +157 -0
  2. ponkan_python-0.1.0.dist-info/RECORD +39 -0
  3. ponkan_python-0.1.0.dist-info/WHEEL +4 -0
  4. ponkan_python-0.1.0.dist-info/entry_points.txt +5 -0
  5. ponkan_python-0.1.0.dist-info/licenses/LICENSE +22 -0
  6. ponkan_python-0.1.0.dist-info/licenses/NOTICE.md +14 -0
  7. py3dscapture/__init__.py +36 -0
  8. py3dscapture/artifacts.py +66 -0
  9. py3dscapture/capture.py +599 -0
  10. py3dscapture/devices/__init__.py +1 -0
  11. py3dscapture/devices/n3dsxl_ftd3.py +238 -0
  12. py3dscapture/errors.py +120 -0
  13. py3dscapture/hardware_gate.py +143 -0
  14. py3dscapture/image/__init__.py +1 -0
  15. py3dscapture/image/frame.py +166 -0
  16. py3dscapture/protocol/__init__.py +1 -0
  17. py3dscapture/protocol/layout_3ds.py +60 -0
  18. py3dscapture/protocol/n3dsxl.py +249 -0
  19. py3dscapture/protocol/sizes.py +128 -0
  20. py3dscapture/py.typed +1 -0
  21. py3dscapture/streaming/__init__.py +1 -0
  22. py3dscapture/streaming/buffers.py +156 -0
  23. py3dscapture/streaming/engine.py +285 -0
  24. py3dscapture/streaming/policies.py +157 -0
  25. py3dscapture/streaming/stats.py +254 -0
  26. py3dscapture/tools/__init__.py +1 -0
  27. py3dscapture/tools/capture_raw.py +44 -0
  28. py3dscapture/tools/list_devices.py +68 -0
  29. py3dscapture/tools/raw_to_png.py +251 -0
  30. py3dscapture/tools/stream_n3dsxl.py +152 -0
  31. py3dscapture/transport/__init__.py +1 -0
  32. py3dscapture/transport/d3xx_backend.py +850 -0
  33. py3dscapture/transport/d3xx_native.py +268 -0
  34. py3dscapture/transport/d3xx_native_streaming.py +306 -0
  35. py3dscapture/transport/d3xx_streaming.py +202 -0
  36. py3dscapture/transport/ftd3_backend.py +275 -0
  37. py3dscapture/transport/ftd3_pipe.py +387 -0
  38. py3dscapture/transport/libusb_async.py +134 -0
  39. py3dscapture/transport/libusb_backend.py +357 -0
@@ -0,0 +1,850 @@
1
+ # ruff: noqa: N802
2
+ """Optional FTDI D3XX backend boundary."""
3
+
4
+ import ctypes
5
+ from collections.abc import Iterator, Mapping
6
+ from contextlib import contextmanager
7
+ from dataclasses import dataclass
8
+ from importlib import import_module
9
+ from types import ModuleType
10
+ from typing import Any, Literal, Protocol, cast
11
+
12
+ from py3dscapture.devices.n3dsxl_ftd3 import DeviceCandidate, classify_n3dsxl_device
13
+ from py3dscapture.errors import CaptureError, OptionalDependencyError
14
+ from py3dscapture.protocol.sizes import N3DSXL_VENDOR_ID
15
+ from py3dscapture.transport.libusb_backend import UsbDeviceInfo
16
+
17
+ FT_OK = 0
18
+ D3XX_OPEN_BY_SERIAL_NUMBER = 0x01
19
+ D3XX_OPEN_BY_INDEX = 0x10
20
+ D3XX_DEFAULT_TIMEOUT_MS = 500
21
+ PYD3XX_MODULE_NAMES = ("PyD3XX", "pyd3xx")
22
+
23
+
24
+ class D3xxBinding(Protocol):
25
+ """Subset of the PyD3XX module needed for device enumeration and I/O.
26
+
27
+ The real package exposes module-level functions and factory classes. This
28
+ protocol describes only the calls used by ``D3xxBackend`` and ``D3xxHandle``.
29
+ """
30
+
31
+ FT_Pipe: Any
32
+ FT_Buffer: Any
33
+
34
+ def FT_CreateDeviceInfoList(self) -> tuple[int, int]:
35
+ """Return D3XX status and number of devices.
36
+
37
+ Returns:
38
+ ``(status, count)`` where status must be ``FT_OK``.
39
+ """
40
+ ...
41
+
42
+ def FT_GetDeviceInfoDetail(self, index: int) -> tuple[int, object]:
43
+ """Return D3XX status and one device information node.
44
+
45
+ Args:
46
+ index: Zero-based device index in the current D3XX device list.
47
+
48
+ Returns:
49
+ ``(status, detail)`` where detail contains ID, description,
50
+ serial-number, and flag fields.
51
+ """
52
+ ...
53
+
54
+ def FT_Create(self, identifier: object, open_flag: int, device: object) -> int:
55
+ """Open a D3XX device into an initialized FT_Device object.
56
+
57
+ Args:
58
+ identifier: Serial number or index used by the selected open flag.
59
+ open_flag: D3XX open mode such as serial-number or index.
60
+ device: Device detail object to initialize.
61
+
62
+ Returns:
63
+ D3XX status code.
64
+ """
65
+ ...
66
+
67
+ def FT_Close(self, device: object) -> int:
68
+ """Close an opened D3XX device object.
69
+
70
+ Args:
71
+ device: Open D3XX device object.
72
+
73
+ Returns:
74
+ D3XX status code.
75
+ """
76
+ ...
77
+
78
+ def FT_AbortPipe(self, device: object, pipe: object) -> int:
79
+ """Abort one D3XX native pipe.
80
+
81
+ Args:
82
+ device: Open D3XX device object.
83
+ pipe: D3XX pipe object with the selected pipe ID.
84
+
85
+ Returns:
86
+ D3XX status code.
87
+ """
88
+ ...
89
+
90
+ def FT_SetStreamPipe(
91
+ self,
92
+ device: object,
93
+ all_write_pipes: bool,
94
+ all_read_pipes: bool,
95
+ pipe: object,
96
+ stream_size: int,
97
+ ) -> int:
98
+ """Configure streaming for one D3XX native pipe.
99
+
100
+ Args:
101
+ device: Open D3XX device object.
102
+ all_write_pipes: Whether all write pipes should be affected.
103
+ all_read_pipes: Whether all read pipes should be affected.
104
+ pipe: D3XX pipe object with the selected pipe ID.
105
+ stream_size: Stream transfer size in bytes.
106
+
107
+ Returns:
108
+ D3XX status code.
109
+ """
110
+ ...
111
+
112
+ def FT_ReadPipe(
113
+ self,
114
+ device: object,
115
+ pipe: object,
116
+ buffer_length: int,
117
+ overlapped_timeout_ms: int,
118
+ ) -> tuple[int, object, int]:
119
+ """Read bytes from one D3XX native pipe.
120
+
121
+ Args:
122
+ device: Open D3XX device object.
123
+ pipe: D3XX pipe object with the selected pipe ID.
124
+ buffer_length: Maximum read length in bytes.
125
+ overlapped_timeout_ms: Read timeout in milliseconds.
126
+
127
+ Returns:
128
+ ``(status, buffer, transferred)``.
129
+ """
130
+ ...
131
+
132
+ def FT_ReadPipeEx(
133
+ self,
134
+ device: object,
135
+ pipe: object,
136
+ buffer_length: int,
137
+ overlapped_timeout_ms: int,
138
+ ) -> tuple[int, object, int]:
139
+ """Read bytes from one D3XX native stream pipe.
140
+
141
+ Args:
142
+ device: Open D3XX device object.
143
+ pipe: D3XX pipe object with the selected pipe ID.
144
+ buffer_length: Maximum read length in bytes.
145
+ overlapped_timeout_ms: Read timeout in milliseconds.
146
+
147
+ Returns:
148
+ ``(status, buffer, transferred)``.
149
+ """
150
+ ...
151
+
152
+ def FT_WritePipe(
153
+ self,
154
+ device: object,
155
+ pipe: object,
156
+ buffer: object,
157
+ buffer_length: int,
158
+ overlapped_timeout_ms: int,
159
+ ) -> tuple[int, int]:
160
+ """Write bytes to one D3XX native pipe.
161
+
162
+ Args:
163
+ device: Open D3XX device object.
164
+ pipe: D3XX pipe object with the selected pipe ID.
165
+ buffer: D3XX buffer object containing payload bytes.
166
+ buffer_length: Number of bytes to write.
167
+ overlapped_timeout_ms: Write timeout in milliseconds.
168
+
169
+ Returns:
170
+ ``(status, transferred)``.
171
+ """
172
+ ...
173
+
174
+
175
+ class D3xxBackendError(CaptureError):
176
+ """Raised when a D3XX API call fails or returns unsupported data.
177
+
178
+ Attributes:
179
+ function: D3XX function or parser step associated with the failure.
180
+ status: Optional native status code.
181
+ field_name: Optional detail field that was missing or invalid.
182
+ """
183
+
184
+ def __init__(
185
+ self,
186
+ function: str,
187
+ status: int | None = None,
188
+ *,
189
+ field_name: str | None = None,
190
+ ) -> None:
191
+ """Create a structured D3XX backend failure.
192
+
193
+ Args:
194
+ function: D3XX function or parser step associated with the failure.
195
+ status: Optional native status code.
196
+ field_name: Optional detail field that was missing or invalid.
197
+ """
198
+ message = _d3xx_error_message(function, status, field_name)
199
+ super().__init__(message)
200
+ self.function = function
201
+ self.status = status
202
+ self.field_name = field_name
203
+
204
+ @classmethod
205
+ def missing_field(cls, field_name: str) -> "D3xxBackendError":
206
+ """Create an error for an unsupported D3XX detail shape.
207
+
208
+ Args:
209
+ field_name: Required field that was not present.
210
+
211
+ Returns:
212
+ Structured backend error.
213
+ """
214
+ return cls("missing field", field_name=field_name)
215
+
216
+ @classmethod
217
+ def invalid_integer(cls, field_name: str) -> "D3xxBackendError":
218
+ """Create an error for an integer field that cannot be parsed.
219
+
220
+ Args:
221
+ field_name: Integer field that could not be converted.
222
+
223
+ Returns:
224
+ Structured backend error.
225
+ """
226
+ return cls("invalid integer", field_name=field_name)
227
+
228
+ @classmethod
229
+ def invalid_candidate(cls) -> "D3xxBackendError":
230
+ """Create an error for an unsupported D3XX candidate object.
231
+
232
+ Returns:
233
+ Structured backend error for a wrong candidate type.
234
+ """
235
+ return cls("invalid candidate")
236
+
237
+
238
+ @dataclass(frozen=True, slots=True)
239
+ class D3xxDeviceInfo:
240
+ """D3XX listing information normalized for N3DSXL classification.
241
+
242
+ Attributes:
243
+ index: Zero-based D3XX device index.
244
+ usb_info: USB identity reconstructed from D3XX detail fields.
245
+ flags: Optional D3XX flags field.
246
+ device_id: Raw D3XX device ID containing VID/PID information.
247
+ """
248
+
249
+ index: int
250
+ usb_info: UsbDeviceInfo
251
+ flags: int | None
252
+ device_id: int
253
+
254
+
255
+ @dataclass(frozen=True, slots=True)
256
+ class D3xxDeviceCandidate:
257
+ """N3DSXL candidate found through the D3XX driver backend.
258
+
259
+ Attributes:
260
+ candidate: Accepted N3DSXL candidate after USB identity classification.
261
+ index: Zero-based D3XX device index.
262
+ flags: Optional D3XX flags field.
263
+ device_id: Raw D3XX device ID containing VID/PID information.
264
+ backend_kind: Normalized backend label for metadata.
265
+ """
266
+
267
+ candidate: DeviceCandidate
268
+ index: int
269
+ flags: int | None
270
+ device_id: int
271
+ backend_kind: str = "d3xx"
272
+
273
+
274
+ class D3xxHandle:
275
+ """Opened D3XX handle with idempotent close.
276
+
277
+ The handle implements the pipe operations expected by ``N3DSXLProtocol`` and
278
+ records which pipes were configured for stream reads.
279
+ """
280
+
281
+ backend_kind: Literal["d3xx"] = "d3xx"
282
+
283
+ def __init__(
284
+ self,
285
+ binding: D3xxBinding,
286
+ device: object,
287
+ candidate: DeviceCandidate,
288
+ d3xx_candidate: D3xxDeviceCandidate | None = None,
289
+ ) -> None:
290
+ """Create a handle from an opened PyD3XX device detail object.
291
+
292
+ Args:
293
+ binding: PyD3XX-compatible module binding.
294
+ device: Open D3XX device detail object.
295
+ candidate: Accepted N3DSXL candidate for metadata.
296
+ d3xx_candidate: Original D3XX candidate, required for reconnect.
297
+ """
298
+ self._binding = binding
299
+ self._device = device
300
+ self.candidate = candidate
301
+ self._d3xx_candidate = d3xx_candidate
302
+ self._closed = False
303
+ self._stream_pipes: set[int] = set()
304
+
305
+ def close(self) -> None:
306
+ """Close the D3XX device handle.
307
+
308
+ The method is idempotent after the first successful or attempted close.
309
+
310
+ Raises:
311
+ D3xxBackendError: ``FT_Close`` returns a non-OK status.
312
+ """
313
+ if self._closed:
314
+ return
315
+ try:
316
+ _check_status("FT_Close", self._binding.FT_Close(self._device))
317
+ finally:
318
+ self._closed = True
319
+
320
+ def abort_pipe(self, pipe: int) -> None:
321
+ """Abort one D3XX native pipe.
322
+
323
+ Args:
324
+ pipe: D3XX pipe ID.
325
+
326
+ Raises:
327
+ D3xxBackendError: ``FT_AbortPipe`` fails.
328
+ """
329
+ pipe_object = _pipe_from_id(self._binding, pipe)
330
+ _check_status("FT_AbortPipe", self._binding.FT_AbortPipe(self._device, pipe_object))
331
+
332
+ def create_pipe(self) -> None:
333
+ """Keep protocol compatibility with the shared FTD3 transport surface.
334
+
335
+ The D3XX native API does not need the libusb command-pipe create
336
+ payload, so this operation is intentionally a no-op.
337
+ """
338
+
339
+ def reconnect_after_drain(self) -> None:
340
+ """Close and reopen after the initial drain, matching cc3dsfs' D3XX path.
341
+
342
+ Raises:
343
+ D3xxBackendError: The handle lacks original candidate metadata, or
344
+ the D3XX detail lookup/open call fails.
345
+ """
346
+ if self._d3xx_candidate is None:
347
+ raise D3xxBackendError.invalid_candidate()
348
+ self.close()
349
+ _, detail = _status_and_value(
350
+ "FT_GetDeviceInfoDetail",
351
+ self._binding.FT_GetDeviceInfoDetail(self._d3xx_candidate.index),
352
+ )
353
+ _check_status(
354
+ "FT_Create",
355
+ self._binding.FT_Create(
356
+ _open_identifier(self._d3xx_candidate),
357
+ _open_flag(self._d3xx_candidate),
358
+ detail,
359
+ ),
360
+ )
361
+ self._device = detail
362
+ self._closed = False
363
+
364
+ def set_stream_pipe(self, pipe: int, length: int) -> None:
365
+ """Configure one D3XX native stream pipe.
366
+
367
+ Args:
368
+ pipe: D3XX pipe ID to configure.
369
+ length: Stream transfer length in bytes.
370
+
371
+ Raises:
372
+ D3xxBackendError: ``FT_SetStreamPipe`` fails.
373
+ """
374
+ pipe_object = _pipe_from_id(self._binding, pipe)
375
+ _check_status(
376
+ "FT_SetStreamPipe",
377
+ self._binding.FT_SetStreamPipe(
378
+ self._device,
379
+ False,
380
+ False,
381
+ pipe_object,
382
+ length,
383
+ ),
384
+ )
385
+ self._stream_pipes.add(pipe)
386
+
387
+ def pyd3xx_native_dll(self) -> object | None:
388
+ """Return the loaded PyD3XX DLL object for explicit native adapters.
389
+
390
+ The fast-path backend uses this through ``D3xxNativeApi`` so PyD3XX
391
+ private module details do not leak into the streaming backend itself.
392
+ """
393
+ return _pyd3xx_dll(self._binding)
394
+
395
+ def pyd3xx_native_handle(self) -> object:
396
+ """Return the native D3XX handle object for explicit native adapters.
397
+
398
+ Raises:
399
+ D3xxBackendError: The underlying PyD3XX device does not expose a
400
+ native handle.
401
+ """
402
+ return _device_handle(self._device)
403
+
404
+ def read_pipe(
405
+ self,
406
+ pipe: int,
407
+ length: int,
408
+ timeout_ms: int = D3XX_DEFAULT_TIMEOUT_MS,
409
+ ) -> bytes:
410
+ """Read bytes from one D3XX native pipe.
411
+
412
+ Args:
413
+ pipe: D3XX pipe ID to read.
414
+ length: Maximum number of bytes to read.
415
+ timeout_ms: Read timeout in milliseconds.
416
+
417
+ Returns:
418
+ Bytes read from the native D3XX pipe.
419
+
420
+ Raises:
421
+ D3xxBackendError: The D3XX read call fails or returns unsupported
422
+ buffer metadata.
423
+ """
424
+ if pipe in self._stream_pipes:
425
+ return self._read_stream_pipe(pipe, length, timeout_ms)
426
+ direct = _direct_read_pipe(self._binding, self._device, pipe, length, timeout_ms)
427
+ if direct is not None:
428
+ return direct
429
+ pipe_object = _pipe_from_id(self._binding, pipe)
430
+ result = self._binding.FT_ReadPipe(self._device, pipe_object, length, timeout_ms)
431
+ status, buffer, transferred = _status_buffer_and_transferred("FT_ReadPipe", result)
432
+ _check_status("FT_ReadPipe", status)
433
+ return bytes(_buffer_value(buffer)[:transferred])
434
+
435
+ def _read_stream_pipe(self, pipe: int, length: int, timeout_ms: int) -> bytes:
436
+ direct = _direct_read_pipe_ex(self._binding, self._device, pipe, length, timeout_ms)
437
+ if direct is not None:
438
+ return direct
439
+ pipe_object = _pipe_from_id(self._binding, pipe)
440
+ result = self._binding.FT_ReadPipeEx(self._device, pipe_object, length, timeout_ms)
441
+ status, buffer, transferred = _status_buffer_and_transferred("FT_ReadPipeEx", result)
442
+ _check_status("FT_ReadPipeEx", status)
443
+ return bytes(_buffer_value(buffer)[:transferred])
444
+
445
+ def write_pipe(
446
+ self,
447
+ pipe: int,
448
+ payload: bytes,
449
+ timeout_ms: int = D3XX_DEFAULT_TIMEOUT_MS,
450
+ ) -> int:
451
+ """Write bytes to one D3XX native pipe.
452
+
453
+ Args:
454
+ pipe: D3XX pipe ID to write.
455
+ payload: Bytes to transfer.
456
+ timeout_ms: Write timeout in milliseconds.
457
+
458
+ Returns:
459
+ Number of bytes transferred.
460
+
461
+ Raises:
462
+ D3xxBackendError: The D3XX write call fails.
463
+ """
464
+ direct = _direct_write_pipe(self._binding, self._device, pipe, payload, timeout_ms)
465
+ if direct is not None:
466
+ return direct
467
+ pipe_object = _pipe_from_id(self._binding, pipe)
468
+ buffer = _buffer_from_bytes(self._binding, payload)
469
+ status, transferred = _status_and_transferred(
470
+ "FT_WritePipe",
471
+ self._binding.FT_WritePipe(
472
+ self._device,
473
+ pipe_object,
474
+ buffer,
475
+ len(payload),
476
+ timeout_ms,
477
+ ),
478
+ )
479
+ _check_status("FT_WritePipe", status)
480
+ return transferred
481
+
482
+
483
+ def load_pyd3xx_binding() -> D3xxBinding:
484
+ """Import the optional PyD3XX module.
485
+
486
+ Returns:
487
+ Imported module cast to the D3XX binding protocol.
488
+
489
+ Raises:
490
+ OptionalDependencyError: Neither supported PyD3XX module name can be
491
+ imported.
492
+ """
493
+ for module_name in PYD3XX_MODULE_NAMES:
494
+ try:
495
+ return cast("D3xxBinding", import_module(module_name))
496
+ except ImportError:
497
+ continue
498
+ raise OptionalDependencyError("PyD3XX", "d3xx")
499
+
500
+
501
+ class D3xxBackend:
502
+ """FTDI D3XX-backed device enumeration.
503
+
504
+ This backend is used as a fallback when libusb cannot open an otherwise
505
+ accepted N3DSXL because the installed Windows driver belongs to D3XX.
506
+ """
507
+
508
+ def __init__(self, binding: D3xxBinding | None = None) -> None:
509
+ """Create a backend using an injected or optional PyD3XX binding.
510
+
511
+ Args:
512
+ binding: Optional test or real PyD3XX binding. When omitted, the
513
+ optional dependency is imported lazily.
514
+
515
+ Raises:
516
+ OptionalDependencyError: ``binding`` is omitted and PyD3XX is not
517
+ installed.
518
+ """
519
+ self._binding = binding or load_pyd3xx_binding()
520
+
521
+ def iter_devices(self) -> tuple[D3xxDeviceInfo, ...]:
522
+ """Return D3XX devices visible through the binding.
523
+
524
+ Returns:
525
+ Tuple of normalized D3XX device information.
526
+
527
+ Raises:
528
+ D3xxBackendError: The binding returns a non-OK status or an
529
+ unsupported detail shape.
530
+ """
531
+ _, count = _status_and_value(
532
+ "FT_CreateDeviceInfoList",
533
+ self._binding.FT_CreateDeviceInfoList(),
534
+ )
535
+ devices: list[D3xxDeviceInfo] = []
536
+ for index in range(_int_from_object("FT_CreateDeviceInfoList.count", count)):
537
+ _, detail = _status_and_value(
538
+ "FT_GetDeviceInfoDetail",
539
+ self._binding.FT_GetDeviceInfoDetail(index),
540
+ )
541
+ devices.append(_device_info_from_detail(index=index, detail=detail))
542
+ return tuple(devices)
543
+
544
+ def iter_device_candidates(self) -> tuple[D3xxDeviceCandidate, ...]:
545
+ """Return N3DSXL candidates visible through the D3XX backend.
546
+
547
+ Returns:
548
+ D3XX devices that pass the same N3DSXL classification policy as the
549
+ libusb path.
550
+ """
551
+ candidates: list[D3xxDeviceCandidate] = []
552
+ for device in self.iter_devices():
553
+ classified = classify_n3dsxl_device(device.usb_info)
554
+ if isinstance(classified, DeviceCandidate):
555
+ candidates.append(
556
+ D3xxDeviceCandidate(
557
+ candidate=classified,
558
+ index=device.index,
559
+ flags=device.flags,
560
+ device_id=device.device_id,
561
+ )
562
+ )
563
+ return tuple(candidates)
564
+
565
+ def open(self, candidate: object) -> D3xxHandle:
566
+ """Open one D3XX candidate and return a closeable handle.
567
+
568
+ Args:
569
+ candidate: ``D3xxDeviceCandidate`` returned by this backend.
570
+
571
+ Returns:
572
+ Open D3XX handle compatible with the N3DSXL protocol pipe surface.
573
+
574
+ Raises:
575
+ D3xxBackendError: The candidate type is unsupported, or the D3XX
576
+ detail lookup/open call fails.
577
+ """
578
+ if not isinstance(candidate, D3xxDeviceCandidate):
579
+ raise D3xxBackendError.invalid_candidate()
580
+ _, detail = _status_and_value(
581
+ "FT_GetDeviceInfoDetail",
582
+ self._binding.FT_GetDeviceInfoDetail(candidate.index),
583
+ )
584
+ _check_status(
585
+ "FT_Create",
586
+ self._binding.FT_Create(
587
+ _open_identifier(candidate),
588
+ _open_flag(candidate),
589
+ detail,
590
+ ),
591
+ )
592
+ return D3xxHandle(
593
+ binding=self._binding,
594
+ device=detail,
595
+ candidate=candidate.candidate,
596
+ d3xx_candidate=candidate,
597
+ )
598
+
599
+
600
+ def _device_info_from_detail(*, index: int, detail: object) -> D3xxDeviceInfo:
601
+ device_id = _int_from_object("FT_GetDeviceInfoDetail.ID", _field(detail, "ID"))
602
+ vendor_id, product_id = _vid_pid_from_device_id(device_id)
603
+ usb_info = UsbDeviceInfo(
604
+ bus_number=None,
605
+ address=None,
606
+ vendor_id=vendor_id,
607
+ product_id=product_id,
608
+ product_string=_optional_text(_field(detail, "Description")),
609
+ serial_number=_optional_text(_field(detail, "SerialNumber")),
610
+ )
611
+ flags = _optional_int(_field(detail, "Flags"))
612
+ return D3xxDeviceInfo(index=index, usb_info=usb_info, flags=flags, device_id=device_id)
613
+
614
+
615
+ def _open_identifier(candidate: D3xxDeviceCandidate) -> object:
616
+ serial_number = candidate.candidate.info.serial_number
617
+ if serial_number is not None:
618
+ return serial_number
619
+ return candidate.index
620
+
621
+
622
+ def _open_flag(candidate: D3xxDeviceCandidate) -> int:
623
+ if candidate.candidate.info.serial_number is not None:
624
+ return D3XX_OPEN_BY_SERIAL_NUMBER
625
+ return D3XX_OPEN_BY_INDEX
626
+
627
+
628
+ def _status_and_value(function: str, result: object) -> tuple[int, object]:
629
+ if not isinstance(result, tuple) or len(result) < 2:
630
+ raise D3xxBackendError(function)
631
+ status = _int_from_object(f"{function}.status", result[0])
632
+ if status != FT_OK:
633
+ raise D3xxBackendError(function, status)
634
+ return status, result[1]
635
+
636
+
637
+ def _check_status(function: str, status: object) -> None:
638
+ value = _int_from_object(f"{function}.status", status)
639
+ if value != FT_OK:
640
+ raise D3xxBackendError(function, value)
641
+
642
+
643
+ def _status_buffer_and_transferred(function: str, result: object) -> tuple[int, object, int]:
644
+ if not isinstance(result, tuple) or len(result) < 3:
645
+ raise D3xxBackendError(function)
646
+ return (
647
+ _int_from_object(f"{function}.status", result[0]),
648
+ result[1],
649
+ _int_from_object(f"{function}.transferred", result[2]),
650
+ )
651
+
652
+
653
+ def _status_and_transferred(function: str, result: object) -> tuple[int, int]:
654
+ if not isinstance(result, tuple) or len(result) < 2:
655
+ raise D3xxBackendError(function)
656
+ return (
657
+ _int_from_object(f"{function}.status", result[0]),
658
+ _int_from_object(f"{function}.transferred", result[1]),
659
+ )
660
+
661
+
662
+ def _pipe_from_id(binding: D3xxBinding, pipe: int) -> object:
663
+ pipe_type = binding.FT_Pipe
664
+ pipe_object = pipe_type()
665
+ pipe_object.PipeID = pipe
666
+ pipe_object._PipeID = pipe
667
+ return pipe_object
668
+
669
+
670
+ def _buffer_from_bytes(binding: D3xxBinding, payload: bytes) -> object:
671
+ buffer_type = binding.FT_Buffer
672
+ return buffer_type.from_bytes(payload)
673
+
674
+
675
+ def _buffer_value(buffer: object) -> bytearray:
676
+ value_method = cast("Any", buffer).Value
677
+ if not callable(value_method):
678
+ raise D3xxBackendError("FT_Buffer.Value")
679
+ value = value_method()
680
+ if isinstance(value, bytearray):
681
+ return value
682
+ if isinstance(value, bytes):
683
+ return bytearray(value)
684
+ raise D3xxBackendError("FT_Buffer.Value")
685
+
686
+
687
+ def _direct_write_pipe(
688
+ binding: D3xxBinding,
689
+ device: object,
690
+ pipe: int,
691
+ payload: bytes,
692
+ timeout_ms: int,
693
+ ) -> int | None:
694
+ dll = _pyd3xx_dll(binding)
695
+ if dll is None:
696
+ return None
697
+ dll = cast("Any", dll)
698
+ buffer = ctypes.create_string_buffer(payload, len(payload))
699
+ transferred = ctypes.c_ulong(0)
700
+ handle = _device_handle(device)
701
+ with _pipe_timeout(dll, handle, pipe, timeout_ms):
702
+ status = dll.FT_WritePipe(
703
+ handle,
704
+ ctypes.c_ubyte(pipe),
705
+ buffer,
706
+ ctypes.c_ulong(len(payload)),
707
+ ctypes.byref(transferred),
708
+ None,
709
+ )
710
+ _check_status("FT_WritePipe", status)
711
+ return int(transferred.value)
712
+
713
+
714
+ def _direct_read_pipe(
715
+ binding: D3xxBinding,
716
+ device: object,
717
+ pipe: int,
718
+ length: int,
719
+ timeout_ms: int,
720
+ ) -> bytes | None:
721
+ dll = _pyd3xx_dll(binding)
722
+ if dll is None:
723
+ return None
724
+ dll = cast("Any", dll)
725
+ buffer = ctypes.create_string_buffer(length)
726
+ transferred = ctypes.c_ulong(0)
727
+ handle = _device_handle(device)
728
+ with _pipe_timeout(dll, handle, pipe, timeout_ms):
729
+ status = dll.FT_ReadPipe(
730
+ handle,
731
+ ctypes.c_ubyte(pipe),
732
+ buffer,
733
+ ctypes.c_ulong(length),
734
+ ctypes.byref(transferred),
735
+ None,
736
+ )
737
+ _check_status("FT_ReadPipe", status)
738
+ return bytes(buffer.raw[: transferred.value])
739
+
740
+
741
+ def _direct_read_pipe_ex(
742
+ binding: D3xxBinding,
743
+ device: object,
744
+ pipe: int,
745
+ length: int,
746
+ timeout_ms: int,
747
+ ) -> bytes | None:
748
+ dll = _pyd3xx_dll(binding)
749
+ if dll is None:
750
+ return None
751
+ dll = cast("Any", dll)
752
+ buffer = ctypes.create_string_buffer(length)
753
+ transferred = ctypes.c_ulong(0)
754
+ handle = _device_handle(device)
755
+ with _pipe_timeout(dll, handle, pipe, timeout_ms):
756
+ status = dll.FT_ReadPipeEx(
757
+ handle,
758
+ ctypes.c_ubyte(pipe),
759
+ buffer,
760
+ ctypes.c_ulong(length),
761
+ ctypes.byref(transferred),
762
+ None,
763
+ )
764
+ _check_status("FT_ReadPipeEx", status)
765
+ return bytes(buffer.raw[: transferred.value])
766
+
767
+
768
+ @contextmanager
769
+ def _pipe_timeout(dll: object, handle: object, pipe: int, timeout_ms: int) -> Iterator[None]:
770
+ dll = cast("Any", dll)
771
+ old_timeout_ms = ctypes.c_ulong(0)
772
+ status = dll.FT_GetPipeTimeout(handle, ctypes.c_ubyte(pipe), ctypes.byref(old_timeout_ms))
773
+ _check_status("FT_GetPipeTimeout", status)
774
+ status = dll.FT_SetPipeTimeout(handle, ctypes.c_ubyte(pipe), ctypes.c_ulong(timeout_ms))
775
+ _check_status("FT_SetPipeTimeout", status)
776
+ try:
777
+ yield
778
+ finally:
779
+ status = dll.FT_SetPipeTimeout(handle, ctypes.c_ubyte(pipe), old_timeout_ms)
780
+ _check_status("FT_SetPipeTimeout", status)
781
+
782
+
783
+ def _pyd3xx_dll(binding: D3xxBinding) -> object | None:
784
+ if not isinstance(binding, ModuleType):
785
+ return None
786
+ try:
787
+ implementation = import_module("PyD3XX.PyD3XX")
788
+ except ImportError:
789
+ return None
790
+ return getattr(implementation, "_DLL", None)
791
+
792
+
793
+ def _device_handle(device: object) -> object:
794
+ try:
795
+ return cast("Any", device)._Handle
796
+ except AttributeError as exc:
797
+ raise D3xxBackendError.missing_field("_Handle") from exc
798
+
799
+
800
+ def _field(target: object, name: str) -> object:
801
+ if isinstance(target, Mapping):
802
+ mapping = cast("Mapping[str, object]", target)
803
+ if name in mapping:
804
+ return mapping[name]
805
+ raise D3xxBackendError.missing_field(name)
806
+ try:
807
+ return getattr(target, name)
808
+ except AttributeError as exc:
809
+ raise D3xxBackendError.missing_field(name) from exc
810
+
811
+
812
+ def _vid_pid_from_device_id(device_id: int) -> tuple[int, int]:
813
+ high = (device_id >> 16) & 0xFFFF
814
+ low = device_id & 0xFFFF
815
+ if high == N3DSXL_VENDOR_ID:
816
+ return high, low
817
+ if low == N3DSXL_VENDOR_ID:
818
+ return low, high
819
+ return high, low
820
+
821
+
822
+ def _optional_text(value: object) -> str | None:
823
+ if value is None:
824
+ return None
825
+ text = str(value)
826
+ if text == "":
827
+ return None
828
+ return text
829
+
830
+
831
+ def _optional_int(value: object) -> int | None:
832
+ if value is None:
833
+ return None
834
+ return _int_from_object("optional int", value)
835
+
836
+
837
+ def _int_from_object(field_name: str, value: object) -> int:
838
+ if isinstance(value, int):
839
+ return value
840
+ if isinstance(value, str | bytes | bytearray):
841
+ return int(value)
842
+ raise D3xxBackendError.invalid_integer(field_name)
843
+
844
+
845
+ def _d3xx_error_message(function: str, status: int | None, field_name: str | None) -> str:
846
+ if field_name is not None:
847
+ return f"{function}: {field_name}"
848
+ if status is None:
849
+ return function
850
+ return f"{function} failed with status {status}"