Metadata-Version: 2.1
Name: libusb-package
Version: 1.0.24.0
Summary: Package containing libusb so it can be installed via Python package managers
Home-page: https://github.com/pyocd/libusb-package
Author: Chris Reed
Author-email: flit@me.com
License: Apache 2.0
Project-URL: Home, https://github.com/pyocd/libusb-package
Project-URL: Documentation, https://github.com/pyocd/libusb-package/docs
Project-URL: Bug Tracker, https://github.com/pyocd/libusb-package/issues
Project-URL: Discussions, https://github.com/pyocd/libusb-package/discussions
Project-URL: Changelog, https://github.com/pyocd/libusb-package/releases
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: importlib-resources ; python_version < "3.7"

# Container package for libusb

This Python package functions as an installation vehicle for libusb shared libraries, to
simplify installation of tools that require libusb. The main use case is so that users
don't have to install libusb manually for projects that use pyusb. However, any Python
project that uses a libusb wrapper can also benefit.


## APIs

There are four public functions exported by `libusb_package`.

- `find(*args, **kwargs)`: Wrapper around pyusb's `usb.core.find()` that sets the `backend`
    parameter to a libusb1 backend created from the libusb library included in `libusb_package`.
    All other parameters are passed unmodified

- `get_libusb1_backend()`: Returns a `pyusb` backend object for the libusb version contained
    in `libusb_package`.

- `find_library(candidate)`: Lower level function that returns either the full path to a
    library contained in `libusb_package` with a name starting with `candidate`, or None if
    no matching library is found. This function is suitable for use with the `find_library`
    callback parameter for pyusb's `get_backend()` functions.

    If `get_library_path()` returns None, indicating there is no included library, this function
    will fall back to `ctypes.util.find_library()`.

- `get_library_path()`: Returns an absolute Path object for the included library. If there is not
    an included library, None is returned.

Both `get_libusb1_backend()` and `get_library_path()` cache their return values.


## Versioning

The version of libusb-package is composed of the libusb version plus an additional field for
the version of the Python code. For instance, 1.0.24.0. The Python code version will be reset
to 0 when the libusb version is incremented for new libusb release.


## Examples

Usage example for `find()`:

```py
import libusb_package

for dev in libusb_package.find(find_all=True):
    print(dev)
```


Usage example for `find_library()`:

```py
import libusb_package
import usb.core
import usb.backend.libusb1

libusb1_backend = usb.backend.libusb1.get_backend(find_library=libusb_package.find_library)
# -> calls usb.libloader.load_locate_library(
#                ('usb-1.0', 'libusb-1.0', 'usb'),
#                'cygusb-1.0.dll', 'Libusb 1',
#                win_cls=win_cls,
#                find_library=find_library, check_symbols=('libusb_init',))
#
# -> calls find_library(candidate) with candidate in ('usb-1.0', 'libusb-1.0', 'usb')
#   returns lib name or path (as appropriate for OS) if matching lib is found

# It would also be possible to pass the output of libusb_package.get_libsusb1_backend()
# to the backend parameter here. In fact, that function is simply a shorthand for the line
# above.
print(list(usb.core.find(find_all=True, backend=libusb1_backend)))
```


### Source distribution

Before building a source distribution, be sure to clean all untracked files from the libusb
submodule using `git -C src/libusb clean -dfx`.


