sdev 0.4.4__tar.gz → 0.4.6__tar.gz

{sdev-0.4.4/sdev.egg-info → sdev-0.4.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sdev
-Version: 0.4.4
+Version: 0.4.6
 Summary: 串口控制器工具包
 Home-page: https://github.com/klrc/sdev
 Author: klrc
@@ -34,9 +34,9 @@ Dynamic: requires-python
 
 # SDEV
 
-串口开发板控制器：后台按行读缓冲、按 flag 扫描与回显着色、执行命令、存活检测。
+串口开发板控制器：基于后台异步读缓冲、提供快速存活检测、多进程串口互斥锁、以及人性化的命令回显。
 
-**注意**：同一串口同一时间只能被一个 sdev 进程使用。请勿并行执行多条 `sdev shell ...` 或快速连续执行，否则可能报「串口已被其他 sdev 进程占用」或挂死；需等前一条命令结束后再执行下一条。
+**注意**：`sdev` 内置了跨进程串口锁（flock），支持多个进程同时尝试连接同一串口。后启动的进程会阻塞等待，直到前一个进程释放串口，从而避免了串口冲突或挂死。
 
 ## 安装
 
@@ -95,20 +95,20 @@ with Demoboard("/dev/ttyUSB0", 115200) as board:
 |------|------|
 | `shell(cmd, prompt_flag=" #", timeout=None, stream=False)` | 清缓冲 -> 发送命令 -> 等待命令回显 -> 等待提示符。返回输出列表或生成器。 |
 | `execute_command(cmd, flag, timeout=None, stream=False)` | `shell` 方法的别名，用于兼容旧版代码。 |
-| `check_alive(uboot_flag="uboot#", prompt_flag=" #", response_timeout=3)` | 存活检测：处理 U-Boot 挂起、发送 Ctrl-C 唤醒并等待提示符。 |
+| `check_alive(uboot_flag="uboot#", prompt_flag=" #", timeout=2.0)` | 鲁棒存活检测：自动处理串口残留输出、U-Boot 挂起、发送 Ctrl-C 唤醒。具备乐观探测能力，在系统稳定时可秒级完成检测。 |
 
-### SerialDevice (底层)
+### SerialDevice (底层驱动)
+
+底层串口基础类，仅负责 I/O 和锁管理，不包含任何 UI/显示逻辑。
 
 | 方法 / 属性 | 说明 |
 |-------------|------|
-| `STABLE_FLAG` | 类常量 `" #"`，常用作默认提示符。 |
 | `connect()` / `disconnect()` | 打开/关闭串口并启停后台读线程。 |
 | `send(text)` | 发送一行（自动加换行）。 |
 | `scan(end_flag, timeout=None)` | 从缓存中持续读取直到目标 flag，或读到 timeout 结束。 |
-| `display(lines, flag=None, flag_type=None)` | 对传入的行按 flag 类型回显（着色）并 yield 原始行。 |
 | `clear()` | 清空读缓冲。 |
 
-- **回显着色**：匹配到 `flag` 的行为绿色，命令回显行为青色，其余灰色；支持设备折行后的跨行匹配。
+- **回显样式**：`Demoboard` 提供了增强的视觉体验。用户输入的命令和提示符符号 `>` 以黄色高亮显示，命令执行结果以白色显示，而普通的板端日志则以深灰色背景化。
 
 ## 依赖
 

{sdev-0.4.4 → sdev-0.4.6}/README.md

@@ -1,8 +1,8 @@
 # SDEV
 
-串口开发板控制器：后台按行读缓冲、按 flag 扫描与回显着色、执行命令、存活检测。
+串口开发板控制器：基于后台异步读缓冲、提供快速存活检测、多进程串口互斥锁、以及人性化的命令回显。
 
-**注意**：同一串口同一时间只能被一个 sdev 进程使用。请勿并行执行多条 `sdev shell ...` 或快速连续执行，否则可能报「串口已被其他 sdev 进程占用」或挂死；需等前一条命令结束后再执行下一条。
+**注意**：`sdev` 内置了跨进程串口锁（flock），支持多个进程同时尝试连接同一串口。后启动的进程会阻塞等待，直到前一个进程释放串口，从而避免了串口冲突或挂死。
 
 ## 安装
 
@@ -61,20 +61,20 @@ with Demoboard("/dev/ttyUSB0", 115200) as board:
 |------|------|
 | `shell(cmd, prompt_flag=" #", timeout=None, stream=False)` | 清缓冲 -> 发送命令 -> 等待命令回显 -> 等待提示符。返回输出列表或生成器。 |
 | `execute_command(cmd, flag, timeout=None, stream=False)` | `shell` 方法的别名，用于兼容旧版代码。 |
-| `check_alive(uboot_flag="uboot#", prompt_flag=" #", response_timeout=3)` | 存活检测：处理 U-Boot 挂起、发送 Ctrl-C 唤醒并等待提示符。 |
+| `check_alive(uboot_flag="uboot#", prompt_flag=" #", timeout=2.0)` | 鲁棒存活检测：自动处理串口残留输出、U-Boot 挂起、发送 Ctrl-C 唤醒。具备乐观探测能力，在系统稳定时可秒级完成检测。 |
 
-### SerialDevice (底层)
+### SerialDevice (底层驱动)
+
+底层串口基础类，仅负责 I/O 和锁管理，不包含任何 UI/显示逻辑。
 
 | 方法 / 属性 | 说明 |
 |-------------|------|
-| `STABLE_FLAG` | 类常量 `" #"`，常用作默认提示符。 |
 | `connect()` / `disconnect()` | 打开/关闭串口并启停后台读线程。 |
 | `send(text)` | 发送一行（自动加换行）。 |
 | `scan(end_flag, timeout=None)` | 从缓存中持续读取直到目标 flag，或读到 timeout 结束。 |
-| `display(lines, flag=None, flag_type=None)` | 对传入的行按 flag 类型回显（着色）并 yield 原始行。 |
 | `clear()` | 清空读缓冲。 |
 
-- **回显着色**：匹配到 `flag` 的行为绿色，命令回显行为青色，其余灰色；支持设备折行后的跨行匹配。
+- **回显样式**：`Demoboard` 提供了增强的视觉体验。用户输入的命令和提示符符号 `>` 以黄色高亮显示，命令执行结果以白色显示，而普通的板端日志则以深灰色背景化。
 
 ## 依赖
 

{sdev-0.4.4 → sdev-0.4.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sdev"
-version = "0.4.4"
+version = "0.4.6"
 description = "串口控制器工具包"
 readme = "README.md"
 license = {text = "MIT"}

{sdev-0.4.4 → sdev-0.4.6}/sdev/__init__.py

@@ -14,7 +14,7 @@ from typing import Literal
 from .core import SerialDevice
 from .class_wrapper import Demoboard, Relay
 
-__version__ = "0.4.4"
+__version__ = "0.4.6"
 __author__ = "klrc"
 __email__ = "1440698245@qq.com"
 

sdev-0.4.6/sdev/class_wrapper.py

@@ -0,0 +1,164 @@
+"""
+面向对象封装：
+
+- Demoboard：继承 SerialDevice，并增加显示回显（display）、日志记录和高层方法（shell, check_alive）；
+- Relay：继承 SerialDevice，仅保留基础串口能力。
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from typing import Generator, Iterable, List, Literal, Optional, Union
+
+from loguru import logger
+
+from .core import SerialDevice
+from .demoboard import check_alive as _check_alive_func
+from .demoboard import shell as _shell_func
+
+# 配色方案（仅用于 Demoboard 显示）
+_GREY = "\033[90m"
+_GREEN = "\033[32m"
+_YELLOW = "\033[33m"
+_RESET = "\033[0m"
+
+# ANSI 颜色转义正则
+_ANSI_ESCAPE_RE = re.compile(r"\x1b\[[0-9;]*m")
+
+
+class Demoboard(SerialDevice):
+    """
+    Demoboard 设备：
+    - 具备完整的显示回显和着色能力；
+    - 提供 shell() / check_alive() 等交互式方法。
+    """
+
+    def __init__(self, port: str, baudrate: int = 115200, check_alive: bool = True):
+        super().__init__(port, baudrate)
+        self._auto_check_alive = check_alive
+        self._display = True
+        self._last_output_ends_with_newline = True
+
+    def connect(self) -> None:
+        """连接并自动执行 check_alive。"""
+        if self._is_connected:
+            return
+        super().connect()
+        if self._auto_check_alive:
+            self.check_alive()
+
+    # --- 高级显示与日志逻辑 (重写基类接口) ---
+
+    def _write_raw(self, text: str) -> None:
+        """重写：增加终端输出。"""
+        if text:
+            self._last_output_ends_with_newline = text.endswith("\n")
+            sys.stdout.write(text)
+            sys.stdout.flush()
+
+    def _ensure_newline(self) -> None:
+        """重写：增加自动补全换行逻辑。"""
+        if not self._last_output_ends_with_newline:
+            sys.stdout.write("\n")
+            sys.stdout.flush()
+            self._last_output_ends_with_newline = True
+
+    def info(self, msg: str) -> None:
+        self._ensure_newline()
+        logger.info(msg)
+
+    def success(self, msg: str) -> None:
+        self._ensure_newline()
+        logger.success(msg)
+
+    def warning(self, msg: str) -> None:
+        self._ensure_newline()
+        logger.warning(msg)
+
+    def error(self, msg: str) -> None:
+        self._ensure_newline()
+        logger.error(msg)
+
+    def _echo_normal(self, line: str) -> None:
+        self._write_raw(f"{_GREY}{line}{_RESET}")
+
+    def display(
+        self,
+        lines: Iterable[str],
+        flag: Optional[str] = None,
+        flag_type: Optional[Literal["end_flag", "prompt"]] = None,
+        raw_color: bool = False,
+    ) -> Generator[str, None, None]:
+        """重写：增加局部着色回显。"""
+        for line in lines:
+            if self._display:
+                if raw_color:
+                    self._write_raw(line)
+                elif flag is None:
+                    self._echo_normal(line)
+                else:
+                    # 高亮模式：仅对匹配到的 flag 部分加色
+                    plain = _ANSI_ESCAPE_RE.sub("", line)
+                    if flag and flag in plain:
+                        parts = plain.split(flag, 1)
+                        # 如果是 prompt (输入命令回显)，使用 Yellow；如果是 end_flag (提示符)，使用 Green
+                        color = _GREEN if flag_type == "end_flag" else _YELLOW
+                        formatted = f"{_GREY}{parts[0]}{_RESET}{color}{flag}{_RESET}{_GREY}{parts[1]}{_RESET}"
+                        self._write_raw(formatted)
+                    else:
+                        self._echo_normal(plain)
+            yield line
+
+    # --- 高层业务方法 ---
+
+    def shell(
+        self,
+        cmd: str,
+        *,
+        prompt_flag: str = " #",
+        timeout: Optional[float] = None,
+        stream: bool = False,
+    ) -> Union[List[str], Generator[str, None, None]]:
+        return _shell_func(self, cmd, prompt_flag=prompt_flag, timeout=timeout, stream=stream)
+
+    def execute_command(
+        self,
+        cmd: str,
+        flag: str = " #",
+        timeout: Optional[float] = None,
+        stream: bool = False,
+    ) -> Union[List[str], Generator[str, None, None]]:
+        """兼容旧版签名的 shell 别名。"""
+        return self.shell(cmd, prompt_flag=flag, timeout=timeout, stream=stream)
+
+    def check_alive(
+        self,
+        *,
+        uboot_flag: str = "uboot#",
+        prompt_flag: str = " #",
+        timeout: float = 2.0,
+    ) -> None:
+        _check_alive_func(
+            self,
+            uboot_flag=uboot_flag,
+            prompt_flag=prompt_flag,
+            timeout=timeout,
+        )
+
+    def __exit__(self, exc_type, exc_value, traceback) -> None:
+        super().__exit__(exc_type, exc_value, traceback)
+        self._ensure_newline()
+
+
+class Relay(SerialDevice):
+    """
+    继电器设备：仅继承基础串口能力，不具备 Demoboard 的显示回显功能。
+    """
+
+    def __init__(self, port: str, baudrate: int = 115200, **kwargs):
+        kwargs.pop("check_alive", None)
+        super().__init__(port, baudrate)
+
+
+__all__ = ["Demoboard", "Relay"]

{sdev-0.4.4 → sdev-0.4.6}/sdev/core.py

@@ -1,8 +1,8 @@
 """
-串口设备核心：连接、后台按行读、发送、按 flag 扫描/回显、清空缓存。
+串口设备核心：连接、后台按行读、发送、按 flag 扫描、清空缓存。
 跨进程串口互斥：同一 port 的 connect 通过 fcntl.flock 阻塞等待，依次执行。
 
-高层功能（shell、check_alive 等）放在上层模块中实现，例如 `sdev.demoboard.functional`。
+底层类，不包含任何 UI/显示逻辑。
 """
 
 import fcntl
@@ -11,7 +11,7 @@ import queue
 import re
 import threading
 import time
-from typing import Generator, Iterable, Literal, Optional
+from typing import Generator, Iterable, Optional
 
 from loguru import logger
 import serial
@@ -31,8 +31,6 @@ def _port_lock_path(port: str) -> str:
 def _acquire_port_lock(port: str):
     """
     对 port 持有跨进程排他锁（阻塞直到拿到），返回打开的 fd，调用方负责 close。
-
-    注意：这里是 sdev 的全局锁机制入口，请不要在上层重复实现文件锁。
     """
     path = _port_lock_path(port)
     fd = os.open(path, os.O_RDWR | os.O_CREAT, 0o600)
@@ -46,9 +44,10 @@ def _acquire_port_lock(port: str):
             now = time.monotonic()
             if now - last_log >= 5.0:
                 waited = now - start
+                # 底层锁提示，保持简单
                 logger.warning(
                     f"Waiting for cross-process serial lock on {port} "
-                    f"for {waited:.1f} seconds; another sdev instance may be using this port."
+                    f"for {waited:.1f} seconds..."
                 )
                 last_log = now
             time.sleep(0.1)
@@ -68,32 +67,12 @@ def _release_port_lock(fd: Optional[int]) -> None:
 
 
 def _content_contains_ctrl_c(text: str) -> bool:
-    """是否包含设备回显的 Ctrl+C（\\x03 或 ^C、^C\\x00 等）。"""
+    """是否包含设备回显的 Ctrl+C。"""
     n = text.replace("\x00", "")
     return CTRL_C in n or "^C" in n
 
 
-def _line_matches_flag(line: str, flag: str) -> bool:
-    """行（rstrip 后）是否以 flag 结尾；CTRL_C 兼容 \\x03 / \"^C\" 等回显形式。"""
-    stripped = line.rstrip()
-    if flag != CTRL_C:
-        return stripped.endswith(flag)
-    normalized = stripped.strip().replace("\x00", "")
-    return normalized == CTRL_C or normalized == "^C" or normalized.endswith("^C") or stripped.endswith(flag)
-
-
-_GREY = "\033[90m"
-_SENT = "\033[36m"
-_GREEN = "\033[32m"
-_RESET = "\033[0m"
-
-# 匹配已有的 ANSI 颜色转义，用于在高亮模式下去掉原始颜色
-_ANSI_ESCAPE_RE = re.compile(r"\x1b\[[0-9;]*m")
-
-
 class SerialDevice:
-    STABLE_FLAG = " #"
-
     def __init__(self, port: str, baudrate: int = 115200):
         self.port = port
         self.baudrate = baudrate
@@ -102,8 +81,6 @@ class SerialDevice:
         self._reader_thread: Optional[threading.Thread] = None
         self._is_connected = False
         self._stop_reading = False
-        self._display = True
-        # 跨进程串口锁 fd，connect 时持锁，disconnect 时释放
         self._lock_fd: Optional[int] = None
 
         # 扫描相关通用参数
@@ -111,10 +88,6 @@ class SerialDevice:
         self._max_lines_per_prompt = 4
 
     def _serial_reader(self) -> None:
-        """
-        后台 daemon：readline → UTF-8 解码 → put(line)；
-        解码失败则跳过该行。disconnect 时 _stop_reading + put(None) 唤醒阻塞 get()。
-        """
         while not self._stop_reading and self._serial is not None and self._serial.is_open:
             raw = self._serial.readline()
             if raw:
@@ -126,13 +99,9 @@ class SerialDevice:
                     continue
 
     def connect(self) -> None:
-        """
-        打开串口并启动后台读取线程；已连接则直接 return。
-        同一 port 的多次 connect 会因跨进程锁而阻塞排队。
-        """
         if self._is_connected:
             return
-        self._lock_fd = _acquire_port_lock(self.port)  # 阻塞直到拿到串口锁
+        self._lock_fd = _acquire_port_lock(self.port)
         try:
             self._serial = serial.Serial(self.port, self.baudrate, timeout=self._scan_timeout)
             if not self._serial.is_open:
@@ -147,13 +116,9 @@ class SerialDevice:
             raise
 
     def disconnect(self) -> None:
-        """
-        关闭串口并停止后台线程；幂等。
-        """
         if not self._is_connected:
             return
         self._stop_reading = True
-        # 唤醒可能阻塞在 _buffer.get() 的 scan() 调用
         self._buffer.put(None)
         if self._reader_thread is not None and self._reader_thread.is_alive():
             self._reader_thread.join()
@@ -166,33 +131,26 @@ class SerialDevice:
         self._is_connected = False
 
     def send(self, prompt: str) -> None:
-        """发送 prompt + 换行并 flush；prompt 不得含 \\n/\\r。"""
         if not self._is_connected or self._serial is None:
             raise RuntimeError("not connected")
-        assert prompt is not None, "prompt 不得为 None"
-        assert "\n" not in prompt and "\r" not in prompt, "send(prompt) 不得包含换行符"
+        assert prompt is not None
         self._serial.write((prompt + "\n").encode("utf-8"))
         self._serial.flush()
 
     def _scan_raw(self, timeout: Optional[float] = None) -> Generator[str, None, None]:
-        """
-        从 _buffer 逐行 yield。
-        有 timeout 时按「无响应超时」语义处理：超过 timeout 一直没有新行则抛 TimeoutError；
-        收到 None 结束。
-        """
         if not self._is_connected:
             raise RuntimeError("not connected")
         last_activity = time.monotonic()
         scan_timeout = self._scan_timeout if timeout is not None else None
 
-        while True:  # timeout loop
+        while True:
             try:
                 line = self._buffer.get(timeout=scan_timeout) if scan_timeout else self._buffer.get()
             except queue.Empty:
                 if timeout is not None and time.monotonic() - last_activity > timeout:
                     raise TimeoutError("scan deadline exceeded (no response)")
                 continue
-            if line is None:  # _serial_reader sentinel
+            if line is None:
                 return
             last_activity = time.monotonic()
             yield line
@@ -203,16 +161,6 @@ class SerialDevice:
         timeout: Optional[float] = None,
         replace_with_acc: bool = False,
     ) -> Generator[str, None, None]:
-        """
-        从缓存中持续读取直到目标 flag，或读到 timeout 结束。
-
-        - end_flag 为 None 时：持续按行读取，直到内部 timeout 为止，TimeoutError 视为正常结束（return）。
-        - end_flag 非 None：内部维护一个 acc_cache 保留最近几行，并拼成 acc_line（无换行），
-          以支持跨行匹配；命中后：
-          - replace_with_acc=True：yield 一行拼接后的 acc_line + \"\\n\"；
-          - replace_with_acc=False：逐行 yield acc_cache 中的原始行。
-        - 如果 end_flag 是 CTRL_C，则通过 _content_contains_ctrl_c() 进行兼容匹配。
-        """
         if end_flag is None:
             try:
                 for line in self._scan_raw(timeout):
@@ -224,7 +172,6 @@ class SerialDevice:
         for line in self._scan_raw(timeout):
             acc_cache.append(line)
             if len(acc_cache) > self._max_lines_per_prompt:
-                # 缓存过多则把最旧的一行交给调用方
                 yield acc_cache.pop(0)
 
             acc_line = "".join([x.rstrip("\r\n") for x in acc_cache])
@@ -237,54 +184,7 @@ class SerialDevice:
                         yield x
                 break
 
-    def _echo_prompt(self, line: str) -> None:
-        print(f"{_SENT}{line}{_RESET}", end="", flush=True)
-
-    def _echo_normal(self, line: str) -> None:
-        print(f"{_GREY}{line}{_RESET}", end="", flush=True)
-
-    def _echo_flag(self, line: str) -> None:
-        print(f"{_GREEN}{line}{_RESET}", end="", flush=True)
-
-    def display(
-        self,
-        lines: Iterable[str],
-        flag: Optional[str] = None,
-        flag_type: Optional[Literal["end_flag", "prompt"]] = None,
-        raw_color = False,
-    ) -> Generator[str, None, None]:
-        """
-        对传入的行按 flag_type 回显并 yield 原始行。
-
-        - flag/flag_type 为 None 时：保持原始输出（包括设备自身带的颜色），不做处理。
-        - flag_type=\"end_flag\"：匹配行高亮为绿色，其它行灰色；在高亮模式下会去除原始 ANSI 颜色。
-        - flag_type=\"prompt\"：匹配行高亮为青色，其它行灰色；在高亮模式下会去除原始 ANSI 颜色。
-        """
-        for line in lines:
-            if self._display:
-                if raw_color:
-                    # 不做任何颜色包裹，保留设备原始颜色
-                    print(line, end="", flush=True)
-                elif flag is None:
-                    self._echo_normal(line)
-                else:
-                    # 高亮模式：去除原始颜色后按 flag_type 统一着色
-                    plain = _ANSI_ESCAPE_RE.sub("", line)
-                    find_flag = _line_matches_flag(plain, flag)
-                    if find_flag:
-                        if flag_type == "end_flag":
-                            self._echo_flag(plain)
-                        elif flag_type == "prompt":
-                            self._echo_prompt(plain)
-                    else:
-                        self._echo_normal(plain)
-            yield line
-
     def clear(self) -> None:
-        """
-        清空 _buffer 中已入队行。
-        取到 None 则 put(None) 后 return（保留 sentinel）。
-        """
         while True:
             try:
                 item = self._buffer.get_nowait()
@@ -294,22 +194,36 @@ class SerialDevice:
             except queue.Empty:
                 return
 
+    # --- 基础日志与输出接口 (供子类扩展或 functional 使用) ---
+
+    def _write_raw(self, text: str) -> None:
+        """底层默认不向终端输出任何内容。"""
+        pass
+
+    def _ensure_newline(self) -> None:
+        """底层默认不处理换行。"""
+        pass
+
+    def info(self, msg: str) -> None:
+        """底层默认仅通过 logger 记录。"""
+        logger.info(msg)
+
+    def success(self, msg: str) -> None:
+        logger.success(msg)
+
+    def warning(self, msg: str) -> None:
+        logger.warning(msg)
+
+    def error(self, msg: str) -> None:
+        logger.error(msg)
+
+    def display(self, lines: Iterable[str], **kwargs) -> Generator[str, None, None]:
+        """底层默认仅 yield 数据，不进行任何回显。"""
+        yield from lines
+
     def __enter__(self) -> "SerialDevice":
         self.connect()
         return self
 
     def __exit__(self, exc_type, exc_value, traceback) -> None:
         self.disconnect()
-        print()
-
-
-if __name__ == "__main__":
-    # 简单示例：打印一条命令输出（不做存活检测等高层逻辑）
-    with SerialDevice("/dev/ttyUSB0", 115200) as board:
-        board.send("ls")
-        for _ in board.display(
-            board.scan(SerialDevice.STABLE_FLAG, timeout=3),
-            SerialDevice.STABLE_FLAG,
-            "end_flag",
-        ):
-            pass

sdev-0.4.6/sdev/demoboard/functional.py

@@ -0,0 +1,177 @@
+"""
+Demoboard 相关的高层功能：
+
+- shell(): clear + send + scan + display，执行一条命令并按提示符结束；
+- check_alive(): 通过 Ctrl-C / uboot / reboot / 提示符 等 flag 检查板子是否存活。
+
+注意：这里假设底层设备实现了 SerialDevice 接口：
+- clear()
+- send(cmd: str)
+- scan(end_flag: Optional[str], timeout: Optional[float], replace_with_acc: bool)
+- display(lines, flag: Optional[str], flag_type: Optional[str])
+"""
+
+from __future__ import annotations
+
+import time
+from itertools import chain
+from typing import Generator, Iterable, List, Optional, Union
+from loguru import logger
+
+from ..core import CTRL_C, SerialDevice
+
+
+def _scan_and_display(
+    device: SerialDevice,
+    end_flag: str,
+    flag_type: str,
+    timeout: Optional[float],
+    replace_with_acc: bool,
+) -> Generator[str, None, None]:
+    """内部小工具：封装一段 scan + display，返回的是 scan 的原始行。"""
+    lines = device.scan(end_flag=end_flag, timeout=timeout, replace_with_acc=replace_with_acc)
+    for line in device.display(lines, flag=end_flag, flag_type=flag_type):  # pragma: no branch
+        yield line
+
+
+def shell(
+    device: SerialDevice,
+    cmd: str,
+    prompt_flag: str = " #",
+    timeout: Optional[float] = None,
+    stream: bool = False,
+    clear: bool = True,
+) -> Union[List[str], Generator[str, None, None]]:
+    """
+    在 demoboard 上执行一条命令：
+    - clear: 清理残留输出，避免错位；
+    - send: 发送命令；
+    - 第一阶段：scan(cmd) + display(prompt 高亮)，直到命令回显完整出现；
+    - 第二阶段：scan(prompt_flag) + display(end_flag 高亮)，直到提示符行出现。
+
+    返回的是 scan 的原始行（设备输出的原始内容），不是 display 的显示结果：
+    - stream=False：返回这些原始行的 list（两阶段全部合并）；
+    - stream=True：返回 yielding 原始行的 generator，不预先把结果拉成 list。
+    """
+    if clear:
+        device.clear()
+
+    # 第一段：把「命令本身的回显」当作 prompt 高亮
+    part1 = []
+    if cmd is not None:
+        # 营造类似 Python 交互式的结构：空一行，另起一行打印 > 符号
+        device._ensure_newline()
+        device._write_raw(f"\n\033[33m>\033[0m ")  # 黄色的 > 符号
+        device.send(cmd)
+        part1 = _scan_and_display(
+            device,
+            end_flag=cmd,
+            flag_type="prompt",
+            timeout=timeout,
+            replace_with_acc=True,
+        )
+
+    # 第二段：直到提示符
+    part2 = _scan_and_display(
+        device,
+        end_flag=prompt_flag,
+        flag_type="end_flag",
+        timeout=timeout,
+        replace_with_acc=False,
+    )
+    merged = (line for line in chain(part1, part2))
+
+    if stream:
+        # 按要求返回「原始 generator」
+        return merged
+    return list(merged)
+
+def check_alive(
+    device: SerialDevice,
+    uboot_flag: str = "uboot#",
+    prompt_flag: str = " #",
+    timeout: float = 2.0,
+) -> None:
+    """
+    检查 demoboard 是否「醒着」且有 shell 提示符。
+
+    语义（鲁棒性逻辑）：
+    1. 乐观探测 (Fast Path)：如果已经在提示符状态或串口静默，直接探测以节省时间。
+    2. 标准流程：检查 timeout 内是否有输出；如果有，循环等待直到没有输出；
+    3. 输入 CTRL-C 并检查输出：
+       - 如果包含 uboot_flag，输入 'reboot' 并递归调用 check_alive；
+       - 否则，检查是否包含 prompt_flag。如果不包含，提示并抛出错误；
+    4. 如果一切正常，视为 check 成功。
+    """
+
+    # 1. 乐观探测 (Fast Path)
+    try:
+        # 极短采样 (0.3s)
+        sample = list(shell(device, None, prompt_flag=None, timeout=0.3, clear=False))
+        sample_out = "".join(sample)
+
+        # 场景 A: 已经在提示符处
+        if prompt_flag in sample_out:
+            if uboot_flag in sample_out:
+                device.warning(f"Found uboot flag '{uboot_flag}', sending 'reboot' and re-checking...")
+                device.send("reboot")
+                return check_alive(device, uboot_flag, prompt_flag, timeout)
+            return
+
+        # 场景 B: 串口当前没动静，尝试主动探测
+        if not sample_out:
+            device.send(CTRL_C)
+            # 探测回显 (0.5s)
+            probe = list(shell(device, None, prompt_flag=None, timeout=0.5, clear=False))
+            probe_out = "".join(probe)
+            if prompt_flag in probe_out:
+                if uboot_flag in probe_out:
+                    device.warning(f"Found uboot flag '{uboot_flag}', sending 'reboot' and re-checking...")
+                    device.send("reboot")
+                    return check_alive(device, uboot_flag, prompt_flag, timeout)
+                return
+    except Exception as e:
+        logger.debug(f"Optimistic probe encountered error: {e}")
+
+    # 2. 标准流程：检查并等待输出停止
+    while True:
+        try:
+            # shell(device, None, ...) 不发送命令，仅执行 scan(None) 直到 silence timeout。
+            lines = list(shell(device, None, prompt_flag=None, timeout=timeout, clear=False))
+            if not lines:
+                break
+            device.warning("Detecting serial output, waiting for it to stop...")
+        except (TimeoutError, Exception) as e:
+            logger.debug(f"Stop-output loop encountered error: {e}")
+            break
+
+    # 3. 发送 CTRL-C 并获取输出
+    device.send(CTRL_C)
+    lines = list(shell(device, None, prompt_flag=None, timeout=timeout, clear=False))
+    output = "".join(lines)
+
+    # 4. 如果输出包含 uboot_flag，输入 reboot 并返回递归的 check_alive
+    if uboot_flag in output:
+        device.warning(f"Found uboot flag '{uboot_flag}', sending 'reboot' and re-checking...")
+        device.send("reboot")
+        return check_alive(device, uboot_flag, prompt_flag, timeout)
+
+    # 5. 检查 prompt_flag
+    if prompt_flag not in output:
+        msg = f"Prompt flag '{prompt_flag}' not found in output. Serial port might not be connected or device is unresponsive. Please check."
+        device.error(msg)
+        raise RuntimeError(msg)
+
+    # 6. 成功
+    device.success("Check alive passed.")
+
+
+if __name__ == "__main__":
+    # 简单测试：demoboard shell 功能
+    import os
+
+    port = os.environ.get("SDEV_PORT", "/dev/ttyUSB0")
+    with SerialDevice(port) as board:
+        check_alive(board)
+        shell(board, "cat /proc/meminfo")
+

{sdev-0.4.4 → sdev-0.4.6/sdev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sdev
-Version: 0.4.4
+Version: 0.4.6
 Summary: 串口控制器工具包
 Home-page: https://github.com/klrc/sdev
 Author: klrc
@@ -34,9 +34,9 @@ Dynamic: requires-python
 
 # SDEV
 
-串口开发板控制器：后台按行读缓冲、按 flag 扫描与回显着色、执行命令、存活检测。
+串口开发板控制器：基于后台异步读缓冲、提供快速存活检测、多进程串口互斥锁、以及人性化的命令回显。
 
-**注意**：同一串口同一时间只能被一个 sdev 进程使用。请勿并行执行多条 `sdev shell ...` 或快速连续执行，否则可能报「串口已被其他 sdev 进程占用」或挂死；需等前一条命令结束后再执行下一条。
+**注意**：`sdev` 内置了跨进程串口锁（flock），支持多个进程同时尝试连接同一串口。后启动的进程会阻塞等待，直到前一个进程释放串口，从而避免了串口冲突或挂死。
 
 ## 安装
 
@@ -95,20 +95,20 @@ with Demoboard("/dev/ttyUSB0", 115200) as board:
 |------|------|
 | `shell(cmd, prompt_flag=" #", timeout=None, stream=False)` | 清缓冲 -> 发送命令 -> 等待命令回显 -> 等待提示符。返回输出列表或生成器。 |
 | `execute_command(cmd, flag, timeout=None, stream=False)` | `shell` 方法的别名，用于兼容旧版代码。 |
-| `check_alive(uboot_flag="uboot#", prompt_flag=" #", response_timeout=3)` | 存活检测：处理 U-Boot 挂起、发送 Ctrl-C 唤醒并等待提示符。 |
+| `check_alive(uboot_flag="uboot#", prompt_flag=" #", timeout=2.0)` | 鲁棒存活检测：自动处理串口残留输出、U-Boot 挂起、发送 Ctrl-C 唤醒。具备乐观探测能力，在系统稳定时可秒级完成检测。 |
 
-### SerialDevice (底层)
+### SerialDevice (底层驱动)
+
+底层串口基础类，仅负责 I/O 和锁管理，不包含任何 UI/显示逻辑。
 
 | 方法 / 属性 | 说明 |
 |-------------|------|
-| `STABLE_FLAG` | 类常量 `" #"`，常用作默认提示符。 |
 | `connect()` / `disconnect()` | 打开/关闭串口并启停后台读线程。 |
 | `send(text)` | 发送一行（自动加换行）。 |
 | `scan(end_flag, timeout=None)` | 从缓存中持续读取直到目标 flag，或读到 timeout 结束。 |
-| `display(lines, flag=None, flag_type=None)` | 对传入的行按 flag 类型回显（着色）并 yield 原始行。 |
 | `clear()` | 清空读缓冲。 |
 
-- **回显着色**：匹配到 `flag` 的行为绿色，命令回显行为青色，其余灰色；支持设备折行后的跨行匹配。
+- **回显样式**：`Demoboard` 提供了增强的视觉体验。用户输入的命令和提示符符号 `>` 以黄色高亮显示，命令执行结果以白色显示，而普通的板端日志则以深灰色背景化。
 
 ## 依赖
 

{sdev-0.4.4 → sdev-0.4.6}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r", encoding="utf-8") as fh:
 
 setup(
     name="sdev",
-    version="0.4.4",
+    version="0.4.6",
     author="klrc",
     author_email="144069824@qq.com",
     description="串口控制器工具包",

sdev-0.4.4/sdev/class_wrapper.py

@@ -1,85 +0,0 @@
-"""
-面向对象封装：
-
-- Demoboard：继承 SerialDevice，并把 demoboard.functional 里的函数挂成方法；
-- Relay：占位类，后续扩展继电器相关串口控制。
-"""
-
-from __future__ import annotations
-
-from typing import Generator, List, Optional, Union
-
-from .core import SerialDevice
-from .demoboard import check_alive as _check_alive_func
-from .demoboard import shell as _shell_func
-
-
-class Demoboard(SerialDevice):
-    """
-    Demoboard 设备：
-    - 保留 SerialDevice 的所有底层能力；
-    - 提供 shell() / check_alive() 等高层方法。
-    """
-
-    def __init__(self, port: str, baudrate: int = 115200, check_alive: bool = True):
-        super().__init__(port, baudrate)
-        self._auto_check_alive = check_alive
-
-    def connect(self) -> None:
-        """连接并自动执行 check_alive。"""
-        if self._is_connected:
-            return
-        super().connect()
-        if self._auto_check_alive:
-            self.check_alive()
-
-    def execute_command(
-        self,
-        cmd: str,
-        flag: str = " #",
-        timeout: Optional[float] = None,
-        stream: bool = False,
-    ) -> Union[List[str], Generator[str, None, None]]:
-        """alias for shell"""
-        return self.shell(cmd, prompt_flag=flag, timeout=timeout, stream=stream)
-
-    def shell(
-        self,
-        cmd: str,
-        *,
-        prompt_flag: str = " #",
-        timeout: Optional[float] = None,
-        stream: bool = False,
-    ) -> Union[List[str], Generator[str, None, None]]:
-        return _shell_func(self, cmd, prompt_flag=prompt_flag, timeout=timeout, stream=stream)
-
-    def check_alive(
-        self,
-        *,
-        uboot_flag: str = "uboot#",
-        prompt_flag: str = " #",
-        response_timeout: float = 3,
-    ) -> None:
-        _check_alive_func(
-            self,
-            uboot_flag=uboot_flag,
-            prompt_flag=prompt_flag,
-            response_timeout=response_timeout,
-        )
-
-
-class Relay(SerialDevice):
-    """
-    继电器设备占位类：
-    - 继承 SerialDevice；
-    - 具体继电器控制逻辑后续在 sdev.relay.functional 中补充。
-    """
-
-    def __init__(self, port: str, baudrate: int = 115200, **kwargs):
-        # 吞掉不支持的参数，确保与 sdev() 工厂兼容
-        kwargs.pop("check_alive", None)
-        super().__init__(port, baudrate)
-
-
-__all__ = ["Demoboard", "Relay"]
-

sdev-0.4.4/sdev/demoboard/functional.py

@@ -1,146 +0,0 @@
-"""
-Demoboard 相关的高层功能：
-
-- shell(): clear + send + scan + display，执行一条命令并按提示符结束；
-- check_alive(): 通过 Ctrl-C / uboot / reboot / 提示符 等 flag 检查板子是否存活。
-
-注意：这里假设底层设备实现了 SerialDevice 接口：
-- clear()
-- send(cmd: str)
-- scan(end_flag: Optional[str], timeout: Optional[float], replace_with_acc: bool)
-- display(lines, flag: Optional[str], flag_type: Optional[str])
-"""
-
-from __future__ import annotations
-
-import time
-from itertools import chain
-from typing import Generator, Iterable, List, Optional, Union
-from loguru import logger
-
-from ..core import CTRL_C, SerialDevice
-
-
-def _scan_and_display(
-    device: SerialDevice,
-    end_flag: str,
-    flag_type: str,
-    timeout: Optional[float],
-    replace_with_acc: bool,
-) -> Generator[str, None, None]:
-    """内部小工具：封装一段 scan + display，返回的是 scan 的原始行。"""
-    lines = device.scan(end_flag=end_flag, timeout=timeout, replace_with_acc=replace_with_acc)
-    for line in device.display(lines, flag=end_flag, flag_type=flag_type):  # pragma: no branch
-        yield line
-
-
-def shell(
-    device: SerialDevice,
-    cmd: str,
-    prompt_flag: str = " #",
-    timeout: Optional[float] = None,
-    stream: bool = False,
-    clear: bool = True,
-) -> Union[List[str], Generator[str, None, None]]:
-    """
-    在 demoboard 上执行一条命令：
-    - clear: 清理残留输出，避免错位；
-    - send: 发送命令；
-    - 第一阶段：scan(cmd) + display(prompt 高亮)，直到命令回显完整出现；
-    - 第二阶段：scan(prompt_flag) + display(end_flag 高亮)，直到提示符行出现。
-
-    返回的是 scan 的原始行（设备输出的原始内容），不是 display 的显示结果：
-    - stream=False：返回这些原始行的 list（两阶段全部合并）；
-    - stream=True：返回 yielding 原始行的 generator，不预先把结果拉成 list。
-    """
-    if clear:
-        device.clear()
-
-    # 第一段：把「命令本身的回显」当作 prompt 高亮
-    part1 = []
-    if cmd is not None:
-        device.send(cmd)
-        part1 = _scan_and_display(
-            device,
-            end_flag=cmd,
-            flag_type="prompt",
-            timeout=timeout,
-            replace_with_acc=True,
-        )
-
-    # 第二段：直到提示符
-    part2 = _scan_and_display(
-        device,
-        end_flag=prompt_flag,
-        flag_type="end_flag",
-        timeout=timeout,
-        replace_with_acc=False,
-    )
-    merged = (line for line in chain(part1, part2))
-
-    if stream:
-        # 按要求返回「原始 generator」
-        return merged
-    return list(merged)
-
-def check_alive(
-    device: SerialDevice,
-    uboot_flag: str = "uboot#",
-    prompt_flag: str = " #",
-    response_timeout: float = 3,    
-) -> None:
-    """
-    检查 demoboard 是否「醒着」且有 shell 提示符。
-
-    语义（带超时的熔断）：
-    1. 发送 Ctrl-C 并读取一段输出：
-       - 如果输出中出现 uboot_flag（如 "uboot#"），认为当前在 U-Boot；
-    2. 若在 U-Boot：
-       - 发送 "reboot"；
-       - 等待 awaken_flag（如 "Process ... done" 中的 "Process"）出现，超时则抛 TimeoutError；
-    3. 最后，无论是否经过 reboot，统一等待 shell 提示符 prompt_flag（如 "#"），超时抛 TimeoutError。
-    """
-
-    # 1. Ctrl-C，判定控制台是否响应
-    under_reboot = False
-    try:
-        lines = shell(device, CTRL_C, prompt_flag, timeout=response_timeout)
-    except TimeoutError:
-        wait_iter = 0
-        while True:
-            device.send(CTRL_C)
-            lines = shell(device, None, None, timeout=response_timeout, clear=False)
-            if len(lines) > 0:
-                under_reboot = True
-                break
-            wait_iter += 1
-            if wait_iter > 5:
-                logger.warning("CTRL-C test failed, please check the connection")
-                break
-
-    # 2. 检查是否被中止进入uboot
-    for line in lines:
-        if uboot_flag in line:
-            logger.warning("uboot flag found, rebooting")
-            device.send("reboot")
-            under_reboot = True
-            break
-
-    # 3. 进入启动流程
-    if under_reboot:
-        try:
-            lines = shell(device, None, None, timeout=response_timeout)
-        except TimeoutError:
-            pass  # 等待启动彻底完成
-        return check_alive(device, uboot_flag, prompt_flag, response_timeout)
-
-
-if __name__ == "__main__":
-    # 简单测试：demoboard shell 功能
-    import os
-
-    port = os.environ.get("SDEV_PORT", "/dev/ttyUSB0")
-    with SerialDevice(port) as board:
-        check_alive(board)
-        shell(board, "cat /proc/meminfo")
-