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.
@@ -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 = ["setuptools>=77"]
3
- build-backend = "setuptools.build_meta"
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.1.0"
8
- description = "Repeatable file and process operations without shell command strings"
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.11"
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.setuptools.packages.find]
31
- where = ["src"]
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)
@@ -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,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`.
@@ -1,4 +0,0 @@
1
- [egg_info]
2
- tag_build =
3
- tag_date = 0
4
-
@@ -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,2 +0,0 @@
1
- [console_scripts]
2
- shellless-ops = shellless_ops.__main__:main
@@ -1 +0,0 @@
1
- shellless_ops
File without changes