nfcscript 0.0.6__tar.gz → 0.0.8__tar.gz

nfcscript-0.0.8/PKG-INFO

@@ -0,0 +1,264 @@
+Metadata-Version: 2.4
+Name: nfcscript
+Version: 0.0.8
+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.8/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.6 → nfcscript-0.0.8}/pyproject.toml

@@ -1,12 +1,13 @@
 [project]
 name = "nfcscript"
-version = "0.0.6"
+version = "0.0.8"
 description = "A plugin-based core engine for DSL-style NFC testing automation."
 readme = "README.md"
 requires-python = ">=3.14"
 authors = [{name = "crthu"}]
 dependencies = [
     "nfctester",
+    "python-dotenv",
 ]
 
 [tool.setuptools.packages.find]
@@ -14,6 +15,7 @@ where = ["src"]
 
 [project.scripts]
 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,7 +34,7 @@ dev = [
 ]
 
 [tool.bumpversion]
-current_version = "0.0.6"
+current_version = "0.0.8"
 commit = true
 tag = true
 allow_dirty = true

{nfcscript-0.0.6 → nfcscript-0.0.8}/src/nfc/__init__.py

@@ -4,3 +4,4 @@ from .assertions import *
 from .bits import *
 from .hex_util import *
 from .checksum import *
+from . import trace

nfcscript-0.0.8/src/nfc/cli.py

@@ -0,0 +1,116 @@
+import sys
+import argparse
+import os
+import runpy
+
+from dotenv import load_dotenv
+
+def _find_dotenv_all(start_dir):
+    chain = []
+    path = start_dir
+    while True:
+        env_path = os.path.join(path, ".env")
+        if os.path.exists(env_path):
+            chain.append(env_path)
+        parent = os.path.dirname(path)
+        if parent == path:
+            break
+        path = parent
+    chain.reverse()
+    return chain
+
+def _parse_level(value: str) -> int:
+    """将字符串解析为解析级别，支持数字和别名"""
+    val = value.lower().strip()
+    if val in ("0", "false", "no", "off"):
+        return 0
+    if val in ("1", "simple", "summary"):
+        return 1
+    if val in ("2", "full", "tree"):
+        return 2
+    try:
+        return int(value)
+    except ValueError:
+        return 1
+
+def run_script(script_path):
+    script_dir = os.path.dirname(os.path.abspath(script_path))
+    cwd = os.getcwd()
+
+    # 1. 加入当前工作目录 (CWD)，优先级最高
+    if cwd not in sys.path:
+        sys.path.insert(0, cwd)
+        
+    # 2. 加入脚本所在目录 (如果不是 CWD 的话)
+    if script_dir != cwd and script_dir not in sys.path:
+        sys.path.insert(0, script_dir)
+
+    runpy.run_path(script_path, run_name="__main__")
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="nfcscript",
+        description="NFC Script Runner - 执行 NFC 测试脚本"
+    )
+    parser.add_argument("script", help="脚本文件路径")
+    parser.add_argument("-p", "--port", default=None, help="串口号 (默认: NFC_PORT 环境变量或 COM20)")
+    parser.add_argument("-r", "--reader", default=None, help="读卡器类型 (默认: NFC_READER 环境变量或 pn532)")
+    parser.add_argument("--trace-driver", action="store_true", help="开启 DRIVER 层追踪")
+    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()
+
+    if not os.path.exists(args.script):
+        print(f"Error: Script not found: {args.script}")
+        sys.exit(1)
+
+    sys.argv = [args.script] + extra
+
+    script_dir = os.path.dirname(os.path.abspath(args.script))
+    dotenv_files = _find_dotenv_all(script_dir)
+    for dotenv_path in dotenv_files:
+        load_dotenv(dotenv_path, override=True)
+
+    if args.port is not None:
+        os.environ["NFC_PORT"] = args.port
+    if args.reader is not None:
+        os.environ["NFC_READER"] = args.reader
+
+    from nfc import trace
+
+    trace_level = os.environ.get("NFC_TRACE_LEVEL", "INFO")
+    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":
+        trace_level = args.trace_level
+    if args.trace_driver:
+        trace_driver = True
+    if args.trace_protocol:
+        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
+
+    run_script(args.script)
+
+if __name__ == "__main__":
+    main()