shellless-ops 0.1.0__tar.gz → 0.3.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- shellless_ops-0.3.0/PKG-INFO +106 -0
- shellless_ops-0.3.0/README.md +86 -0
- {shellless_ops-0.1.0 → shellless_ops-0.3.0}/pyproject.toml +7 -7
- shellless_ops-0.3.0/src/shellless_ops/__init__.py +145 -0
- shellless_ops-0.3.0/src/shellless_ops/__main__.py +131 -0
- shellless_ops-0.3.0/src/shellless_ops/evidence.py +142 -0
- shellless_ops-0.3.0/tests/test_evidence.py +118 -0
- {shellless_ops-0.1.0 → shellless_ops-0.3.0}/tests/test_shellless_ops.py +94 -1
- shellless_ops-0.1.0/PKG-INFO +0 -69
- shellless_ops-0.1.0/README.md +0 -50
- shellless_ops-0.1.0/setup.cfg +0 -4
- shellless_ops-0.1.0/src/shellless_ops/__init__.py +0 -73
- shellless_ops-0.1.0/src/shellless_ops/__main__.py +0 -60
- shellless_ops-0.1.0/src/shellless_ops.egg-info/PKG-INFO +0 -69
- shellless_ops-0.1.0/src/shellless_ops.egg-info/SOURCES.txt +0 -11
- shellless_ops-0.1.0/src/shellless_ops.egg-info/dependency_links.txt +0 -1
- shellless_ops-0.1.0/src/shellless_ops.egg-info/entry_points.txt +0 -2
- shellless_ops-0.1.0/src/shellless_ops.egg-info/top_level.txt +0 -1
- {shellless_ops-0.1.0 → shellless_ops-0.3.0}/LICENSE +0 -0
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: shellless-ops
|
|
3
|
+
Version: 0.3.0
|
|
4
|
+
Summary: Cross-platform file and process tools with bounded Python failure evidence
|
|
5
|
+
Requires-Python: >=3.8
|
|
6
|
+
Description-Content-Type: text/markdown
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
Classifier: Development Status :: 3 - Alpha
|
|
9
|
+
Classifier: Operating System :: MacOS
|
|
10
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
11
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
14
|
+
Classifier: Topic :: Utilities
|
|
15
|
+
License-File: LICENSE
|
|
16
|
+
Project-URL: Issues, https://github.com/zhangs-cedar/shellless-ops/issues
|
|
17
|
+
Project-URL: Repository, https://github.com/zhangs-cedar/shellless-ops
|
|
18
|
+
Import-Name: shellless_ops
|
|
19
|
+
|
|
20
|
+
# shellless-ops
|
|
21
|
+
|
|
22
|
+
`shellless-ops` 是一套跨平台的 Python 文件和进程工具。它统一路径、编码、查找结果和退出码,减少同一任务需要分别维护 Bash 和 PowerShell 版本的情况。要求 Python 3.8+,无运行时依赖。
|
|
23
|
+
|
|
24
|
+
## 安装
|
|
25
|
+
|
|
26
|
+
从 [PyPI](https://pypi.org/project/shellless-ops/) 安装:
|
|
27
|
+
|
|
28
|
+
```text
|
|
29
|
+
python -m pip install shellless-ops
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## 示例
|
|
33
|
+
|
|
34
|
+
```python
|
|
35
|
+
import sys
|
|
36
|
+
|
|
37
|
+
from shellless_ops import find_files, mkdir, run, write_text
|
|
38
|
+
|
|
39
|
+
out = mkdir("build reports")
|
|
40
|
+
write_text(out / "summary.txt", "ready\n")
|
|
41
|
+
files = find_files(out, "*.txt")
|
|
42
|
+
result = run([sys.executable, "--version"], cwd=out, timeout=10)
|
|
43
|
+
print(files, result.stdout.strip())
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
```text
|
|
47
|
+
shellless-ops mkdir "build reports"
|
|
48
|
+
shellless-ops write "build reports/summary.txt" "ready"
|
|
49
|
+
shellless-ops copy "build reports/summary.txt" "build reports/backup.txt"
|
|
50
|
+
shellless-ops find "build reports" --pattern "*.txt"
|
|
51
|
+
shellless-ops search "build reports" "ready" --pattern "*.txt" --limit 5
|
|
52
|
+
shellless-ops read "build reports/summary.txt"
|
|
53
|
+
shellless-ops run --timeout 10 -- python --version
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
也可以用 `python -m shellless_ops`。任务运行器如果支持参数数组,传入 `["python", "-m", "shellless_ops", "find", "build reports", "--pattern", "*.txt"]`,无需拼 Shell 命令字符串。在终端直接键入命令时,仍需按当前 Shell 的规则给含空格的路径和通配模式加引号。
|
|
57
|
+
|
|
58
|
+
## 接口约定
|
|
59
|
+
|
|
60
|
+
| API | 行为 |
|
|
61
|
+
| --- | --- |
|
|
62
|
+
| `mkdir(path)` | 创建缺失的父目录,接受已存在的目录,返回 `Path`。 |
|
|
63
|
+
| `read_text(path)` / `write_text(path, text)` | 默认 UTF-8,保留原换行。写入要求父目录已存在,会覆盖原内容并返回 `Path`。CLI `read` 输出 UTF-8 字节。 |
|
|
64
|
+
| `copy_file(source, target)` | 复制内容到指定目标文件并返回 `Path`,目标已存在时拒绝覆盖。不复制元数据;写入中断时不清理部分目标文件。 |
|
|
65
|
+
| `find_files(root, pattern="*")` | 递归匹配文件名,区分大小写,包含隐藏文件。按使用 `/` 分隔的相对路径排序。跳过文件符号链接,不进入目录符号链接或扫描中遇到的 Windows 目录重解析点。CLI `find` 输出 JSON 路径数组,分隔符统一为 `/`。 |
|
|
66
|
+
| `search_text(root, query, *, pattern="*", limit=50, max_line_chars=240, max_files=1000, encoding="utf-8-sig")` | 搜索单文件或目录,按路径和行号返回区分大小写的字面命中。`pattern` 只筛目录内的文件名。默认读取 UTF-8(含 BOM);CLI `search` 输出 UTF-8 JSON。 |
|
|
67
|
+
| `run(argv, *, cwd=None, timeout=None, check=True, capture=True, encoding="utf-8")` | 用非空列表或元组分别传入程序和参数,返回 `subprocess.CompletedProcess`。默认按 UTF-8 捕获输出,非零退出抛出 `CalledProcessError`。`encoding=None` 返回字节,`capture=False` 继承输出。CLI `run` 继承输出并传递退出码,超时为 124,POSIX 信号终止为 `128 + 信号编号`。 |
|
|
68
|
+
|
|
69
|
+
`run` 不做变量展开、管道或重定向,不支持 Windows `.bat` 和 `.cmd`。程序查找遵循操作系统规则;要指定某个安装,传可执行文件的绝对路径。超时针对直接启动的子进程,不承诺回收整棵进程树。不经 Shell 启动不等于沙箱,只运行可信的程序和参数。
|
|
70
|
+
|
|
71
|
+
### 给 agent 的搜索结果
|
|
72
|
+
|
|
73
|
+
`search_text` 和 `search` 使用同一结果结构:
|
|
74
|
+
|
|
75
|
+
```json
|
|
76
|
+
{"matches":[{"path":"build reports/summary.txt","line":1,"text":"ready","text_truncated":false}],"truncated":false,"scan_limited":false,"skipped_decode":0}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
- `line` 从 1 开始。一行命中多次也只返回一条,以首次命中定位预览。
|
|
80
|
+
- `text_truncated` 表示预览被裁剪;`truncated` 表示已找到额外命中但没放进结果。精确凑满上限不算截断。
|
|
81
|
+
- 搜索目录默认跳过后代路径中的 `.git`、`.hg`、`.svn` 和 `.venv`。遇到解码失败的文件时丢弃该文件已收集的命中,累加 `skipped_decode` 后继续;显式搜索单文件时仍报错。缺路径或打开失败不会作为零命中返回。
|
|
82
|
+
- `--max-files` 限制最多打开多少个候选文件。发现尚未打开的候选文件时,`scan_limited` 为 `true`;这不代表后续一定有命中。遇到额外命中提前结束时,不会继续检查后续文件。文件数不是用时或单行内存上限。大仓库优先传更小的根目录或 `--pattern "*.py"`。
|
|
83
|
+
|
|
84
|
+
## 失败证据
|
|
85
|
+
|
|
86
|
+
给 agent 一份小报告,而不是把完整 traceback 和源码塞进同一个响应:
|
|
87
|
+
|
|
88
|
+
```text
|
|
89
|
+
shellless-ops evidence --output failure.json --var amount --source-root . -- script.py
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
命令保留脚本原本的输出和退出行为,未处理的异常仍打印 traceback(含运行器帧)。报告单独写入新建的 JSON 文件,不覆盖旧文件。agent 可以只读取报告,需要时再看进程输出。报告默认记录解释器、脚本路径和工作目录;脚本参数默认不记录,确认无敏感信息后可用 `--record-args`。`--code-version` 是调用方给出的复现提示,不证明内容与 Git 提交完全一致。
|
|
93
|
+
|
|
94
|
+
```python
|
|
95
|
+
from shellless_ops.evidence import capture
|
|
96
|
+
|
|
97
|
+
with capture(names=("amount",)) as report:
|
|
98
|
+
run_the_operation()
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
由原调用方处理异常,异常仍会传播;捕获后从 `report["failure"]` 读取证据。报告只包含最近 8 帧、失败帧中显式指定的变量和可选的 5 行源码。默认不读源码、不记录异常消息或环境变量,不调用对象的 `repr` 或 `__summary__`。若生成证据本身失败,报告用 `capture_error` 标记。这只观察当前 Python 进程里未处理的 `Exception`,不会分析子进程、已被业务处理的异常或 `SystemExit`。源码是捕获时磁盘上的文本。只选适合分享的变量和文件,报告不做脱敏。
|
|
102
|
+
|
|
103
|
+
## 贡献
|
|
104
|
+
|
|
105
|
+
欢迎提交 [Issue](https://github.com/zhangs-cedar/shellless-ops/issues) 或 Pull Request。在仓库目录执行 `python -m pip install .` 安装当前代码,再运行 `python -m unittest discover -s tests -v`。
|
|
106
|
+
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
# shellless-ops
|
|
2
|
+
|
|
3
|
+
`shellless-ops` 是一套跨平台的 Python 文件和进程工具。它统一路径、编码、查找结果和退出码,减少同一任务需要分别维护 Bash 和 PowerShell 版本的情况。要求 Python 3.8+,无运行时依赖。
|
|
4
|
+
|
|
5
|
+
## 安装
|
|
6
|
+
|
|
7
|
+
从 [PyPI](https://pypi.org/project/shellless-ops/) 安装:
|
|
8
|
+
|
|
9
|
+
```text
|
|
10
|
+
python -m pip install shellless-ops
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## 示例
|
|
14
|
+
|
|
15
|
+
```python
|
|
16
|
+
import sys
|
|
17
|
+
|
|
18
|
+
from shellless_ops import find_files, mkdir, run, write_text
|
|
19
|
+
|
|
20
|
+
out = mkdir("build reports")
|
|
21
|
+
write_text(out / "summary.txt", "ready\n")
|
|
22
|
+
files = find_files(out, "*.txt")
|
|
23
|
+
result = run([sys.executable, "--version"], cwd=out, timeout=10)
|
|
24
|
+
print(files, result.stdout.strip())
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
```text
|
|
28
|
+
shellless-ops mkdir "build reports"
|
|
29
|
+
shellless-ops write "build reports/summary.txt" "ready"
|
|
30
|
+
shellless-ops copy "build reports/summary.txt" "build reports/backup.txt"
|
|
31
|
+
shellless-ops find "build reports" --pattern "*.txt"
|
|
32
|
+
shellless-ops search "build reports" "ready" --pattern "*.txt" --limit 5
|
|
33
|
+
shellless-ops read "build reports/summary.txt"
|
|
34
|
+
shellless-ops run --timeout 10 -- python --version
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
也可以用 `python -m shellless_ops`。任务运行器如果支持参数数组,传入 `["python", "-m", "shellless_ops", "find", "build reports", "--pattern", "*.txt"]`,无需拼 Shell 命令字符串。在终端直接键入命令时,仍需按当前 Shell 的规则给含空格的路径和通配模式加引号。
|
|
38
|
+
|
|
39
|
+
## 接口约定
|
|
40
|
+
|
|
41
|
+
| API | 行为 |
|
|
42
|
+
| --- | --- |
|
|
43
|
+
| `mkdir(path)` | 创建缺失的父目录,接受已存在的目录,返回 `Path`。 |
|
|
44
|
+
| `read_text(path)` / `write_text(path, text)` | 默认 UTF-8,保留原换行。写入要求父目录已存在,会覆盖原内容并返回 `Path`。CLI `read` 输出 UTF-8 字节。 |
|
|
45
|
+
| `copy_file(source, target)` | 复制内容到指定目标文件并返回 `Path`,目标已存在时拒绝覆盖。不复制元数据;写入中断时不清理部分目标文件。 |
|
|
46
|
+
| `find_files(root, pattern="*")` | 递归匹配文件名,区分大小写,包含隐藏文件。按使用 `/` 分隔的相对路径排序。跳过文件符号链接,不进入目录符号链接或扫描中遇到的 Windows 目录重解析点。CLI `find` 输出 JSON 路径数组,分隔符统一为 `/`。 |
|
|
47
|
+
| `search_text(root, query, *, pattern="*", limit=50, max_line_chars=240, max_files=1000, encoding="utf-8-sig")` | 搜索单文件或目录,按路径和行号返回区分大小写的字面命中。`pattern` 只筛目录内的文件名。默认读取 UTF-8(含 BOM);CLI `search` 输出 UTF-8 JSON。 |
|
|
48
|
+
| `run(argv, *, cwd=None, timeout=None, check=True, capture=True, encoding="utf-8")` | 用非空列表或元组分别传入程序和参数,返回 `subprocess.CompletedProcess`。默认按 UTF-8 捕获输出,非零退出抛出 `CalledProcessError`。`encoding=None` 返回字节,`capture=False` 继承输出。CLI `run` 继承输出并传递退出码,超时为 124,POSIX 信号终止为 `128 + 信号编号`。 |
|
|
49
|
+
|
|
50
|
+
`run` 不做变量展开、管道或重定向,不支持 Windows `.bat` 和 `.cmd`。程序查找遵循操作系统规则;要指定某个安装,传可执行文件的绝对路径。超时针对直接启动的子进程,不承诺回收整棵进程树。不经 Shell 启动不等于沙箱,只运行可信的程序和参数。
|
|
51
|
+
|
|
52
|
+
### 给 agent 的搜索结果
|
|
53
|
+
|
|
54
|
+
`search_text` 和 `search` 使用同一结果结构:
|
|
55
|
+
|
|
56
|
+
```json
|
|
57
|
+
{"matches":[{"path":"build reports/summary.txt","line":1,"text":"ready","text_truncated":false}],"truncated":false,"scan_limited":false,"skipped_decode":0}
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
- `line` 从 1 开始。一行命中多次也只返回一条,以首次命中定位预览。
|
|
61
|
+
- `text_truncated` 表示预览被裁剪;`truncated` 表示已找到额外命中但没放进结果。精确凑满上限不算截断。
|
|
62
|
+
- 搜索目录默认跳过后代路径中的 `.git`、`.hg`、`.svn` 和 `.venv`。遇到解码失败的文件时丢弃该文件已收集的命中,累加 `skipped_decode` 后继续;显式搜索单文件时仍报错。缺路径或打开失败不会作为零命中返回。
|
|
63
|
+
- `--max-files` 限制最多打开多少个候选文件。发现尚未打开的候选文件时,`scan_limited` 为 `true`;这不代表后续一定有命中。遇到额外命中提前结束时,不会继续检查后续文件。文件数不是用时或单行内存上限。大仓库优先传更小的根目录或 `--pattern "*.py"`。
|
|
64
|
+
|
|
65
|
+
## 失败证据
|
|
66
|
+
|
|
67
|
+
给 agent 一份小报告,而不是把完整 traceback 和源码塞进同一个响应:
|
|
68
|
+
|
|
69
|
+
```text
|
|
70
|
+
shellless-ops evidence --output failure.json --var amount --source-root . -- script.py
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
命令保留脚本原本的输出和退出行为,未处理的异常仍打印 traceback(含运行器帧)。报告单独写入新建的 JSON 文件,不覆盖旧文件。agent 可以只读取报告,需要时再看进程输出。报告默认记录解释器、脚本路径和工作目录;脚本参数默认不记录,确认无敏感信息后可用 `--record-args`。`--code-version` 是调用方给出的复现提示,不证明内容与 Git 提交完全一致。
|
|
74
|
+
|
|
75
|
+
```python
|
|
76
|
+
from shellless_ops.evidence import capture
|
|
77
|
+
|
|
78
|
+
with capture(names=("amount",)) as report:
|
|
79
|
+
run_the_operation()
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
由原调用方处理异常,异常仍会传播;捕获后从 `report["failure"]` 读取证据。报告只包含最近 8 帧、失败帧中显式指定的变量和可选的 5 行源码。默认不读源码、不记录异常消息或环境变量,不调用对象的 `repr` 或 `__summary__`。若生成证据本身失败,报告用 `capture_error` 标记。这只观察当前 Python 进程里未处理的 `Exception`,不会分析子进程、已被业务处理的异常或 `SystemExit`。源码是捕获时磁盘上的文本。只选适合分享的变量和文件,报告不做脱敏。
|
|
83
|
+
|
|
84
|
+
## 贡献
|
|
85
|
+
|
|
86
|
+
欢迎提交 [Issue](https://github.com/zhangs-cedar/shellless-ops/issues) 或 Pull Request。在仓库目录执行 `python -m pip install .` 安装当前代码,再运行 `python -m unittest discover -s tests -v`。
|
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
[build-system]
|
|
2
|
-
requires = ["
|
|
3
|
-
build-backend = "
|
|
2
|
+
requires = ["flit_core>=4.2,<5"]
|
|
3
|
+
build-backend = "flit_core.buildapi"
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "shellless-ops"
|
|
7
|
-
version = "0.
|
|
8
|
-
description = "
|
|
7
|
+
version = "0.3.0"
|
|
8
|
+
description = "Cross-platform file and process tools with bounded Python failure evidence"
|
|
9
9
|
readme = "README.md"
|
|
10
|
-
requires-python = ">=3.
|
|
10
|
+
requires-python = ">=3.8"
|
|
11
11
|
license = "MIT"
|
|
12
12
|
license-files = ["LICENSE"]
|
|
13
13
|
classifiers = [
|
|
@@ -27,5 +27,5 @@ Issues = "https://github.com/zhangs-cedar/shellless-ops/issues"
|
|
|
27
27
|
[project.scripts]
|
|
28
28
|
shellless-ops = "shellless_ops.__main__:main"
|
|
29
29
|
|
|
30
|
-
[tool.
|
|
31
|
-
|
|
30
|
+
[tool.flit.sdist]
|
|
31
|
+
include = ["tests/*.py"]
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
import os
|
|
2
|
+
import shutil
|
|
3
|
+
import stat
|
|
4
|
+
import subprocess
|
|
5
|
+
from codecs import lookup
|
|
6
|
+
from fnmatch import fnmatchcase
|
|
7
|
+
from pathlib import Path
|
|
8
|
+
|
|
9
|
+
__all__ = ["copy_file", "find_files", "mkdir", "read_text", "run", "search_text", "write_text"]
|
|
10
|
+
|
|
11
|
+
_SEARCH_EXCLUDES = {".git", ".hg", ".svn", ".venv"}
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def mkdir(path):
|
|
15
|
+
path = Path(path)
|
|
16
|
+
path.mkdir(parents=True, exist_ok=True)
|
|
17
|
+
return path
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def read_text(path, *, encoding="utf-8"):
|
|
21
|
+
with Path(path).open(encoding=encoding, newline="") as stream:
|
|
22
|
+
return stream.read()
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def write_text(path, text, *, encoding="utf-8"):
|
|
26
|
+
path = Path(path)
|
|
27
|
+
with path.open("w", encoding=encoding, newline="") as stream:
|
|
28
|
+
stream.write(text)
|
|
29
|
+
return path
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def copy_file(source, target):
|
|
33
|
+
"""Copy file contents to a new path without overwriting."""
|
|
34
|
+
target = Path(target)
|
|
35
|
+
with Path(source).open("rb") as reader, target.open("xb") as writer:
|
|
36
|
+
shutil.copyfileobj(reader, writer)
|
|
37
|
+
return target
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def find_files(root, pattern="*"):
|
|
41
|
+
"""Match file basenames recursively without following directory links."""
|
|
42
|
+
return list(_matching_files(Path(root), pattern))
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def _matching_files(root, pattern, *, exclude=()):
|
|
46
|
+
pending = [(root, True)]
|
|
47
|
+
while pending:
|
|
48
|
+
path, directory = pending.pop()
|
|
49
|
+
if not directory:
|
|
50
|
+
yield path
|
|
51
|
+
continue
|
|
52
|
+
children = []
|
|
53
|
+
with os.scandir(path) as entries:
|
|
54
|
+
for entry in entries:
|
|
55
|
+
if exclude and entry.name.casefold() in exclude:
|
|
56
|
+
continue
|
|
57
|
+
if entry.is_dir(follow_symlinks=False):
|
|
58
|
+
# Windows junctions are not always reported as symlinks.
|
|
59
|
+
if os.name == "nt" and (
|
|
60
|
+
entry.stat(follow_symlinks=False).st_file_attributes
|
|
61
|
+
& stat.FILE_ATTRIBUTE_REPARSE_POINT
|
|
62
|
+
):
|
|
63
|
+
continue
|
|
64
|
+
children.append((Path(entry.path), True))
|
|
65
|
+
elif fnmatchcase(entry.name, pattern) and entry.is_file(follow_symlinks=False):
|
|
66
|
+
children.append((Path(entry.path), False))
|
|
67
|
+
# Include the separator in the sort key so descendants keep path order.
|
|
68
|
+
children.sort(key=lambda item: item[0].name + ("/" if item[1] else ""), reverse=True)
|
|
69
|
+
pending.extend(children)
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def search_text(
|
|
73
|
+
root, query, *, pattern="*", limit=50, max_line_chars=240, max_files=1000, encoding="utf-8-sig"
|
|
74
|
+
):
|
|
75
|
+
"""Return bounded, case-sensitive literal matches, one per line."""
|
|
76
|
+
if not query or "\n" in query or "\r" in query:
|
|
77
|
+
raise ValueError("query must be nonempty and single-line")
|
|
78
|
+
for name, value in (
|
|
79
|
+
("limit", limit), ("max_line_chars", max_line_chars), ("max_files", max_files)
|
|
80
|
+
):
|
|
81
|
+
if type(value) is not int or value < 1:
|
|
82
|
+
raise ValueError(f"{name} must be a positive integer")
|
|
83
|
+
try:
|
|
84
|
+
lookup(encoding)
|
|
85
|
+
except LookupError as error:
|
|
86
|
+
raise ValueError(str(error)) from error
|
|
87
|
+
|
|
88
|
+
root = Path(root)
|
|
89
|
+
single_file = stat.S_ISREG(root.stat().st_mode)
|
|
90
|
+
paths = [root] if single_file else _matching_files(root, pattern, exclude=_SEARCH_EXCLUDES)
|
|
91
|
+
matches = []
|
|
92
|
+
report = {"matches": matches, "truncated": False, "scan_limited": False, "skipped_decode": 0}
|
|
93
|
+
for file_number, path in enumerate(paths, 1):
|
|
94
|
+
if file_number > max_files:
|
|
95
|
+
report["scan_limited"] = True
|
|
96
|
+
break
|
|
97
|
+
checkpoint = len(matches)
|
|
98
|
+
try:
|
|
99
|
+
with path.open(encoding=encoding) as stream:
|
|
100
|
+
for line_number, line in enumerate(stream, 1):
|
|
101
|
+
index = line.find(query)
|
|
102
|
+
if index < 0:
|
|
103
|
+
continue
|
|
104
|
+
if len(matches) == limit:
|
|
105
|
+
report["truncated"] = True
|
|
106
|
+
return report
|
|
107
|
+
|
|
108
|
+
text = line[:-1] if line.endswith("\n") else line
|
|
109
|
+
clipped = len(text) > max_line_chars
|
|
110
|
+
if clipped:
|
|
111
|
+
context = max(0, (max_line_chars - len(query)) // 2)
|
|
112
|
+
start = min(max(0, index - context), len(text) - max_line_chars)
|
|
113
|
+
text = text[start:start + max_line_chars]
|
|
114
|
+
matches.append({
|
|
115
|
+
"path": path.as_posix(),
|
|
116
|
+
"line": line_number,
|
|
117
|
+
"text": text,
|
|
118
|
+
"text_truncated": clipped,
|
|
119
|
+
})
|
|
120
|
+
except UnicodeDecodeError as error:
|
|
121
|
+
if single_file:
|
|
122
|
+
raise ValueError(f"{path}: {error}") from error
|
|
123
|
+
del matches[checkpoint:]
|
|
124
|
+
report["skipped_decode"] += 1
|
|
125
|
+
except LookupError as error:
|
|
126
|
+
raise ValueError(f"{path}: {error}") from error
|
|
127
|
+
return report
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
def run(argv, *, cwd=None, timeout=None, check=True, capture=True, encoding="utf-8"):
|
|
131
|
+
if not isinstance(argv, (list, tuple)) or not argv:
|
|
132
|
+
raise TypeError("argv must be a non-empty list or tuple")
|
|
133
|
+
if os.name == "nt":
|
|
134
|
+
executable = os.fsdecode(argv[0]).rstrip(" .").lower()
|
|
135
|
+
if executable.endswith((".bat", ".cmd")):
|
|
136
|
+
raise ValueError("Windows batch files are not supported")
|
|
137
|
+
return subprocess.run(
|
|
138
|
+
argv,
|
|
139
|
+
cwd=cwd,
|
|
140
|
+
timeout=timeout,
|
|
141
|
+
check=check,
|
|
142
|
+
capture_output=capture,
|
|
143
|
+
encoding=encoding,
|
|
144
|
+
shell=False,
|
|
145
|
+
)
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
import argparse
|
|
2
|
+
import json
|
|
3
|
+
import runpy
|
|
4
|
+
import subprocess
|
|
5
|
+
import sys
|
|
6
|
+
from pathlib import Path
|
|
7
|
+
|
|
8
|
+
from . import copy_file, find_files, mkdir, read_text, run, search_text, write_text
|
|
9
|
+
from .evidence import capture
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
def _run_evidence(args, parser):
|
|
13
|
+
if args.script[:1] == ["--"]:
|
|
14
|
+
args.script.pop(0)
|
|
15
|
+
if not args.script:
|
|
16
|
+
parser.error("a Python script is required")
|
|
17
|
+
|
|
18
|
+
try:
|
|
19
|
+
script = Path(args.script[0]).resolve()
|
|
20
|
+
manager = capture(names=args.var, source_root=args.source_root)
|
|
21
|
+
if not script.is_file():
|
|
22
|
+
parser.error(f"script is not a file: {script}")
|
|
23
|
+
command = [sys.executable, str(script), *args.script[1:]]
|
|
24
|
+
repro = {"argv": command if args.record_args else command[:2], "cwd": str(Path.cwd())}
|
|
25
|
+
if not args.record_args and len(command) > 2:
|
|
26
|
+
repro["omitted_args"] = len(command) - 2
|
|
27
|
+
if args.code_version is not None:
|
|
28
|
+
repro["code_version"] = args.code_version
|
|
29
|
+
stream = Path(args.output).open("x", encoding="utf-8", errors="backslashreplace")
|
|
30
|
+
except (OSError, ValueError) as error:
|
|
31
|
+
parser.exit(1, f"shellless-ops: {error}\n")
|
|
32
|
+
|
|
33
|
+
argv, path = sys.argv, sys.path
|
|
34
|
+
sys.argv = command[1:]
|
|
35
|
+
sys.path = [str(script.parent), *path]
|
|
36
|
+
try:
|
|
37
|
+
with manager as report:
|
|
38
|
+
runpy.run_path(str(script), run_name="__main__")
|
|
39
|
+
finally:
|
|
40
|
+
sys.argv, sys.path = argv, path
|
|
41
|
+
# Finalization errors must not change an active script exception.
|
|
42
|
+
active_error = sys.exc_info()[1]
|
|
43
|
+
try:
|
|
44
|
+
with stream:
|
|
45
|
+
json.dump(
|
|
46
|
+
{"repro": repro, **report}, stream, ensure_ascii=False, separators=(",", ":")
|
|
47
|
+
)
|
|
48
|
+
stream.write("\n")
|
|
49
|
+
except OSError:
|
|
50
|
+
if active_error is None:
|
|
51
|
+
raise
|
|
52
|
+
print("shellless-ops: could not write evidence report", file=sys.stderr)
|
|
53
|
+
return 0
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def main():
|
|
57
|
+
parser = argparse.ArgumentParser(
|
|
58
|
+
prog="shellless-ops", description="Common file and process operations"
|
|
59
|
+
)
|
|
60
|
+
commands = parser.add_subparsers(dest="command", required=True)
|
|
61
|
+
commands.add_parser("mkdir", help="create a directory and its parents").add_argument("path")
|
|
62
|
+
commands.add_parser("read", help="read UTF-8 text").add_argument("path")
|
|
63
|
+
write = commands.add_parser("write", help="write UTF-8 text")
|
|
64
|
+
write.add_argument("path")
|
|
65
|
+
write.add_argument("text", help="use -- before the path if text starts with a dash")
|
|
66
|
+
copy = commands.add_parser("copy", help="copy a file without overwriting")
|
|
67
|
+
copy.add_argument("source")
|
|
68
|
+
copy.add_argument("target")
|
|
69
|
+
find = commands.add_parser("find", help="return matching file paths as JSON")
|
|
70
|
+
find.add_argument("root")
|
|
71
|
+
find.add_argument("--pattern", default="*")
|
|
72
|
+
search = commands.add_parser("search", help="return bounded literal text matches as JSON")
|
|
73
|
+
search.add_argument("root")
|
|
74
|
+
search.add_argument("query")
|
|
75
|
+
search.add_argument("--pattern", default="*")
|
|
76
|
+
search.add_argument("--limit", type=int, default=50)
|
|
77
|
+
search.add_argument("--max-line-chars", type=int, default=240)
|
|
78
|
+
search.add_argument("--max-files", type=int, default=1000)
|
|
79
|
+
search.add_argument("--encoding", default="utf-8-sig")
|
|
80
|
+
execute = commands.add_parser("run", help="invoke an executable with separate arguments")
|
|
81
|
+
execute.add_argument("--cwd")
|
|
82
|
+
execute.add_argument("--timeout", type=float)
|
|
83
|
+
execute.add_argument("argv", nargs=argparse.REMAINDER)
|
|
84
|
+
evidence = commands.add_parser("evidence", help="run a Python script and write failure evidence")
|
|
85
|
+
evidence.add_argument("--output", required=True, help="new JSON report file")
|
|
86
|
+
evidence.add_argument("--var", action="append", default=[], help="local name to include on failure")
|
|
87
|
+
evidence.add_argument("--source-root", help="include a source excerpt inside this directory")
|
|
88
|
+
evidence.add_argument("--code-version", help="caller-supplied revision for reproduction")
|
|
89
|
+
evidence.add_argument("--record-args", action="store_true", help="include script arguments in the report")
|
|
90
|
+
evidence.add_argument("script", nargs=argparse.REMAINDER, help="script file and its arguments")
|
|
91
|
+
args = parser.parse_args()
|
|
92
|
+
if args.command == "evidence":
|
|
93
|
+
return _run_evidence(args, evidence)
|
|
94
|
+
if args.command == "run":
|
|
95
|
+
if args.argv[:1] == ["--"]:
|
|
96
|
+
args.argv.pop(0)
|
|
97
|
+
if not args.argv:
|
|
98
|
+
execute.error("an executable is required")
|
|
99
|
+
try:
|
|
100
|
+
if args.command == "mkdir":
|
|
101
|
+
mkdir(args.path)
|
|
102
|
+
elif args.command == "read":
|
|
103
|
+
sys.stdout.buffer.write(read_text(args.path).encode("utf-8"))
|
|
104
|
+
elif args.command == "write":
|
|
105
|
+
write_text(args.path, args.text)
|
|
106
|
+
elif args.command == "copy":
|
|
107
|
+
copy_file(args.source, args.target)
|
|
108
|
+
elif args.command == "find":
|
|
109
|
+
print(json.dumps([path.as_posix() for path in find_files(args.root, args.pattern)]))
|
|
110
|
+
elif args.command == "search":
|
|
111
|
+
result = search_text(
|
|
112
|
+
args.root, args.query, pattern=args.pattern, limit=args.limit,
|
|
113
|
+
max_line_chars=args.max_line_chars, max_files=args.max_files, encoding=args.encoding,
|
|
114
|
+
)
|
|
115
|
+
data = json.dumps(result, ensure_ascii=False, separators=(",", ":"))
|
|
116
|
+
sys.stdout.buffer.write((data + "\n").encode("utf-8", "backslashreplace"))
|
|
117
|
+
else:
|
|
118
|
+
result = run(
|
|
119
|
+
args.argv, cwd=args.cwd, timeout=args.timeout, check=False, capture=False
|
|
120
|
+
)
|
|
121
|
+
code = result.returncode
|
|
122
|
+
return 128 - code if code < 0 else code
|
|
123
|
+
except subprocess.TimeoutExpired as error:
|
|
124
|
+
parser.exit(124, f"{parser.prog}: {error}\n")
|
|
125
|
+
except (OSError, ValueError) as error:
|
|
126
|
+
parser.exit(1, f"{parser.prog}: {error}\n")
|
|
127
|
+
return 0
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
if __name__ == "__main__":
|
|
131
|
+
raise SystemExit(main())
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
"""Bounded failure evidence for trusted Python runs."""
|
|
2
|
+
|
|
3
|
+
from collections import deque
|
|
4
|
+
from math import isfinite
|
|
5
|
+
from pathlib import Path
|
|
6
|
+
from tokenize import open as open_source
|
|
7
|
+
|
|
8
|
+
__all__ = ["capture"]
|
|
9
|
+
|
|
10
|
+
_TYPE_NAME = type.__dict__["__name__"]
|
|
11
|
+
_MAX_FRAMES = 8
|
|
12
|
+
_MAX_TEXT = 160
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def _type_name(kind):
|
|
16
|
+
# A class name can be a str subclass with its own __getitem__.
|
|
17
|
+
return str.__getitem__(_TYPE_NAME.__get__(kind), slice(80))
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def _summary(value):
|
|
21
|
+
kind = type(value)
|
|
22
|
+
if value is None or kind is bool:
|
|
23
|
+
return value
|
|
24
|
+
if kind is int and value.bit_length() <= 53:
|
|
25
|
+
return value
|
|
26
|
+
if kind is float and isfinite(value):
|
|
27
|
+
return value
|
|
28
|
+
if kind is str:
|
|
29
|
+
if len(value) <= _MAX_TEXT:
|
|
30
|
+
return value
|
|
31
|
+
return {"type": "str", "text": value[:_MAX_TEXT], "length": len(value)}
|
|
32
|
+
if any(kind is container for container in (bytes, dict, list, tuple, set, frozenset)):
|
|
33
|
+
return {"type": _type_name(kind), "length": len(value)}
|
|
34
|
+
if kind is int:
|
|
35
|
+
return {"type": "int", "bits": value.bit_length()}
|
|
36
|
+
return {"type": _type_name(kind)}
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def _local_values(frame, names):
|
|
40
|
+
namespace = frame.f_locals
|
|
41
|
+
# Function locals use a native frame-locals proxy on newer CPython.
|
|
42
|
+
if issubclass(type(namespace), dict):
|
|
43
|
+
items = dict.items(namespace)
|
|
44
|
+
elif type(namespace) is _FUNCTION_LOCALS:
|
|
45
|
+
items = namespace.items()
|
|
46
|
+
else:
|
|
47
|
+
return {}
|
|
48
|
+
wanted = set(names)
|
|
49
|
+
values = {}
|
|
50
|
+
for key, value in items:
|
|
51
|
+
if type(key) is str and key in wanted:
|
|
52
|
+
values[key] = _summary(value)
|
|
53
|
+
wanted.remove(key)
|
|
54
|
+
if not wanted:
|
|
55
|
+
break
|
|
56
|
+
return values
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def _function_locals_type():
|
|
60
|
+
from sys import _getframe
|
|
61
|
+
|
|
62
|
+
return type(_getframe().f_locals)
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
_FUNCTION_LOCALS = _function_locals_type()
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def _source_excerpt(filename, line, root):
|
|
69
|
+
if filename.startswith("<"):
|
|
70
|
+
return None
|
|
71
|
+
try:
|
|
72
|
+
path = Path(filename).resolve()
|
|
73
|
+
if (path != root and root not in path.parents) or not path.is_file():
|
|
74
|
+
return None
|
|
75
|
+
with open_source(path) as stream:
|
|
76
|
+
return [
|
|
77
|
+
{"line": number, "text": text.rstrip("\r\n")[:240]}
|
|
78
|
+
for number, text in zip(range(1, line + 3), stream)
|
|
79
|
+
if number >= line - 2
|
|
80
|
+
] or None
|
|
81
|
+
except (OSError, RuntimeError, ValueError, SyntaxError):
|
|
82
|
+
return None
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
def _failure(kind, tb, names, source_root):
|
|
86
|
+
frames = deque(maxlen=_MAX_FRAMES)
|
|
87
|
+
while tb is not None:
|
|
88
|
+
frames.append(tb)
|
|
89
|
+
tb = tb.tb_next
|
|
90
|
+
locations = []
|
|
91
|
+
for item in frames:
|
|
92
|
+
code = item.tb_frame.f_code
|
|
93
|
+
locations.append({
|
|
94
|
+
"path": code.co_filename[:512],
|
|
95
|
+
"line": item.tb_lineno,
|
|
96
|
+
"function": code.co_name[:80],
|
|
97
|
+
})
|
|
98
|
+
values = {}
|
|
99
|
+
source = None
|
|
100
|
+
if frames:
|
|
101
|
+
innermost = frames[-1]
|
|
102
|
+
frame = innermost.tb_frame
|
|
103
|
+
if names:
|
|
104
|
+
values = _local_values(frame, names)
|
|
105
|
+
if source_root is not None:
|
|
106
|
+
source = _source_excerpt(frame.f_code.co_filename, innermost.tb_lineno, source_root)
|
|
107
|
+
return {
|
|
108
|
+
"type": _type_name(kind),
|
|
109
|
+
"frames": locations,
|
|
110
|
+
"values": values,
|
|
111
|
+
"missing": [name for name in names if name not in values],
|
|
112
|
+
"source": source,
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
class _Capture:
|
|
117
|
+
def __init__(self, names, source_root):
|
|
118
|
+
self.names = names
|
|
119
|
+
self.source_root = source_root
|
|
120
|
+
|
|
121
|
+
def __enter__(self):
|
|
122
|
+
self.report = {"failure": None}
|
|
123
|
+
return self.report
|
|
124
|
+
|
|
125
|
+
def __exit__(self, kind, error, tb):
|
|
126
|
+
if error is None or not issubclass(kind, Exception):
|
|
127
|
+
return
|
|
128
|
+
try:
|
|
129
|
+
self.report["failure"] = _failure(kind, tb, self.names, self.source_root)
|
|
130
|
+
except Exception as capture_error:
|
|
131
|
+
# Optional diagnostics must never replace the original failure.
|
|
132
|
+
self.report["capture_error"] = _type_name(type(capture_error))
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
def capture(*, names=(), source_root=None):
|
|
136
|
+
"""Collect opt-in evidence when an exception escapes the block, without suppressing it."""
|
|
137
|
+
if not isinstance(names, (list, tuple)) or len(names) > 8 or any(
|
|
138
|
+
type(name) is not str or len(name) > 128 or not name.isidentifier() for name in names
|
|
139
|
+
):
|
|
140
|
+
raise ValueError("names must contain at most eight Python identifiers of up to 128 characters")
|
|
141
|
+
root = None if source_root is None else Path(source_root).resolve()
|
|
142
|
+
return _Capture(tuple(names), root)
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
import json
|
|
2
|
+
import subprocess
|
|
3
|
+
import sys
|
|
4
|
+
import tempfile
|
|
5
|
+
import traceback
|
|
6
|
+
import unittest
|
|
7
|
+
from pathlib import Path
|
|
8
|
+
|
|
9
|
+
from shellless_ops.evidence import capture
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class EvidenceTests(unittest.TestCase):
|
|
13
|
+
def test_capture_keeps_original_exception_and_only_named_locals(self):
|
|
14
|
+
class Object:
|
|
15
|
+
def __repr__(self):
|
|
16
|
+
raise AssertionError("repr called")
|
|
17
|
+
|
|
18
|
+
def __summary__(self):
|
|
19
|
+
raise AssertionError("summary hook called")
|
|
20
|
+
|
|
21
|
+
error = ValueError("message is not in the evidence")
|
|
22
|
+
|
|
23
|
+
def fail():
|
|
24
|
+
amount = "100"
|
|
25
|
+
obj = Object()
|
|
26
|
+
private = "do not collect"
|
|
27
|
+
observations = list(range(500))
|
|
28
|
+
raise error
|
|
29
|
+
|
|
30
|
+
try:
|
|
31
|
+
with capture(names=("amount", "obj", "observations", "typo")) as report:
|
|
32
|
+
fail()
|
|
33
|
+
except ValueError as received:
|
|
34
|
+
self.assertIs(received, error)
|
|
35
|
+
self.assertEqual(traceback.extract_tb(received.__traceback__)[-1].name, "fail")
|
|
36
|
+
else:
|
|
37
|
+
self.fail("capture suppressed the exception")
|
|
38
|
+
failure = report["failure"]
|
|
39
|
+
self.assertEqual(failure["type"], "ValueError")
|
|
40
|
+
self.assertEqual(failure["frames"][-1]["function"], "fail")
|
|
41
|
+
self.assertEqual(failure["values"], {
|
|
42
|
+
"amount": "100", "obj": {"type": "Object"}, "observations": {"type": "list", "length": 500}
|
|
43
|
+
})
|
|
44
|
+
self.assertEqual(failure["missing"], ["typo"])
|
|
45
|
+
self.assertIsNone(failure["source"])
|
|
46
|
+
self.assertNotIn("do not collect", json.dumps(report))
|
|
47
|
+
with capture() as normal:
|
|
48
|
+
self.assertEqual(2 + 2, 4)
|
|
49
|
+
self.assertEqual(normal, {"failure": None})
|
|
50
|
+
|
|
51
|
+
def test_capture_does_not_call_custom_type_name_slice(self):
|
|
52
|
+
class DiagnosticError(Exception):
|
|
53
|
+
pass
|
|
54
|
+
|
|
55
|
+
class TypeName(str):
|
|
56
|
+
def __getitem__(self, key):
|
|
57
|
+
raise DiagnosticError("custom type name slice called")
|
|
58
|
+
|
|
59
|
+
class Object:
|
|
60
|
+
pass
|
|
61
|
+
|
|
62
|
+
DiagnosticError.__name__ = TypeName("DiagnosticError")
|
|
63
|
+
Object.__name__ = TypeName("Object")
|
|
64
|
+
original = ValueError("original failure")
|
|
65
|
+
with self.assertRaises(ValueError) as caught, capture(names=("obj",)) as report:
|
|
66
|
+
obj = Object()
|
|
67
|
+
raise original
|
|
68
|
+
|
|
69
|
+
self.assertIs(caught.exception, original)
|
|
70
|
+
self.assertEqual(report["failure"]["values"], {"obj": {"type": "Object"}})
|
|
71
|
+
|
|
72
|
+
def test_source_is_opt_in_and_runtime_frames_are_bounded(self):
|
|
73
|
+
def recurse(depth):
|
|
74
|
+
if depth:
|
|
75
|
+
return recurse(depth - 1)
|
|
76
|
+
raise RuntimeError()
|
|
77
|
+
|
|
78
|
+
with self.assertRaises(RuntimeError):
|
|
79
|
+
with capture(source_root=Path(__file__).parent) as report:
|
|
80
|
+
recurse(20)
|
|
81
|
+
failure = report["failure"]
|
|
82
|
+
self.assertEqual(len(failure["frames"]), 8)
|
|
83
|
+
line = failure["frames"][-1]["line"]
|
|
84
|
+
self.assertIn({"line": line, "text": " raise RuntimeError()"}, failure["source"])
|
|
85
|
+
with tempfile.TemporaryDirectory() as another_root, self.assertRaises(RuntimeError):
|
|
86
|
+
with capture(source_root=another_root) as elsewhere:
|
|
87
|
+
recurse(0)
|
|
88
|
+
self.assertIsNone(elsewhere["failure"]["source"])
|
|
89
|
+
|
|
90
|
+
def test_evidence_cli_writes_separate_report_without_overwriting(self):
|
|
91
|
+
with tempfile.TemporaryDirectory() as directory:
|
|
92
|
+
root = Path(directory)
|
|
93
|
+
script = root / "例子 程序.py"
|
|
94
|
+
output = root / "证据.json"
|
|
95
|
+
script.write_text(
|
|
96
|
+
"import sys\nprint(sys.argv[1])\nvalue = 7\nraise RuntimeError('failed')\n",
|
|
97
|
+
encoding="utf-8",
|
|
98
|
+
)
|
|
99
|
+
command = [
|
|
100
|
+
sys.executable, "-m", "shellless_ops", "evidence", "--output", str(output),
|
|
101
|
+
"--var", "value", "--source-root", directory, "--code-version", "rev-123",
|
|
102
|
+
"--", str(script), "argument-not-recorded",
|
|
103
|
+
]
|
|
104
|
+
result = subprocess.run(command, capture_output=True)
|
|
105
|
+
self.assertEqual(result.returncode, 1, result.stderr)
|
|
106
|
+
self.assertEqual(result.stdout.splitlines(), [b"argument-not-recorded"])
|
|
107
|
+
self.assertIn(b"RuntimeError: failed", result.stderr)
|
|
108
|
+
evidence = output.read_text(encoding="utf-8")
|
|
109
|
+
report = json.loads(evidence)
|
|
110
|
+
self.assertEqual(report["failure"]["values"], {"value": 7})
|
|
111
|
+
self.assertEqual(report["failure"]["frames"][-1]["line"], 4)
|
|
112
|
+
self.assertEqual(report["repro"]["code_version"], "rev-123")
|
|
113
|
+
self.assertEqual(report["repro"]["omitted_args"], 1)
|
|
114
|
+
self.assertNotIn("argument-not-recorded", evidence)
|
|
115
|
+
repeated = subprocess.run(command, capture_output=True)
|
|
116
|
+
self.assertEqual(repeated.returncode, 1)
|
|
117
|
+
self.assertEqual(repeated.stdout, b"")
|
|
118
|
+
self.assertEqual(output.read_text(encoding="utf-8"), evidence)
|
|
@@ -5,8 +5,9 @@ import sys
|
|
|
5
5
|
import tempfile
|
|
6
6
|
import unittest
|
|
7
7
|
from pathlib import Path
|
|
8
|
+
from unittest.mock import patch
|
|
8
9
|
|
|
9
|
-
from shellless_ops import copy_file, find_files, mkdir, read_text, run, write_text
|
|
10
|
+
from shellless_ops import copy_file, find_files, mkdir, read_text, run, search_text, write_text
|
|
10
11
|
|
|
11
12
|
|
|
12
13
|
class ShelllessOpsTests(unittest.TestCase):
|
|
@@ -42,6 +43,98 @@ class ShelllessOpsTests(unittest.TestCase):
|
|
|
42
43
|
write_text(self.root / "b.TXT", "")
|
|
43
44
|
self.assertEqual(find_files(self.root, "*.txt"), [lower])
|
|
44
45
|
|
|
46
|
+
def test_search_text_cli_and_api_return_numbered_literal_previews(self):
|
|
47
|
+
file = mkdir(self.root) / "配置 日志.txt"
|
|
48
|
+
query = "失败[1]"
|
|
49
|
+
write_text(file, f"{query}\r\n失败1\r\n{'x' * 30_000}{query}后续\r\n", encoding="utf-8-sig")
|
|
50
|
+
(self.root / "binary.dat").write_bytes(b"\xff")
|
|
51
|
+
expected = {
|
|
52
|
+
"matches": [
|
|
53
|
+
{"path": file.as_posix(), "line": 1, "text": query, "text_truncated": False},
|
|
54
|
+
{"path": file.as_posix(), "line": 3, "text": "xxxxx失败[1]后续", "text_truncated": True},
|
|
55
|
+
],
|
|
56
|
+
"truncated": False,
|
|
57
|
+
"scan_limited": False,
|
|
58
|
+
"skipped_decode": 0,
|
|
59
|
+
}
|
|
60
|
+
self.assertEqual(
|
|
61
|
+
search_text(self.root, query, pattern="*.txt", limit=2, max_line_chars=12),
|
|
62
|
+
expected,
|
|
63
|
+
)
|
|
64
|
+
result = self.cli(
|
|
65
|
+
"search", self.root, query, "--pattern", "*.txt", "--limit", "2", "--max-line-chars", "12"
|
|
66
|
+
)
|
|
67
|
+
self.assertEqual(result.returncode, 0, result.stderr)
|
|
68
|
+
self.assertIn(query.encode("utf-8"), result.stdout)
|
|
69
|
+
self.assertEqual(json.loads(result.stdout), expected)
|
|
70
|
+
|
|
71
|
+
def test_search_text_limit_and_order(self):
|
|
72
|
+
later = write_text(mkdir(self.root) / "z.txt", "needle\n")
|
|
73
|
+
earlier = write_text(mkdir(self.root / "a") / "first.txt", "needle needle\nneedle\n")
|
|
74
|
+
result = search_text(self.root, "needle", limit=2)
|
|
75
|
+
self.assertTrue(result["truncated"])
|
|
76
|
+
self.assertEqual(
|
|
77
|
+
[(hit["path"], hit["line"]) for hit in result["matches"]],
|
|
78
|
+
[(earlier.as_posix(), 1), (earlier.as_posix(), 2)],
|
|
79
|
+
)
|
|
80
|
+
self.assertEqual(
|
|
81
|
+
search_text(later, "missing"),
|
|
82
|
+
{"matches": [], "truncated": False, "scan_limited": False, "skipped_decode": 0},
|
|
83
|
+
)
|
|
84
|
+
|
|
85
|
+
def test_search_text_reports_missing_and_decode_errors(self):
|
|
86
|
+
with self.assertRaises(FileNotFoundError):
|
|
87
|
+
search_text(self.root, "needle")
|
|
88
|
+
bad = mkdir(self.root) / "wrong.txt"
|
|
89
|
+
bad.write_bytes(b"\xffneedle")
|
|
90
|
+
with self.assertRaisesRegex(ValueError, "wrong.txt"):
|
|
91
|
+
search_text(bad, "needle")
|
|
92
|
+
self.assertEqual(search_text(bad, "needle", encoding="latin-1")["matches"][0]["line"], 1)
|
|
93
|
+
result = self.cli("search", bad, "needle")
|
|
94
|
+
self.assertEqual(result.returncode, 1)
|
|
95
|
+
self.assertEqual(result.stdout, b"")
|
|
96
|
+
self.assertIn(b"wrong.txt", result.stderr)
|
|
97
|
+
|
|
98
|
+
def test_search_repository_skips_default_exclusions_and_counts_decode_errors(self):
|
|
99
|
+
write_text(mkdir(self.root / ".git") / "config", "needle")
|
|
100
|
+
write_text(mkdir(self.root / ".venv") / "artifact.txt", "needle")
|
|
101
|
+
bad = self.root / "a.bin"
|
|
102
|
+
bad.write_bytes(b"needle\n" + b"x\n" * 5_000 + b"\xff")
|
|
103
|
+
visible = write_text(mkdir(self.root / ".source") / "源 文件.txt", "needle")
|
|
104
|
+
result = self.cli("search", self.root, "needle")
|
|
105
|
+
self.assertEqual(result.returncode, 0, result.stderr)
|
|
106
|
+
report = json.loads(result.stdout)
|
|
107
|
+
self.assertEqual(report["skipped_decode"], 1)
|
|
108
|
+
self.assertEqual([hit["path"] for hit in report["matches"]], [visible.as_posix()])
|
|
109
|
+
self.assertFalse(report["scan_limited"])
|
|
110
|
+
self.assertEqual(len(find_files(self.root)), 4)
|
|
111
|
+
|
|
112
|
+
def test_search_text_scan_budget_is_distinct_from_match_limit(self):
|
|
113
|
+
write_text(mkdir(self.root) / "a.txt", "needle\n")
|
|
114
|
+
write_text(self.root / "b.txt", "needle\n")
|
|
115
|
+
report = search_text(self.root, "needle", limit=1, max_files=1)
|
|
116
|
+
self.assertEqual(len(report["matches"]), 1)
|
|
117
|
+
self.assertTrue(report["scan_limited"])
|
|
118
|
+
self.assertFalse(report["truncated"])
|
|
119
|
+
cli = self.cli("search", self.root, "needle", "--limit", "1", "--max-files", "1")
|
|
120
|
+
self.assertEqual(cli.returncode, 0, cli.stderr)
|
|
121
|
+
self.assertEqual(json.loads(cli.stdout), report)
|
|
122
|
+
for key, value in (("limit", 2.5), ("max_files", True), ("max_line_chars", 0)):
|
|
123
|
+
with self.subTest(key=key):
|
|
124
|
+
with self.assertRaisesRegex(ValueError, key):
|
|
125
|
+
search_text(self.root, "needle", **{key: value})
|
|
126
|
+
self.assertEqual(self.cli("search", self.root, "needle", "--max-files", "0").returncode, 1)
|
|
127
|
+
|
|
128
|
+
def test_search_can_stop_before_descending_into_later_directories(self):
|
|
129
|
+
file = write_text(mkdir(self.root) / "a.txt", "needle\nneedle\n")
|
|
130
|
+
nested = mkdir(self.root / "a")
|
|
131
|
+
child = write_text(nested / "file.txt", "needle\n")
|
|
132
|
+
with patch("shellless_ops.os.scandir", wraps=os.scandir) as scandir:
|
|
133
|
+
result = search_text(self.root, "needle", limit=1)
|
|
134
|
+
self.assertTrue(result["truncated"])
|
|
135
|
+
scandir.assert_called_once_with(self.root)
|
|
136
|
+
self.assertEqual(find_files(self.root), [file, child])
|
|
137
|
+
|
|
45
138
|
@unittest.skipIf(os.name == "nt", "symlink creation can require privileges on Windows")
|
|
46
139
|
def test_find_skips_symbolic_links(self):
|
|
47
140
|
mkdir(self.root)
|
shellless_ops-0.1.0/PKG-INFO
DELETED
|
@@ -1,69 +0,0 @@
|
|
|
1
|
-
Metadata-Version: 2.4
|
|
2
|
-
Name: shellless-ops
|
|
3
|
-
Version: 0.1.0
|
|
4
|
-
Summary: Repeatable file and process operations without shell command strings
|
|
5
|
-
License-Expression: MIT
|
|
6
|
-
Project-URL: Repository, https://github.com/zhangs-cedar/shellless-ops
|
|
7
|
-
Project-URL: Issues, https://github.com/zhangs-cedar/shellless-ops/issues
|
|
8
|
-
Classifier: Development Status :: 3 - Alpha
|
|
9
|
-
Classifier: Operating System :: MacOS
|
|
10
|
-
Classifier: Operating System :: Microsoft :: Windows
|
|
11
|
-
Classifier: Operating System :: POSIX :: Linux
|
|
12
|
-
Classifier: Programming Language :: Python :: 3
|
|
13
|
-
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
14
|
-
Classifier: Topic :: Utilities
|
|
15
|
-
Requires-Python: >=3.11
|
|
16
|
-
Description-Content-Type: text/markdown
|
|
17
|
-
License-File: LICENSE
|
|
18
|
-
Dynamic: license-file
|
|
19
|
-
|
|
20
|
-
# shellless-ops
|
|
21
|
-
|
|
22
|
-
Repeatable file and process operations without maintaining separate Bash and PowerShell scripts. Built for Python 3.11+ with no runtime dependencies. Use the Python API for scripts, or pass an argument array to the CLI from task runners.
|
|
23
|
-
|
|
24
|
-
## Install
|
|
25
|
-
|
|
26
|
-
Before the first PyPI release, install from a local checkout:
|
|
27
|
-
|
|
28
|
-
```text
|
|
29
|
-
python -m pip install .
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
## Example
|
|
33
|
-
|
|
34
|
-
```python
|
|
35
|
-
import sys
|
|
36
|
-
|
|
37
|
-
from shellless_ops import find_files, mkdir, run, write_text
|
|
38
|
-
|
|
39
|
-
out = mkdir("build reports")
|
|
40
|
-
write_text(out / "summary.txt", "ready\n")
|
|
41
|
-
files = find_files(out, "*.txt")
|
|
42
|
-
result = run([sys.executable, "--version"], cwd=out, timeout=10)
|
|
43
|
-
print(files, result.stdout.strip())
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
```text
|
|
47
|
-
shellless-ops mkdir "build reports"
|
|
48
|
-
shellless-ops write "build reports/summary.txt" "ready"
|
|
49
|
-
shellless-ops copy "build reports/summary.txt" "build reports/backup.txt"
|
|
50
|
-
shellless-ops find "build reports" --pattern "*.txt"
|
|
51
|
-
shellless-ops read "build reports/summary.txt"
|
|
52
|
-
shellless-ops run --timeout 10 -- python --version
|
|
53
|
-
```
|
|
54
|
-
|
|
55
|
-
`python -m shellless_ops` also works. A task runner with an argument-array API can use `["python", "-m", "shellless_ops", "find", "build reports", "--pattern", "*.txt"]`. A command typed into a terminal is still parsed by that terminal's shell; quote paths with spaces and wildcard patterns at that boundary.
|
|
56
|
-
|
|
57
|
-
## Behavior
|
|
58
|
-
|
|
59
|
-
| API | Contract |
|
|
60
|
-
| --- | --- |
|
|
61
|
-
| `mkdir(path)` | Create missing parents, accept an existing directory and return its `Path`. |
|
|
62
|
-
| `read_text(path)` / `write_text(path, text)` | Default to UTF-8 and preserve line endings. Writing replaces existing contents, requires an existing parent directory and returns the `Path`. CLI `read` emits UTF-8 bytes. |
|
|
63
|
-
| `copy_file(source, target)` | Copy the contents to an exact destination and return its `Path`. Reject an existing destination. Metadata is not copied. An interrupted copy can leave a partial destination. |
|
|
64
|
-
| `find_files(root, pattern="*")` | Recursively match file basenames, including dotfiles, with case-sensitive glob matching. Return paths sorted by their `/`-separated relative names. Skip file symlinks and do not descend into directory symlinks or nested Windows directory reparse points. CLI `find` emits a JSON array of paths with `/` separators. |
|
|
65
|
-
| `run(argv, *, cwd=None, timeout=None, check=True, capture=True, encoding="utf-8")` | Pass the executable and each argument separately in a non-empty list or tuple. Return `subprocess.CompletedProcess`. By default, capture output as UTF-8 text and raise `CalledProcessError` on a nonzero exit. Set `encoding=None` for bytes or `capture=False` to inherit output. CLI `run` inherits output and propagates exit status; it uses 124 on timeout and `128 + signal` for signal exits on POSIX. |
|
|
66
|
-
|
|
67
|
-
`run` does not expand variables, implement pipelines or redirection, or support Windows `.bat` and `.cmd` entry points. It uses the operating system's executable lookup rules; pass an absolute executable path to select a specific installation. A timeout targets the directly launched process, not its entire process tree. Choose the executable and its options as trusted configuration: shell-free launching is not a sandbox for the program being run.
|
|
68
|
-
|
|
69
|
-
Run tests from the checkout after installing: `python -m unittest discover -s tests -v`.
|
shellless_ops-0.1.0/README.md
DELETED
|
@@ -1,50 +0,0 @@
|
|
|
1
|
-
# shellless-ops
|
|
2
|
-
|
|
3
|
-
Repeatable file and process operations without maintaining separate Bash and PowerShell scripts. Built for Python 3.11+ with no runtime dependencies. Use the Python API for scripts, or pass an argument array to the CLI from task runners.
|
|
4
|
-
|
|
5
|
-
## Install
|
|
6
|
-
|
|
7
|
-
Before the first PyPI release, install from a local checkout:
|
|
8
|
-
|
|
9
|
-
```text
|
|
10
|
-
python -m pip install .
|
|
11
|
-
```
|
|
12
|
-
|
|
13
|
-
## Example
|
|
14
|
-
|
|
15
|
-
```python
|
|
16
|
-
import sys
|
|
17
|
-
|
|
18
|
-
from shellless_ops import find_files, mkdir, run, write_text
|
|
19
|
-
|
|
20
|
-
out = mkdir("build reports")
|
|
21
|
-
write_text(out / "summary.txt", "ready\n")
|
|
22
|
-
files = find_files(out, "*.txt")
|
|
23
|
-
result = run([sys.executable, "--version"], cwd=out, timeout=10)
|
|
24
|
-
print(files, result.stdout.strip())
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
```text
|
|
28
|
-
shellless-ops mkdir "build reports"
|
|
29
|
-
shellless-ops write "build reports/summary.txt" "ready"
|
|
30
|
-
shellless-ops copy "build reports/summary.txt" "build reports/backup.txt"
|
|
31
|
-
shellless-ops find "build reports" --pattern "*.txt"
|
|
32
|
-
shellless-ops read "build reports/summary.txt"
|
|
33
|
-
shellless-ops run --timeout 10 -- python --version
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
`python -m shellless_ops` also works. A task runner with an argument-array API can use `["python", "-m", "shellless_ops", "find", "build reports", "--pattern", "*.txt"]`. A command typed into a terminal is still parsed by that terminal's shell; quote paths with spaces and wildcard patterns at that boundary.
|
|
37
|
-
|
|
38
|
-
## Behavior
|
|
39
|
-
|
|
40
|
-
| API | Contract |
|
|
41
|
-
| --- | --- |
|
|
42
|
-
| `mkdir(path)` | Create missing parents, accept an existing directory and return its `Path`. |
|
|
43
|
-
| `read_text(path)` / `write_text(path, text)` | Default to UTF-8 and preserve line endings. Writing replaces existing contents, requires an existing parent directory and returns the `Path`. CLI `read` emits UTF-8 bytes. |
|
|
44
|
-
| `copy_file(source, target)` | Copy the contents to an exact destination and return its `Path`. Reject an existing destination. Metadata is not copied. An interrupted copy can leave a partial destination. |
|
|
45
|
-
| `find_files(root, pattern="*")` | Recursively match file basenames, including dotfiles, with case-sensitive glob matching. Return paths sorted by their `/`-separated relative names. Skip file symlinks and do not descend into directory symlinks or nested Windows directory reparse points. CLI `find` emits a JSON array of paths with `/` separators. |
|
|
46
|
-
| `run(argv, *, cwd=None, timeout=None, check=True, capture=True, encoding="utf-8")` | Pass the executable and each argument separately in a non-empty list or tuple. Return `subprocess.CompletedProcess`. By default, capture output as UTF-8 text and raise `CalledProcessError` on a nonzero exit. Set `encoding=None` for bytes or `capture=False` to inherit output. CLI `run` inherits output and propagates exit status; it uses 124 on timeout and `128 + signal` for signal exits on POSIX. |
|
|
47
|
-
|
|
48
|
-
`run` does not expand variables, implement pipelines or redirection, or support Windows `.bat` and `.cmd` entry points. It uses the operating system's executable lookup rules; pass an absolute executable path to select a specific installation. A timeout targets the directly launched process, not its entire process tree. Choose the executable and its options as trusted configuration: shell-free launching is not a sandbox for the program being run.
|
|
49
|
-
|
|
50
|
-
Run tests from the checkout after installing: `python -m unittest discover -s tests -v`.
|
shellless_ops-0.1.0/setup.cfg
DELETED
|
@@ -1,73 +0,0 @@
|
|
|
1
|
-
import os
|
|
2
|
-
import shutil
|
|
3
|
-
import stat
|
|
4
|
-
import subprocess
|
|
5
|
-
from fnmatch import fnmatchcase
|
|
6
|
-
from pathlib import Path
|
|
7
|
-
|
|
8
|
-
__all__ = ["copy_file", "find_files", "mkdir", "read_text", "run", "write_text"]
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
def mkdir(path):
|
|
12
|
-
path = Path(path)
|
|
13
|
-
path.mkdir(parents=True, exist_ok=True)
|
|
14
|
-
return path
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
def read_text(path, *, encoding="utf-8"):
|
|
18
|
-
with Path(path).open(encoding=encoding, newline="") as stream:
|
|
19
|
-
return stream.read()
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
def write_text(path, text, *, encoding="utf-8"):
|
|
23
|
-
path = Path(path)
|
|
24
|
-
with path.open("w", encoding=encoding, newline="") as stream:
|
|
25
|
-
stream.write(text)
|
|
26
|
-
return path
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
def copy_file(source, target):
|
|
30
|
-
"""Copy file contents to a new path without overwriting."""
|
|
31
|
-
target = Path(target)
|
|
32
|
-
with Path(source).open("rb") as reader, target.open("xb") as writer:
|
|
33
|
-
shutil.copyfileobj(reader, writer)
|
|
34
|
-
return target
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
def find_files(root, pattern="*"):
|
|
38
|
-
"""Match file basenames recursively without following directory links."""
|
|
39
|
-
root = Path(root)
|
|
40
|
-
files = []
|
|
41
|
-
pending = [root]
|
|
42
|
-
while pending:
|
|
43
|
-
with os.scandir(pending.pop()) as entries:
|
|
44
|
-
for entry in entries:
|
|
45
|
-
if entry.is_dir(follow_symlinks=False):
|
|
46
|
-
# Windows junctions are not always reported as symlinks.
|
|
47
|
-
if os.name == "nt" and (
|
|
48
|
-
entry.stat(follow_symlinks=False).st_file_attributes
|
|
49
|
-
& stat.FILE_ATTRIBUTE_REPARSE_POINT
|
|
50
|
-
):
|
|
51
|
-
continue
|
|
52
|
-
pending.append(Path(entry.path))
|
|
53
|
-
elif fnmatchcase(entry.name, pattern) and entry.is_file(follow_symlinks=False):
|
|
54
|
-
files.append(Path(entry.path))
|
|
55
|
-
return sorted(files, key=lambda path: path.relative_to(root).as_posix())
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
def run(argv, *, cwd=None, timeout=None, check=True, capture=True, encoding="utf-8"):
|
|
59
|
-
if not isinstance(argv, (list, tuple)) or not argv:
|
|
60
|
-
raise TypeError("argv must be a non-empty list or tuple")
|
|
61
|
-
if os.name == "nt":
|
|
62
|
-
executable = os.fsdecode(argv[0]).rstrip(" .").lower()
|
|
63
|
-
if executable.endswith((".bat", ".cmd")):
|
|
64
|
-
raise ValueError("Windows batch files are not supported")
|
|
65
|
-
return subprocess.run(
|
|
66
|
-
argv,
|
|
67
|
-
cwd=cwd,
|
|
68
|
-
timeout=timeout,
|
|
69
|
-
check=check,
|
|
70
|
-
capture_output=capture,
|
|
71
|
-
encoding=encoding,
|
|
72
|
-
shell=False,
|
|
73
|
-
)
|
|
@@ -1,60 +0,0 @@
|
|
|
1
|
-
import argparse
|
|
2
|
-
import json
|
|
3
|
-
import subprocess
|
|
4
|
-
import sys
|
|
5
|
-
|
|
6
|
-
from . import copy_file, find_files, mkdir, read_text, run, write_text
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
def main():
|
|
10
|
-
parser = argparse.ArgumentParser(
|
|
11
|
-
prog="shellless-ops", description="Common file and process operations"
|
|
12
|
-
)
|
|
13
|
-
commands = parser.add_subparsers(dest="command", required=True)
|
|
14
|
-
commands.add_parser("mkdir", help="create a directory and its parents").add_argument("path")
|
|
15
|
-
commands.add_parser("read", help="read UTF-8 text").add_argument("path")
|
|
16
|
-
write = commands.add_parser("write", help="write UTF-8 text")
|
|
17
|
-
write.add_argument("path")
|
|
18
|
-
write.add_argument("text", help="use -- before the path if text starts with a dash")
|
|
19
|
-
copy = commands.add_parser("copy", help="copy a file without overwriting")
|
|
20
|
-
copy.add_argument("source")
|
|
21
|
-
copy.add_argument("target")
|
|
22
|
-
find = commands.add_parser("find", help="return matching file paths as JSON")
|
|
23
|
-
find.add_argument("root")
|
|
24
|
-
find.add_argument("--pattern", default="*")
|
|
25
|
-
execute = commands.add_parser("run", help="invoke an executable with separate arguments")
|
|
26
|
-
execute.add_argument("--cwd")
|
|
27
|
-
execute.add_argument("--timeout", type=float)
|
|
28
|
-
execute.add_argument("argv", nargs=argparse.REMAINDER)
|
|
29
|
-
args = parser.parse_args()
|
|
30
|
-
if args.command == "run":
|
|
31
|
-
if args.argv[:1] == ["--"]:
|
|
32
|
-
args.argv.pop(0)
|
|
33
|
-
if not args.argv:
|
|
34
|
-
execute.error("an executable is required")
|
|
35
|
-
try:
|
|
36
|
-
if args.command == "mkdir":
|
|
37
|
-
mkdir(args.path)
|
|
38
|
-
elif args.command == "read":
|
|
39
|
-
sys.stdout.buffer.write(read_text(args.path).encode("utf-8"))
|
|
40
|
-
elif args.command == "write":
|
|
41
|
-
write_text(args.path, args.text)
|
|
42
|
-
elif args.command == "copy":
|
|
43
|
-
copy_file(args.source, args.target)
|
|
44
|
-
elif args.command == "find":
|
|
45
|
-
print(json.dumps([path.as_posix() for path in find_files(args.root, args.pattern)]))
|
|
46
|
-
else:
|
|
47
|
-
result = run(
|
|
48
|
-
args.argv, cwd=args.cwd, timeout=args.timeout, check=False, capture=False
|
|
49
|
-
)
|
|
50
|
-
code = result.returncode
|
|
51
|
-
return 128 - code if code < 0 else code
|
|
52
|
-
except subprocess.TimeoutExpired as error:
|
|
53
|
-
parser.exit(124, f"{parser.prog}: {error}\n")
|
|
54
|
-
except (OSError, ValueError) as error:
|
|
55
|
-
parser.exit(1, f"{parser.prog}: {error}\n")
|
|
56
|
-
return 0
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
if __name__ == "__main__":
|
|
60
|
-
raise SystemExit(main())
|
|
@@ -1,69 +0,0 @@
|
|
|
1
|
-
Metadata-Version: 2.4
|
|
2
|
-
Name: shellless-ops
|
|
3
|
-
Version: 0.1.0
|
|
4
|
-
Summary: Repeatable file and process operations without shell command strings
|
|
5
|
-
License-Expression: MIT
|
|
6
|
-
Project-URL: Repository, https://github.com/zhangs-cedar/shellless-ops
|
|
7
|
-
Project-URL: Issues, https://github.com/zhangs-cedar/shellless-ops/issues
|
|
8
|
-
Classifier: Development Status :: 3 - Alpha
|
|
9
|
-
Classifier: Operating System :: MacOS
|
|
10
|
-
Classifier: Operating System :: Microsoft :: Windows
|
|
11
|
-
Classifier: Operating System :: POSIX :: Linux
|
|
12
|
-
Classifier: Programming Language :: Python :: 3
|
|
13
|
-
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
14
|
-
Classifier: Topic :: Utilities
|
|
15
|
-
Requires-Python: >=3.11
|
|
16
|
-
Description-Content-Type: text/markdown
|
|
17
|
-
License-File: LICENSE
|
|
18
|
-
Dynamic: license-file
|
|
19
|
-
|
|
20
|
-
# shellless-ops
|
|
21
|
-
|
|
22
|
-
Repeatable file and process operations without maintaining separate Bash and PowerShell scripts. Built for Python 3.11+ with no runtime dependencies. Use the Python API for scripts, or pass an argument array to the CLI from task runners.
|
|
23
|
-
|
|
24
|
-
## Install
|
|
25
|
-
|
|
26
|
-
Before the first PyPI release, install from a local checkout:
|
|
27
|
-
|
|
28
|
-
```text
|
|
29
|
-
python -m pip install .
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
## Example
|
|
33
|
-
|
|
34
|
-
```python
|
|
35
|
-
import sys
|
|
36
|
-
|
|
37
|
-
from shellless_ops import find_files, mkdir, run, write_text
|
|
38
|
-
|
|
39
|
-
out = mkdir("build reports")
|
|
40
|
-
write_text(out / "summary.txt", "ready\n")
|
|
41
|
-
files = find_files(out, "*.txt")
|
|
42
|
-
result = run([sys.executable, "--version"], cwd=out, timeout=10)
|
|
43
|
-
print(files, result.stdout.strip())
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
```text
|
|
47
|
-
shellless-ops mkdir "build reports"
|
|
48
|
-
shellless-ops write "build reports/summary.txt" "ready"
|
|
49
|
-
shellless-ops copy "build reports/summary.txt" "build reports/backup.txt"
|
|
50
|
-
shellless-ops find "build reports" --pattern "*.txt"
|
|
51
|
-
shellless-ops read "build reports/summary.txt"
|
|
52
|
-
shellless-ops run --timeout 10 -- python --version
|
|
53
|
-
```
|
|
54
|
-
|
|
55
|
-
`python -m shellless_ops` also works. A task runner with an argument-array API can use `["python", "-m", "shellless_ops", "find", "build reports", "--pattern", "*.txt"]`. A command typed into a terminal is still parsed by that terminal's shell; quote paths with spaces and wildcard patterns at that boundary.
|
|
56
|
-
|
|
57
|
-
## Behavior
|
|
58
|
-
|
|
59
|
-
| API | Contract |
|
|
60
|
-
| --- | --- |
|
|
61
|
-
| `mkdir(path)` | Create missing parents, accept an existing directory and return its `Path`. |
|
|
62
|
-
| `read_text(path)` / `write_text(path, text)` | Default to UTF-8 and preserve line endings. Writing replaces existing contents, requires an existing parent directory and returns the `Path`. CLI `read` emits UTF-8 bytes. |
|
|
63
|
-
| `copy_file(source, target)` | Copy the contents to an exact destination and return its `Path`. Reject an existing destination. Metadata is not copied. An interrupted copy can leave a partial destination. |
|
|
64
|
-
| `find_files(root, pattern="*")` | Recursively match file basenames, including dotfiles, with case-sensitive glob matching. Return paths sorted by their `/`-separated relative names. Skip file symlinks and do not descend into directory symlinks or nested Windows directory reparse points. CLI `find` emits a JSON array of paths with `/` separators. |
|
|
65
|
-
| `run(argv, *, cwd=None, timeout=None, check=True, capture=True, encoding="utf-8")` | Pass the executable and each argument separately in a non-empty list or tuple. Return `subprocess.CompletedProcess`. By default, capture output as UTF-8 text and raise `CalledProcessError` on a nonzero exit. Set `encoding=None` for bytes or `capture=False` to inherit output. CLI `run` inherits output and propagates exit status; it uses 124 on timeout and `128 + signal` for signal exits on POSIX. |
|
|
66
|
-
|
|
67
|
-
`run` does not expand variables, implement pipelines or redirection, or support Windows `.bat` and `.cmd` entry points. It uses the operating system's executable lookup rules; pass an absolute executable path to select a specific installation. A timeout targets the directly launched process, not its entire process tree. Choose the executable and its options as trusted configuration: shell-free launching is not a sandbox for the program being run.
|
|
68
|
-
|
|
69
|
-
Run tests from the checkout after installing: `python -m unittest discover -s tests -v`.
|
|
@@ -1,11 +0,0 @@
|
|
|
1
|
-
LICENSE
|
|
2
|
-
README.md
|
|
3
|
-
pyproject.toml
|
|
4
|
-
src/shellless_ops/__init__.py
|
|
5
|
-
src/shellless_ops/__main__.py
|
|
6
|
-
src/shellless_ops.egg-info/PKG-INFO
|
|
7
|
-
src/shellless_ops.egg-info/SOURCES.txt
|
|
8
|
-
src/shellless_ops.egg-info/dependency_links.txt
|
|
9
|
-
src/shellless_ops.egg-info/entry_points.txt
|
|
10
|
-
src/shellless_ops.egg-info/top_level.txt
|
|
11
|
-
tests/test_shellless_ops.py
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
shellless_ops
|
|
File without changes
|