nfcscript 0.0.11__tar.gz → 0.0.13__tar.gz

{nfcscript-0.0.11 → nfcscript-0.0.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nfcscript
-Version: 0.0.11
+Version: 0.0.13
 Summary: A plugin-based core engine for DSL-style NFC testing automation.
 Author: crthu
 Requires-Python: >=3.14
@@ -123,14 +123,14 @@ connect()
 trace.set_layer("DRIVER", True)
 trace.set_layer("PROTOCOL", True)
 
-# 寻卡
+# 寻卡（自动切换协议解析器）
 card_info = active()
 ASSERT_IS_NOT_NONE(card_info, "未扫描到卡片")
-print(f"UID: {card_info['uid'].hex().upper()}")
+print(f"UID: {' '.join(f'{b:02X}' for b in card_info.uid)}")
 
 # 创建卡片实例
 from nfctester.registry import CardRegistry
-card = CardRegistry.create("mifare", reader=get_reader())
+card = CardRegistry.create("mifare_classic", reader=get_reader())
 
 # 关闭连接
 close()
@@ -142,8 +142,8 @@ close()
 from nfc import *
 
 with session() as reader:
-    card_info = reader.find()
-    print(card_info)
+    card_info = reader.active()
+    print(card_info.uid)
 # 自动断开连接
 ```
 
@@ -167,7 +167,7 @@ with session() as reader:
 |------|------|
 | `connect(port, reader_type)` | 连接读卡器 |
 | `get_reader()` | 获取当前读卡器实例 |
-| `active(low_layer, ignore_error, reqa_cmd)` | 寻卡，返回 uid/atq/sak |
+| `active(low_layer, ignore_error, reqa_cmd)` | 寻卡，返回 CardInfo (uid/atq/sak)，自动切换协议解析器 |
 | `transceive(data, tx_crc, rx_crc)` | 底层帧交互 |
 | `transceive_bits(data, last_tx_bits, tx_crc, rx_crc)` | 位控制帧交互 |
 | `reqa()` | ISO14443-A REQA |
@@ -185,6 +185,9 @@ with session() as reader:
 |------|------|
 | `trace.set_layer(layer, enable)` | 开启/关闭追踪层 |
 | `trace.set_level(level)` | 设置日志级别 |
+| `trace.set_parse(level)` | 设置解析级别 (0=关闭, 1=hex+摘要) |
+| `trace.add_sink(fn)` | 注册结构化 trace 事件回调 |
+| `trace.remove_sink(fn)` | 移除已注册的回调 |
 | `trace.info(msg)` / `trace.error(msg)` / `trace.warning(msg)` / `trace.success(msg)` / `trace.debug(msg)` | 输出日志 |
 
 ### assertions.py

{nfcscript-0.0.11 → nfcscript-0.0.13}/README.md

@@ -113,14 +113,14 @@ connect()
 trace.set_layer("DRIVER", True)
 trace.set_layer("PROTOCOL", True)
 
-# 寻卡
+# 寻卡（自动切换协议解析器）
 card_info = active()
 ASSERT_IS_NOT_NONE(card_info, "未扫描到卡片")
-print(f"UID: {card_info['uid'].hex().upper()}")
+print(f"UID: {' '.join(f'{b:02X}' for b in card_info.uid)}")
 
 # 创建卡片实例
 from nfctester.registry import CardRegistry
-card = CardRegistry.create("mifare", reader=get_reader())
+card = CardRegistry.create("mifare_classic", reader=get_reader())
 
 # 关闭连接
 close()
@@ -132,8 +132,8 @@ close()
 from nfc import *
 
 with session() as reader:
-    card_info = reader.find()
-    print(card_info)
+    card_info = reader.active()
+    print(card_info.uid)
 # 自动断开连接
 ```
 
@@ -157,7 +157,7 @@ with session() as reader:
 |------|------|
 | `connect(port, reader_type)` | 连接读卡器 |
 | `get_reader()` | 获取当前读卡器实例 |
-| `active(low_layer, ignore_error, reqa_cmd)` | 寻卡，返回 uid/atq/sak |
+| `active(low_layer, ignore_error, reqa_cmd)` | 寻卡，返回 CardInfo (uid/atq/sak)，自动切换协议解析器 |
 | `transceive(data, tx_crc, rx_crc)` | 底层帧交互 |
 | `transceive_bits(data, last_tx_bits, tx_crc, rx_crc)` | 位控制帧交互 |
 | `reqa()` | ISO14443-A REQA |
@@ -175,6 +175,9 @@ with session() as reader:
 |------|------|
 | `trace.set_layer(layer, enable)` | 开启/关闭追踪层 |
 | `trace.set_level(level)` | 设置日志级别 |
+| `trace.set_parse(level)` | 设置解析级别 (0=关闭, 1=hex+摘要) |
+| `trace.add_sink(fn)` | 注册结构化 trace 事件回调 |
+| `trace.remove_sink(fn)` | 移除已注册的回调 |
 | `trace.info(msg)` / `trace.error(msg)` / `trace.warning(msg)` / `trace.success(msg)` / `trace.debug(msg)` | 输出日志 |
 
 ### assertions.py

{nfcscript-0.0.11 → nfcscript-0.0.13}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nfcscript"
-version = "0.0.11"
+version = "0.0.13"
 description = "A plugin-based core engine for DSL-style NFC testing automation."
 readme = "README.md"
 requires-python = ">=3.14"
@@ -34,7 +34,7 @@ dev = [
 ]
 
 [tool.bumpversion]
-current_version = "0.0.11"
+current_version = "0.0.13"
 commit = true
 tag = true
 allow_dirty = true

{nfcscript-0.0.11 → nfcscript-0.0.13}/src/nfc/cli.py

@@ -59,8 +59,6 @@ def main():
     parser.add_argument("--trace-protocol", action="store_true", help="开启 PROTOCOL 层追踪")
     parser.add_argument("--trace-parse", type=int, default=None, choices=[0, 1, 2],
                         help="解析级别: 0=关闭 1=简单 2=复杂 (默认: NFC_TRACE_PARSE 或 1)")
-    parser.add_argument("--trace-card-type", default=None,
-                        help="卡片类型标识 (默认: NFC_TRACE_CARD_TYPE)")
     parser.add_argument("--trace-level", default="INFO", help="日志级别 (默认: INFO)")
 
     args, extra = parser.parse_known_args()
@@ -87,7 +85,6 @@ def main():
     trace_driver = os.environ.get("NFC_TRACE_DRIVER", "").lower() in ("1", "true", "yes")
     trace_protocol = os.environ.get("NFC_TRACE_PROTOCOL", "").lower() in ("1", "true", "yes")
     trace_parse = os.environ.get("NFC_TRACE_PARSE", "1")
-    trace_card_type = os.environ.get("NFC_TRACE_CARD_TYPE")
     trace_width = os.environ.get("NFC_TRACE_WIDTH")
 
     if args.trace_level != "INFO":
@@ -98,15 +95,11 @@ def main():
         trace_protocol = True
     if args.trace_parse is not None:
         trace_parse = str(args.trace_parse)
-    if args.trace_card_type is not None:
-        trace_card_type = args.trace_card_type
 
     trace.set_level(trace_level)
     trace.set_layer("DRIVER", trace_driver)
     trace.set_layer("PROTOCOL", trace_protocol)
     trace.set_parse(_parse_level(trace_parse))
-    if trace_card_type is not None:
-        trace.set_card_type(trace_card_type)
     if trace_width is not None:
         os.environ["CRFT_TRACE_WIDTH"] = trace_width
 

{nfcscript-0.0.11 → nfcscript-0.0.13}/src/nfc/reader.py

@@ -2,6 +2,7 @@ import os
 from contextlib import contextmanager
 from nfctester.drivers.card_reader import CardInfo, TransceiveBits
 from nfctester.registry import CardReaderRegistry
+from nfctester.trace import trace as _trace
 from .assertions import ASSERT_EQUAL, ASSERT_IS_NOT_NONE, ASSERT_LEN
 from .checksum import GET_BCC
 from .hex_util import FORMAT_HEX
@@ -102,7 +103,7 @@ def active(low_layer: bool = False, ignore_error: bool = False, reqa_cmd: int =
     # 手动底层寻卡流程
     # 1. REQA
     res_reqa = reqa(cmd=reqa_cmd)
-    if not res_reqa:
+    if not res_reqa.data:
         return None
     atq = res_reqa.data
 
@@ -110,7 +111,7 @@ def active(low_layer: bool = False, ignore_error: bool = False, reqa_cmd: int =
     full_uid = []
     for cl in [1, 2, 3]:
         res = anticoll(cl_level=cl, nvb=0x20)
-        if not res or not res.data:
+        if not res.data:
             return None
 
         data = res.data
@@ -146,7 +147,10 @@ def active(low_layer: bool = False, ignore_error: bool = False, reqa_cmd: int =
             sak = sak_res[0] if sak_res else 0
             break
 
-    return CardInfo(uid=full_uid, atq=atq, sak=sak)
+    info = CardInfo(uid=full_uid, atq=atq, sak=sak)
+    atqa = int.from_bytes(atq, "little")
+    _trace.set_parser(atqa, sak)
+    return info
 
 
 def transceive(data: list[int], tx_crc: bool = True, rx_crc: bool = True) -> list[int]:
@@ -167,7 +171,7 @@ def transceive(data: list[int], tx_crc: bool = True, rx_crc: bool = True) -> lis
     return res.data if res and res.data else []
 
 
-def transceive_bits(data: list[int], last_tx_bits: int = 0, tx_crc: bool = True, rx_crc: bool = True) -> TransceiveBits | None:
+def transceive_bits(data: list[int], last_tx_bits: int = 0, tx_crc: bool = True, rx_crc: bool = True) -> TransceiveBits:
     """
     使用底层帧交互方式发送数据，并支持对最后一个字节进行位控制。
 
@@ -178,14 +182,15 @@ def transceive_bits(data: list[int], last_tx_bits: int = 0, tx_crc: bool = True,
         rx_crc: 接收时是否自动校验 CRC。False 则原样接收不校验。
 
     Returns:
-        TransceiveBits | None: 包含 data 和 bits 属性，失败返回 None。
+        TransceiveBits: 包含 data 和 bits 属性，失败返回空的 TransceiveBits(data=[], bits=0)。
     """
     _state.ensure_connected()
     reader = _state.reader
-    return reader.transceive(data, last_tx_bits=last_tx_bits, tx_crc=tx_crc, rx_crc=rx_crc)
+    res = reader.transceive(data, last_tx_bits=last_tx_bits, tx_crc=tx_crc, rx_crc=rx_crc)
+    return res if res else TransceiveBits(data=[], bits=0)
 
 
-def reqa(cmd: int = 0x26) -> TransceiveBits | None:
+def reqa(cmd: int = 0x26) -> TransceiveBits:
     """
     ISO14443-A REQA (7 bits)。
 
@@ -193,27 +198,27 @@ def reqa(cmd: int = 0x26) -> TransceiveBits | None:
         cmd: REQA 命令字节，默认 0x26。
 
     Returns:
-        TransceiveBits | None: 包含 data 和 bits 属性，失败返回 None。
+        TransceiveBits: 包含 data 和 bits 属性，失败返回空的 TransceiveBits(data=[], bits=0)。
     """
     return transceive_bits([cmd], last_tx_bits=7, tx_crc=False, rx_crc=False)
 
 
-def wupa() -> TransceiveBits | None:
+def wupa() -> TransceiveBits:
     """
     ISO14443-A WUPA (7 bits)。
 
     Returns:
-        TransceiveBits | None: 包含 data 和 bits 属性，失败返回 None。
+        TransceiveBits: 包含 data 和 bits 属性，失败返回空的 TransceiveBits(data=[], bits=0)。
     """
     return transceive_bits([0x52], last_tx_bits=7, tx_crc=False, rx_crc=False)
 
 
-def halt() -> list[int] | None:
+def halt() -> list[int]:
     """
     ISO14443-A HALT (Standard Frame)。
 
     Returns:
-        list[int] | None: 返回响应数据，失败返回 None。
+        list[int]: 返回响应数据。
     """
     return transceive([0x50, 0x00], tx_crc=True, rx_crc=True)
 
@@ -237,7 +242,7 @@ def _get_sel_cmd(cl_level: int) -> int:
     return sel_map[cl_level]
 
 
-def anticoll(cl_level: int, nvb: int = 0x20, uid_prefix: list[int] = []) -> TransceiveBits | None:
+def anticoll(cl_level: int, nvb: int = 0x20, uid_prefix: list[int] = []) -> TransceiveBits:
     """
     ISO14443-A ANTICOLL (Anti-collision)。
 
@@ -247,13 +252,13 @@ def anticoll(cl_level: int, nvb: int = 0x20, uid_prefix: list[int] = []) -> Tran
         uid_prefix: 已知的部分 UID (0-4 字节)。
 
     Returns:
-        TransceiveBits | None: 包含 data 和 bits 属性，失败返回 None。
+        TransceiveBits: 包含 data 和 bits 属性，失败返回空的 TransceiveBits(data=[], bits=0)。
     """
     cmd = [_get_sel_cmd(cl_level), nvb] + uid_prefix
     return transceive_bits(cmd, last_tx_bits=0, tx_crc=False, rx_crc=False)
 
 
-def select(cl_level: int, uid: list[int]) -> list[int] | None:
+def select(cl_level: int, uid: list[int]) -> list[int]:
     """
     ISO14443-A SELECT (Standard Frame)。
 
@@ -262,7 +267,7 @@ def select(cl_level: int, uid: list[int]) -> list[int] | None:
         uid: 完整 5 字节 UID (包含 BCC)。
 
     Returns:
-        list[int] | None: 返回响应数据，失败返回 None。
+        list[int]: 返回响应数据。
     """
     cmd = [_get_sel_cmd(cl_level), 0x70] + uid
     return transceive(cmd, tx_crc=True, rx_crc=True)

{nfcscript-0.0.11 → nfcscript-0.0.13}/src/nfc/trace.py

@@ -39,16 +39,6 @@ def set_parse(level: int = 1):
     _trace.set_parse(level)
 
 
-def set_card_type(card_type: str):
-    """
-    设置当前卡片类型，注入到所有协议解析器的 state 中。
-
-    Args:
-        card_type: 卡片类型标识，如 "mifare_classic_1k", "ntag213"
-    """
-    _trace.set_card_type(card_type)
-
-
 def info(msg: str):
     """输出 INFO 级别日志"""
     _trace.info(msg)

{nfcscript-0.0.11 → nfcscript-0.0.13}/src/nfcscript.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nfcscript
-Version: 0.0.11
+Version: 0.0.13
 Summary: A plugin-based core engine for DSL-style NFC testing automation.
 Author: crthu
 Requires-Python: >=3.14
@@ -123,14 +123,14 @@ connect()
 trace.set_layer("DRIVER", True)
 trace.set_layer("PROTOCOL", True)
 
-# 寻卡
+# 寻卡（自动切换协议解析器）
 card_info = active()
 ASSERT_IS_NOT_NONE(card_info, "未扫描到卡片")
-print(f"UID: {card_info['uid'].hex().upper()}")
+print(f"UID: {' '.join(f'{b:02X}' for b in card_info.uid)}")
 
 # 创建卡片实例
 from nfctester.registry import CardRegistry
-card = CardRegistry.create("mifare", reader=get_reader())
+card = CardRegistry.create("mifare_classic", reader=get_reader())
 
 # 关闭连接
 close()
@@ -142,8 +142,8 @@ close()
 from nfc import *
 
 with session() as reader:
-    card_info = reader.find()
-    print(card_info)
+    card_info = reader.active()
+    print(card_info.uid)
 # 自动断开连接
 ```
 
@@ -167,7 +167,7 @@ with session() as reader:
 |------|------|
 | `connect(port, reader_type)` | 连接读卡器 |
 | `get_reader()` | 获取当前读卡器实例 |
-| `active(low_layer, ignore_error, reqa_cmd)` | 寻卡，返回 uid/atq/sak |
+| `active(low_layer, ignore_error, reqa_cmd)` | 寻卡，返回 CardInfo (uid/atq/sak)，自动切换协议解析器 |
 | `transceive(data, tx_crc, rx_crc)` | 底层帧交互 |
 | `transceive_bits(data, last_tx_bits, tx_crc, rx_crc)` | 位控制帧交互 |
 | `reqa()` | ISO14443-A REQA |
@@ -185,6 +185,9 @@ with session() as reader:
 |------|------|
 | `trace.set_layer(layer, enable)` | 开启/关闭追踪层 |
 | `trace.set_level(level)` | 设置日志级别 |
+| `trace.set_parse(level)` | 设置解析级别 (0=关闭, 1=hex+摘要) |
+| `trace.add_sink(fn)` | 注册结构化 trace 事件回调 |
+| `trace.remove_sink(fn)` | 移除已注册的回调 |
 | `trace.info(msg)` / `trace.error(msg)` / `trace.warning(msg)` / `trace.success(msg)` / `trace.debug(msg)` | 输出日志 |
 
 ### assertions.py

{nfcscript-0.0.11 → nfcscript-0.0.13}/tests/test_trace.py

@@ -37,14 +37,6 @@ class TestSetParse:
         mock_trace.set_parse.assert_called_once_with(2)
 
 
-class TestSetCardType:
-
-    @patch("nfc.trace._trace")
-    def test_set_card_type(self, mock_trace):
-        trace.set_card_type("mifare_classic_1k")
-        mock_trace.set_card_type.assert_called_once_with("mifare_classic_1k")
-
-
 class TestLogFunctions:
 
     @patch("nfc.trace._trace")