pyutilscripts 0.8.0__tar.gz → 0.10.0__tar.gz

pyutilscripts-0.10.0/.editorconfig

@@ -0,0 +1,13 @@
+# Editor configuration, see https://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+# 下面只覆盖不一样的配置，其他全部继承 [*]
+[*.md]
+indent_size = 2 

pyutilscripts-0.10.0/.github/workflows/python-publish.yml

@@ -0,0 +1,70 @@
+# This workflow will upload a Python Package to PyPI when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build release distributions
+        run: |
+          # NOTE: put your own distribution build steps here.
+          python -m pip install build
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+
+    # Dedicated environments with protections for publishing are strongly recommended.
+    # For more information, see: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-protection-rules
+    environment:
+      name: pypi
+      # OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status:
+      # url: https://pypi.org/p/YOURPROJECT
+      #
+      # ALTERNATIVE: if your GitHub Release name is the PyPI project version string
+      # ALTERNATIVE: exactly, uncomment the following line instead:
+      # url: https://pypi.org/project/YOURPROJECT/${{ github.event.release.name }}
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

pyutilscripts-0.10.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__
+.vscode
+*.egg-info
+build
+dist

pyutilscripts-0.10.0/Changelog.md

@@ -0,0 +1,60 @@
+# Changelog
+
+## v0.10.0
+
+- fcopy   优化 交互模式的行动清单, 将说明注释放在文档尾部
+- ntunnel 添加 一个简单的网络工具, 基于 TUN 设备的 UPD/TCP 隧道，用于向远端转发 IP报文
+
+## v0.9.0
+
+- httpd 添加 http.server 限速版的文件服务器
+
+## v0.8.0
+
+- toast 添加 windows toast 通知支持
+
+## v0.7.0
+
+- fcopy 调整了运行时与verbose模式的输出, 提升用户体验
+- fcopy 调整了默认编辑器优先级, 优先使用 Nano, 可通过 `export EDITOR=vim` 覆盖
+- fcopy 调整了行动清单的输出与注释，增强可读性
+- fcopy 修复一些bugs: --filter 为None导致的异常, Windows下因为BOM 文件头不能解析的问题
+
+## v0.6.0
+
+- fcopy 重构了行动列表与执行输出的内容, 使宏观行为更加清晰
+- fcopy 调整了过滤逻辑, --filter 选项去除默认值, 输入文件无效视为致命错误
+
+## v0.5.0
+
+- fcopy 添加空目录支持
+- fcopy 添加文件统计信息
+
+## v0.4.0
+
+- fcopy 添加严格模式, 将警告视为错误
+- fcopy 优化交互内容, 增强用户体验
+
+## v0.3.1
+
+- fcopy 交互模式: 行动列表支持行尾注释
+- fcopy 交互模式: 添加文件属性注释, 以便了解文件为何会被忽略
+
+## v0.3.0
+
+- fcopy 添加文件清单生成模式
+- fcopy 添加单元测试覆盖
+- fcopy 修复拷贝逻辑Bug
+
+## v0.2.0
+
+- fcopy 添加更新、覆盖、重命名模式
+- fcopy 支持交互模式（生成行动列表，在用户编辑或确认后，才开始执行）
+- fcopy 添加过滤模式
+
+## v0.1.0
+
+- Initial release.
+- fcopy.py
+- prunedirs.py
+- forward-tcp.py

{pyutilscripts-0.8.0/pyutilscripts.egg-info → pyutilscripts-0.10.0}/PKG-INFO

@@ -1,32 +1,33 @@
 Metadata-Version: 2.4
 Name: pyutilscripts
-Version: 0.8.0
+Version: 0.10.0
 Summary: PyUtilScripts 是一个基于 Python 的通用小工具集合，目标是提供编写通用任务的辅助工具。
-Author-email: Zero Kwok <zero.kwok@foxmail.com>
-License: MIT License
 Project-URL: Homepage, https://github.com/ZeroKwok/pyutilscripts
 Project-URL: Issues, https://github.com/ZeroKwok/pyutilscripts/issues
+Author-email: Zero Kwok <zero.kwok@foxmail.com>
+License: MIT License
+License-File: LICENSE
 Keywords: tools
 Classifier: Intended Audience :: Developers
-Classifier: Topic :: Software Development :: Build Tools
 Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.7
 Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Build Tools
 Requires-Python: >=3.7
-Description-Content-Type: text/markdown
-License-File: LICENSE
 Requires-Dist: click
 Requires-Dist: natsort
+Requires-Dist: pytun-pmd3
 Requires-Dist: termcolor
 Provides-Extra: dev
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
-Dynamic: license-file
+Requires-Dist: debugpy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Description-Content-Type: text/markdown
 
 # **PyUtilScripts**  
 

pyutilscripts-0.10.0/TODO.md

@@ -0,0 +1,28 @@
+# TODO
+
+`PyUtilScripts` 是一个基于 Python 的通用小工具集合，目标是提供便捷的日常任务自动化/辅助工具，帮助开发者、运维人员或普通用户提升效率。
+
+## 近期
+
+- [x] fcopy --actions 清单细化行动模式
+  - [x] c 拷贝, 即目标不存在
+  - [x] s 跳过, 即目标存在, 深/浅对比无差异, 视为文件无更新
+  - [x] i 忽略, 即目标存在, 元数据对比不一致, 但深对比无差异, 忽略
+  - [x] u 更新, 即目标存在, 元数据对比不一致, 但源文件更新鲜
+  - [x] o 覆盖, 即目标存在, 无条件拷贝并覆盖(--mode overwrite)
+  - [x] r 重命名, 即目标存在, 拷贝并递增文件名(--mode rename)
+  - [x] m 创建目录, 源文件是目录, 且目标不存在 (确保空目录被创建)
+- [x] fcopy --actions 清单 action 为 u 时, 添加两个文件的修改时间注释
+- [x] fcopy --filter  添加正则匹配过滤
+- [x] fcopy --actions 清单支持行尾注释
+- [x] fcopy 增加严格模式, 避免在拷贝时源文件不存在, 导致结果不如预期
+- [x] fcopy --actions 清单添加原/目标目录, 与必要的注释
+- [x] fcopy 支持空目录
+- [x] fcopy --filter 过滤掉的文件, 应该出现在清单文件中,  f
+- [x] fcopy -i 交互模式下, 源目录中不存在的文件, 应该出现在清单文件中, m
+- [x] fcopy 因拷贝创建的目录是冗余的, 因此只有空目录才体现在清单中, e
+- [x] fcopy -i 交互模式下, 拷贝时不应出现: 过滤/缺失/忽略的文件警告, 仅在非交互模式下显示
+- [x] fcopy -i 交互模式下, 如果存被过滤的项, 则显示过滤文件名, 便于调试
+- [x] fcopy 优化 交互模式的行动清单, 将说明注释放在文档尾部
+- [ ] fcopy 支持 将目标目录中, 未在 --list 清单中指定的文件, 移动至回收站(待定)
+- [ ] fcopy 增加 忽略警告模式

pyutilscripts-0.10.0/makefile

@@ -0,0 +1,28 @@
+.PHONY: build upload test clean
+
+build: clean
+	@echo "Building..."
+	python -m build
+
+upload:
+	@echo "Uploading..."
+	twine upload --repository testpypi dist/*
+	twine upload dist/*
+
+setup:
+	@echo "Setting up..."
+	python -m pip install .
+
+test: clean
+	@echo "Testing..."
+	python -m pip install -e .[dev]
+	pytest tests
+
+venv:
+	@echo "Setting up virtual environment..."
+	python -m venv venv
+	source venv/bin/activate
+	pip install -e .[dev]
+
+clean:
+	rm -fr dist/*

{pyutilscripts-0.8.0 → pyutilscripts-0.10.0}/pyproject.toml

@@ -1,6 +1,9 @@
 [build-system]
-requires = ["setuptools"]
-build-backend = "setuptools.build_meta"
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "pyutilscripts/__init__.py"
 
 [project]
 name = "pyutilscripts"
@@ -28,17 +31,16 @@ dependencies = [
     "click",
     "natsort",
     "termcolor",
+    "pytun_pmd3",
 ]
 
 [project.optional-dependencies]
 dev = [
+    "debugpy",
     "pytest",
     "pytest-cov",
 ]
 
-[tool.setuptools.dynamic]
-version = {attr = "pyutilscripts.projectVersion"}
-
 [project.urls]
 Homepage = "https://github.com/ZeroKwok/pyutilscripts"
 Issues = "https://github.com/ZeroKwok/pyutilscripts/issues"
@@ -46,4 +48,6 @@ Issues = "https://github.com/ZeroKwok/pyutilscripts/issues"
 [project.scripts]
 "fcopy" = "pyutilscripts.fcopy:main"
 "prunedirs" = "pyutilscripts.prunedirs:main"
-"forward.tcp" = "pyutilscripts.forward_tcp:main"
+"forward.tcp" = "pyutilscripts.forward_tcp:main"
+"httpd" = "pyutilscripts.httpd:main"
+"ntunnel" = "pyutilscripts.ntunnel:main"

pyutilscripts-0.10.0/pytest.ini

@@ -0,0 +1,4 @@
+[pytest]
+testpaths = tests
+python_files = test_*.py
+python_functions = test_*

{pyutilscripts-0.8.0 → pyutilscripts-0.10.0}/pyutilscripts/__init__.py

@@ -2,7 +2,7 @@
 PyUtilScripts 是一个基于 Python 的通用小工具集合，目标是提供编写通用任务的辅助工具。
 """
 
-__version__ = "0.8.0"
+__version__ = "0.10.0"
 __status__ = ""
 __author__ = "zero <zero.kwok@foxmail.com>"
 

{pyutilscripts-0.8.0 → pyutilscripts-0.10.0}/pyutilscripts/fcopy.py

@@ -37,8 +37,16 @@ ListFileHead = """# File list generated by fcopy on {Date}
 # Count : {Count}
 """
 
-ActionFileHead = """# Action plan for file copying (edit this file to change actions)
+ActionFileHead = """
+# fcopy action plan — edit to change copying actions (see end of this file for details)
 #
+# Source Directory: {Source}
+# Target Directory: {Target}
+# Blacklist       : {Filter}
+# Action Count    : {Count}
+"""
+
+ActionFileTail = """
 # Actions:
 # c - Copy      : Target doesn't exist
 # u - Update    : Target exists with metadata mismatch, source is newer
@@ -56,11 +64,6 @@ ActionFileHead = """# Action plan for file copying (edit this file to change act
 # r file3.txt -> file(3).txt    Copy and Rename to file(3).txt
 # i file2.txt # file:=, meta:>  Files are the same and source file is newer
 # i file2.txt # file:≠, meta:<  Files are different and source is older
-#
-# Source Directory: {Source}
-# Target Directory: {Target}
-# Blacklist       : {Filter}
-# Action Count    : {Count}
 """
 
 ActionPriority = ["c", "u", "o", "r", "e", "m", "i", "f", "s"]
@@ -449,7 +452,7 @@ def line_append_space(line, align=16, minLength=32):
     return line + max(n - l, 1) * " "
 
 
-def join_actions(actions: list[Action], head: str, args):
+def join_actions(actions: list[Action], head: str, tail: str, args):
     def comment1(prefix, same, cmp): 
         return f'{prefix} file:{["≠", "="][same]}, meta:{["<", ">"][cmp == 1]}'
     def comment2(prefix, stat): 
@@ -489,10 +492,10 @@ def join_actions(actions: list[Action], head: str, args):
     body = "\n".join(lines)
     body = body.format(**counter)
 
-    return head.rstrip() + "\n" + body + "\n"
+    return head.strip() + "\n" + body + "\n" + tail.strip()
 
 
-def print_actions(actions: list, head: str, args):
+def print_actions(actions: list, head: str, tail: str, args):
     output(2, f"\nThe following actions will be performed:\n", "yellow")
     colors = {
         "#": "dark_grey",
@@ -500,7 +503,7 @@ def print_actions(actions: list, head: str, args):
     }
     colors.update(ActionColors)
 
-    lines = join_actions(actions, head, args)
+    lines = join_actions(actions, head, tail, args)
     for line in lines.splitlines():
         if not line:
             output(2)
@@ -523,12 +526,12 @@ def get_available_editor(defaults=["nano", "vim", "vi", "notepad"]):
     return None
 
 
-def edit_actions(actions: list, head: str, args) -> list:
+def edit_actions(actions: list, head: str, tail: str, args) -> list:
     """
     使用 click.edit() 启动编辑器让用户编辑行动计划。
     返回: None 用户取消编辑或没保存
     """
-    content = join_actions(actions, head, args)
+    content = join_actions(actions, head, tail, args)
 
     # 打开编辑器让用户编辑内容
     edited = click.edit(
@@ -555,9 +558,9 @@ def copy_files(args):
         return 1
 
     if args.interactive:
-        actions = edit_actions(actions, ActionFileHead, args)
+        actions = edit_actions(actions, ActionFileHead, ActionFileTail, args)
     elif args.dry_run or args.verbose > 1:
-        print_actions(actions, ActionFileHead, args)
+        print_actions(actions, ActionFileHead, ActionFileTail, args)
     output(2)
 
     copied, skipped, missing, filtered = 0, 0, 0, 0

pyutilscripts-0.10.0/pyutilscripts/httpd.py

@@ -0,0 +1,105 @@
+#! python
+# -*- coding: utf-8 -*-
+
+import time
+import argparse
+import sys
+import os
+from http.server import HTTPServer, SimpleHTTPRequestHandler
+from socketserver import ThreadingMixIn
+
+class RateLimitHandler(SimpleHTTPRequestHandler):
+    # Default value
+    SPEED_LIMIT = -1 
+
+    def copyfile(self, source, outputfile):
+        """Override copyfile to implement rate limiting. If unlimited, use the original efficient method."""
+        # If unlimited, call parent class method (which uses shutil.copyfileobj internally and is more efficient)
+        if self.SPEED_LIMIT <= 0:
+            return super().copyfile(source, outputfile)
+
+        chunk_size = 1024 * 64  # 64KB chunk size
+        try:
+            start_time = time.time()
+            bytes_sent = 0
+            while True:
+                data = source.read(chunk_size)
+                if not data:
+                    break
+                outputfile.write(data)
+                bytes_sent += len(data)
+
+                # Rate limiting calculation
+                elapsed = time.time() - start_time
+                expected_time = bytes_sent / self.SPEED_LIMIT
+
+                if elapsed < expected_time:
+                    # 最小睡眠时间设为 0.5 秒, 因此理论最低速度约为 0.5 * 64kb = 128KB/s
+                    time.sleep(min(expected_time - elapsed, 0.5)) 
+        except (ConnectionResetError, BrokenPipeError):
+            print(f"\n[!] Client {self.client_address[0]} disconnected")
+
+class ThreadedHTTPServer(ThreadingMixIn, HTTPServer):
+    daemon_threads = True
+
+def parse_speed(speed_str):
+    """Parse speed string; support negative for unlimited."""
+    s = speed_str.upper()
+    try:
+        # Handle unlimited cases
+        if s == '-1' or s == '0' or s == 'UNLIMITED':
+            return -1
+        
+        if s.endswith('MB'):
+            return int(float(s[:-2]) * 1024 * 1024)
+        elif s.endswith('KB'):
+            return int(float(s[:-2]) * 1024)
+        else:
+            return int(s)
+    except ValueError:
+        raise argparse.ArgumentTypeError("Invalid speed format. Use '1MB', '500KB', '-1' (unlimited), or a byte value.")
+
+def main():
+    parser = argparse.ArgumentParser(description="Multithreaded HTTP file server with rate limiting")
+    parser.add_argument('--port', '-p', type=int, default=8000, help='Port to listen on (default: 8000)')
+    parser.add_argument('--bind', '-b', default='0.0.0.0', help='Bind address (default: 0.0.0.0)')
+    parser.add_argument('--limit', '-l', default='-1', help="Rate limit (e.g., 1MB, 500KB). Use -1 for unlimited")
+    parser.add_argument('--dir', '-d', default='.', help='Root directory to serve (default: current directory)')
+
+    args = parser.parse_args()
+
+    # 1. Verify directory exists
+    if not os.path.isdir(args.dir):
+        print(f"[ERROR] Directory does not exist: {args.dir}")
+        sys.exit(1)
+    
+    # 2. Change to and record absolute path
+    abs_path = os.path.abspath(args.dir)
+    os.chdir(abs_path)
+
+    # 3. Parse rate limit
+    limit_bps = parse_speed(args.limit)
+    limit_display = f"{args.limit}/s ({limit_bps})" if limit_bps > 0 else "Unlimited"
+
+    # 4. Dynamic handler class
+    HandlerClass = type('CustomHandler', (RateLimitHandler,), {'SPEED_LIMIT': limit_bps})
+
+    server_address = (args.bind, args.port)
+    httpd = ThreadedHTTPServer(server_address, HandlerClass)
+
+    print(f"{'='*45}")
+    print(f"[*] HTTP server started")
+    print(f"[*] Listening on: http://{args.bind}:{args.port}")
+    print(f"[*] Serving directory: {abs_path}")
+    print(f"[*] Speed limit: {limit_display}")
+    print(f"{'='*45}")
+    print("[!] Press Ctrl+C to stop the server\n")
+
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        print("\n[!] Shutting down server...")
+        httpd.server_close()
+
+if __name__ == "__main__":
+    main()

pyutilscripts-0.10.0/pyutilscripts/ntraffic.py

@@ -0,0 +1,269 @@
+#! python
+# -*- coding: utf-8 -*-
+#
+# This file is part of the PyUtilScripts project.
+# Copyright (c) 2020-2026 zero <zero.kwok@foxmail.com>
+#
+# For the full copyright and license information, please view the LICENSE
+# file that was distributed with this source code.
+
+import time
+import struct
+import socket
+import logging
+import threading
+import contextlib
+
+prefix = b'\xef\x5a'
+logger = logging.getLogger(__name__)
+
+class AnyEndpoint:
+    def __init__(self):
+        self.sock = None
+        self.peers = None
+
+        self.tx_bytes = 0       # 发送字节数   
+        self.rx_bytes = 0       # 接收字节数
+        self.tx_packets = 0     # 发送包数
+        self.rx_packets = 0     # 接收包数
+        self.stats_time = time.time()
+        self.stats_lock = threading.Lock()
+
+    def add_tx(self, tx_bytes=0, tx_packets=1):
+        with self.stats_lock:
+            self.tx_bytes += tx_bytes
+            self.tx_packets += tx_packets
+
+    def add_rx(self, rx_bytes=0, rx_packets=1):
+        with self.stats_lock:
+            self.rx_bytes += rx_bytes
+            self.rx_packets += rx_packets
+
+    def stats(self, reset_timer:bool=True):
+        with self.stats_lock:
+            elapsed = time.time() - self.stats_time
+            if reset_timer:
+                self.stats_time = time.time()
+            tx_rate = self.tx_bytes / elapsed if elapsed > 0 else 0
+            rx_rate = self.rx_bytes / elapsed if elapsed > 0 else 0
+            return (elapsed, (self.tx_packets, self.tx_bytes, tx_rate), (self.rx_packets, self.rx_bytes, rx_rate))
+
+
+class UDPEndpoint(AnyEndpoint):
+    def __init__(self, addr, peers = None):
+        super().__init__()
+        self.type = 'UDP'
+        self.addr = addr
+        self.peers = peers
+        self.closed = True
+
+    def listen(self):
+        self.close()
+        try:
+            self.sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+            self.sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            self.sock.bind(self.addr)
+            self.addr = self.sock.getsockname()
+            self.closed = False
+        except OSError as e:
+            logger.error(f"UDPEndpoint listen failed on {self.addr}: {e}")
+            self.close()
+            return False
+
+    def establish(self) -> bool:
+        if self.closed or not self.sock:
+            logger.error("UDPEndpoint establish: socket not ready")
+            return False
+        self.send_packet(prefix + b'HELLO') # 握手, 目的是传送地址
+        return True
+
+    def close(self):
+        if self.sock:
+            self.closed = True
+            with contextlib.suppress(Exception):
+                self.sock.close()
+            self.sock = None
+
+    def release(self):
+        self.close()
+
+    def send_packet(self, data):
+        if not self.sock:
+            logger.error("UDPEndpoint send: socket not created")
+            return False
+        if self.peers is None:
+            logger.debug("UDPEndpoint send: no peers address")
+            return False
+
+        try:
+            self.sock.sendto(data, self.peers)
+            self.add_tx(len(data))
+            return True
+        except Exception as e:
+            logger.error(f"UDPEndpoint send failed to {self.peers}: {e}")
+            return False
+
+    def recv_packet(self):
+        if not self.sock or self.closed:
+            return None
+        
+        try:
+            data, addr = self.sock.recvfrom(65535)
+            self.add_rx(len(data))
+
+            if data.startswith(prefix):
+                if data[2:] == b'HELLO':
+                    self.peers = addr
+                    logger.debug(f"UDPEndpoint recv HELLO from {addr}")
+            return data
+        except socket.timeout:
+            return None
+        except ConnectionResetError as e: # 对端未监听端口
+            return None
+        except OSError as e:
+            if not self.closed:
+                logger.error(f"UDPEndpoint recv error: {e}")
+            return None
+
+
+
+class TCPEndpoint(AnyEndpoint):
+    def __init__(self, addr, peers = None, timeout=5):
+        super().__init__()
+        self.type = 'TCP'
+        self.addr = addr
+        self.peers = peers
+        self.timeout = timeout
+        self.connected = False
+        self.listen_sock = None
+
+    def listen(self):
+        if self.peers:          # client mode not need to listen
+            return True
+        if self.listen_sock:    # already listening
+            return True
+        if self.connected or not self.addr:
+            return False
+
+        try:
+            sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            sock.settimeout(self.timeout)
+            sock.bind(self.addr)
+            sock.listen(1)
+            self.listen_sock = sock
+            return True
+        except OSError as e:
+            logger.error(f"TCP listen failed on {self.addr}: {str(e)}", exc_info=True)
+            if 'sock' in locals() and sock:
+                sock.close()
+            return False
+
+    def connect(self):
+        logger.debug(f"TCP connect to {self.addr} ...")
+        if self.connected:
+            return True
+
+        try:
+            self.close()
+            self.sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            self.sock.settimeout(self.timeout)
+            self.sock.connect(self.peers)
+            self.connected = True
+            logger.info(f"[+] TCP connected to {self.peers}")
+            return True
+        except OSError  as e:
+            logger.error(f"TCPEndpoint connect failed to {self.peers}: {e}")
+            if self.sock:
+                self.close()
+            return False
+
+    def accept(self):
+        if not self.listen_sock:
+            logger.error("TCPEndpoint accept: no listen socket")
+            return False
+        if self.connected:
+            return True
+
+        try:
+            self.close()
+            self.sock, self.peers = self.listen_sock.accept()
+            self.sock.settimeout(self.timeout)
+            self.connected = True
+            logger.debug(f"TCPEndpoint accept: connected to {self.peers}")
+            return True
+        except socket.timeout:
+            return False
+        except OSError as e:
+            if self.listen_sock:
+                logger.error(f"TCPEndpoint accept error: {e}")
+                if self.sock:
+                    self.close()
+            return False
+
+    def establish(self) -> bool:
+        if not self.connected:
+            if self.listen_sock:
+                return self.accept()
+            else:
+                return self.connect()
+        return True
+
+    def close(self):
+        self.connected = False
+        if self.sock:
+            with contextlib.suppress(Exception):
+                self.sock.close()
+            self.sock = None
+
+    def release(self):
+        self.close()
+        if self.listen_sock:
+            with contextlib.suppress(Exception):
+                self.listen_sock.close()
+        self.listen_sock = None
+
+    def send_packet(self, data):
+        if not self.establish():
+            logger.debug("TCPEndpoint send packet: failed to establish connection")
+            return False
+        try:
+            self.sock.sendall(struct.pack('!I', len(data)) + data)
+            self.add_tx(len(data))
+            return True
+        except OSError as e:
+            logger.error(f"TCPEndpoint send failed to {self.peers}: {e}")
+            self.close()
+            return False
+
+    def recv_packet(self):
+        if not self.establish():
+            logger.debug("TCPEndpoint recv packet: failed to establish connection")
+            return None
+        try:
+            length = self._recv_exact(4)
+            if not length:
+                return None
+            length = struct.unpack('!I', length)[0]
+            data = self._recv_exact(length)
+            self.add_rx(len(data))
+            return data
+        except OSError as e:
+            logger.error(f"TCPEndpoint recv failed from {self.peers}: {e}")
+            self.close()
+            return None
+
+    def _recv_exact(self, size):
+        data = b''
+        while len(data) < size:
+            try:
+                chunk = self.sock.recv(size - len(data))
+                if not chunk: # EOF
+                    self.close()
+                    return None
+                data += chunk
+            except socket.timeout:
+                logger.warning(f"TCPEndpoint recv timeout, peer={self.peers}")
+                self.close()
+                return None
+        return data

pyutilscripts-0.10.0/pyutilscripts/ntunnel.py

@@ -0,0 +1,173 @@
+#! python
+# -*- coding: utf-8 -*-
+#
+# This file is part of the PyUtilScripts project.
+# Copyright (c) 2020-2026 zero <zero.kwok@foxmail.com>
+#
+# For the full copyright and license information, please view the LICENSE
+# file that was distributed with this source code.
+
+import sys
+import time
+import logging
+import argparse
+import traceback
+import threading
+import contextlib
+
+from .utils import *
+from .ntraffic import UDPEndpoint, TCPEndpoint, AnyEndpoint
+
+running = True
+
+def create_tun(name:str, addr: tuple, mtu=1400):
+    try:
+        import pytun_pmd3 as pytun
+        if sys.platform == 'win32':
+            tun = pytun.TunTapDevice(name=name)
+        else:
+            tun = pytun.TunTapDevice(name=name, flags=pytun.linux.IFF_NO_PI | pytun.linux.IFF_TUN)
+        tun.addr = addr
+        tun.mtu = mtu
+        tun.up()
+        return tun
+    except ImportError:
+        print('[!] pytun module not found. Please install "pytun-pmd3" using pip.')
+    except Exception as e:
+        print(f"[!] Error creating TUN device: {e}")
+    exit(1)
+
+def forward_tun_to_peers(tun, endpoint:AnyEndpoint, args:dict):
+    global running
+    while running:
+        try:
+            packet = tun.read(tun.mtu)
+            if packet:
+                args.debug and print_packet(packet, prefix='[TUN -> PEER]')
+                endpoint.send_packet(packet)
+        except TimeoutError:
+            continue
+        except Exception as e:
+            if running:
+                print(f"[!] Error in [TUN -> PEER]: {traceback.format_exc()}")
+
+def forward_peers_to_tun(tun, endpoint:AnyEndpoint, args:dict):
+    global running
+    while running:
+        try:
+            data = endpoint.recv_packet()
+            if data:
+                args.debug and print_packet(data, prefix='[TUN <- PEER]')
+                with contextlib.suppress(OSError): # 忽略无效数据包引发的无效参数异常
+                    tun.write(data)
+            else:
+                time.sleep(1)
+        except Exception as e:
+            print(f"[!] Error in [TUN <- PEER]: {traceback.format_exc()}")
+
+def print_packet(packet, prefix=''):
+    src = dst = "N/A"
+    version = packet[0] >> 4
+    if version == 4:
+        src, dst = packet[12:16], packet[16:20]
+        src, dst = ".".join(map(str, src)), ".".join(map(str, dst))
+    elif version == 6:
+        src, dst = packet[8:24], packet[24:40]
+        src, dst = src.hex(':'), dst.hex(':')
+    print(f"{prefix}: {src} -> {dst} (len={len(packet)})")
+
+def report_stats(args, endpoint: AnyEndpoint):
+    while True:
+        time.sleep(args.stats_interval)
+        (elapsed, (tx_packets, tx_bytes, tx_rate), (rx_packets, rx_bytes, rx_rate)) = endpoint.stats()
+        tx = f"{tx_packets} pkts {format_bytes(tx_bytes, precision='.2f')} {format_bytes(tx_rate, precision=' 7.1f', postfix='/s')}"
+        rx = f"{rx_packets} pkts {format_bytes(rx_bytes, precision='.2f')} {format_bytes(rx_rate, precision=' 7.1f', postfix='/s')}"
+        print(f"[*] {elapsed:06.1f}s TX [{tx}] - RX [{rx}]")
+
+def main():
+    parser = argparse.ArgumentParser(description="Create a simple TUN to forward IP packets to remote peers")
+    parser.add_argument("--name", default="tun0", help="Interface name (default: tun0)")
+    parser.add_argument("--addr", default="fd00::1", help="IPv6 Address (default: fd00::1)") 
+    parser.add_argument("--protocol", default="udp", help="Transport protocol (udp/tcp)") 
+    parser.add_argument("--remote", type=str, default=None, help="Forward packets to remote endpoint")
+    parser.add_argument("--listen", type=str, default='0.0.0.0:8001', help="Listen for incoming packets (default: 0.0.0.0:8001)")
+    parser.add_argument("--stats-interval", type=int, default=5, help="Traffic report interval in seconds (default: 5)")
+    parser.add_argument("--no-stats", action="store_true", help="Disable traffic statistics reporting")
+    parser.add_argument("--debug", action="store_true", help="Enable debug mode")
+    args = parser.parse_args()
+    
+    if args.debug:
+        print(f"[*] Debug: Starting with arguments: {args}")
+        input("Press Enter to continue...")
+        logging.root.addHandler(logging.StreamHandler())
+        logging.root.setLevel(logging.DEBUG)
+        logging.debug("[*] Debug: Logging enabled")
+
+    def parse_addr(addr, default=None):
+        if addr is None:
+            return None
+        host, port = addr.split(':')
+        host = host if host else default[0]
+        port = port if port else default[1]
+        return (host, int(port))
+
+    args.remote = parse_addr(args.remote, default=('127.0.0.1', 0))
+    args.listen = parse_addr(args.listen, default=('0.0.0.0', 0))
+
+    if args.protocol.upper() != 'UDP':
+        Endpoint = TCPEndpoint
+    else:
+        Endpoint = UDPEndpoint
+
+    endpoint = Endpoint(addr=args.listen, peers=args.remote)
+    endpoint.listen()
+    endpoint.establish()
+    print(f"[+] {endpoint.type} socket listen to {endpoint.addr}")
+
+    tun = create_tun(args.name, args.addr)
+    print(f"[+] Interface {tun.name} is UP")
+    print(f"[+] IP Address: {args.addr}")
+
+    # 启动转发线程
+    t1 = threading.Thread(target=forward_tun_to_peers, args=(tun, endpoint, args))
+    t1.daemon = True
+    t1.start()
+
+    t2 = threading.Thread(target=forward_peers_to_tun, args=(tun, endpoint, args))
+    t2.daemon = True
+    t2.start()
+    
+    # 启动统计报告线程（如果不禁用）
+    if not args.no_stats:
+        t_stats = threading.Thread(target=report_stats, args=(args, endpoint))
+        t_stats.daemon = True
+        t_stats.start()
+        print(f"[+] Traffic statistics reporting every {args.stats_interval}s")
+    else:
+        print("[*] Traffic statistics reporting disabled")
+
+    print(f"[*] Tunnel is running. Press Ctrl+C to exit.")
+    try:
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        print("\n[!] Shutting down...")
+    finally:
+        # 最终报告
+        if not args.no_stats:
+            print("\n[!] Final Traffic Summary:")
+            (_, (tx_packets, tx_bytes, _), (rx_packets, rx_bytes, _)) = endpoint.stats()
+            print(f"     Total TX: {format_bytes(tx_bytes)} ({tx_packets} packets)")
+            print(f"     Total RX: {format_bytes(rx_bytes)} ({rx_packets} packets)")
+            print(f"     Total: {format_bytes(tx_bytes + rx_bytes)}")
+
+        global running
+        running = False
+        tun.down()
+        tun.close()
+        endpoint.release()
+        print("[+] Cleanup complete.")
+
+
+if __name__ == "__main__":
+    main()

{pyutilscripts-0.8.0 → pyutilscripts-0.10.0}/pyutilscripts/utils/__init__.py

@@ -2,14 +2,16 @@ import math
 import time
 
 
-def format_bytes(size_bytes: int, precision: int = 2) -> str:
-    """自动将字节数格式化为人类可读的单位（B, KB, MB, GB...）"""
+def format_bytes(
+    size_bytes: int, precision: str = ".2f", postfix: str = "", base: int = 1024
+) -> str:
+    """将字节数格式化为人类可读形式"""
     if size_bytes == 0:
         return "0B"
     units = ("B", "KB", "MB", "GB", "TB", "PB")
-    i = int(math.floor(math.log(size_bytes, 1024)))
-    size = size_bytes / (1024**i)
-    return f"{size:.{precision}f}{units[i]}"
+    i = int(math.floor(math.log(size_bytes, base)))
+    size = size_bytes / (base**i)
+    return f"{size:{precision}}{units[i]}"
 
 
 def format_ftime(seconds: float, format: str = "%Y-%m-%d %H:%M"):

pyutilscripts-0.8.0/PKG-INFO

@@ -1,82 +0,0 @@
-Metadata-Version: 2.4
-Name: pyutilscripts
-Version: 0.8.0
-Summary: PyUtilScripts 是一个基于 Python 的通用小工具集合，目标是提供编写通用任务的辅助工具。
-Author-email: Zero Kwok <zero.kwok@foxmail.com>
-License: MIT License
-Project-URL: Homepage, https://github.com/ZeroKwok/pyutilscripts
-Project-URL: Issues, https://github.com/ZeroKwok/pyutilscripts/issues
-Keywords: tools
-Classifier: Intended Audience :: Developers
-Classifier: Topic :: Software Development :: Build Tools
-Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.7
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Requires-Python: >=3.7
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: click
-Requires-Dist: natsort
-Requires-Dist: termcolor
-Provides-Extra: dev
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
-Dynamic: license-file
-
-# **PyUtilScripts**  
-
-`PyUtilScripts` 是一个基于 Python 的通用小工具集合，目标是提供编写通用任务的辅助工具。  
-
-## 📦 安装
-
-### 通过 pip 安装
-
-```bash
-pip install pyutilscripts
-```
-
-### 从源码安装
-
-```bash
-git clone https://github.com/ZeroKwok/PyUtilScripts.git
-cd PyUtilScripts
-pip install .
-```
-
----
-
-## 📝 使用说明
-
-- **fcopy**
-  - 基于清单文件的复制工具
-  - 特点
-    - 支持 更新、覆盖写、重命名模式
-    - 支持 交互模式，精准把控拷贝细节（拷贝前生成行动列表，在用户编辑或确认后，才具体执行行动列表中记录的动作）
-    - 支持 过滤模式，忽略某些文件或目录
-  - 示例：
-    - 按文件清单拷贝指定目录下的文件
-      - 更新模式 `fcopy -l /path/to/list.txt -s /path/to/src -t /path/to/dest`
-      - 覆盖模式 `fcopy -l /path/to/list.txt -s /path/to/src -t /path/to/dest -m o`
-      - 重命名模式 `fcopy -l /path/to/list.txt -s /path/to/src -t /path/to/dest -m r`
-    - 通过指定目录下的文件生成文件清单
-      - `fcopy -l /path/to/list.txt -s /path/to/src --update-list`
-    - 交互模式下拷贝指定目录的文件
-      - `fcopy -l /path/to/list.txt -s /path/to/src -t /path/to/dest -i`
-  - 概念
-    - 文件清单(fcopy.list)决定要拷贝的文件
-    - 行动清单决定拷贝行为(交互模式下通过编辑器呈现)
-
-- **prunedirs**
-  - 递归删除空目录
-  - 示例：
-    - `prunedirs /path/to/dir`
-
-- **forward.tcp**
-  - TCP 端口转发工具
-  - 示例：
-    - `forward.tcp -s 0.0.0.0:8081 -d 127.0.0.1:1081`

pyutilscripts-0.8.0/pyutilscripts.egg-info/SOURCES.txt

@@ -1,18 +0,0 @@
-LICENSE
-README.md
-pyproject.toml
-pyutilscripts/__init__.py
-pyutilscripts/fcopy.py
-pyutilscripts/forward_tcp.py
-pyutilscripts/prunedirs.py
-pyutilscripts/toast.py
-pyutilscripts.egg-info/PKG-INFO
-pyutilscripts.egg-info/SOURCES.txt
-pyutilscripts.egg-info/dependency_links.txt
-pyutilscripts.egg-info/entry_points.txt
-pyutilscripts.egg-info/requires.txt
-pyutilscripts.egg-info/top_level.txt
-pyutilscripts/utils/__init__.py
-tests/test_action_parser.py
-tests/test_fcopy.py
-tests/test_fcopy_cli.py

pyutilscripts-0.8.0/pyutilscripts.egg-info/dependency_links.txt

@@ -1 +0,0 @@
-

pyutilscripts-0.8.0/pyutilscripts.egg-info/entry_points.txt

@@ -1,4 +0,0 @@
-[console_scripts]
-fcopy = pyutilscripts.fcopy:main
-forward.tcp = pyutilscripts.forward_tcp:main
-prunedirs = pyutilscripts.prunedirs:main

pyutilscripts-0.8.0/pyutilscripts.egg-info/requires.txt

@@ -1,7 +0,0 @@
-click
-natsort
-termcolor
-
-[dev]
-pytest
-pytest-cov

pyutilscripts-0.8.0/pyutilscripts.egg-info/top_level.txt

@@ -1 +0,0 @@
-pyutilscripts

pyutilscripts-0.8.0/setup.cfg

@@ -1,4 +0,0 @@
-[egg_info]
-tag_build = 
-tag_date = 0
-