1Metadata-Version: 1.1
2Name: libusb1
3Version: 1.9.3
4Summary: Pure-python wrapper for libusb-1.0
5Home-page: http://github.com/vpelletier/python-libusb1
6Author: Vincent Pelletier
7Author-email: plr.vincent@gmail.com
8License: LGPLv2.1+
9Description: .. contents::
10
11        Pure-python wrapper for libusb-1.0
12
13        Supports all transfer types, both in synchronous and asynchronous mode.
14
15        Home: http://github.com/vpelletier/python-libusb1
16
17        PyPI: http://pypi.python.org/pypi/libusb1
18
19        .. role:: c_code(code)
20          :language: c
21
22        .. role:: python_code(code)
23          :language: python
24
25        Dependencies
26        ============
27
28        - CPython_ 2.7+ or 3.4+, pypy_ 2.0+. Older versions may work, but are not
29          recommended as there is no automated regression testing set up for them.
30
31        - libusb-1.0_
32
33        Supported OSes
34        ==============
35
36        python-libusb1 can be expected to work on:
37
38        - GNU/Linux
39
40        - Windows [#]_ native dll or via Cygwin_
41
42        - OSX [#]_ via MacPorts_, Fink_ or Homebrew_
43
44        - FreeBSD (including Debian GNU/kFreeBSD)
45
46        - OpenBSD
47
48        .. [#] Beware of libusb-win32, which implements 0.1 API, not 1.0 .
49
50        .. [#] Beware of possible lack of select.poll if you want to use asynchronous
51               API.
52
53        Installation
54        ============
55
56        Releases from PyPI, with name *libusb1*. Installing from command line::
57
58            $ pip install libusb1
59
60        or::
61
62            $ easy_install libusb1
63
64        Latest version from source tree::
65
66            $ git clone https://github.com/vpelletier/python-libusb1.git
67            $ cd python-libusb1
68            $ python setup.py install
69
70        Usage
71        =====
72
73        Finding a device and gaining exclusive access:
74
75        .. code:: python
76
77            import usb1
78            with usb1.USBContext() as context:
79                handle = context.openByVendorIDAndProductID(
80                    VENDOR_ID,
81                    PRODUCT_ID,
82                    skip_on_error=True,
83                )
84                if handle is None:
85                    # Device not present, or user is not allowed to access device.
86                with handle.claimInterface(INTERFACE):
87                    # Do stuff with endpoints on claimed interface.
88
89        Synchronous I/O:
90
91        .. code:: python
92
93            while True:
94                data = handle.bulkRead(ENDPOINT, BUFFER_SIZE)
95                # Process data...
96
97        Asynchronous I/O, with more error handling:
98
99        .. code:: python
100
101            def processReceivedData(transfer):
102                if transfer.getStatus() != usb1.TRANSFER_COMPLETED:
103                    # Transfer did not complete successfully, there is no data to read.
104                    # This example does not resubmit transfers on errors. You may want
105                    # to resubmit in some cases (timeout, ...).
106                    return
107                data = transfer.getBuffer()[:transfer.getActualLength()]
108                # Process data...
109                # Resubmit transfer once data is processed.
110                transfer.submit()
111
112            # Build a list of transfer objects and submit them to prime the pump.
113            transfer_list = []
114            for _ in range(TRANSFER_COUNT):
115                transfer = handle.getTransfer()
116                transfer.setBulk(
117                    usb1.ENDPOINT_IN | ENDPOINT,
118                    BUFFER_SIZE,
119                    callback=processReceivedData,
120                )
121                transfer.submit()
122                transfer_list.append(transfer)
123            # Loop as long as there is at least one submitted transfer.
124            while any(x.isSubmitted() for x in transfer_list):
125                try:
126                    context.handleEvents()
127                except usb1.USBErrorInterrupted:
128                    pass
129
130        For more, see the ``example`` directory.
131
132        Documentation
133        =============
134
135        python-libusb1 main documentation is accessible with python's standard
136        ``pydoc`` command.
137
138        python-libusb1 follows libusb-1.0 documentation as closely as possible, without
139        taking decisions for you. Thanks to this, python-libusb1 does not need to
140        duplicate the nice existing `libusb1.0 documentation`_.
141
142        Some description is needed though on how to jump from libusb-1.0 documentation
143        to python-libusb1, and vice-versa:
144
145        ``usb1`` module groups libusb-1.0 functions as class methods. The first
146        parameter (when it's a ``libusb_...`` pointer) defined the class the fonction
147        belongs to. For example:
148
149        - :c_code:`int libusb_init (libusb_context **context)` becomes USBContext class
150          constructor, :python_code:`USBContext.__init__(self)`
151
152        - :c_code:`ssize_t libusb_get_device_list (libusb_context *ctx,
153          libusb_device ***list)` becomes an USBContext method, returning a
154          list of USBDevice instances, :python_code:`USBDevice.getDeviceList(self)`
155
156        - :c_code:`uint8_t libusb_get_bus_number (libusb_device *dev)` becomes an
157          USBDevice method, :python_code:`USBDevice.getBusNumber(self)`
158
159        Error statuses are converted into :python_code:`usb1.USBError` exceptions, with
160        status as ``value`` instance property.
161
162        ``usb1`` module also defines a few more functions and classes, which are
163        otherwise not so convenient to call from Python: the event handling API needed
164        by async API.
165
166        History
167        =======
168
169        0.0.1
170        -----
171
172        Initial release
173
174        0.1.1
175        -----
176
177        Massive rework of usb1.py, making it more python-ish and fixing some
178        memory leaks.
179
180        0.1.2
181        -----
182
183        Deprecate "transfer" constructor parameter to allow instance reuse.
184
185        0.1.3
186        -----
187
188        Some work on isochronous "in" transfers. They don't raise exceptions anymore,
189        but data validity and python-induced latency impact weren't properly checked.
190
191        0.2.0
192        -----
193
194        Fix asynchronous configuration transfers.
195
196        Stand-alone polling thread for multi-threaded apps.
197
198        More libusb methods exposed on objects, including ones not yet part of
199        released libusb versions (up to their commit 4630fc2).
200
201        2to3 friendly.
202
203        Drop deprecated USBDevice.reprConfigurations method.
204
205        0.2.1
206        -----
207
208        Add FreeBSD support.
209
210        0.2.2
211        -----
212
213        Add Cygwin support.
214
215        OpenBSD support checked (no change).
216
217        0.2.3
218        -----
219
220        Add fink and homebrew support on OSX.
221
222        Drop PATH_MAX definition.
223
224        Try harder when looking for libusb.
225
226        1.0.0
227        -----
228
229        Fix FreeBSD ABI compatibility.
230
231        Easier to list connected devices.
232
233        Easier to terminate all async transfers for clean exit.
234
235        Fix few segfault causes.
236
237        pypy support.
238
239        1.1.0
240        -----
241
242        Descriptor walk API documented.
243
244        Version and capability APIs exposed.
245
246        Some portability fixes (OSes, python versions).
247
248        Isochronous transfer refuses to round transfer size.
249
250        Better exception handling in enumeration.
251
252        Add examples.
253
254        Better documentation.
255
256        1.2.0
257        -----
258
259        Wrap hotplug API.
260
261        Wrap port number API.
262
263        Wrap kernel auto-detach API.
264
265        Drop wrapper for libusb_strerror, with compatibility place-holder.
266
267        Add a few new upstream enum values.
268
269        1.3.0
270        -----
271
272        **Backward-incompatible change**: Enum class now affects caller's local scope,
273        not its global scope. This should not be of much importance, as:
274
275        - This class is probably very little used outside libusb1.py
276
277        - This class is probably mostly used at module level, where locals == globals.
278
279          It is possible to get former behaviour by providing the new ``scope_dict``
280          parameter to ``Enum`` constructor::
281
282            SOME_ENUM = libusb1.Enum({...}, scope_dict=globals())
283
284        Improve start-up time on CPython by not importing standard ``inspect`` module.
285
286        Fix some more USBTransfer memory leaks.
287
288        Add Transfer.iterISO for more efficient isochronous reception.
289
290        1.3.1
291        -----
292
293        Fixed USBContext.waitForEvent.
294
295        Fix typo in USBInterfaceSetting.getClassTuple method name. Backward
296        compatibility preserved.
297
298        Remove globals accesses from USBDeviceHandle destructor.
299
300        Assorted documentation improvements.
301
302        1.3.2
303        -----
304
305        Made USBDevice instances hashable.
306
307        Relaxed licensing by moving from GPL v2+ to LGPL v2.1+, for consistency with
308        libusb1.
309
310        1.4.0
311        -----
312
313        Reduce (remove ?) the need to import libusb1 module by exposing USBError and
314        constants in usb1 module.
315
316        Fix libusb1.LIBUSB_ENDPOINT_ENDPOINT_MASK and
317        libusb1.LIBUSB_ENDPOINT_DIR_MASK naming.
318
319        Fix pydoc appearance of several USBContext methods.
320
321        Define exception classes for each error values.
322
323        1.4.1
324        -----
325
326        Fix wheel generation (``python3 setup.py bdist_wheel``).
327
328        1.5.0
329        -----
330
331        controlWrite, bulkWrite and interruptWrite now reject (with TypeError) numeric
332        values for ``data`` parameter.
333
334        Fix libusb1.REQUEST_TYPE_* names (were TYPE_*). Preserve backward
335        compatibility.
336
337        Add USBContext.getDeviceIterator method.
338
339        Rename USBContext.exit as USBContext.close for consistency with other USB*
340        classes. Preserve backward compatibility.
341
342        Make USBDeviceHandle.claimInterface a context manager, for easier interface
343        releasing.
344
345        1.5.1
346        -----
347
348        Introduce USBPollerThread.stop .
349
350        Fix USBDeviceHandle.getSupportedLanguageList bug when running under python 3.
351        While fixing this bug it was realised that this method returned ctypes objects.
352        This was not intended, and it now returns regular integers.
353
354        1.5.2
355        -----
356
357        Make USBTransfer.cancel raise specific error instances.
358
359        1.5.3
360        -----
361
362        Fix USBTransfer.cancel exception raising introduced in 1.5.2: it was
363        accidentally becomming a bound method, preventing the raise to actually
364        happen (in at least CPython 2.x) or raising type conversion errors (in at least
365        CPython 3.5.2).
366
367        1.6
368        ---
369
370        Improve asynchronous transfer performance: (very) suboptimal code was used to
371        initialise asynchronous transfer buffer. As a consequence, usb1 now exposes
372        ``bytearrays`` where it used to expose ``bytes`` or ``str`` objects.
373
374        Deprecate libusb1 module import, which should not be needed since all (?)
375        needed constants were re-bound to usb1 module.
376
377        Move testUSB1 module inside usb1, to eventually only expose usb1 as top-level
378        module.
379
380        1.6.1
381        -----
382
383        Fix getSupportedLanguageList.
384
385        Fix and extend get{,ASCII}StringDescriptor .
386
387        Fix iterISO and getISOBufferList.
388
389        1.6.2
390        -----
391
392        Fix getASCIIStringDescriptor: unlike getStringDescriptor, this returns only the
393        payload of the string descriptor, without its header.
394
395        1.6.3
396        -----
397
398        Deprecate USBPollerThread . It is mileading users for which the simple version
399        (a thread calling ``USBContext.handleEvents``) would be enough. And for more
400        advanced uses (ie, actually needing to poll non-libusb file descriptors), this
401        class only works reliably with epoll: kqueue (which should tehcnically work)
402        has a different API on python level, and poll (which has the same API as epoll
403        on python level) lacks the critical ability to change the set of monitored file
404        descriptors while a poll is already running, causing long pauses - if not
405        deadlocks.
406
407        1.6.4
408        -----
409
410        Fix asynchronous control transfers.
411
412        1.6.5
413        -----
414
415        Document hotplug handler limitations.
416
417        Run 2to3 when running setup.py with python3, and reduce differences with
418        python3.
419
420        Properly cast libusb_set_pollfd_notifiers arguments.
421        Fix null pointer value: POINTER(None) is the type of a pointer which may be a
422        null pointer, which falls back to c_void_p. But c_void_p() is an actual null
423        pointer.
424
425        1.6.6
426        -----
427
428        Expose bare string descriptors (aka string indexes) on USBDevice.
429
430        1.6.7
431        -----
432
433        get{,ASCII}StringDescriptor now return None for descriptor 0 instead of raising
434        UnicodeDecodeError. Use getSupportedLanguageList to access it.
435        Moved getManufacturer, getProduct and getSerialNumber to USBDeviceHandle. Kept
436        shortcuts for these on USBDevice.
437
438        1.7
439        ---
440
441        get{,ASCII}StringDescriptor now return None for descriptor 0, use
442        getSupportedLanguageList to get its content.
443        getManufacturer, getProduct and getSerialNumber are now on USBDeviceHandle,
444        with backward-compatibility aliases on their original location.
445        Synchronous bulk and interrupt API exposes number of bytes sent and received
446        bytes even when a timeout occurs.
447
448        1.7.1
449        -----
450
451        usb1.__version__ is now present, managed by versioneer.
452        Fix an occasional segfault when closing a transfer from inside its callback
453        function.
454
455        1.8
456        ---
457
458        Fix getExtra and libusb1.libusb_control_transfer_get_data .
459        Fix getMaxPower unit on SuperSpeed devices.
460
461        1.8.1
462        -----
463
464        Release process rework:
465
466        - embed libusb1 dll for easier deployment on Windows
467        - cryptographically signed releases
468
469        Use libusb_free_pollfds whenever available (libusb1>=1.0.20).
470        Fix hotplug callback destruction at context teardown.
471        Drop remnants of python 2.6 support code.
472
473        1.9
474        ---
475
476        Drop USBPollerThread and deprecate libusb-lock-related USBContext API.
477
478        1.9.1
479        -----
480
481        Fix installation from pypi source tarball, broken in 1.8.1 .
482
483        1.9.2
484        -----
485
486        Windows wheels: Update bundled libusb to 1.0.24 .
487        Fix soure-only build when wheel is not available.
488
489        1.9.3
490        -----
491
492        Add support for pyinstaller.
493        Improve the way the windows dlls are embedded in wheels.
494        Fix support for python 3.10 .
495        Add support for homebrew on Apple M1.
496
497        .. _CPython: http://www.python.org/
498
499        .. _pypy: http://pypy.org/
500
501        .. _Cygwin: https://www.cygwin.com/
502
503        .. _MacPorts: https://www.macports.org/
504
505        .. _Fink: http://www.finkproject.org/
506
507        .. _Homebrew: http://brew.sh/
508
509        .. _libusb-1.0: https://github.com/libusb/libusb/wiki/
510
511        .. _libusb1.0 documentation: http://libusb.sourceforge.net/api-1.0/
512
513Keywords: usb libusb
514Platform: any
515Classifier: Intended Audience :: Developers
516Classifier: License :: OSI Approved :: GNU Lesser General Public License v2 or later (LGPLv2+)
517Classifier: Operating System :: OS Independent
518Classifier: Programming Language :: Python :: 2.7
519Classifier: Programming Language :: Python :: 3
520Classifier: Programming Language :: Python :: 3.4
521Classifier: Programming Language :: Python :: 3.5
522Classifier: Programming Language :: Python :: 3.6
523Classifier: Programming Language :: Python :: 3.7
524Classifier: Programming Language :: Python :: Implementation :: CPython
525Classifier: Programming Language :: Python :: Implementation :: PyPy
526Classifier: Topic :: Software Development :: Libraries
527Classifier: Topic :: System :: Hardware :: Hardware Drivers
528