brp-lib 4.0.2__tar.gz → 4.2.0__tar.gz

{brp_lib-4.0.2 → brp_lib-4.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brp_lib
-Version: 4.0.2
+Version: 4.2.0
 Summary: Low-level C library wrapper for Baltech RFID readers.
 Author-email: Baltech AG <info@baltech.de>
 Requires-Python: >=3.9

{brp_lib-4.0.2 → brp_lib-4.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "brp_lib"
-version = "4.0.2"
+version = "4.2.0"
 description = "Low-level C library wrapper for Baltech RFID readers."
 authors = [{ name = "Baltech AG", email = "info@baltech.de" }]
 requires-python = ">=3.9"

{brp_lib-4.0.2 → brp_lib-4.2.0}/src/brp_lib/__init__.py

@@ -3,16 +3,24 @@ import importlib.resources
 from pathlib import Path
 from typing import Optional, Union
 
-from .protocols import BrpStack, UsbHid, RS232, SecureChannel
+from .protocols import (
+    BrpProtocol, BrpStack, CryptoProtocol, CustomProtocol, IoProtocol, Layer,
+    RS232, SecureChannel, UsbHid,
+)
 from .dll_wrapper import c_brp_lib
 from . import err, protocols
 
 __all__ = [
     "c_brp_lib",
+    "BrpProtocol",
+    "IoProtocol",
+    "CryptoProtocol",
     "BrpStack",
     "UsbHid",
     "RS232",
     "SecureChannel",
+    "CustomProtocol",
+    "Layer",
     "protocols",
     "get_brp_lib_path",
     "set_brp_lib_path",

{brp_lib-4.0.2 → brp_lib-4.2.0}/src/brp_lib/dll_wrapper.py

@@ -1,6 +1,8 @@
 import ctypes
 import typing
 import functools
+import os
+import sys
 from contextlib import suppress
 from pathlib import Path
 from typing import Any, Protocol, TypeVar, Callable, Optional
@@ -105,6 +107,23 @@ class CBrpLibFunction(Protocol[P, R]):
         ...
 
 
+def _decode_path(raw: bytes) -> str:
+    # the DLL builds paths via ANSI Win32 APIs, so they arrive in the current
+    # ANSI code page ("mbcs"), not UTF-8; strict on purpose: never fabricate a
+    # wrong path - callers degrade to None instead
+    if sys.platform == "win32":
+        return raw.decode("mbcs")
+    return os.fsdecode(raw)
+
+
+def _encode_path(path: str) -> bytes:
+    # strict: a path the ANSI code page cannot represent must fail at set time
+    # instead of being silently rewritten by Windows' best-fit mapping
+    if sys.platform == "win32":
+        return path.encode("mbcs")
+    return os.fsencode(path)
+
+
 CharP = Annotated[ctypes.Array[ctypes.c_char], ctypes.c_char_p]
 CharPP = Annotated[Any, ctypes.POINTER(ctypes.c_char_p)]
 CInt = Annotated[int, ctypes.c_int]
@@ -125,6 +144,7 @@ CMempool = Annotated[Any, mempool]
 CIoiter = Annotated[Any, ioiter]
 CIoiterP = Annotated[Any, ioiter_p]
 CUShort = Annotated[int, ctypes.c_ushort]
+CPath = Annotated[Optional[str], ctypes.c_char_p, (_decode_path, _encode_path)]
 
 ErrorCode = Annotated[None, errcode]
 
@@ -140,48 +160,81 @@ def _to_ctype(t: Any) -> Any:
     return t
 
 
-def _get_log_link(prot: Any) -> Optional[str]:
-    path_ptr = c_brp_lib.brp_get_log_path(prot, None)
-    if not path_ptr:
+def _get_codec(t: Any) -> Any:
+    # optional third Annotated arg: a (decode, encode) pair converting this type
+    # at the C boundary (decode: C result -> python, encode: python arg -> C)
+    args = typing.get_args(t)
+    return args[2] if len(args) > 2 else None
+
+
+def _with_codecs(
+        fn: Callable[..., Any], argtypes: Any, restype: Any
+) -> Callable[..., Any]:
+    arg_codecs = [_get_codec(t) for t in argtypes]
+    result_codec = _get_codec(restype)
+    if not any(arg_codecs) and result_codec is None:
+        return fn
+
+    @functools.wraps(fn)
+    def wrapper(*args: Any) -> Any:
+        converted = [
+            codec[1](arg) if codec is not None and arg is not None else arg
+            for codec, arg in zip(arg_codecs, args)
+        ]
+        result = fn(*converted)
+        if result_codec is not None and result is not None:
+            return result_codec[0](result)
+        return result
+
+    return wrapper
+
+
+def _get_log_link(lib: "CBrpLib", prot: Any) -> Optional[str]:
+    log_path = lib.brp_get_log_path(prot, None)
+    if not log_path:
         return None
 
-    path = Path(ctypes.string_at(path_ptr).decode('utf-8'))
+    path = Path(log_path)
     if not path.exists():
         return None
     url = f"{path.as_uri()}"
 
     anchor_ptr = ctypes.c_char_p()
-    c_brp_lib.brp_get_current_log_anchor(prot, ctypes.byref(anchor_ptr), None)
+    lib.brp_get_current_log_anchor(prot, ctypes.byref(anchor_ptr), None)
     if anchor_ptr.value:
         return f"{url}{anchor_ptr.value.decode('utf-8')}"
     return url
 
 
-def with_error_handling(fn: Callable[P, int]) -> Callable[P, None]:
+def with_error_handling(lib: "CBrpLib", fn: Callable[P, int]) -> Callable[P, None]:
+    """Map nonzero errcodes to BrpError, attaching the log link looked up via
+    ``lib`` — the instance the wrapped function belongs to, not the global."""
     @functools.wraps(fn)
     def wrapper(*args: P.args, **kwargs: P.kwargs) -> None:
         result = fn(*args, **kwargs)
         if result:
             log_url = None
-            with suppress():
+            with suppress(Exception):
                 if len(args) > 0 and isinstance(args[0], protocol):
-                    log_url = _get_log_link(args[0])
+                    log_url = _get_log_link(lib, args[0])
             raise BrpError.from_error_code(result, log_url=log_url)
 
     return wrapper
 
 
-def _not_implemented(name: str, version: str, *args: object, **kwargs: object) -> Never:
-    raise NotImplementedError(f"{name} is not implemented in brp_lib {version}")
-
-
 class CBrpLib:
     brp_get_version: CBrpLibFunction[[], CharP]
     brp_create: CBrpLibFunction[[], CProtocol]
+    brp_create_custom: CBrpLibFunction[[CInt], CProtocol]
     brp_destroy: CBrpLibFunction[[CProtocol], ErrorCode]
+    brp_protocol_free: CBrpLibFunction[[CProtocol], None]
     brp_set_io: CBrpLibFunction[[CProtocol, CProtocol], ErrorCode]
+    brp_set_layer: CBrpLibFunction[[CProtocol, CInt, CProtocol], ErrorCode]
+    brp_get_layer: CBrpLibFunction[[CProtocol, CInt], CProtocol]
+    brp_detach_layer: CBrpLibFunction[[CProtocol, CInt], CProtocol]
     brp_open: CBrpLibFunction[[CProtocol], ErrorCode]
     brp_close: CBrpLibFunction[[CProtocol], ErrorCode]
+    brp_flush: CBrpLibFunction[[CProtocol], ErrorCode]
     brp_suppress_monitoring: CBrpLibFunction[[CProtocol], ErrorCode]
     brp_get_io_id: CBrpLibFunction[[CProtocol, CharPP, CFrame], ErrorCode]
     brp_get_friendly_name: CBrpLibFunction[[CProtocol, CharPP], ErrorCode]
@@ -209,9 +262,9 @@ class CBrpLib:
     brp_frame_read_eof: CBrpLibFunction[[CFrameReader], CBool]
     brp_annotation_start: CBrpLibFunction[[CProtocol], None]
     brp_annotation_end: CBrpLibFunction[[CProtocol, CBool, CharP], None]
-    brp_set_log_path: CBrpLibFunction[[CProtocol, CharP], ErrorCode]
+    brp_set_log_path: CBrpLibFunction[[CProtocol, CPath], ErrorCode]
     brp_get_current_log_anchor: CBrpLibFunction[[CProtocol, CharPP, CMempool], ErrorCode]
-    brp_get_log_path: CBrpLibFunction[[CProtocol, CMempool], CharP]
+    brp_get_log_path: CBrpLibFunction[[CProtocol, CMempool], CPath]
 
     def __init__(self) -> None:
         self.__dll_path: Optional[Path] = None
@@ -222,28 +275,29 @@ class CBrpLib:
 
     @dll_path.setter
     def dll_path(self, dll_path: Path) -> None:
-        self.__dll_path = dll_path.absolute()
-        dll = ctypes.CDLL(str(self.__dll_path))
+        abs_path = dll_path.absolute()
+        dll = ctypes.CDLL(str(abs_path))
+        if getattr(dll, "brp_get_version", None) is None:
+            raise ValueError(
+                f"{abs_path} is not a brp_lib library (does not export brp_get_version)"
+            )
+        self.__dll_path = abs_path
 
         for name, annotation in type(self).__annotations__.items():
             if typing.get_origin(annotation) == CBrpLibFunction:
                 argtypes, restype = typing.get_args(annotation)
-                fn = getattr(dll, name, None)
-                if fn is None:
-                    fn = functools.partial(
-                        _not_implemented,
-                        name=name,
-                        version=bytes(self.brp_get_version()).decode("ascii")
-                                if name != "brp_get_version"
-                                else "<unknown>"
-                    )
-                else:
-                    fn.restype = _to_ctype(restype)
-                    fn.argtypes = tuple(map(_to_ctype, argtypes))
-                    if restype == ErrorCode:
-                        fn = with_error_handling(fn)
+                fn: Any = getattr(dll, name, functools.partial(self._raise_not_implemented, name))
+                fn.restype = _to_ctype(restype)
+                fn.argtypes = tuple(map(_to_ctype, argtypes))
+                fn = _with_codecs(fn, argtypes, restype)
+                if restype == ErrorCode:
+                    fn = with_error_handling(self, fn)
                 setattr(self, name, fn)
 
+    def _raise_not_implemented(self, name: str, *args: object, **kwargs: object) -> Never:
+        version = bytes(self.brp_get_version()).decode("ascii")
+        raise NotImplementedError(f"{name} is not implemented in brp_lib {version}")
+
     def __getattr__(self, item: str) -> Any:
         if item in type(self).__annotations__:
             raise RuntimeError("Please initialize the brp_lib path calling `brp_lib.set_brp_lib_path('.../libbrp_lib.so')`.")

{brp_lib-4.0.2 → brp_lib-4.2.0}/src/brp_lib/err.py

@@ -3,6 +3,7 @@ from typing import Dict, Type, Optional
 
 __all__ = [
     "BrpError",
+    "UnknownError",
     "DeviceError",
     "CommunicationError",
     "CommUnsupported",
@@ -63,8 +64,10 @@ class BrpError(Exception, metaclass=abc.ABCMeta):
 
     @classmethod
     def from_error_code(cls, ec: int, *, log_url: Optional[str] = None) -> "BrpError":
-        error_class: Type["BrpError"] = cls.ErrorCodeMap.get(ec, cls)
-        return error_class(log_url=log_url)
+        error_class = cls.ErrorCodeMap.get(ec)
+        if error_class is not None:
+            return error_class(log_url=log_url)
+        return UnknownError(ec, log_url=log_url)
 
     def __init__(self, message: str = "", *, log_url: Optional[str] = None) -> None:
         self.log_url = log_url
@@ -75,7 +78,7 @@ class BrpError(Exception, metaclass=abc.ABCMeta):
             map(str,
                 filter(
                     lambda i: i is not None, [
-                        f"0x{self.ErrorCode:08X} {super()!s}\n",
+                        f"0x{self.ErrorCode:08X} {super().__str__()}\n",
                         f"DESC: {self.__doc__.strip() if self.__doc__ else None}",
                         f"DOCS: {self.URL}" if self.URL else None,
                         f"LOGS: {self.log_url}" if self.log_url else None,
@@ -85,6 +88,13 @@ class BrpError(Exception, metaclass=abc.ABCMeta):
         )
 
 
+class UnknownError(BrpError):
+    """An error with an error code not known to the SDK."""
+    def __init__(self, error_code: int, *, log_url: Optional[str] = None) -> None:
+        self.ErrorCode = error_code
+        super().__init__(log_url=log_url)
+
+
 class CommunicationError(BrpError, metaclass=abc.ABCMeta):
     """Any kind of device <-> host communication problem"""