cmdchain 0.1.0__tar.gz → 0.1.2__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.
- cmdchain-0.1.2/PKG-INFO +863 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/README.md +3 -3
- {cmdchain-0.1.0 → cmdchain-0.1.2}/pyproject.toml +3 -2
- {cmdchain-0.1.0 → cmdchain-0.1.2}/src/clichain/core.py +52 -12
- cmdchain-0.1.2/src/cmdchain/__init__.py +10 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/tests/test_core.py +3 -1
- cmdchain-0.1.0/PKG-INFO +0 -22
- {cmdchain-0.1.0 → cmdchain-0.1.2}/.github/workflows/ci.yml +0 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/.github/workflows/publish.yml +0 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/.gitignore +0 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/LICENSE-APACHE +0 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/LICENSE-MIT +0 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/benchmarks/bench.py +0 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/benchmarks/bench_from_file.py +0 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/examples/01_basic_pipe.py +0 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/examples/02_capture_interpolate.py +0 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/examples/03_filter.py +0 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/examples/04_file_io.py +0 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/examples/05_each.py +0 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/examples/06_disk_image.py +0 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/examples/07_video_convert.py +0 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/examples/08_checks.py +0 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/examples/09_meter.py +0 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/examples/10_report_sbom.py +0 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/examples/11_compilable.py +0 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/examples/12_webhook_metrics.py +0 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/logos/clichain-favicon.svg +0 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/logos/clichain-horizontal-dark.svg +0 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/logos/clichain-horizontal-light.svg +0 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/logos/clichain-logo-dark.svg +0 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/logos/clichain-logo-light.svg +0 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/logos/clichain-mark-dark.svg +0 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/logos/clichain-mark-light.svg +0 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/logos/clichain_angular_chain_final.svg +0 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/src/clichain/__init__.py +0 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/src/clichain/checks.py +0 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/src/clichain/cli.py +0 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/src/clichain/py.typed +0 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/tests/__init__.py +0 -0
- {cmdchain-0.1.0 → cmdchain-0.1.2}/tests/test_compile.py +0 -0
cmdchain-0.1.2/PKG-INFO
ADDED
|
@@ -0,0 +1,863 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: cmdchain
|
|
3
|
+
Version: 0.1.2
|
|
4
|
+
Summary: Fluent CLI tool chaining for Python
|
|
5
|
+
Author-email: Darcy Luis Neves Bras da Silva <stardevelin@gmail.com>
|
|
6
|
+
License-Expression: MIT OR Apache-2.0
|
|
7
|
+
License-File: LICENSE-APACHE
|
|
8
|
+
License-File: LICENSE-MIT
|
|
9
|
+
Keywords: chain,cli,pipe,subprocess
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: License :: OSI Approved :: Apache Software License
|
|
13
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Typing :: Typed
|
|
20
|
+
Requires-Python: >=3.10
|
|
21
|
+
Provides-Extra: compile
|
|
22
|
+
Requires-Dist: pyinstaller>=6.0; extra == 'compile'
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
|
|
25
|
+
<p align="center">
|
|
26
|
+
<picture>
|
|
27
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/dardevelin/clichain/main/logos/clichain-horizontal-dark.svg">
|
|
28
|
+
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/dardevelin/clichain/main/logos/clichain-horizontal-light.svg">
|
|
29
|
+
<img alt="clichain" src="https://raw.githubusercontent.com/dardevelin/clichain/main/logos/clichain-horizontal-dark.svg" width="340">
|
|
30
|
+
</picture>
|
|
31
|
+
</p>
|
|
32
|
+
|
|
33
|
+
<p align="center">
|
|
34
|
+
Fluent CLI tool chaining for Python.<br>
|
|
35
|
+
<code>pip install cmdchain</code>
|
|
36
|
+
</p>
|
|
37
|
+
|
|
38
|
+
<p align="center">
|
|
39
|
+
<a href="https://github.com/dardevelin/clichain/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/dardevelin/clichain/actions/workflows/ci.yml/badge.svg"></a>
|
|
40
|
+
<a href="https://pypi.org/project/cmdchain/"><img alt="PyPI" src="https://img.shields.io/pypi/v/cmdchain"></a>
|
|
41
|
+
<a href="https://pypi.org/project/cmdchain/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/cmdchain"></a>
|
|
42
|
+
<a href="LICENSE-MIT"><img alt="License" src="https://img.shields.io/badge/license-MIT%2FApache--2.0-blue"></a>
|
|
43
|
+
</p>
|
|
44
|
+
|
|
45
|
+
<p align="center">
|
|
46
|
+
<a href="#install">Install</a> ·
|
|
47
|
+
<a href="#quickstart">Quickstart</a> ·
|
|
48
|
+
<a href="#api-reference">API</a> ·
|
|
49
|
+
<a href="#cli">CLI</a> ·
|
|
50
|
+
<a href="#performance">Performance</a> ·
|
|
51
|
+
<a href="#security">Security</a> ·
|
|
52
|
+
<a href="#license">License</a>
|
|
53
|
+
</p>
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
clichain replaces bash scripts with typed, inspectable, lazy-evaluated pipelines
|
|
58
|
+
of CLI commands connected by real kernel pipes. Zero runtime dependencies. Python 3.10+.
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
pip install cmdchain
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
```python
|
|
65
|
+
from clichain import tool # module name is clichain
|
|
66
|
+
|
|
67
|
+
echo = tool("echo")
|
|
68
|
+
grep = tool("grep")
|
|
69
|
+
sort = tool("sort")
|
|
70
|
+
wc = tool("wc")
|
|
71
|
+
|
|
72
|
+
result = (
|
|
73
|
+
echo("cherry\napple\nbanana\napricot")
|
|
74
|
+
.pipe(grep("a"))
|
|
75
|
+
.pipe(sort())
|
|
76
|
+
.pipe(wc("-l"))
|
|
77
|
+
.run()
|
|
78
|
+
)
|
|
79
|
+
|
|
80
|
+
print(result.stdout.strip()) # 3
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Nothing executes until `.run()`. The chain is data -- a list of step descriptions
|
|
84
|
+
that can be inspected, validated, and reused before any process spawns.
|
|
85
|
+
|
|
86
|
+
## Why not bash?
|
|
87
|
+
|
|
88
|
+
Bash works. Until it doesn't. Quoting breaks, error handling is `set -e` and hope,
|
|
89
|
+
debugging is `echo` statements, and CI failures give you exit code 1 with no context.
|
|
90
|
+
|
|
91
|
+
clichain gives you the same pipe-based execution model with:
|
|
92
|
+
|
|
93
|
+
- **Type safety** -- args are lists, never shell-interpreted
|
|
94
|
+
- **Streaming** -- kernel pipes between commands, same as bash `|`
|
|
95
|
+
- **Preflight checks** -- verify tools exist and versions match before execution
|
|
96
|
+
- **Error diagnostics** -- error codes, execution traces, source locations
|
|
97
|
+
- **Profiling** -- time, lines, bytes, spawns per step
|
|
98
|
+
- **SBOM** -- full bill of materials for every execution
|
|
99
|
+
- **Compilation** -- bundle scripts to single binaries for CI
|
|
100
|
+
|
|
101
|
+
## Install
|
|
102
|
+
|
|
103
|
+
The PyPI package name is **cmdchain**, the Python module is **clichain**.
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
pip install cmdchain
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
```python
|
|
110
|
+
from clichain import tool
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Zero runtime dependencies. Python 3.10+ only.
|
|
114
|
+
|
|
115
|
+
For compiling scripts to standalone binaries:
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
pip install cmdchain[compile]
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## Development setup
|
|
122
|
+
|
|
123
|
+
Clone the repository and install in editable mode with dev tooling:
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
git clone https://github.com/dardevelin/clichain.git
|
|
127
|
+
cd clichain
|
|
128
|
+
python -m venv .venv
|
|
129
|
+
source .venv/bin/activate # or .venv\Scripts\activate on Windows
|
|
130
|
+
pip install -e .
|
|
131
|
+
pip install --dependency-group dev
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
This gives you:
|
|
135
|
+
- **pytest** -- test runner (`python -m pytest`)
|
|
136
|
+
- **ruff** -- linter and formatter (`ruff check src/ tests/` and `ruff format src/ tests/`)
|
|
137
|
+
- **basedpyright** -- type checker
|
|
138
|
+
|
|
139
|
+
Run the full check suite:
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
ruff check src/ tests/ # lint
|
|
143
|
+
ruff format --check src/ tests/ # format check
|
|
144
|
+
python -m pytest tests/ # unit tests (62 tests)
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Compile end-to-end tests require pyinstaller and are skipped by default:
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
pip install cmdchain[compile]
|
|
151
|
+
python -m pytest tests/test_compile.py # compile + run binary tests
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
### Project structure
|
|
155
|
+
|
|
156
|
+
```
|
|
157
|
+
src/clichain/
|
|
158
|
+
__init__.py # public API: tool, Cmd, Pipeline, Result, set_output
|
|
159
|
+
core.py # steps, pipeline execution, streaming, profiling, SBOM
|
|
160
|
+
checks.py # preflight checks: binary, env, file_exists
|
|
161
|
+
cli.py # CLI: explain, check, compile
|
|
162
|
+
py.typed # PEP 561 typed package marker
|
|
163
|
+
tests/
|
|
164
|
+
test_core.py # unit tests for all primitives
|
|
165
|
+
test_compile.py # end-to-end compile tests (requires pyinstaller)
|
|
166
|
+
examples/ # runnable examples covering all features
|
|
167
|
+
benchmarks/ # performance comparisons vs bash
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
## Quickstart
|
|
171
|
+
|
|
172
|
+
### Basic pipe
|
|
173
|
+
|
|
174
|
+
```python
|
|
175
|
+
from clichain import tool
|
|
176
|
+
|
|
177
|
+
echo = tool("echo")
|
|
178
|
+
grep = tool("grep")
|
|
179
|
+
|
|
180
|
+
result = echo("hello\nworld").pipe(grep("hello")).run()
|
|
181
|
+
print(result.stdout) # hello\n
|
|
182
|
+
print(result.ok) # True
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
### Multi-stage pipe
|
|
186
|
+
|
|
187
|
+
Consecutive `.pipe()` calls are connected by kernel pipes -- all processes run concurrently,
|
|
188
|
+
data streams through without Python buffering:
|
|
189
|
+
|
|
190
|
+
```python
|
|
191
|
+
result = (
|
|
192
|
+
echo("foo\nbar\nbaz")
|
|
193
|
+
.pipe(grep("ba"))
|
|
194
|
+
.pipe(sort())
|
|
195
|
+
.pipe(wc("-l"))
|
|
196
|
+
.run()
|
|
197
|
+
)
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
### Adding arguments
|
|
201
|
+
|
|
202
|
+
`tool()` returns a callable. Call it with arguments to get a command ready to execute:
|
|
203
|
+
|
|
204
|
+
```python
|
|
205
|
+
grep = tool("grep")
|
|
206
|
+
|
|
207
|
+
# These are equivalent:
|
|
208
|
+
grep("-r", "-i", "pattern", ".")
|
|
209
|
+
grep("-ri", "pattern", ".")
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
Arguments are passed as a list to `subprocess.Popen` -- never through a shell.
|
|
213
|
+
No quoting issues, no injection.
|
|
214
|
+
|
|
215
|
+
### Capture and interpolate
|
|
216
|
+
|
|
217
|
+
Capture a step's output and reference it in later arguments with `{name}`:
|
|
218
|
+
|
|
219
|
+
```python
|
|
220
|
+
pwd = tool("pwd")
|
|
221
|
+
ls = tool("ls")
|
|
222
|
+
|
|
223
|
+
result = (
|
|
224
|
+
pwd()
|
|
225
|
+
.capture("cwd")
|
|
226
|
+
.pipe(ls("{cwd}"))
|
|
227
|
+
.run()
|
|
228
|
+
)
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
`.capture()` buffers the output and strips whitespace. `{name}` uses Python's
|
|
232
|
+
`str.format_map()` for substitution. Only the final output of a piped group
|
|
233
|
+
can be captured.
|
|
234
|
+
|
|
235
|
+
### Filter with Python logic
|
|
236
|
+
|
|
237
|
+
`.filter()` receives each line (stripped of newline), keeps lines where the function returns True.
|
|
238
|
+
It streams line-by-line through a thread -- no full buffering:
|
|
239
|
+
|
|
240
|
+
```python
|
|
241
|
+
ls = tool("ls")
|
|
242
|
+
wc = tool("wc")
|
|
243
|
+
|
|
244
|
+
result = (
|
|
245
|
+
ls(".")
|
|
246
|
+
.filter(lambda f: f.endswith(".py"))
|
|
247
|
+
.pipe(wc("-l"))
|
|
248
|
+
.run()
|
|
249
|
+
)
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
Filters can be chained:
|
|
253
|
+
|
|
254
|
+
```python
|
|
255
|
+
result = (
|
|
256
|
+
echo("1\n2\n3\n4\n5")
|
|
257
|
+
.filter(lambda line: int(line) > 2)
|
|
258
|
+
.filter(lambda line: int(line) < 5)
|
|
259
|
+
.run()
|
|
260
|
+
)
|
|
261
|
+
# result.lines == ["3", "4"]
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
### Peek
|
|
265
|
+
|
|
266
|
+
Observe data flowing through without modifying it. Useful for debugging:
|
|
267
|
+
|
|
268
|
+
```python
|
|
269
|
+
seen = []
|
|
270
|
+
result = (
|
|
271
|
+
echo("hello\nworld")
|
|
272
|
+
.peek(fn=lambda line: seen.append(line))
|
|
273
|
+
.pipe(wc("-l"))
|
|
274
|
+
.run()
|
|
275
|
+
)
|
|
276
|
+
# seen == ["hello\n", "world\n"]
|
|
277
|
+
# result.stdout.strip() == "2" -- data passed through unchanged
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
With a label (prints to the configured output destination):
|
|
281
|
+
|
|
282
|
+
```python
|
|
283
|
+
.peek(label="after filter")
|
|
284
|
+
# [after filter] hello
|
|
285
|
+
# [after filter] world
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
### Feed
|
|
289
|
+
|
|
290
|
+
Provide a string as stdin to the first command:
|
|
291
|
+
|
|
292
|
+
```python
|
|
293
|
+
sort = tool("sort")
|
|
294
|
+
|
|
295
|
+
result = sort().feed("cherry\napple\nbanana\n").run()
|
|
296
|
+
# result.lines == ["apple", "banana", "cherry"]
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
### File I/O
|
|
300
|
+
|
|
301
|
+
**Read from file** -- the file descriptor is passed directly to the process.
|
|
302
|
+
The kernel handles buffering, no Python overhead:
|
|
303
|
+
|
|
304
|
+
```python
|
|
305
|
+
sort = tool("sort")
|
|
306
|
+
|
|
307
|
+
# bash: sort < input.txt
|
|
308
|
+
sort().from_file("input.txt").run()
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
With explicit block size -- a thread reads N bytes at a time.
|
|
312
|
+
Useful when Python needs to mediate (e.g., meter on binary data).
|
|
313
|
+
~5-10% throughput cost vs kernel mode:
|
|
314
|
+
|
|
315
|
+
```python
|
|
316
|
+
sort().from_file("large.bin", block_size=65536).run()
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
**Write to file:**
|
|
320
|
+
|
|
321
|
+
```python
|
|
322
|
+
echo = tool("echo")
|
|
323
|
+
sort = tool("sort")
|
|
324
|
+
make = tool("make")
|
|
325
|
+
|
|
326
|
+
# bash: sort < input.txt > output.txt
|
|
327
|
+
sort().from_file("input.txt").redirect(stdout="output.txt").run()
|
|
328
|
+
|
|
329
|
+
# Append mode: >>
|
|
330
|
+
echo("new line").redirect(stdout="log.txt", append=True).run()
|
|
331
|
+
|
|
332
|
+
# Separate stderr:
|
|
333
|
+
make().redirect(stdout="build.log", stderr="errors.log").run()
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
### Merge stderr
|
|
337
|
+
|
|
338
|
+
Combine stderr into stdout (bash `2>&1`):
|
|
339
|
+
|
|
340
|
+
```python
|
|
341
|
+
bash = tool("bash")
|
|
342
|
+
result = bash("-c", "echo out; echo err >&2").merge_stderr().run()
|
|
343
|
+
# result.stdout contains both "out" and "err"
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
### Collect
|
|
347
|
+
|
|
348
|
+
Explicit buffering boundary. Forces all data to be collected in memory before
|
|
349
|
+
the next step proceeds:
|
|
350
|
+
|
|
351
|
+
```python
|
|
352
|
+
echo = tool("echo")
|
|
353
|
+
result = echo("hello").collect().run()
|
|
354
|
+
```
|
|
355
|
+
|
|
356
|
+
Most useful before `.each()` when you want to ensure all input is gathered
|
|
357
|
+
before spawning per-line commands.
|
|
358
|
+
|
|
359
|
+
### Per-line execution with each
|
|
360
|
+
|
|
361
|
+
`.each()` runs a command for every line of input. Each line becomes different arguments --
|
|
362
|
+
a separate process per line:
|
|
363
|
+
|
|
364
|
+
```python
|
|
365
|
+
find = tool("find")
|
|
366
|
+
ffmpeg = tool("ffmpeg")
|
|
367
|
+
|
|
368
|
+
# Convert all .mkv files to .mp3
|
|
369
|
+
(
|
|
370
|
+
find(".", "-name", "*.mkv")
|
|
371
|
+
.each(lambda f: ffmpeg("-i", f, "-vn", f.replace(".mkv", ".mp3")))
|
|
372
|
+
.run()
|
|
373
|
+
)
|
|
374
|
+
```
|
|
375
|
+
|
|
376
|
+
**Parallel execution** with `workers`:
|
|
377
|
+
|
|
378
|
+
```python
|
|
379
|
+
# 4 ffmpeg processes at a time
|
|
380
|
+
.each(lambda f: ffmpeg("-i", f, "-vn", f + ".mp3"), workers=4)
|
|
381
|
+
```
|
|
382
|
+
|
|
383
|
+
`.each()` stops on first failure -- remaining lines are skipped.
|
|
384
|
+
|
|
385
|
+
**When to use `.each()` vs `.pipe()`:**
|
|
386
|
+
- `.each()` -- command args change per line (different `-i` file each time)
|
|
387
|
+
- `.pipe()` -- command reads stdin line by line (grep, sort, awk)
|
|
388
|
+
|
|
389
|
+
`.pipe()` is one process, streaming. `.each()` is one process per line.
|
|
390
|
+
|
|
391
|
+
### Meter
|
|
392
|
+
|
|
393
|
+
Count bytes and lines flowing through the pipeline. Streams line-by-line,
|
|
394
|
+
reports throughput periodically:
|
|
395
|
+
|
|
396
|
+
```python
|
|
397
|
+
seq = tool("seq")
|
|
398
|
+
sort = tool("sort")
|
|
399
|
+
wc = tool("wc")
|
|
400
|
+
|
|
401
|
+
result = (
|
|
402
|
+
seq("1000000")
|
|
403
|
+
.meter(label="raw")
|
|
404
|
+
.pipe(sort("-rn"))
|
|
405
|
+
.meter(label="sorted")
|
|
406
|
+
.pipe(wc("-l"))
|
|
407
|
+
.run()
|
|
408
|
+
)
|
|
409
|
+
```
|
|
410
|
+
|
|
411
|
+
Parameters:
|
|
412
|
+
- `label` -- prefix for the output
|
|
413
|
+
- `interval` -- seconds between reports (default `1.0`, use `0` for every line)
|
|
414
|
+
- `to` -- custom destination: `None` (uses configured output), a callable receiving `MeterStats`, or a file-like object
|
|
415
|
+
|
|
416
|
+
```python
|
|
417
|
+
# Custom callback -- collect stats programmatically
|
|
418
|
+
stats_log = []
|
|
419
|
+
echo("a\nb\nc").meter(to=lambda stats: stats_log.append(stats), interval=0).run()
|
|
420
|
+
|
|
421
|
+
# MeterStats fields:
|
|
422
|
+
# stats.label str
|
|
423
|
+
# stats.bytes int -- total bytes seen
|
|
424
|
+
# stats.lines int -- total lines seen
|
|
425
|
+
# stats.elapsed float -- seconds since start
|
|
426
|
+
# stats.bytes_per_sec float
|
|
427
|
+
# stats.lines_per_sec float
|
|
428
|
+
```
|
|
429
|
+
|
|
430
|
+
When a meter is present, the execution report includes a bytes column.
|
|
431
|
+
Without meter, the column is hidden -- no overhead unless you ask for it.
|
|
432
|
+
|
|
433
|
+
### Version constraints
|
|
434
|
+
|
|
435
|
+
```python
|
|
436
|
+
ffmpeg = tool("ffmpeg", version=">=6.0", msg="brew install ffmpeg")
|
|
437
|
+
jq = tool("jq", version=">=1.7")
|
|
438
|
+
```
|
|
439
|
+
|
|
440
|
+
**`tool()` parameters:**
|
|
441
|
+
- `name` -- binary name (looked up on `$PATH`)
|
|
442
|
+
- `version` -- semver constraint. Supports `>=`, `<=`, `>`, `<`, `==` and comma-separated combinations like `>=6.0,<8.0`
|
|
443
|
+
- `on_fail` -- what to do if the check fails: `"error"` (default, stops execution), `"warn"` (logs, continues), `"pass"` (silent, continues)
|
|
444
|
+
- `msg` -- custom message shown on failure
|
|
445
|
+
|
|
446
|
+
Version detection tries `--version`, `-version`, `version`, `-v` flags in order
|
|
447
|
+
and regex-matches the first semver string from the output.
|
|
448
|
+
|
|
449
|
+
### Preflight checks
|
|
450
|
+
|
|
451
|
+
Binary checks run automatically before execution by default. You can also add
|
|
452
|
+
custom checks for environment variables, files, or arbitrary conditions:
|
|
453
|
+
|
|
454
|
+
```python
|
|
455
|
+
from clichain import env, file_exists
|
|
456
|
+
|
|
457
|
+
result = pipeline.run(pre=[
|
|
458
|
+
env("API_KEY", on_fail="error", msg="set in .env"),
|
|
459
|
+
env("DEBUG", on_fail="warn"),
|
|
460
|
+
file_exists("input.mkv"),
|
|
461
|
+
])
|
|
462
|
+
```
|
|
463
|
+
|
|
464
|
+
**Check levels:**
|
|
465
|
+
| Level | Stops execution | Shows message |
|
|
466
|
+
|---|---|---|
|
|
467
|
+
| `error` | yes | yes |
|
|
468
|
+
| `warn` | no | yes |
|
|
469
|
+
| `pass` | no | no |
|
|
470
|
+
|
|
471
|
+
**Skip all validation:**
|
|
472
|
+
|
|
473
|
+
```python
|
|
474
|
+
result = pipeline.run(validate=False)
|
|
475
|
+
```
|
|
476
|
+
|
|
477
|
+
**Check without running:**
|
|
478
|
+
|
|
479
|
+
```python
|
|
480
|
+
checks = pipeline.check() # returns list[CheckResult]
|
|
481
|
+
for c in checks:
|
|
482
|
+
print(c.ok, c.name, c.found, c.msg)
|
|
483
|
+
```
|
|
484
|
+
|
|
485
|
+
`CheckResult` fields: `ok`, `name`, `expected`, `found`, `msg`, `on_fail`.
|
|
486
|
+
|
|
487
|
+
## API reference
|
|
488
|
+
|
|
489
|
+
### tool()
|
|
490
|
+
|
|
491
|
+
```python
|
|
492
|
+
tool(
|
|
493
|
+
name: str,
|
|
494
|
+
version: str | None = None,
|
|
495
|
+
on_fail: "error" | "warn" | "pass" = "error",
|
|
496
|
+
msg: str = "",
|
|
497
|
+
) -> Cmd
|
|
498
|
+
```
|
|
499
|
+
|
|
500
|
+
Creates a command wrapper for a binary. Call the result with arguments:
|
|
501
|
+
|
|
502
|
+
```python
|
|
503
|
+
grep = tool("grep")
|
|
504
|
+
grep("-ri", "pattern", ".") # returns a new Cmd with those args
|
|
505
|
+
```
|
|
506
|
+
|
|
507
|
+
### Pipeline primitives
|
|
508
|
+
|
|
509
|
+
| Method | What it does | Streaming |
|
|
510
|
+
|---|---|---|
|
|
511
|
+
| `.pipe(cmd)` | Connect stdout to stdin via kernel pipe | yes |
|
|
512
|
+
| `.filter(fn)` | Keep lines where `fn(line)` is True | yes, via thread |
|
|
513
|
+
| `.each(fn, workers=1)` | Run command per input line, stops on first failure | per-line spawn |
|
|
514
|
+
| `.peek(label=, fn=)` | Observe data without modifying | yes, via thread |
|
|
515
|
+
| `.meter(label=, to=, interval=1.0)` | Count bytes/lines, report throughput | yes, via thread |
|
|
516
|
+
| `.collect()` | Explicit buffering boundary | no |
|
|
517
|
+
| `.capture(name)` | Buffer and bind to `{name}` for interpolation | no |
|
|
518
|
+
| `.feed(data)` | String as stdin (inserted at start) | no |
|
|
519
|
+
| `.from_file(path, block_size=0)` | File as stdin (`0` = kernel, `N` = chunked thread) | yes |
|
|
520
|
+
| `.redirect(stdout=, stderr=, append=False)` | Write to file | yes |
|
|
521
|
+
| `.merge_stderr()` | Combine stderr into stdout (2>&1) | yes |
|
|
522
|
+
|
|
523
|
+
### Execution and inspection
|
|
524
|
+
|
|
525
|
+
| Method | What it does |
|
|
526
|
+
|---|---|
|
|
527
|
+
| `.run(validate=True, pre=None)` | Execute pipeline, returns `Result` |
|
|
528
|
+
| `.check()` | Validate binaries exist, returns `list[CheckResult]` |
|
|
529
|
+
| `.describe()` | Print steps and requirements without executing |
|
|
530
|
+
|
|
531
|
+
### Result
|
|
532
|
+
|
|
533
|
+
```python
|
|
534
|
+
result = pipeline.run()
|
|
535
|
+
|
|
536
|
+
# Status
|
|
537
|
+
result.ok # bool: returncode == 0
|
|
538
|
+
result.returncode # int: exit code or negative signal number
|
|
539
|
+
result.stdout # str: captured output
|
|
540
|
+
result.stderr # str: captured errors
|
|
541
|
+
result.lines # list[str]: stdout split by newline, stripped
|
|
542
|
+
|
|
543
|
+
# Diagnostics
|
|
544
|
+
result.checks # list[CheckResult]: preflight results
|
|
545
|
+
result.profile # list[StepProfile]: timing per step group
|
|
546
|
+
result.elapsed # float: total seconds
|
|
547
|
+
|
|
548
|
+
# Methods
|
|
549
|
+
result.report() # print full execution report
|
|
550
|
+
result.explain() # print error diagnosis with trace
|
|
551
|
+
result.sbom() # dict: software bill of materials
|
|
552
|
+
result.sbom_json(indent=2) # str: SBOM as JSON
|
|
553
|
+
```
|
|
554
|
+
|
|
555
|
+
**`StepProfile` fields:**
|
|
556
|
+
- `name` -- step group description
|
|
557
|
+
- `elapsed` -- seconds
|
|
558
|
+
- `lines_in`, `lines_out` -- line counts at group boundaries
|
|
559
|
+
- `spawns` -- number of processes created
|
|
560
|
+
- `bytes_in`, `bytes_out` -- byte counts (only when `.meter()` is present, otherwise `None`)
|
|
561
|
+
|
|
562
|
+
### Output control
|
|
563
|
+
|
|
564
|
+
```python
|
|
565
|
+
import sys
|
|
566
|
+
import logging
|
|
567
|
+
import clichain
|
|
568
|
+
|
|
569
|
+
clichain.set_output(sys.stderr) # default -- stderr
|
|
570
|
+
clichain.set_output(None) # silent -- no output
|
|
571
|
+
clichain.set_output(logging.info) # callable -- receives each line as a string
|
|
572
|
+
clichain.set_output(open("log.txt", "a")) # file-like -- anything with .write()
|
|
573
|
+
```
|
|
574
|
+
|
|
575
|
+
All library output goes through this single destination: check results, peek output,
|
|
576
|
+
meter stats, reports, and error explanations. Set once at the top of your script.
|
|
577
|
+
|
|
578
|
+
### Describe
|
|
579
|
+
|
|
580
|
+
Inspect what a pipeline will do without executing:
|
|
581
|
+
|
|
582
|
+
```python
|
|
583
|
+
pipeline.describe()
|
|
584
|
+
```
|
|
585
|
+
|
|
586
|
+
```
|
|
587
|
+
========================================================================
|
|
588
|
+
pipeline: 3 steps
|
|
589
|
+
------------------------------------------------------------------------
|
|
590
|
+
[0] FromFile < input.txt
|
|
591
|
+
[1] Cmd sort
|
|
592
|
+
[2] Cmd wc -l
|
|
593
|
+
------------------------------------------------------------------------
|
|
594
|
+
requires:
|
|
595
|
+
sort /usr/bin/sort ok
|
|
596
|
+
wc /usr/bin/wc ok
|
|
597
|
+
------------------------------------------------------------------------
|
|
598
|
+
< input.txt
|
|
599
|
+
========================================================================
|
|
600
|
+
```
|
|
601
|
+
|
|
602
|
+
Available via environment variable -- works with compiled binaries:
|
|
603
|
+
|
|
604
|
+
```bash
|
|
605
|
+
CLICHAIN_DESCRIBE=describe ./my_binary # human-readable
|
|
606
|
+
CLICHAIN_DESCRIBE=json ./my_binary # machine-readable JSON
|
|
607
|
+
```
|
|
608
|
+
|
|
609
|
+
The JSON output includes generator info, environment (OS, arch), steps with types and names,
|
|
610
|
+
tools with paths/versions/found status, and files read/written.
|
|
611
|
+
|
|
612
|
+
### Error diagnostics
|
|
613
|
+
|
|
614
|
+
```python
|
|
615
|
+
result.explain()
|
|
616
|
+
```
|
|
617
|
+
|
|
618
|
+
```
|
|
619
|
+
error[S13]: signal 13 (SIGPIPE: broken pipe -- downstream closed
|
|
620
|
+
before upstream finished)
|
|
621
|
+
|
|
622
|
+
execution trace:
|
|
623
|
+
[0] Cmd seq 100000
|
|
624
|
+
[1] Filter filter at script.py:12
|
|
625
|
+
[2] Cmd sort -rn <--
|
|
626
|
+
[3] Cmd head -10
|
|
627
|
+
[4] Cmd wc -l
|
|
628
|
+
|
|
629
|
+
source: script.py:15
|
|
630
|
+
|
|
631
|
+
This usually means a downstream command (like head or grep -m)
|
|
632
|
+
closed its input before the upstream command finished writing.
|
|
633
|
+
This is often normal behavior, not a real error.
|
|
634
|
+
```
|
|
635
|
+
|
|
636
|
+
The execution trace shows every step, marks the failure with `<--`, and includes
|
|
637
|
+
source locations for Python callables (filter/each lambdas) and the `.run()` call site.
|
|
638
|
+
|
|
639
|
+
Error codes follow the pattern `S{n}` for signals, `X{n}` for exit codes.
|
|
640
|
+
Each has a registry entry with a detailed explanation:
|
|
641
|
+
|
|
642
|
+
| Code | Meaning |
|
|
643
|
+
|---|---|
|
|
644
|
+
| `S2` | SIGINT -- interrupted (ctrl+c) |
|
|
645
|
+
| `S9` | SIGKILL -- killed (OOM killer, timeout) |
|
|
646
|
+
| `S11` | SIGSEGV -- segmentation fault (bug in the tool) |
|
|
647
|
+
| `S13` | SIGPIPE -- broken pipe (downstream closed early) |
|
|
648
|
+
| `S15` | SIGTERM -- terminated (process manager, CI shutdown) |
|
|
649
|
+
| `X1` | General error -- check stderr |
|
|
650
|
+
| `X2` | Invalid arguments |
|
|
651
|
+
| `X126` | Permission denied -- binary not executable |
|
|
652
|
+
| `X127` | Command not found |
|
|
653
|
+
|
|
654
|
+
### Execution report
|
|
655
|
+
|
|
656
|
+
```python
|
|
657
|
+
result.report()
|
|
658
|
+
```
|
|
659
|
+
|
|
660
|
+
```
|
|
661
|
+
========================================================================
|
|
662
|
+
clichain 0.1.0 | python 3.14.3 | Darwin 25.4.0 arm64
|
|
663
|
+
hostname /path/to/project
|
|
664
|
+
2026-04-02T08:56:47.959010+00:00
|
|
665
|
+
OK 0.0069s
|
|
666
|
+
========================================================================
|
|
667
|
+
tool version path
|
|
668
|
+
------------------------------------------------------------------------
|
|
669
|
+
sort 2.3 /usr/bin/sort
|
|
670
|
+
uniq - /usr/bin/uniq
|
|
671
|
+
------------------------------------------------------------------------
|
|
672
|
+
< /tmp/input.txt
|
|
673
|
+
> /tmp/output.txt
|
|
674
|
+
------------------------------------------------------------------------
|
|
675
|
+
# time in out spawn command
|
|
676
|
+
------------------------------------------------------------------------
|
|
677
|
+
0 0.007s 0 3 3 < input.txt | sort | uniq -c
|
|
678
|
+
| sort -rn
|
|
679
|
+
1 0.000s 3 3 0 redirect > output.txt
|
|
680
|
+
------------------------------------------------------------------------
|
|
681
|
+
0.007s total
|
|
682
|
+
------------------------------------------------------------------------
|
|
683
|
+
[ok] sort: /usr/bin/sort
|
|
684
|
+
[ok] uniq: /usr/bin/uniq
|
|
685
|
+
========================================================================
|
|
686
|
+
```
|
|
687
|
+
|
|
688
|
+
Long command chains wrap at pipe (`|`) boundaries to stay within 72 columns.
|
|
689
|
+
When `.meter()` is present, a bytes column appears in the profile table.
|
|
690
|
+
|
|
691
|
+
### SBOM
|
|
692
|
+
|
|
693
|
+
Every execution produces a software bill of materials:
|
|
694
|
+
|
|
695
|
+
```python
|
|
696
|
+
result.sbom() # dict
|
|
697
|
+
result.sbom_json() # formatted JSON string
|
|
698
|
+
result.sbom_json(indent=4) # custom indentation
|
|
699
|
+
```
|
|
700
|
+
|
|
701
|
+
```json
|
|
702
|
+
{
|
|
703
|
+
"generator": {
|
|
704
|
+
"name": "clichain",
|
|
705
|
+
"version": "0.1.0",
|
|
706
|
+
"python": "3.14.3"
|
|
707
|
+
},
|
|
708
|
+
"environment": {
|
|
709
|
+
"os": "Darwin",
|
|
710
|
+
"os_version": "25.4.0",
|
|
711
|
+
"arch": "arm64",
|
|
712
|
+
"hostname": "build-runner-01",
|
|
713
|
+
"cwd": "/home/ci/project"
|
|
714
|
+
},
|
|
715
|
+
"timestamp": "2026-04-02T08:40:24.941071+00:00",
|
|
716
|
+
"elapsed": 0.0086,
|
|
717
|
+
"exit_code": 0,
|
|
718
|
+
"tools": [
|
|
719
|
+
{"name": "sort", "path": "/usr/bin/sort", "version": "2.3"},
|
|
720
|
+
{"name": "wc", "path": "/usr/bin/wc"}
|
|
721
|
+
],
|
|
722
|
+
"files_read": ["/tmp/input.txt"],
|
|
723
|
+
"files_written": ["/tmp/output.txt"],
|
|
724
|
+
"call_tree": [
|
|
725
|
+
{"step": 0, "type": "FromFileStep", "path": "/tmp/input.txt"},
|
|
726
|
+
{"step": 1, "type": "CmdStep", "cmd": "sort"},
|
|
727
|
+
{"step": 2, "type": "CmdStep", "cmd": "wc -l"},
|
|
728
|
+
{"step": 3, "type": "RedirectStep", "stdout": "/tmp/output.txt"}
|
|
729
|
+
]
|
|
730
|
+
}
|
|
731
|
+
```
|
|
732
|
+
|
|
733
|
+
## CLI
|
|
734
|
+
|
|
735
|
+
```bash
|
|
736
|
+
clichain explain S13 # explain an error code
|
|
737
|
+
clichain check script.py # preflight all tools in a script
|
|
738
|
+
clichain compile script.py # bundle to standalone binary
|
|
739
|
+
clichain compile script.py -o name --clean
|
|
740
|
+
```
|
|
741
|
+
|
|
742
|
+
### explain
|
|
743
|
+
|
|
744
|
+
Look up any error code interactively:
|
|
745
|
+
|
|
746
|
+
```bash
|
|
747
|
+
$ clichain explain X127
|
|
748
|
+
error[X127]: exit 127
|
|
749
|
+
command not found
|
|
750
|
+
|
|
751
|
+
The binary was not found in any directory listed in $PATH.
|
|
752
|
+
Check that the tool is installed and its location is in your PATH.
|
|
753
|
+
```
|
|
754
|
+
|
|
755
|
+
### check
|
|
756
|
+
|
|
757
|
+
Preflight a script -- imports the module and validates all `tool()` declarations:
|
|
758
|
+
|
|
759
|
+
```bash
|
|
760
|
+
$ clichain check my_pipeline.py
|
|
761
|
+
tool: ffmpeg (ffmpeg)
|
|
762
|
+
ok: ffmpeg (7.0.1 at /usr/bin/ffmpeg)
|
|
763
|
+
tool: jq (jq)
|
|
764
|
+
error: jq — jq not found on $PATH
|
|
765
|
+
```
|
|
766
|
+
|
|
767
|
+
Note: `clichain check` executes the script to discover tools. Only run on trusted code.
|
|
768
|
+
|
|
769
|
+
### compile
|
|
770
|
+
|
|
771
|
+
Bundle a clichain script to a standalone binary. Requires `pip install cmdchain[compile]`.
|
|
772
|
+
|
|
773
|
+
```bash
|
|
774
|
+
clichain compile my_pipeline.py -o my_pipeline
|
|
775
|
+
clichain compile my_pipeline.py -o my_pipeline --clean # clean build artifacts
|
|
776
|
+
```
|
|
777
|
+
|
|
778
|
+
The compiled binary supports `CLICHAIN_DESCRIBE`:
|
|
779
|
+
|
|
780
|
+
```bash
|
|
781
|
+
./my_pipeline # runs normally
|
|
782
|
+
CLICHAIN_DESCRIBE=describe ./my_pipeline # shows requirements
|
|
783
|
+
CLICHAIN_DESCRIBE=json ./my_pipeline # JSON description
|
|
784
|
+
```
|
|
785
|
+
|
|
786
|
+
## Streaming architecture
|
|
787
|
+
|
|
788
|
+
Consecutive commands connected by `.pipe()` run as concurrent OS processes linked by kernel pipes.
|
|
789
|
+
Data flows in ~64KB chunks managed by the kernel -- Python never touches it:
|
|
790
|
+
|
|
791
|
+
```
|
|
792
|
+
[echo ...] --kernel pipe--> [grep ...] --kernel pipe--> [sort] --kernel pipe--> [wc -l]
|
|
793
|
+
```
|
|
794
|
+
|
|
795
|
+
When a Python step (`.filter()`, `.peek()`, `.meter()`) sits between commands, clichain creates
|
|
796
|
+
an OS pipe pair and runs a thread to bridge them. The thread reads lines from the upstream pipe,
|
|
797
|
+
processes them, and writes to the downstream pipe:
|
|
798
|
+
|
|
799
|
+
```
|
|
800
|
+
[echo ...] --kernel pipe--> [thread: filter(fn)] --os pipe--> [wc -l]
|
|
801
|
+
```
|
|
802
|
+
|
|
803
|
+
Steps that require all data before proceeding are explicit buffering boundaries:
|
|
804
|
+
- `.collect()` -- explicit
|
|
805
|
+
- `.capture()` -- needs full output to store
|
|
806
|
+
- `.each()` -- needs lines to iterate
|
|
807
|
+
|
|
808
|
+
The pipeline planner groups consecutive streamable steps (commands, filters, peeks, meters)
|
|
809
|
+
together so they run as a single streaming unit. Non-streamable steps force a boundary
|
|
810
|
+
between groups.
|
|
811
|
+
|
|
812
|
+
## Performance
|
|
813
|
+
|
|
814
|
+
Benchmarked against equivalent bash on macOS arm64:
|
|
815
|
+
|
|
816
|
+
| Workload | bash | clichain | ratio |
|
|
817
|
+
|---|---|---|---|
|
|
818
|
+
| 3-stage pipe | 9.1ms | 6.6ms | 0.73x |
|
|
819
|
+
| 4-stage pipe | 8.5ms | 7.8ms | 0.92x |
|
|
820
|
+
| Python filter between cmds | 35.5ms | 18.2ms | 0.51x |
|
|
821
|
+
| 1M lines through pipes | 123ms | 117ms | 0.96x |
|
|
822
|
+
| Feed + sort 10k lines | 13.8ms | 5.7ms | 0.42x |
|
|
823
|
+
|
|
824
|
+
Streaming pipes are on par or faster than bash.
|
|
825
|
+
|
|
826
|
+
`.each()` spawns a process per line -- inherently expensive. Use `workers=N` for parallelism,
|
|
827
|
+
or `.pipe()` when the tool reads stdin (one process, streaming).
|
|
828
|
+
|
|
829
|
+
`from_file(block_size=0)` (default) matches native bash `< file` redirection.
|
|
830
|
+
`block_size=N` adds ~5-10% overhead for the control it provides.
|
|
831
|
+
|
|
832
|
+
## Security
|
|
833
|
+
|
|
834
|
+
clichain has the same trust model as bash: you trust the commands you run and the inputs
|
|
835
|
+
you provide. The difference is clichain makes that trust boundary visible and auditable.
|
|
836
|
+
|
|
837
|
+
**By design:**
|
|
838
|
+
|
|
839
|
+
- Commands are passed as argument lists to `subprocess.Popen`, never through `shell=True`
|
|
840
|
+
- `from_file()` and `redirect()` operate on any path the process has access to -- no sandboxing
|
|
841
|
+
- `{name}` interpolation inserts captured values as literal arguments, not shell expressions. If captured data comes from untrusted sources, the values become arguments to downstream commands
|
|
842
|
+
- All spawned processes inherit the parent environment including sensitive variables
|
|
843
|
+
- `sbom()` and `report()` include host-identifying information (hostname, cwd, tool paths)
|
|
844
|
+
- `clichain check` executes the target script to discover tools -- only run on trusted code
|
|
845
|
+
- Version detection (`--version`) executes binaries during preflight
|
|
846
|
+
|
|
847
|
+
**Process management:**
|
|
848
|
+
|
|
849
|
+
On SIGINT/SIGTERM, clichain terminates all child processes gracefully (SIGTERM, 5s grace period,
|
|
850
|
+
SIGKILL), joins threads, and closes file handles. No orphan processes. Signal handlers are only
|
|
851
|
+
installed on the main thread.
|
|
852
|
+
|
|
853
|
+
## Future
|
|
854
|
+
|
|
855
|
+
The following features are being considered based on demand:
|
|
856
|
+
|
|
857
|
+
- **Plugin system** -- typed wrappers for specific tools with autocomplete and version-aware flag mapping
|
|
858
|
+
- **`from_bash`** -- parse bash one-liners into clichain pipelines (dev-only migration tool)
|
|
859
|
+
- **Stub generation** -- `.pyi` stubs from `$PATH` scanning for IDE autocomplete
|
|
860
|
+
|
|
861
|
+
## License
|
|
862
|
+
|
|
863
|
+
Dual licensed under [MIT](LICENSE-MIT) or [Apache 2.0](LICENSE-APACHE), at your option.
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
<p align="center">
|
|
2
2
|
<picture>
|
|
3
|
-
<source media="(prefers-color-scheme: dark)" srcset="logos/clichain-horizontal-dark.svg">
|
|
4
|
-
<source media="(prefers-color-scheme: light)" srcset="logos/clichain-horizontal-light.svg">
|
|
5
|
-
<img alt="clichain" src="logos/clichain-horizontal-dark.svg" width="340">
|
|
3
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/dardevelin/clichain/main/logos/clichain-horizontal-dark.svg">
|
|
4
|
+
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/dardevelin/clichain/main/logos/clichain-horizontal-light.svg">
|
|
5
|
+
<img alt="clichain" src="https://raw.githubusercontent.com/dardevelin/clichain/main/logos/clichain-horizontal-dark.svg" width="340">
|
|
6
6
|
</picture>
|
|
7
7
|
</p>
|
|
8
8
|
|
|
@@ -4,8 +4,9 @@ build-backend = "hatchling.build"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "cmdchain"
|
|
7
|
-
version = "0.1.
|
|
7
|
+
version = "0.1.2"
|
|
8
8
|
description = "Fluent CLI tool chaining for Python"
|
|
9
|
+
readme = "README.md"
|
|
9
10
|
requires-python = ">=3.10"
|
|
10
11
|
license = "MIT OR Apache-2.0"
|
|
11
12
|
keywords = ["cli", "subprocess", "pipe", "chain"]
|
|
@@ -41,7 +42,7 @@ dev = [
|
|
|
41
42
|
]
|
|
42
43
|
|
|
43
44
|
[tool.hatch.build.targets.wheel]
|
|
44
|
-
packages = ["src/clichain"]
|
|
45
|
+
packages = ["src/clichain", "src/cmdchain"]
|
|
45
46
|
|
|
46
47
|
[tool.ruff]
|
|
47
48
|
target-version = "py310"
|
|
@@ -157,9 +157,11 @@ class Result:
|
|
|
157
157
|
sep = "=" * W
|
|
158
158
|
div = "-" * W
|
|
159
159
|
v, py = gen["version"], gen["python"]
|
|
160
|
+
commit = gen.get("commit", "")
|
|
161
|
+
ver = f"{v} ({commit})" if commit else v
|
|
160
162
|
plat = f"{env['os']} {env['os_version']} {env['arch']}"
|
|
161
163
|
_emit(sep)
|
|
162
|
-
_emit(f" clichain {
|
|
164
|
+
_emit(f" clichain {ver} | python {py} | {plat}")
|
|
163
165
|
_emit(f" {env['hostname']} {env['cwd']}")
|
|
164
166
|
_emit(f" {data['timestamp']}")
|
|
165
167
|
_emit(f" {status} {data['elapsed']}s")
|
|
@@ -315,12 +317,16 @@ class Result:
|
|
|
315
317
|
|
|
316
318
|
import platform
|
|
317
319
|
|
|
320
|
+
gen: dict = {
|
|
321
|
+
"name": "clichain",
|
|
322
|
+
"version": _version,
|
|
323
|
+
"python": sys.version.split()[0],
|
|
324
|
+
}
|
|
325
|
+
if _git_hash:
|
|
326
|
+
gen["commit"] = _git_hash
|
|
327
|
+
|
|
318
328
|
sbom: dict = {
|
|
319
|
-
"generator":
|
|
320
|
-
"name": "clichain",
|
|
321
|
-
"version": _version,
|
|
322
|
-
"python": sys.version.split()[0],
|
|
323
|
-
},
|
|
329
|
+
"generator": gen,
|
|
324
330
|
"environment": {
|
|
325
331
|
"os": platform.system(),
|
|
326
332
|
"os_version": platform.release(),
|
|
@@ -484,7 +490,37 @@ def _explain_exit(code: int) -> str:
|
|
|
484
490
|
|
|
485
491
|
|
|
486
492
|
_output: IO[str] | Callable[[str], None] | None = sys.stderr
|
|
487
|
-
|
|
493
|
+
_git_hash: str = ""
|
|
494
|
+
|
|
495
|
+
|
|
496
|
+
def _get_version() -> str:
|
|
497
|
+
try:
|
|
498
|
+
from importlib.metadata import version
|
|
499
|
+
|
|
500
|
+
return version("cmdchain")
|
|
501
|
+
except Exception:
|
|
502
|
+
return "0.0.0"
|
|
503
|
+
|
|
504
|
+
|
|
505
|
+
_version: str = _get_version()
|
|
506
|
+
|
|
507
|
+
|
|
508
|
+
def _detect_git_hash() -> str:
|
|
509
|
+
try:
|
|
510
|
+
result = subprocess.run(
|
|
511
|
+
["git", "rev-parse", "--short", "HEAD"],
|
|
512
|
+
capture_output=True,
|
|
513
|
+
text=True,
|
|
514
|
+
timeout=2,
|
|
515
|
+
)
|
|
516
|
+
if result.returncode == 0:
|
|
517
|
+
return result.stdout.strip()
|
|
518
|
+
except (FileNotFoundError, subprocess.TimeoutExpired):
|
|
519
|
+
pass
|
|
520
|
+
return ""
|
|
521
|
+
|
|
522
|
+
|
|
523
|
+
_git_hash = _detect_git_hash()
|
|
488
524
|
|
|
489
525
|
|
|
490
526
|
def set_output(dest: IO[str] | Callable[[str], None] | None) -> None:
|
|
@@ -1029,12 +1065,16 @@ class Pipeline:
|
|
|
1029
1065
|
}
|
|
1030
1066
|
steps.append(node)
|
|
1031
1067
|
|
|
1068
|
+
desc_gen: dict = {
|
|
1069
|
+
"name": "clichain",
|
|
1070
|
+
"version": _version,
|
|
1071
|
+
"python": sys.version.split()[0],
|
|
1072
|
+
}
|
|
1073
|
+
if _git_hash:
|
|
1074
|
+
desc_gen["commit"] = _git_hash
|
|
1075
|
+
|
|
1032
1076
|
result: dict = {
|
|
1033
|
-
"generator":
|
|
1034
|
-
"name": "clichain",
|
|
1035
|
-
"version": _version,
|
|
1036
|
-
"python": sys.version.split()[0],
|
|
1037
|
-
},
|
|
1077
|
+
"generator": desc_gen,
|
|
1038
1078
|
"environment": {
|
|
1039
1079
|
"os": platform.system(),
|
|
1040
1080
|
"arch": platform.machine(),
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
"""cmdchain — alias for clichain.
|
|
2
|
+
|
|
3
|
+
pip install cmdchain
|
|
4
|
+
from clichain import tool # preferred
|
|
5
|
+
from cmdchain import tool # also works
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from clichain import * # noqa: F403
|
|
9
|
+
from clichain import __all__ as __all__
|
|
10
|
+
from clichain import __version__ as __version__
|
|
@@ -425,7 +425,9 @@ def test_sbom_generator():
|
|
|
425
425
|
sbom = result.sbom()
|
|
426
426
|
assert "generator" in sbom
|
|
427
427
|
assert sbom["generator"]["name"] == "clichain"
|
|
428
|
-
|
|
428
|
+
from clichain.core import _version
|
|
429
|
+
|
|
430
|
+
assert sbom["generator"]["version"] == _version
|
|
429
431
|
assert "python" in sbom["generator"]
|
|
430
432
|
|
|
431
433
|
|
cmdchain-0.1.0/PKG-INFO
DELETED
|
@@ -1,22 +0,0 @@
|
|
|
1
|
-
Metadata-Version: 2.4
|
|
2
|
-
Name: cmdchain
|
|
3
|
-
Version: 0.1.0
|
|
4
|
-
Summary: Fluent CLI tool chaining for Python
|
|
5
|
-
Author-email: Darcy Luis Neves Bras da Silva <stardevelin@gmail.com>
|
|
6
|
-
License-Expression: MIT OR Apache-2.0
|
|
7
|
-
License-File: LICENSE-APACHE
|
|
8
|
-
License-File: LICENSE-MIT
|
|
9
|
-
Keywords: chain,cli,pipe,subprocess
|
|
10
|
-
Classifier: Development Status :: 3 - Alpha
|
|
11
|
-
Classifier: Intended Audience :: Developers
|
|
12
|
-
Classifier: License :: OSI Approved :: Apache Software License
|
|
13
|
-
Classifier: License :: OSI Approved :: MIT License
|
|
14
|
-
Classifier: Programming Language :: Python :: 3
|
|
15
|
-
Classifier: Programming Language :: Python :: 3.10
|
|
16
|
-
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
-
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
-
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
-
Classifier: Typing :: Typed
|
|
20
|
-
Requires-Python: >=3.10
|
|
21
|
-
Provides-Extra: compile
|
|
22
|
-
Requires-Dist: pyinstaller>=6.0; extra == 'compile'
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|