shellless-ops 0.1.0__py3-none-any.whl
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/__init__.py +73 -0
- shellless_ops/__main__.py +60 -0
- shellless_ops-0.1.0.dist-info/METADATA +69 -0
- shellless_ops-0.1.0.dist-info/RECORD +8 -0
- shellless_ops-0.1.0.dist-info/WHEEL +5 -0
- shellless_ops-0.1.0.dist-info/entry_points.txt +2 -0
- shellless_ops-0.1.0.dist-info/licenses/LICENSE +21 -0
- shellless_ops-0.1.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,73 @@
|
|
|
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
|
+
)
|
|
@@ -0,0 +1,60 @@
|
|
|
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())
|
|
@@ -0,0 +1,69 @@
|
|
|
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`.
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
shellless_ops/__init__.py,sha256=YhnUAeEW3XzYVVhGVrpta_vb8GCnZV6UaFjclhf5wtw,2405
|
|
2
|
+
shellless_ops/__main__.py,sha256=4G74KEs14WgCEMT0dkgfsUQGqHvBwuVstD5c1bGOJYM,2428
|
|
3
|
+
shellless_ops-0.1.0.dist-info/licenses/LICENSE,sha256=9ow7hSy7wNbGsT7AzyJvNpa76m3VhicsyiiZ92Cr90s,1069
|
|
4
|
+
shellless_ops-0.1.0.dist-info/METADATA,sha256=HKuZpi5pTeudB85KH10umisGfgbeB0bguKjYw5qGZfk,4017
|
|
5
|
+
shellless_ops-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
6
|
+
shellless_ops-0.1.0.dist-info/entry_points.txt,sha256=o9vgJlWGmSgHmiFMhxhnudo5nTV-EvLi60NeHoWBf38,62
|
|
7
|
+
shellless_ops-0.1.0.dist-info/top_level.txt,sha256=kldIza2DmOetJdaIIcUJtLqlH7NOx53Dmn5-MqcEPGo,14
|
|
8
|
+
shellless_ops-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 zhangs-cedar
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
shellless_ops
|