# subprocess

Python API: `modelconverter.utils.subprocess`

转换使用的外部命令的执行。

转换通过命令行工具驱动供应商工具链。这里的辅助函数运行此类命令，将其输出流式传输到日志（删除 ANSI 转义序列），并记录整个进程树的峰值内存使用量和挂钟运行时间。

## 类

### SubprocessHandle

一个上下文管理器，它封装了一个子进程，具有实时 psutil 访问和延迟结果收集功能。

#### 方法

##### init

```python
def __init__(cmd: str | Sequence[PathType], *, silent: bool = False, timeout: float | None = None):
```

初始化子进程句柄。

参数

 * `cmd` (`str | Sequence[PathType]`): 要执行的命令。如果给定字符串，它将按空格分割。如果给定列表，每个元素将转换为字符串。
 * `silent` (`bool`): 如果为 `True`，则抑制来自命令的所有输出。
 * `timeout` (`float | None`): 如果给定，则为允许进程运行的最大时间（秒）。超时超出时会引发 `subprocess.TimeoutExpired` -- 从真值测试（也会终止进程）或从 `wait`（使其继续运行）。

##### is_suspended

```python
def is_suspended(self) -> bool:
```

返回进程当前是否已暂停。

##### poll

```python
def poll(self) -> int | None:
```

检查进程是否已终止。

返回

 * `int | None`: 返回码，如果进程仍在运行则为 `None`。

##### result

```python
def result(self) -> SubprocessResult:
```

收集已完成进程的结果。

等待读取器线程完成并记录运行摘要，除非句柄处于静默状态。

返回

 * `SubprocessResult`: 命令的结果，包含其捕获的输出、峰值内存使用量和总运行时间。

引发

 * `subprocess.SubprocessError`: 如果命令以非零返回码完成。

##### resume

```python
def resume(self):
```

恢复进程。

##### suspend

```python
def suspend(self):
```

暂停进程。

##### wait

```python
def wait(timeout: float | None = None) -> int:
```

等待进程终止。

参数

 * `timeout` (`float | None`): 最大等待时间（秒）。如果创建句柄时已给定超时，则忽略此参数。

返回

 * `int`: 进程的返回码。

引发

 * `subprocess.TimeoutExpired`: 如果进程未在超时时间内完成。与真值测试不同，这会使进程继续运行。

#### 属性

##### proc

返回底层的 `subprocess.Popen` 对象。

引发

 * `RuntimeError`: 如果进程尚未启动。

##### ps_proc

返回封装进程的 `psutil.Process`。

引发

 * `RuntimeError`: 如果进程尚未启动。

### SubprocessResult

`subprocess.CompletedProcess` 的扩展，也包含峰值内存使用量。

#### 方法

##### init

```python
def __init__(*args, peak_memory: int, total_time: float, **kwargs):
```

初始化结果。

参数

 * `*args`: 传递给 `subprocess.CompletedProcess` 的位置参数。
 * `peak_memory` (`int`): 进程及其子进程的峰值内存使用量，以字节为单位。
 * `total_time` (`float`): 进程的挂钟运行时间，以秒为单位。
 * `**kwargs`: 传递给 `subprocess.CompletedProcess` 的关键字参数。

#### 属性

##### peak_memory

进程及其子进程的峰值内存使用量，以字节为单位。

##### total_time

进程的挂钟运行时间，以秒为单位。

## 函数

### strip_ansi

```python
def strip_ansi(s: str) -> str:
```

从字符串中删除 ANSI 转义序列。

> **示例**
> ```pycon
>>> strip_ansi("\x1b[31mred\x1b[0m")
'red'
```

参数

 * `s` (`str`): 要剥离的字符串。

返回

 * `str`: 不带 ANSI 转义序列的字符串。

### subprocess_run

```python
def subprocess_run(cmd: str | Sequence[PathType], *, silent: bool = False, timeout: float | None = None) -> SubprocessResult:
```

运行命令并阻塞直到它完成。

[SubprocessHandle](/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter/modelconverter-api-reference/utils/subprocess.md) 的向后兼容包装器。

参数

 * `cmd` (`str | Sequence[PathType]`): 要执行的命令。如果给定字符串，它将按空格分割。如果给定列表，每个元素将转换为字符串。
 * `silent` (`bool`): 如果为 `True`，则抑制来自命令的所有输出。
 * `timeout` (`float | None`): 如果给定，则为允许进程运行的最大时间（秒）。如果超时超出，进程将被终止并引发 `subprocess.TimeoutExpired`。

返回

 * `SubprocessResult`: 命令的结果。
