shellless-ops 0.2.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.
@@ -1,10 +1,10 @@
1
- Metadata-Version: 2.4
1
+ Metadata-Version: 2.5
2
2
  Name: shellless-ops
3
- Version: 0.2.0
3
+ Version: 0.3.0
4
4
  Summary: Cross-platform file and process tools with bounded Python failure evidence
5
+ Requires-Python: >=3.8
6
+ Description-Content-Type: text/markdown
5
7
  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
8
  Classifier: Development Status :: 3 - Alpha
9
9
  Classifier: Operating System :: MacOS
10
10
  Classifier: Operating System :: Microsoft :: Windows
@@ -12,14 +12,14 @@ Classifier: Operating System :: POSIX :: Linux
12
12
  Classifier: Programming Language :: Python :: 3
13
13
  Classifier: Topic :: Software Development :: Libraries :: Python Modules
14
14
  Classifier: Topic :: Utilities
15
- Requires-Python: >=3.11
16
- Description-Content-Type: text/markdown
17
15
  License-File: LICENSE
18
- Dynamic: license-file
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
19
 
20
20
  # shellless-ops
21
21
 
22
- `shellless-ops` 是一套跨平台的 Python 文件和进程工具。它统一路径、编码、查找结果和退出码,减少同一任务需要分别维护 Bash 和 PowerShell 版本的情况。要求 Python 3.11+,无运行时依赖。
22
+ `shellless-ops` 是一套跨平台的 Python 文件和进程工具。它统一路径、编码、查找结果和退出码,减少同一任务需要分别维护 Bash 和 PowerShell 版本的情况。要求 Python 3.8+,无运行时依赖。
23
23
 
24
24
  ## 安装
25
25
 
@@ -104,4 +104,3 @@ with capture(names=("amount",)) as report:
104
104
 
105
105
  欢迎提交 [Issue](https://github.com/zhangs-cedar/shellless-ops/issues) 或 Pull Request。在仓库目录执行 `python -m pip install .` 安装当前代码,再运行 `python -m unittest discover -s tests -v`。
106
106
 
107
- 想试用常驻 Python 内核、按需读取失败现场和多 agent 独立会话,见 [AI 调试会话实验](experiments/ai-session/README.md)。它不属于基础库的发行包。
@@ -1,6 +1,6 @@
1
1
  # shellless-ops
2
2
 
3
- `shellless-ops` 是一套跨平台的 Python 文件和进程工具。它统一路径、编码、查找结果和退出码,减少同一任务需要分别维护 Bash 和 PowerShell 版本的情况。要求 Python 3.11+,无运行时依赖。
3
+ `shellless-ops` 是一套跨平台的 Python 文件和进程工具。它统一路径、编码、查找结果和退出码,减少同一任务需要分别维护 Bash 和 PowerShell 版本的情况。要求 Python 3.8+,无运行时依赖。
4
4
 
5
5
  ## 安装
6
6
 
@@ -84,5 +84,3 @@ with capture(names=("amount",)) as report:
84
84
  ## 贡献
85
85
 
86
86
  欢迎提交 [Issue](https://github.com/zhangs-cedar/shellless-ops/issues) 或 Pull Request。在仓库目录执行 `python -m pip install .` 安装当前代码,再运行 `python -m unittest discover -s tests -v`。
87
-
88
- 想试用常驻 Python 内核、按需读取失败现场和多 agent 独立会话,见 [AI 调试会话实验](experiments/ai-session/README.md)。它不属于基础库的发行包。
@@ -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.2.0"
7
+ version = "0.3.0"
8
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"]
@@ -105,7 +105,7 @@ def search_text(
105
105
  report["truncated"] = True
106
106
  return report
107
107
 
108
- text = line.removesuffix("\n")
108
+ text = line[:-1] if line.endswith("\n") else line
109
109
  clipped = len(text) > max_line_chars
110
110
  if clipped:
111
111
  context = max(0, (max_line_chars - len(query)) // 2)
@@ -39,7 +39,7 @@ def _run_evidence(args, parser):
39
39
  finally:
40
40
  sys.argv, sys.path = argv, path
41
41
  # Finalization errors must not change an active script exception.
42
- active_error = sys.exception()
42
+ active_error = sys.exc_info()[1]
43
43
  try:
44
44
  with stream:
45
45
  json.dump(
@@ -13,7 +13,8 @@ _MAX_TEXT = 160
13
13
 
14
14
 
15
15
  def _type_name(kind):
16
- return _TYPE_NAME.__get__(kind)[:80]
16
+ # A class name can be a str subclass with its own __getitem__.
17
+ return str.__getitem__(_TYPE_NAME.__get__(kind), slice(80))
17
18
 
18
19
 
19
20
  def _summary(value):
@@ -69,7 +70,7 @@ def _source_excerpt(filename, line, root):
69
70
  return None
70
71
  try:
71
72
  path = Path(filename).resolve()
72
- if not path.is_relative_to(root) or not path.is_file():
73
+ if (path != root and root not in path.parents) or not path.is_file():
73
74
  return None
74
75
  with open_source(path) as stream:
75
76
  return [
@@ -48,6 +48,27 @@ class EvidenceTests(unittest.TestCase):
48
48
  self.assertEqual(2 + 2, 4)
49
49
  self.assertEqual(normal, {"failure": None})
50
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
+
51
72
  def test_source_is_opt_in_and_runtime_frames_are_bounded(self):
52
73
  def recurse(depth):
53
74
  if depth:
@@ -1,107 +0,0 @@
1
- Metadata-Version: 2.4
2
- Name: shellless-ops
3
- Version: 0.2.0
4
- Summary: Cross-platform file and process tools with bounded Python failure evidence
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
- `shellless-ops` 是一套跨平台的 Python 文件和进程工具。它统一路径、编码、查找结果和退出码,减少同一任务需要分别维护 Bash 和 PowerShell 版本的情况。要求 Python 3.11+,无运行时依赖。
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
-
107
- 想试用常驻 Python 内核、按需读取失败现场和多 agent 独立会话,见 [AI 调试会话实验](experiments/ai-session/README.md)。它不属于基础库的发行包。
@@ -1,4 +0,0 @@
1
- [egg_info]
2
- tag_build =
3
- tag_date = 0
4
-
@@ -1,13 +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/evidence.py
7
- src/shellless_ops.egg-info/PKG-INFO
8
- src/shellless_ops.egg-info/SOURCES.txt
9
- src/shellless_ops.egg-info/dependency_links.txt
10
- src/shellless_ops.egg-info/entry_points.txt
11
- src/shellless_ops.egg-info/top_level.txt
12
- tests/test_evidence.py
13
- 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