nfcscript 0.0.1__tar.gz → 0.0.7__tar.gz

nfcscript-0.0.7/PKG-INFO

@@ -0,0 +1,264 @@
+Metadata-Version: 2.4
+Name: nfcscript
+Version: 0.0.7
+Summary: A plugin-based core engine for DSL-style NFC testing automation.
+Author: crthu
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+Requires-Dist: nfctester
+Requires-Dist: python-dotenv
+
+# nfcscript
+
+NFC 测试脚本 DSL 执行环境，基于 `nfctester` 插件化架构。
+
+## 安装
+
+```bash
+uv sync
+```
+
+## 使用
+
+### nfcscript - 脚本执行
+
+```bash
+nfcscript test_card.py
+```
+
+#### 常用参数
+
+```bash
+# 指定串口
+nfcscript test_card.py -p COM21
+
+# 指定读卡器类型
+nfcscript test_card.py -r acr122u
+
+# 开启追踪层
+nfcscript test_card.py --trace-driver --trace-protocol
+
+# 设置日志级别
+nfcscript test_card.py --trace-level DEBUG
+
+# 组合使用
+nfcscript test_card.py -p COM21 -r pn532 --trace-driver --trace-protocol --trace-level DEBUG
+```
+
+### nfc-cli - 交互式命令行
+
+```bash
+# 列出所有可用卡片类型
+nfc-cli --list-cards
+
+# 连接卡片并进入交互模式
+nfc-cli -c ntag224 -p COM21
+
+# 指定读卡器类型
+nfc-cli -c mifare_classic -p COM21 -r pn532
+
+# 通过环境变量自动发现外部卡片
+export NFC_CARD_PATH="../scripts/lib"
+nfc-cli -c sm7 -p COM20
+
+# 或手动指定
+nfc-cli -c sm7 -p COM20 -i ../scripts/lib
+```
+
+#### 交互命令
+
+进入交互模式后，可以输入命令操作卡片：
+
+```
+> help              # 显示可用命令
+> auth 7 FFFFFFFFFFFF  # 认证块 7
+> read 10           # 读取页 10
+> write 20 AABBCCDD... # 写入页 20
+> quit              # 退出
+```
+
+支持的值格式：
+- 十六进制: `0xFF`, `0xAABBCCDD`
+- 十进制: `7`, `255`
+- 字节串: `b'\xff\x00'`
+
+#### 导入外部卡片
+
+使用 `-i` 参数导入外部卡片模块，支持单个 `.py` 文件或包含 `__init__.py` 的目录：
+
+```bash
+# 导入单个文件
+nfc-cli -c my_card -p COM20 -i /path/to/my_card.py
+
+# 导入目录（需要有 __init__.py）
+nfc-cli -c sm7 -p COM20 -i /path/to/lib
+```
+
+外部卡片模块需要使用 `@CardRegistry.register("name")` 装饰器注册。
+
+#### 示例
+
+```bash
+# NTAG224 认证并读取
+nfc-cli -c ntag224 -p COM21
+> auth 1 AABBCCDD112233445566778899001122
+> read 4
+
+# Mifare Classic 操作
+nfc-cli -c mifare_classic -p COM21
+> authenticate 7 FFFFFFFFFFFF
+> read_block 8
+> write_block 9 AABBCCDD112233445566778899001122
+```
+
+### 脚本示例
+
+```python
+from nfc import *
+
+# 连接读卡器 (默认使用环境变量 NFC_PORT 或 COM20)
+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()}")
+
+# 创建卡片实例
+from nfctester.registry import CardRegistry
+card = CardRegistry.create("mifare", reader=get_reader())
+
+# 关闭连接
+close()
+```
+
+### 上下文管理器
+
+```python
+from nfc import *
+
+with session() as reader:
+    card_info = reader.find()
+    print(card_info)
+# 自动断开连接
+```
+
+## 模块说明
+
+| 模块 | 说明 |
+|------|------|
+| `reader.py` | 读卡器连接与通信 |
+| `trace.py` | 日志追踪控制 |
+| `assertions.py` | 测试断言 |
+| `bits.py` | 位操作工具 |
+| `hex_util.py` | 十六进制工具 |
+| `checksum.py` | 校验工具 |
+| `delay.py` | 延时工具 |
+
+## API 参考
+
+### reader.py
+
+| 函数 | 说明 |
+|------|------|
+| `connect(port, reader_type)` | 连接读卡器 |
+| `get_reader()` | 获取当前读卡器实例 |
+| `active(ll, ignore_error)` | 寻卡，返回 uid/atq/sak |
+| `transceive(data, tx_crc, rx_crc)` | 底层帧交互 |
+| `transceive_bits(data, last_tx_bits, tx_crc, rx_crc)` | 位控制帧交互 |
+| `reqa()` | ISO14443-A REQA |
+| `wupa()` | ISO14443-A WUPA |
+| `halt()` | ISO14443-A HALT |
+| `select(cl_level, uid)` | ISO14443-A SELECT |
+| `anticoll(cl_level, nvb, uid_prefix)` | ISO14443-A ANTICOLL |
+| `field_on()` / `field_off()` | RF 场控制 |
+| `session(port, reader_type)` | 上下文管理器 |
+| `close()` | 断开连接 |
+
+### trace.py
+
+| 函数 | 说明 |
+|------|------|
+| `trace.set_layer(layer, enable)` | 开启/关闭追踪层 |
+| `trace.set_level(level)` | 设置日志级别 |
+| `trace.info(msg)` / `trace.error(msg)` / `trace.warning(msg)` / `trace.success(msg)` / `trace.debug(msg)` | 输出日志 |
+
+### assertions.py
+
+| 函数 | 说明 |
+|------|------|
+| `ASSERT_EQUAL(expected, actual, msg)` | 相等断言 |
+| `ASSERT_LEN(data, expected_len, msg)` | 长度断言 |
+| `ASSERT_IS_NOT_NONE(value, msg)` | 非空断言 |
+| `ASSERT_IS_NONE(value, msg)` | 空值断言 |
+
+### bits.py
+
+| 函数 | 说明 |
+|------|------|
+| `BITS_UPDATE(val, mask, data)` | Read-Modify-Write |
+| `BITS_SET(val, mask)` | 置位 |
+| `BITS_RESET(val, mask)` | 清位 |
+
+### hex_util.py
+
+| 函数 | 说明 |
+|------|------|
+| `PARSE_HEX(text)` | 解析 hex 字符串 |
+| `FORMAT_HEX(data, last_bits)` | 格式化为可视化 hex |
+
+### checksum.py
+
+| 函数 | 说明 |
+|------|------|
+| `GET_BCC(data)` | 计算异或校验 |
+
+### delay.py
+
+| 函数 | 说明 |
+|------|------|
+| `DELAY_MS(ms)` | 毫秒延时 |
+
+## 环境变量
+
+优先级: CLI 参数 > 内层 `.env` > 外层 `.env` > 系统环境变量 (必须配置，否则报错)
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `NFC_PORT` | 串口号 | - |
+| `NFC_READER` | 读卡器类型 | - |
+| `NFC_TRACE_LEVEL` | 日志级别 | `INFO` |
+| `NFC_TRACE_DRIVER` | 开启 DRIVER 层追踪 | `false` |
+| `NFC_TRACE_PROTOCOL` | 开启 PROTOCOL 层追踪 | `false` |
+| `NFC_CARD_PATH` | 外部卡片模块搜索路径 (分号分隔) | - |
+
+支持多层 `.env` 加载：从脚本目录向上搜索所有 `.env` 文件，按从外到内的顺序依次加载（内层覆盖外层同名变量）。
+
+例如，脚本位于 `/project/tests/run.py`，沿途有 `/project/.env` 和 `/project/tests/.env`，加载顺序为：
+
+1. `/project/.env` (基础配置)
+2. `/project/tests/.env` (覆盖基础配置中的同名变量)
+
+在项目根目录或脚本所在目录创建 `.env` 文件进行持久化配置：
+
+```
+NFC_PORT=COM20
+NFC_READER=pn532
+NFC_TRACE_LEVEL=DEBUG
+NFC_TRACE_DRIVER=true
+NFC_TRACE_PROTOCOL=true
+```
+
+## 开发
+
+```bash
+# 运行测试
+uv run pytest
+
+# 运行特定测试
+uv run pytest tests/test_xxx.py
+```

nfcscript-0.0.7/README.md

@@ -0,0 +1,254 @@
+# nfcscript
+
+NFC 测试脚本 DSL 执行环境，基于 `nfctester` 插件化架构。
+
+## 安装
+
+```bash
+uv sync
+```
+
+## 使用
+
+### nfcscript - 脚本执行
+
+```bash
+nfcscript test_card.py
+```
+
+#### 常用参数
+
+```bash
+# 指定串口
+nfcscript test_card.py -p COM21
+
+# 指定读卡器类型
+nfcscript test_card.py -r acr122u
+
+# 开启追踪层
+nfcscript test_card.py --trace-driver --trace-protocol
+
+# 设置日志级别
+nfcscript test_card.py --trace-level DEBUG
+
+# 组合使用
+nfcscript test_card.py -p COM21 -r pn532 --trace-driver --trace-protocol --trace-level DEBUG
+```
+
+### nfc-cli - 交互式命令行
+
+```bash
+# 列出所有可用卡片类型
+nfc-cli --list-cards
+
+# 连接卡片并进入交互模式
+nfc-cli -c ntag224 -p COM21
+
+# 指定读卡器类型
+nfc-cli -c mifare_classic -p COM21 -r pn532
+
+# 通过环境变量自动发现外部卡片
+export NFC_CARD_PATH="../scripts/lib"
+nfc-cli -c sm7 -p COM20
+
+# 或手动指定
+nfc-cli -c sm7 -p COM20 -i ../scripts/lib
+```
+
+#### 交互命令
+
+进入交互模式后，可以输入命令操作卡片：
+
+```
+> help              # 显示可用命令
+> auth 7 FFFFFFFFFFFF  # 认证块 7
+> read 10           # 读取页 10
+> write 20 AABBCCDD... # 写入页 20
+> quit              # 退出
+```
+
+支持的值格式：
+- 十六进制: `0xFF`, `0xAABBCCDD`
+- 十进制: `7`, `255`
+- 字节串: `b'\xff\x00'`
+
+#### 导入外部卡片
+
+使用 `-i` 参数导入外部卡片模块，支持单个 `.py` 文件或包含 `__init__.py` 的目录：
+
+```bash
+# 导入单个文件
+nfc-cli -c my_card -p COM20 -i /path/to/my_card.py
+
+# 导入目录（需要有 __init__.py）
+nfc-cli -c sm7 -p COM20 -i /path/to/lib
+```
+
+外部卡片模块需要使用 `@CardRegistry.register("name")` 装饰器注册。
+
+#### 示例
+
+```bash
+# NTAG224 认证并读取
+nfc-cli -c ntag224 -p COM21
+> auth 1 AABBCCDD112233445566778899001122
+> read 4
+
+# Mifare Classic 操作
+nfc-cli -c mifare_classic -p COM21
+> authenticate 7 FFFFFFFFFFFF
+> read_block 8
+> write_block 9 AABBCCDD112233445566778899001122
+```
+
+### 脚本示例
+
+```python
+from nfc import *
+
+# 连接读卡器 (默认使用环境变量 NFC_PORT 或 COM20)
+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()}")
+
+# 创建卡片实例
+from nfctester.registry import CardRegistry
+card = CardRegistry.create("mifare", reader=get_reader())
+
+# 关闭连接
+close()
+```
+
+### 上下文管理器
+
+```python
+from nfc import *
+
+with session() as reader:
+    card_info = reader.find()
+    print(card_info)
+# 自动断开连接
+```
+
+## 模块说明
+
+| 模块 | 说明 |
+|------|------|
+| `reader.py` | 读卡器连接与通信 |
+| `trace.py` | 日志追踪控制 |
+| `assertions.py` | 测试断言 |
+| `bits.py` | 位操作工具 |
+| `hex_util.py` | 十六进制工具 |
+| `checksum.py` | 校验工具 |
+| `delay.py` | 延时工具 |
+
+## API 参考
+
+### reader.py
+
+| 函数 | 说明 |
+|------|------|
+| `connect(port, reader_type)` | 连接读卡器 |
+| `get_reader()` | 获取当前读卡器实例 |
+| `active(ll, ignore_error)` | 寻卡，返回 uid/atq/sak |
+| `transceive(data, tx_crc, rx_crc)` | 底层帧交互 |
+| `transceive_bits(data, last_tx_bits, tx_crc, rx_crc)` | 位控制帧交互 |
+| `reqa()` | ISO14443-A REQA |
+| `wupa()` | ISO14443-A WUPA |
+| `halt()` | ISO14443-A HALT |
+| `select(cl_level, uid)` | ISO14443-A SELECT |
+| `anticoll(cl_level, nvb, uid_prefix)` | ISO14443-A ANTICOLL |
+| `field_on()` / `field_off()` | RF 场控制 |
+| `session(port, reader_type)` | 上下文管理器 |
+| `close()` | 断开连接 |
+
+### trace.py
+
+| 函数 | 说明 |
+|------|------|
+| `trace.set_layer(layer, enable)` | 开启/关闭追踪层 |
+| `trace.set_level(level)` | 设置日志级别 |
+| `trace.info(msg)` / `trace.error(msg)` / `trace.warning(msg)` / `trace.success(msg)` / `trace.debug(msg)` | 输出日志 |
+
+### assertions.py
+
+| 函数 | 说明 |
+|------|------|
+| `ASSERT_EQUAL(expected, actual, msg)` | 相等断言 |
+| `ASSERT_LEN(data, expected_len, msg)` | 长度断言 |
+| `ASSERT_IS_NOT_NONE(value, msg)` | 非空断言 |
+| `ASSERT_IS_NONE(value, msg)` | 空值断言 |
+
+### bits.py
+
+| 函数 | 说明 |
+|------|------|
+| `BITS_UPDATE(val, mask, data)` | Read-Modify-Write |
+| `BITS_SET(val, mask)` | 置位 |
+| `BITS_RESET(val, mask)` | 清位 |
+
+### hex_util.py
+
+| 函数 | 说明 |
+|------|------|
+| `PARSE_HEX(text)` | 解析 hex 字符串 |
+| `FORMAT_HEX(data, last_bits)` | 格式化为可视化 hex |
+
+### checksum.py
+
+| 函数 | 说明 |
+|------|------|
+| `GET_BCC(data)` | 计算异或校验 |
+
+### delay.py
+
+| 函数 | 说明 |
+|------|------|
+| `DELAY_MS(ms)` | 毫秒延时 |
+
+## 环境变量
+
+优先级: CLI 参数 > 内层 `.env` > 外层 `.env` > 系统环境变量 (必须配置，否则报错)
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `NFC_PORT` | 串口号 | - |
+| `NFC_READER` | 读卡器类型 | - |
+| `NFC_TRACE_LEVEL` | 日志级别 | `INFO` |
+| `NFC_TRACE_DRIVER` | 开启 DRIVER 层追踪 | `false` |
+| `NFC_TRACE_PROTOCOL` | 开启 PROTOCOL 层追踪 | `false` |
+| `NFC_CARD_PATH` | 外部卡片模块搜索路径 (分号分隔) | - |
+
+支持多层 `.env` 加载：从脚本目录向上搜索所有 `.env` 文件，按从外到内的顺序依次加载（内层覆盖外层同名变量）。
+
+例如，脚本位于 `/project/tests/run.py`，沿途有 `/project/.env` 和 `/project/tests/.env`，加载顺序为：
+
+1. `/project/.env` (基础配置)
+2. `/project/tests/.env` (覆盖基础配置中的同名变量)
+
+在项目根目录或脚本所在目录创建 `.env` 文件进行持久化配置：
+
+```
+NFC_PORT=COM20
+NFC_READER=pn532
+NFC_TRACE_LEVEL=DEBUG
+NFC_TRACE_DRIVER=true
+NFC_TRACE_PROTOCOL=true
+```
+
+## 开发
+
+```bash
+# 运行测试
+uv run pytest
+
+# 运行特定测试
+uv run pytest tests/test_xxx.py
+```

{nfcscript-0.0.1 → nfcscript-0.0.7}/pyproject.toml

@@ -1,19 +1,21 @@
 [project]
 name = "nfcscript"
-version = "0.0.1"
-description = "NFC test script"
+version = "0.0.7"
+description = "A plugin-based core engine for DSL-style NFC testing automation."
 readme = "README.md"
 requires-python = ">=3.14"
 authors = [{name = "crthu"}]
 dependencies = [
-    "CarrotRFIDTester",
+    "nfctester",
+    "python-dotenv",
 ]
 
 [tool.setuptools.packages.find]
 where = ["src"]
 
 [project.scripts]
-nfcscript = "nfcscript.main:main"
+nfcscript = "nfc.cli:main"
+nfc-cli = "nfc.nfc_cli:main"
 
 [tool.pytest.ini_options]
 pythonpath = ["src"]
@@ -22,6 +24,9 @@ testpaths = ["tests"]
 [tool.uv]
 package = true
 
+[tool.uv.sources]
+nfctester = { workspace = true }
+
 [dependency-groups]
 dev = [
     "pytest",
@@ -29,12 +34,14 @@ dev = [
 ]
 
 [tool.bumpversion]
-current_version = "0.0.1"
+current_version = "0.0.7"
+commit = true
+tag = true
 allow_dirty = true
+tag_name = "v{new_version}"
+message = "chore(release): bump version {current_version} → {new_version}"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
-search = 'version = "{current_version}"'
-replace = 'version = "{new_version}"'
 
 [[tool.bumpversion.files]]
 filename = "pyproject.toml"

nfcscript-0.0.7/src/nfc/__init__.py

@@ -0,0 +1,7 @@
+from .reader import *
+from .delay import *
+from .assertions import *
+from .bits import *
+from .hex_util import *
+from .checksum import *
+from . import trace

nfcscript-0.0.7/src/nfc/assertions.py

@@ -0,0 +1,68 @@
+import inspect
+from typing import Any, TypeGuard, TypeVar
+
+from nfc.hex_util import FORMAT_HEX
+
+T = TypeVar("T")
+
+def _get_stack_trace() -> str:
+    """获取格式化的调用堆栈"""
+    # inspect.stack()[0] 是 _get_stack_trace
+    # inspect.stack()[1] 是 ASSERT_... 函数
+    # inspect.stack()[2:] 是实际的业务调用代码
+    stack = inspect.stack()[2:]
+    chain = []
+    for frame in stack:
+        # 简化路径，仅显示文件名
+        filename = frame.filename.split('\\')[-1].split('/')[-1]
+        chain.append(f"  at {filename}:{frame.lineno} in {frame.function}")
+    return "\n".join(chain)
+
+def ASSERT_LEN(data: Any, expected_len: int, msg: str | None = None) -> None:
+    actual_len = len(data)
+    if actual_len != expected_len:
+        error_msg = (
+            f"\nAssertion Failed: {msg}\n" if msg else ""
+        ) + (
+            f"Assertion Failed: Length mismatch\n"
+            f"  Expected: {expected_len}\n"
+            f"  Actual  : {actual_len}\n"
+            f"  Data    : {data}\n"
+            f"Stack Trace:\n{_get_stack_trace()}"
+        )
+        raise AssertionError(error_msg)
+
+def ASSERT_EQUAL(expected: Any, actual: Any, msg: str | None = None) -> None:
+    if actual != expected:
+        error_msg = (
+            f"\nAssertion Failed: {msg}\n" if msg else ""
+        ) + (
+            f"Assertion Failed: Value mismatch\n"
+            f"  Expected: {FORMAT_HEX(expected)} ({type(expected).__name__})\n"
+            f"  Actual  : {FORMAT_HEX(actual)} ({type(actual).__name__})\n"
+            f"Stack Trace:\n{_get_stack_trace()}"
+        )
+        raise AssertionError(error_msg)
+
+def ASSERT_IS_NONE(value: Any, msg: str | None = None) -> None:
+    if value is not None:
+        error_msg = (
+            f"\nAssertion Failed: {msg}\n" if msg else ""
+        ) + (
+            f"Assertion Failed: Expected None\n"
+            f"  Actual  : {value} ({type(value).__name__})\n"
+            f"Stack Trace:\n{_get_stack_trace()}"
+        )
+        raise AssertionError(error_msg)
+
+def ASSERT_IS_NOT_NONE(value: T | None, msg: str | None = None) -> TypeGuard[T]:
+    if value is None:
+        error_msg = (
+            f"\nAssertion Failed: {msg}\n" if msg else ""
+        ) + (
+            f"Assertion Failed: Expected Not None\n"
+            f"  Actual  : {value}\n"
+            f"Stack Trace:\n{_get_stack_trace()}"
+        )
+        raise AssertionError(error_msg)
+    return True

{nfcscript-0.0.1/src/nfcscript → nfcscript-0.0.7/src/nfc}/bits.py

@@ -1,4 +1,6 @@
-def bits_update(val: int, mask: int, data: int) -> int:
+from .hex_util import FORMAT_HEX
+
+def BITS_UPDATE(val: int, mask: int, data: int) -> int:
     """
     更新寄存器中的特定位域 (Read-Modify-Write)
     :param val:         当前寄存器的原始值
@@ -6,10 +8,10 @@ def bits_update(val: int, mask: int, data: int) -> int:
     :param data:        已移位对齐的新数值 (例如: 0x20, 即 1 << 5)
     :return:            更新后的寄存器值
     """
-    assert (data & ~mask) == 0, f"Data {hex(data)} contains bits outside mask {hex(mask)}"
+    assert (data & ~mask) == 0, f"Data {FORMAT_HEX(data)} contains bits outside mask {FORMAT_HEX(mask)}"
     return (val & ~mask) | (data & mask)
 
-def bits_set(val: int, mask: int) -> int:
+def BITS_SET(val: int, mask: int) -> int:
     """
     将寄存器中的指定位强制置 1 (OR 操作)
     
@@ -17,7 +19,7 @@ def bits_set(val: int, mask: int) -> int:
     """
     return val | mask
 
-def bits_reset(val: int, mask: int) -> int:
+def BITS_RESET(val: int, mask: int) -> int:
     """
     将寄存器中的指定位强制清 0 (AND-NOT 操作)
     

nfcscript-0.0.7/src/nfc/checksum.py

@@ -0,0 +1,10 @@
+from .assertions import ASSERT_LEN
+from .hex_util import FORMAT_HEX
+
+def GET_BCC(data: list[int]) -> int:
+    """
+    计算 BCC: data[0]^data[1]^data[2]^data[3]
+    :param data: 4字节的UID数据
+    """
+    ASSERT_LEN(data, 4, msg=f"计算BCC时输入数据长度应为4: {FORMAT_HEX(data)}")
+    return data[0] ^ data[1] ^ data[2] ^ data[3]