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,357 @@
1
+ """Thin libusb backend boundary used by device-specific code."""
2
+
3
+ from collections.abc import Iterable
4
+ from contextlib import suppress
5
+ from dataclasses import dataclass
6
+ from importlib import import_module
7
+ from typing import TYPE_CHECKING, Protocol, cast
8
+
9
+ from py3dscapture.errors import DeviceOpenError
10
+
11
+ if TYPE_CHECKING:
12
+ from collections.abc import Callable
13
+
14
+
15
+ @dataclass(frozen=True, slots=True)
16
+ class UsbDeviceInfo:
17
+ """USB descriptor fields needed before opening a capture device.
18
+
19
+ Attributes:
20
+ bus_number: USB bus number when the backend can provide it.
21
+ address: Device address on the bus when available.
22
+ vendor_id: USB vendor ID.
23
+ product_id: USB product ID.
24
+ product_string: Product string read before opening, or ``None`` when it
25
+ cannot be read.
26
+ serial_number: Optional serial number used to disambiguate devices.
27
+ """
28
+
29
+ bus_number: int | None
30
+ address: int | None
31
+ vendor_id: int
32
+ product_id: int
33
+ product_string: str | None
34
+ serial_number: str | None = None
35
+
36
+
37
+ class UsbHandle(Protocol):
38
+ """Opened USB handle primitive.
39
+
40
+ Protocol implemented by real libusb handles and tests. Callers own closing
41
+ any handle returned by a backend.
42
+ """
43
+
44
+ def detach_kernel_driver(self, interface: int) -> None:
45
+ """Detach the kernel driver for an interface when supported.
46
+
47
+ Args:
48
+ interface: USB interface number.
49
+ """
50
+ ...
51
+
52
+ def set_configuration(self, configuration: int) -> None:
53
+ """Select a USB configuration.
54
+
55
+ Args:
56
+ configuration: USB configuration value to select.
57
+ """
58
+ ...
59
+
60
+ def claim_interface(self, interface: int) -> None:
61
+ """Claim a USB interface.
62
+
63
+ Args:
64
+ interface: USB interface number to claim.
65
+ """
66
+ ...
67
+
68
+ def release_interface(self, interface: int) -> None:
69
+ """Release a USB interface.
70
+
71
+ Args:
72
+ interface: USB interface number to release.
73
+ """
74
+ ...
75
+
76
+ def close(self) -> None:
77
+ """Close the device handle.
78
+
79
+ Implementations should make repeated close attempts harmless when the
80
+ underlying library permits it.
81
+ """
82
+ ...
83
+
84
+ def bulk_write(self, endpoint: int, payload: bytes, timeout_ms: int) -> int:
85
+ """Write bytes to a bulk endpoint and return transferred bytes.
86
+
87
+ Args:
88
+ endpoint: USB bulk OUT endpoint address.
89
+ payload: Bytes to transfer.
90
+ timeout_ms: Write timeout in milliseconds.
91
+
92
+ Returns:
93
+ Number of payload bytes transferred.
94
+ """
95
+ ...
96
+
97
+ def bulk_read(self, endpoint: int, length: int, timeout_ms: int) -> bytes:
98
+ """Read bytes from a bulk endpoint.
99
+
100
+ Args:
101
+ endpoint: USB bulk IN endpoint address.
102
+ length: Maximum number of bytes to read.
103
+ timeout_ms: Read timeout in milliseconds.
104
+
105
+ Returns:
106
+ Bytes returned by the backend.
107
+ """
108
+ ...
109
+
110
+
111
+ class LibusbBackend(Protocol):
112
+ """Device enumeration and opening primitive.
113
+
114
+ Backends enumerate descriptor information without sending N3DSXL commands.
115
+ """
116
+
117
+ def iter_devices(self) -> Iterable[UsbDeviceInfo]:
118
+ """Iterate devices visible through the backend.
119
+
120
+ Returns:
121
+ Iterable of USB descriptors visible to this backend.
122
+ """
123
+ ...
124
+
125
+ def open(self, device: UsbDeviceInfo) -> UsbHandle:
126
+ """Open one device descriptor.
127
+
128
+ Args:
129
+ device: Descriptor identity returned by ``iter_devices``.
130
+
131
+ Returns:
132
+ Opened handle owned by the caller.
133
+ """
134
+ ...
135
+
136
+
137
+ class Usb1Backend:
138
+ """libusb1-backed implementation.
139
+
140
+ The backend imports ``usb1`` lazily so package import does not require the
141
+ optional USB runtime to be usable.
142
+ """
143
+
144
+ def iter_devices(self) -> list[UsbDeviceInfo]:
145
+ """Return devices visible through libusb1.
146
+
147
+ Returns:
148
+ List of descriptor records normalized to ``UsbDeviceInfo``.
149
+ """
150
+ usb1 = import_module("usb1")
151
+ context_factory = cast("Callable[[], object]", usb1.USBContext)
152
+ context = context_factory()
153
+ try:
154
+ devices = cast(
155
+ "Iterable[object]",
156
+ _call_method(context, "getDeviceList", skip_on_error=True),
157
+ )
158
+ return [_usb1_device_info(device) for device in devices]
159
+ finally:
160
+ _call_method(context, "close")
161
+
162
+ def open(self, device: UsbDeviceInfo) -> UsbHandle:
163
+ """Open a USB device by descriptor identity.
164
+
165
+ Args:
166
+ device: Descriptor identity to match against the current device
167
+ list.
168
+
169
+ Returns:
170
+ Open libusb handle wrapper. The caller owns ``close``.
171
+
172
+ Raises:
173
+ DeviceOpenError: No matching device can be opened.
174
+ """
175
+ usb1 = import_module("usb1")
176
+ context_factory = cast("Callable[[], object]", usb1.USBContext)
177
+ context = context_factory()
178
+ devices = cast(
179
+ "Iterable[object]",
180
+ _call_method(context, "getDeviceList", skip_on_error=True),
181
+ )
182
+ for candidate in devices:
183
+ if _matches_usb1_device(candidate, device):
184
+ try:
185
+ return _Usb1Handle(context=context, handle=_call_method(candidate, "open"))
186
+ except Exception as exc:
187
+ _call_method(context, "close")
188
+ raise DeviceOpenError from exc
189
+
190
+ _call_method(context, "close")
191
+ raise DeviceOpenError
192
+
193
+
194
+ class _Usb1Handle:
195
+ def __init__(self, context: object, handle: object) -> None:
196
+ self._context = context
197
+ self._handle = handle
198
+ self._closed = False
199
+
200
+ def detach_kernel_driver(self, interface: int) -> None:
201
+ try:
202
+ active = bool(_call_method(self._handle, "kernelDriverActive", interface))
203
+ except AttributeError:
204
+ return
205
+ if active:
206
+ _call_method(self._handle, "detachKernelDriver", interface)
207
+
208
+ def set_configuration(self, configuration: int) -> None:
209
+ _call_method(self._handle, "setConfiguration", configuration)
210
+
211
+ def claim_interface(self, interface: int) -> None:
212
+ _call_method(self._handle, "claimInterface", interface)
213
+
214
+ def release_interface(self, interface: int) -> None:
215
+ _call_method(self._handle, "releaseInterface", interface)
216
+
217
+ def close(self) -> None:
218
+ if self._closed:
219
+ return
220
+ try:
221
+ _call_method(self._handle, "close")
222
+ finally:
223
+ _call_method(self._context, "close")
224
+ self._closed = True
225
+
226
+ def bulk_write(self, endpoint: int, payload: bytes, timeout_ms: int) -> int:
227
+ transferred = _call_method(self._handle, "bulkWrite", endpoint, payload, timeout_ms)
228
+ return _int_from_object(transferred)
229
+
230
+ def bulk_read(self, endpoint: int, length: int, timeout_ms: int) -> bytes:
231
+ data = _call_method(self._handle, "bulkRead", endpoint, length, timeout_ms)
232
+ if isinstance(data, bytes):
233
+ return data
234
+ if isinstance(data, bytearray | memoryview):
235
+ return bytes(data)
236
+ raise TypeError
237
+
238
+
239
+ def _usb1_device_info(device: object) -> UsbDeviceInfo:
240
+ return UsbDeviceInfo(
241
+ bus_number=_optional_int(device, "getBusNumber"),
242
+ address=_optional_int(device, "getDeviceAddress"),
243
+ vendor_id=_int_from_object(_call_method(device, "getVendorID")),
244
+ product_id=_int_from_object(_call_method(device, "getProductID")),
245
+ product_string=_usb1_product_string(device),
246
+ serial_number=_optional_str(device, "getSerialNumber"),
247
+ )
248
+
249
+
250
+ def _usb1_product_string(device: object) -> str | None:
251
+ product = _usb1_product_string_from_handle(device)
252
+ if product is not None:
253
+ return product
254
+ return _optional_str(device, "getProduct")
255
+
256
+
257
+ def _usb1_product_string_from_handle(device: object) -> str | None:
258
+ try:
259
+ descriptor = _int_from_object(_call_method(device, "getProductDescriptor"))
260
+ except (AttributeError, TypeError, ValueError):
261
+ return None
262
+ if descriptor == 0:
263
+ return None
264
+
265
+ try:
266
+ handle = _call_method(device, "open")
267
+ except Exception: # noqa: BLE001
268
+ return None
269
+ try:
270
+ product = _optional_str(handle, "getProduct")
271
+ if product is not None:
272
+ return product
273
+ for language_id in _usb1_language_ids(handle):
274
+ product = _optional_string_descriptor(handle, descriptor, language_id)
275
+ if product is not None:
276
+ return product
277
+ finally:
278
+ with suppress(Exception):
279
+ _call_method(handle, "close")
280
+ return None
281
+
282
+
283
+ def _usb1_language_ids(handle: object) -> tuple[int, ...]:
284
+ try:
285
+ values = _call_method(handle, "getSupportedLanguageList")
286
+ except Exception: # noqa: BLE001
287
+ return (0x0409,)
288
+ try:
289
+ language_ids = tuple(_int_from_object(value) for value in cast("Iterable[object]", values))
290
+ except (TypeError, ValueError):
291
+ return (0x0409,)
292
+ return language_ids or (0x0409,)
293
+
294
+
295
+ def _optional_string_descriptor(
296
+ handle: object,
297
+ descriptor: int,
298
+ language_id: int,
299
+ ) -> str | None:
300
+ try:
301
+ value = _call_method(handle, "getStringDescriptor", descriptor, language_id)
302
+ except Exception: # noqa: BLE001
303
+ return None
304
+ if value == "":
305
+ return None
306
+ return str(value)
307
+
308
+
309
+ def _matches_usb1_device(candidate: object, expected: UsbDeviceInfo) -> bool:
310
+ candidate_info = _usb1_device_info(candidate)
311
+ if expected.bus_number is not None and candidate_info.bus_number != expected.bus_number:
312
+ return False
313
+ if expected.address is not None and candidate_info.address != expected.address:
314
+ return False
315
+ return (
316
+ candidate_info.vendor_id == expected.vendor_id
317
+ and candidate_info.product_id == expected.product_id
318
+ and candidate_info.product_string == expected.product_string
319
+ and candidate_info.serial_number == expected.serial_number
320
+ )
321
+
322
+
323
+ def _optional_int(device: object, method_name: str) -> int | None:
324
+ try:
325
+ return _int_from_object(_call_method(device, method_name))
326
+ except (AttributeError, TypeError, ValueError):
327
+ return None
328
+
329
+
330
+ def _optional_str(device: object, method_name: str) -> str | None:
331
+ try:
332
+ value = _call_method(device, method_name)
333
+ except Exception: # noqa: BLE001
334
+ return None
335
+ if value == "":
336
+ return None
337
+ return str(value)
338
+
339
+
340
+ def _call_method(
341
+ target: object,
342
+ method_name: str,
343
+ *args: object,
344
+ **kwargs: object,
345
+ ) -> object:
346
+ method = getattr(target, method_name)
347
+ if not callable(method):
348
+ raise TypeError
349
+ return method(*args, **kwargs)
350
+
351
+
352
+ def _int_from_object(value: object) -> int:
353
+ if isinstance(value, int):
354
+ return value
355
+ if isinstance(value, str | bytes | bytearray):
356
+ return int(value)
357
+ raise TypeError