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.
- ponkan_python-0.1.0.dist-info/METADATA +157 -0
- ponkan_python-0.1.0.dist-info/RECORD +39 -0
- ponkan_python-0.1.0.dist-info/WHEEL +4 -0
- ponkan_python-0.1.0.dist-info/entry_points.txt +5 -0
- ponkan_python-0.1.0.dist-info/licenses/LICENSE +22 -0
- ponkan_python-0.1.0.dist-info/licenses/NOTICE.md +14 -0
- py3dscapture/__init__.py +36 -0
- py3dscapture/artifacts.py +66 -0
- py3dscapture/capture.py +599 -0
- py3dscapture/devices/__init__.py +1 -0
- py3dscapture/devices/n3dsxl_ftd3.py +238 -0
- py3dscapture/errors.py +120 -0
- py3dscapture/hardware_gate.py +143 -0
- py3dscapture/image/__init__.py +1 -0
- py3dscapture/image/frame.py +166 -0
- py3dscapture/protocol/__init__.py +1 -0
- py3dscapture/protocol/layout_3ds.py +60 -0
- py3dscapture/protocol/n3dsxl.py +249 -0
- py3dscapture/protocol/sizes.py +128 -0
- py3dscapture/py.typed +1 -0
- py3dscapture/streaming/__init__.py +1 -0
- py3dscapture/streaming/buffers.py +156 -0
- py3dscapture/streaming/engine.py +285 -0
- py3dscapture/streaming/policies.py +157 -0
- py3dscapture/streaming/stats.py +254 -0
- py3dscapture/tools/__init__.py +1 -0
- py3dscapture/tools/capture_raw.py +44 -0
- py3dscapture/tools/list_devices.py +68 -0
- py3dscapture/tools/raw_to_png.py +251 -0
- py3dscapture/tools/stream_n3dsxl.py +152 -0
- py3dscapture/transport/__init__.py +1 -0
- py3dscapture/transport/d3xx_backend.py +850 -0
- py3dscapture/transport/d3xx_native.py +268 -0
- py3dscapture/transport/d3xx_native_streaming.py +306 -0
- py3dscapture/transport/d3xx_streaming.py +202 -0
- py3dscapture/transport/ftd3_backend.py +275 -0
- py3dscapture/transport/ftd3_pipe.py +387 -0
- py3dscapture/transport/libusb_async.py +134 -0
- 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
|