# PyCommander

**Repository Path**: reneryan/py-commander

## Basic Information

- **Project Name**: PyCommander
- **Description**: 使用Python开发一个类，提供静态方法，用于多个IP之间的通信、文件传输、指令发送等功能。如：电脑A向B发送指令run test.py，B接收指令并执行。需要兼容WIN XP、WIN7、中标麒麟V4，使用虚拟环境测试，并提供测试用例和测试环境。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-18
- **Last Updated**: 2025-06-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PyCommander项目开发总结

## 项目概述
PyCommander是一个Python库，提供用于多个IP之间通信的静态方法，包括文件传输、命令执行和消息发送功能。设计目标是确保与Windows XP、Windows 7、中标麒麟V4和中标麒麟V7的跨平台兼容性。

## 主要功能
1. 远程命令执行
2. 机器间文件传输
3. 消息发送和接收
4. 系统信息获取
5. 简单的ping功能

## 开发历程

### 初始兼容性问题修复
- 修复`subprocess.run`的`capture_output`参数在Python 3.6中不兼容的问题
- 将`capture_output=True`替换为`stdout=subprocess.PIPE, stderr=subprocess.PIPE`

### 功能需求完善
- 添加消息发送和接收功能
- 确保每个实例既是服务端又是客户端
- 完善四个主要静态方法：初始化/启动、消息发送、文件传输、远端命令执行

### Python 3.4兼容性增强
- 修复f-string语法不兼容问题
- 替换所有格式化字符串为`.format()`方法
- 修复typing模块导入错误
- 移除所有函数参数和返回值的类型注解
- 修复os.makedirs的exist_ok参数不可用问题
- 修复`subprocess.run()`方法在Python 3.4中不可用的问题，使用`subprocess.Popen()`替代
- 修复`subprocess.Popen()`不支持encoding参数的问题，使用`io.TextIOWrapper`处理编码
- 实现自定义的非阻塞读取机制，替代Python 3.6+的`communicate(timeout=)`功能

### 命令执行增强
- 改进多行命令执行支持
- 智能判断命令行数：单行命令直接执行，多行命令写入临时文件
- 根据操作系统类型自动选择合适的解释器（Windows使用cmd，Linux使用bash）
- 根据操作系统类型自动选择正确的编码（Windows使用GBK，Linux使用UTF-8）
- 修复Windows XP下的GBK编码问题
- 增强命令执行的错误处理和超时管理

### 测试增强
- 增强测试客户端的调试能力，添加完整响应的打印输出
- 修复测试用例中的Python脚本编码问题
- 创建全面的测试用例文档
- 添加多行命令和特殊字符的测试用例

### 文档更新
- 更新测试环境文档，确保Windows XP兼容性
- 修改Python版本要求为3.4+
- 明确指出Windows XP最高支持Python 3.4
- 提供已测试的Python下载链接
- 添加编码问题的解决方案说明

## 技术栈
- Python 3.4+（确保各系统兼容性）
- 标准库模块（无外部依赖）

## 修改的文件
- py_commander.py：核心功能实现
- test_client.py：测试客户端
- test_server.py：测试服务器
- README.md：项目文档
- 测试环境说明.md：测试环境设置指南
- 测试用例.md：测试用例集合

## 功能特点

- 远程命令执行
- 机器间文件传输
- 消息发送和接收
- 系统信息获取
- 简单的ping功能
- 跨平台兼容性（Windows XP、Windows 7、中标麒麟V4）

## 系统要求

- Python 3.6或更高版本
- 仅标准库模块（无外部依赖）

## 安装

1. 克隆仓库：
   ```
   git clone https://gitee.com/reneryan/py-commander.git
   cd PyCommander
   ```

2. （可选）创建虚拟环境：
   ```
   python -m venv venv
   ```

3. （可选）激活虚拟环境：
   - Windows：
     ```
     venv\Scripts\activate
     ```
   - Linux/macOS：
     ```
     source venv/bin/activate
     ```

## 使用方法

### 启动服务器

启动监听传入连接的服务器：

```python
from py_commander import PyCommander

# 在默认端口(9999)上启动服务器
PyCommander.start_server()

# 在自定义端口上启动服务器，带有回调函数
def my_callback(data, response, address):
    print(f"从 {address[0]} 接收到 {data.get('type')} 命令")
    print(f"响应: {response}")

PyCommander.start_server(port=8888, callback=my_callback)
```

### 发送消息

向远程机器发送消息：

```python
from py_commander import PyCommander

# 向远程机器发送消息
response = PyCommander.send_message("192.168.1.100", "这是一条测试消息")

# 检查响应
if response['status'] == 'success':
    print(f"消息发送成功: {response.get('message')}")
else:
    print(f"消息发送失败: {response.get('message')}")
```

### 向远程机器发送命令

向远程机器发送要执行的命令：

```python
from py_commander import PyCommander

# 向远程机器发送命令
response = PyCommander.send_command("192.168.1.100", "echo PyCommander测试成功")

# 检查响应
if response['status'] == 'success':
    print(f"命令执行成功！")
    print(f"输出: {response.get('stdout')}")
else:
    print(f"命令执行失败: {response.get('message')}")
```

### 传输文件

向远程机器发送文件：

```python
from py_commander import PyCommander

# 向远程机器发送文件
response = PyCommander.send_file("192.168.1.100", "local_file.txt", "remote_file.txt")

# 检查响应
if response['status'] == 'success':
    print(f"文件传输成功: {response.get('message')}")
else:
    print(f"文件传输失败: {response.get('message')}")
```

### Ping远程机器

Ping远程机器并获取系统信息：

```python
from py_commander import PyCommander

# Ping远程机器
response = PyCommander.ping("192.168.1.100")

# 检查响应
if response['status'] == 'success':
    print(f"Ping成功！")
    print(f"系统信息: {response.get('system_info')}")
else:
    print(f"Ping失败: {response.get('message')}")
```

## 测试脚本

仓库包含几个演示PyCommander功能的测试脚本：

1. `test_server.py` - 启动PyCommander服务器
2. `test_client.py` - 测试客户端功能（ping、命令执行、文件传输）
3. `test_run_script.py` - 演示如何在远程机器上运行Python脚本
4. `sample_script.py` - 可用于测试远程执行的示例脚本

### 运行测试服务器

```
python test_server.py [port]
```

### 运行测试客户端

```
python test_client.py --target <IP> --port <PORT> --action <ACTION>
```

可用操作：
- `ping` - 测试ping功能
- `message` - 测试消息发送功能
- `execute` - 测试命令执行功能
- `transfer` - 测试文件传输功能
- `all` - 测试所有功能

### 运行远程脚本

```
python test_run_script.py --target <IP> --port <PORT> --script <SCRIPT_PATH> [--remote-path <REMOTE_PATH>]
```

## 测试环境

该库已在以下环境中进行了测试：

1. Windows XP
2. Windows 7
3. 中标麒麟V4

在虚拟环境中测试：

1. 使用目标操作系统设置虚拟机
2. 在每台机器上安装Python
3. 在一台机器上启动PyCommander服务器
4. 从另一台机器使用客户端脚本测试功能

## 安全考虑

- 该库默认不实现身份验证或加密
- 建议仅在受信任的网络中使用此库
- 对于生产用途，请考虑添加身份验证和加密机制

## 许可证

本项目采用MIT许可证 - 详情请参阅LICENSE文件

## 会话总结

### 会话的主要目的
修复PyCommander在Windows XP环境下Python 3.4.4版本运行时出现的"'NoneType' object is not subscriptable"错误问题。

### 完成的主要任务
1. 修复了typing模块在Python 3.4.4中的兼容性问题
2. 创建了一个自定义的_DummyType类来处理类型注解的泛型
3. 移除了所有函数参数和返回值的类型注解
4. 确保代码在Python 3.4.4环境下正常工作

### 关键决策和解决方案
- 识别问题根源：Python 3.4.4不完全支持typing模块，在导入失败时简单地将类型设置为None会导致后续使用类型注解时出错
- 解决方案：
  - 创建了一个_DummyType类来模拟泛型类型的行为
  - 为Callable类型创建了一个函数替代
  - 完全移除了函数参数和返回值的类型注解

### 使用的技术栈
- Python 3.4.4兼容代码
- 类型注解向后兼容处理技术

### 修改了哪些文件
- `py_commander.py`: 修改了typing模块的导入方式和函数签名，移除了类型注解

## 会话总结 - 2023-07-06

### 会话的主要目的
修复PyCommander在Windows XP环境下运行test2.py时出现的参数错误问题。

### 完成的主要任务
1. 修复了Network.start_server方法的参数问题，将callback参数改回为可选参数

### 关键决策和解决方案
- 识别问题根源：在之前移除类型注解时，错误地将start_server方法的callback参数从可选参数变成了必需参数
- 解决方案：
  - 恢复start_server方法的参数列表，将callback参数设置为可选参数，默认值为None

### 使用的技术栈
- Python 3.4.4兼容代码

### 修改了哪些文件
- `py_commander.py`: 修复了start_server方法的参数定义

## 会话总结 - 2023-07-07

### 会话的主要目的
增强网络通信的稳定性，为PyCommander添加自动重试机制。

### 完成的主要任务
1. 为Network._send_data方法添加重试机制，当遇到非超时错误时自动重试
2. 实现了最多重试3次，每次间隔5秒的策略
3. 区分了超时错误（不重试）和其他网络错误（重试）

### 关键决策和解决方案
- 识别不同类型的错误并分别处理：
  - 对于socket.timeout异常，直接返回错误，不进行重试
  - 对于其他socket.error和一般Exception，执行重试策略
- 实现重试逻辑：
  - 使用循环结构实现最多3次重试
  - 每次重试前休眠5秒
  - 通过logging记录重试过程和结果
  - 返回详细的错误信息，包括重试次数

### 使用的技术栈
- Python 3.4.4兼容代码
- 异常处理与错误恢复
- 日志记录

### 修改了哪些文件
- `py_commander.py`: 增强了_send_data方法，添加了重试机制

## 会话总结 - 2023-07-08

### 会话的主要目的
增强命令执行功能，添加命令执行结果的返回值字段。

### 完成的主要任务
1. 为命令执行响应数据增加`return_value`字段，用于直接获取命令的执行结果
2. 根据不同的执行情况设置不同的返回值内容：
   - 正常执行：使用stdout内容或returncode值
   - 执行超时：返回"timeout"
   - 执行异常：返回"exception: 异常信息"

### 关键决策和解决方案
- 如何确定返回值内容：
  - 优先使用stdout的内容（如果存在）作为返回值，提供最有用的命令执行结果
  - 如果stdout为空，则使用returncode作为返回值
  - 特殊情况（超时、异常）下提供明确的状态信息
- 确保所有执行路径都包含return_value字段，包括:
  - 单行命令执行
  - 多行命令执行
  - 超时情况
  - 异常情况

### 使用的技术栈
- Python 3.4.4兼容代码
- 命令执行结果处理

### 修改了哪些文件
- `py_commander.py`: 在Network._process_command方法中增加了return_value字段的处理

## 会话总结 - 2023-07-09

### 会话的主要目的
优化命令执行的返回值处理，使返回值更加精确和有用。

### 完成的主要任务
1. 修改了`return_value`字段的处理逻辑，当stdout有内容时只返回最后一行
2. 保留了其他情况的处理逻辑不变（返回码、超时和异常情况）

### 关键决策和解决方案
- 为什么选择返回最后一行：
  - 许多命令的最终结果或摘要通常显示在输出的最后一行
  - 对于多行输出的命令，最后一行往往包含最关键的信息
  - 这种处理使返回值更加简洁，更适合作为单一结果返回
- 实现方式：
  - 使用字符串的`split('\n')`方法将输出拆分为行列表
  - 通过索引`[-1]`获取最后一行
  - 使用`strip()`方法去除前后空白字符

### 使用的技术栈
- Python 3.4.4兼容代码
- 字符串处理

### 修改了哪些文件
- `py_commander.py`: 优化了Network._process_command方法中的返回值处理逻辑

## 会话总结 - 2023-07-10

### 会话的主要目的
修复test1.py中处理消息时的空指针错误。

### 完成的主要任务
1. 修复了test1.py中当`msg`为`None`时仍尝试访问`msg['message']`导致的`TypeError`错误
2. 优化了消息处理的逻辑顺序，确保代码更加健壮

### 关键决策和解决方案
- 错误原因分析：
  - 在循环中先获取msg，然后未检查是否为None就直接访问其字段
  - 先访问`msg['message']`然后才检查`if msg != None`导致逻辑错误
- 解决方案：
  - 调整代码顺序，先检查`msg is None`，如果是则跳过当前循环
  - 确保只有在msg不为None的情况下才访问其字段
  - 使用`is None`代替`!= None`进行更精确的比较

### 使用的技术栈
- Python 3.4.4兼容代码
- 错误处理和防御性编程

### 修改了哪些文件
- `test1.py`: 修复了消息处理逻辑，避免None值导致的TypeError

## 会话总结 - 2023-07-11

### 会话的主要目的
分析现有的消息处理控制方法的有用性，并添加异步操作支持，实现并发的消息发送、文件传输和远端命令执行功能。

### 完成的主要任务
1. 分析了pause_listening、resume_listening、is_listening、is_server_running等方法的用途和有效性
2. 添加了异步版本的核心方法：
   - send_message_async: 异步消息发送
   - send_command_async: 异步命令执行
   - send_file_async: 异步文件传输
   - ping_async: 异步ping操作
3. 增加了shutdown方法用于清理资源
4. 创建了演示异步操作的测试文件

### 关键决策和解决方案
- 分析确认了监听控制方法的价值：
  - 它们提供了对消息处理的精细控制
  - 对于系统监控和状态管理很重要
  - 在实现高可用性服务时非常有用
- 异步操作实现策略：
  - 使用concurrent.futures.ThreadPoolExecutor实现线程池
  - 为每个核心方法添加异步版本，保持原有同步方法不变
  - 提供回调机制，方便进行异步结果处理
  - 返回Future对象，便于检查结果和等待完成
- 资源管理：
  - 添加shutdown方法确保正确清理线程池和服务器资源
  - 防止资源泄露问题

### 使用的技术栈
- Python 3.4.4兼容代码
- 多线程编程(concurrent.futures)
- 异步回调模式
- 资源管理和清理机制

### 修改了哪些文件
- `py_commander.py`: 添加了异步操作支持和资源管理方法
- 新增 `test_async.py`: 创建了测试异步操作的示例文件

## 会话总结 - 2023-07-12

### 会话的主要目的
创建双机通信测试文件，实现两台机器之间的互相通信，包括消息发送、文件传输和远程命令执行功能。

### 完成的主要任务
1. 创建了机器A测试程序(machine_A.py)
2. 创建了机器B测试程序(machine_B.py)
3. 编写了详细的双机通信测试指南(communication_test_readme.md)
4. 实现了全面的通信功能测试，包括同步和异步操作

### 关键决策和解决方案
- 测试文件设计:
  - 每个测试文件既是服务器也是客户端，可以同时接收和发送数据
  - 使用菜单系统提供用户友好的交互界面
  - 自动创建测试目录和文件，便于快速开始测试
- 功能实现:
  - 使用回调函数处理接收到的不同类型的消息
  - 提供同步和异步两种操作模式
  - 实现资源的正确创建和清理
  - 增加错误处理和友好的结果反馈
- 用户体验:
  - 详细的操作提示和结果显示
  - 文件管理功能，可查看接收到的文件
  - 输入验证和错误处理

### 使用的技术栈
- Python 3.4.4兼容代码
- 网络通信(socket)
- 文件和目录操作(os, io)
- 异步编程(concurrent.futures)
- 用户交互设计

### 修改了哪些文件
- 新增 `machine_A.py`: 机器A的测试程序
- 新增 `machine_B.py`: 机器B的测试程序
- 新增 `communication_test_readme.md`: 双机通信测试指南

## 会话总结 - 2023-07-13

### 会话的主要目的
修复双机通信测试程序在Python 3.4.4环境下的兼容性问题，确保在Windows XP等旧系统上正常运行。

### 完成的主要任务
1. 修复了machine_A.py和machine_B.py中使用f-string导致的语法错误
2. 将所有f-string格式化字符串替换为Python 3.4兼容的`.format()`方式

### 关键决策和解决方案
- 识别问题：
  - 错误"SyntaxError: invalid syntax"是由于Python 3.4不支持f-string（在Python 3.6才引入）
  - f-string格式如`f"文本 {变量}"`在Python 3.4中无法解析
- 修复方案：
  - 使用Python 3.4兼容的字符串格式化方法`.format()`
  - 将所有`f"文本 {变量}"`替换为`"文本 {0}".format(变量)`
  - 确保复杂格式化字符串中的占位符索引正确

### 使用的技术栈
- Python 3.4.4兼容代码
- 传统字符串格式化

### 修改了哪些文件
- `machine_A.py`: 更新了所有字符串格式化方式
- `machine_B.py`: 更新了所有字符串格式化方式