sigil-cli 1.5.2__tar.gz → 1.5.4__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.
- {sigil_cli-1.5.2/src/sigil_cli.egg-info → sigil_cli-1.5.4}/PKG-INFO +57 -32
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/README.md +50 -29
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/pyproject.toml +7 -3
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/__init__.py +11 -4
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/__main__.py +7 -0
- sigil_cli-1.5.4/src/sigil/cli_tools/__init__.py +22 -0
- sigil_cli-1.5.4/src/sigil/cli_tools/requirements.py +58 -0
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/cli_tools/tree.py +11 -6
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/cli_tools/util.py +12 -0
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/cli_tools/validate.py +13 -8
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/datasource/__init__.py +11 -1
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/datasource/datasource.py +9 -0
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/datasource/yml_source.py +0 -1
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/entrypoint.py +12 -2
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/models/argparser.py +7 -1
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/models/command.py +1 -0
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/stages/parser.py +59 -8
- {sigil_cli-1.5.2 → sigil_cli-1.5.4/src/sigil_cli.egg-info}/PKG-INFO +57 -32
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil_cli.egg-info/SOURCES.txt +2 -0
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/tests/test_cli_util.py +1 -1
- sigil_cli-1.5.4/tests/test_requirements.py +256 -0
- sigil_cli-1.5.2/src/sigil/cli_tools/__init__.py +0 -9
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/LICENSE +0 -0
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/setup.cfg +0 -0
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/cli_tools/init.py +0 -0
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/datasource/helper.py +0 -0
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/datasource/json_source.py +0 -0
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/models/__init__.py +0 -0
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/models/argument.py +0 -0
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/models/script.py +0 -0
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/script_sources/__init__.py +0 -0
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/script_sources/filesystem_script_source.py +0 -0
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/script_sources/script_source.py +0 -0
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/stages/__init__.py +0 -0
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/stages/builder.py +0 -0
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/stages/resolver.py +0 -0
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/stages/script_loader.py +0 -0
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil_cli.egg-info/dependency_links.txt +0 -0
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil_cli.egg-info/entry_points.txt +0 -0
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil_cli.egg-info/requires.txt +0 -0
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil_cli.egg-info/top_level.txt +0 -0
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/tests/test_builder.py +0 -0
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/tests/test_cli_init.py +0 -0
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/tests/test_cli_tree.py +0 -0
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/tests/test_cli_validate.py +0 -0
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/tests/test_integration.py +0 -0
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/tests/test_reader.py +0 -0
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/tests/test_resolver.py +0 -0
- {sigil_cli-1.5.2 → sigil_cli-1.5.4}/tests/test_scriptloader.py +0 -0
|
@@ -1,21 +1,25 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: sigil-cli
|
|
3
|
-
Version: 1.5.
|
|
3
|
+
Version: 1.5.4
|
|
4
4
|
Summary: Configuration driven CLI builder with subcommands and script loading
|
|
5
5
|
Author-email: Kenzo Staelens <kenzostael@gmail.com>
|
|
6
6
|
License: MIT
|
|
7
7
|
Project-URL: Homepage, https://github.com/kenzo-staelens/sigil
|
|
8
8
|
Project-URL: Repository, https://github.com/kenzo-staelens/sigil
|
|
9
9
|
Project-URL: Issues, https://github.com/kenzo-staelens/sigil/issues
|
|
10
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
11
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
10
12
|
Classifier: Programming Language :: Python :: 3
|
|
11
13
|
Classifier: Programming Language :: Python :: 3.10
|
|
12
14
|
Classifier: Programming Language :: Python :: 3.11
|
|
13
15
|
Classifier: Programming Language :: Python :: 3.12
|
|
14
16
|
Classifier: Programming Language :: Python :: 3.13
|
|
15
17
|
Classifier: Programming Language :: Python :: 3.14
|
|
16
|
-
Classifier: Topic :: Software Development :: User Interfaces
|
|
17
|
-
Classifier: License :: OSI Approved :: MIT License
|
|
18
18
|
Classifier: Operating System :: OS Independent
|
|
19
|
+
Classifier: Environment :: Console
|
|
20
|
+
Classifier: Intended Audience :: Developers
|
|
21
|
+
Classifier: Intended Audience :: System Administrators
|
|
22
|
+
Classifier: Typing :: Typed
|
|
19
23
|
Requires-Python: >=3.10
|
|
20
24
|
Description-Content-Type: text/markdown
|
|
21
25
|
License-File: LICENSE
|
|
@@ -55,17 +59,25 @@ It plays nicely with `argcomplete` out of the box.
|
|
|
55
59
|
- Declarative command hierarchies (parents, subparsers, defaults)
|
|
56
60
|
- Each command can point to a dynamically imported Python script
|
|
57
61
|
- `argcomplete` integration for tab‑completion
|
|
58
|
-
- Pluggable data sources
|
|
62
|
+
- Pluggable data sources - YAML is the default, but JSON, a dict or custom datasource are trivial to swap in
|
|
59
63
|
- No boilerplate argparse code in your main logic
|
|
60
64
|
|
|
61
65
|
## The alternatives
|
|
62
66
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
67
|
+
[Click](https://click.palletsprojects.com/) and [Typer](https://typer.tiangolo.com/) define commands in Python
|
|
68
|
+
(decorators, type hints). Sigil
|
|
69
|
+
defines the command tree as data (YAML by default; JSON or a dict work
|
|
70
|
+
too, or whatever datasource you decide to wire up), and each command points to a script module loaded by name.
|
|
71
|
+
|
|
72
|
+
**Consider Sigil when** you have many subcommands, the tree changes more
|
|
73
|
+
often than the logic, you want it generated or merged from several files
|
|
74
|
+
or you want to stay on the standard library's argparse without the boilerplate.
|
|
75
|
+
Arguments map 1:1 to argparse `add_argument` kwargs, so there's no new API
|
|
76
|
+
to learn, and `sigil validate` / `sigil tree` help you check the config.
|
|
66
77
|
|
|
67
|
-
|
|
68
|
-
|
|
78
|
+
**Stick with Click or Typer when** you have a small app, want type-hint
|
|
79
|
+
driven arguments (`type:` here only supports Python builtins), or need their
|
|
80
|
+
ecosystem and plugins.
|
|
69
81
|
|
|
70
82
|
## Quick Start
|
|
71
83
|
|
|
@@ -86,7 +98,7 @@ cd demo
|
|
|
86
98
|
python main.py --help
|
|
87
99
|
```
|
|
88
100
|
|
|
89
|
-
For a full walkthrough with custom commands and arguments,
|
|
101
|
+
For a full walkthrough with custom commands and arguments, see steps 0-4 below.
|
|
90
102
|
|
|
91
103
|
### 0. Recommended file structure
|
|
92
104
|
|
|
@@ -103,7 +115,9 @@ project_root/
|
|
|
103
115
|
└── ... # other scripts
|
|
104
116
|
```
|
|
105
117
|
|
|
106
|
-
|
|
118
|
+
> [!Important]
|
|
119
|
+
> Don't shoot yourself in the foot, don't symlink the bootstrap script.
|
|
120
|
+
> if using a venv remember to use/alias the right python runtime
|
|
107
121
|
|
|
108
122
|
### 1. Entry script
|
|
109
123
|
|
|
@@ -188,6 +202,9 @@ chmod +x mycli.py
|
|
|
188
202
|
| `name` | Program name (used as `prog` in argparse) |
|
|
189
203
|
| `script_dir` | Directory (relative to the config root) where command scripts are located |
|
|
190
204
|
|
|
205
|
+
> [!NOTE]
|
|
206
|
+
> this section contains only sigil-specific configurations, other argparse arguments still apply
|
|
207
|
+
|
|
191
208
|
### Command
|
|
192
209
|
|
|
193
210
|
| Field | Description |
|
|
@@ -199,14 +216,20 @@ chmod +x mycli.py
|
|
|
199
216
|
| `args` | List of argument definitions (see below) |
|
|
200
217
|
| `default` | If `True`, this subcommand is used when no subcommand is given |
|
|
201
218
|
| `load` | If `False` skips this command (or top level object) from being loaded into the command tree (default `True`) |
|
|
219
|
+
| `requirements` | (Optional) List of pip requirements that this subcommand requires. |
|
|
202
220
|
| any other parser kwarg | except for `dest`, `parents` and `formatter_class` they are all supported |
|
|
203
221
|
|
|
204
|
-
|
|
205
|
-
|
|
222
|
+
> [!NOTE]
|
|
223
|
+
> this section contains only sigil-specific configurations, other argparse arguments still apply
|
|
224
|
+
<!---->
|
|
225
|
+
> [!IMPORTANT]
|
|
226
|
+
> `parent` does not refer to argparse's `parents` parameter but is only used to resolve the parser tree.
|
|
227
|
+
> Parser (multi-)inheritance isn't supported but can be (rougly) emulated by
|
|
228
|
+
> adding arguments to `parent` commands in the tree.
|
|
206
229
|
|
|
207
230
|
### Argument
|
|
208
231
|
|
|
209
|
-
Each argument entry can be a plain dict which maps 1-to-1 with argparse `add_argument`, except name which maps
|
|
232
|
+
Each argument entry can be a plain dict which maps 1-to-1 with argparse `add_argument`, except name which maps its `*args`
|
|
210
233
|
|
|
211
234
|
```yaml
|
|
212
235
|
- name: ["-p", "--port"] # or a single string, e.g. "positional"
|
|
@@ -215,7 +238,7 @@ Each argument entry can be a plain dict which maps 1-to-1 with argparse `add_arg
|
|
|
215
238
|
help: "port number"
|
|
216
239
|
```
|
|
217
240
|
|
|
218
|
-
Groups and mutex groups are also
|
|
241
|
+
Groups and mutex groups are also supported via the "kind" parameter (defaults to `argument`)
|
|
219
242
|
|
|
220
243
|
```yaml
|
|
221
244
|
# mutex group
|
|
@@ -232,17 +255,16 @@ Groups and mutex groups are also suppored via the "kind" parameter (defaults to
|
|
|
232
255
|
The `name` field can be `--flag` for flags or a string for positional arguments.
|
|
233
256
|
Both literal string and list of strings are supported.
|
|
234
257
|
|
|
235
|
-
Types (`type:`) only
|
|
258
|
+
Types (`type:`) only support Python builtins
|
|
236
259
|
|
|
237
260
|
### Script files
|
|
238
261
|
|
|
239
|
-
Each script
|
|
240
|
-
`def run(args: argparse.Namespace, ctx: dict[str, Any]) -> None` method.
|
|
262
|
+
Each script file must define a `def run(args: argparse.Namespace, ctx: dict[str, Any]) -> None` method.
|
|
241
263
|
|
|
242
|
-
|
|
264
|
+
Args is the namespace supplied by argparse (parsed with parse_known_args). Any additional args can be found in `ctx['other_args']`.
|
|
243
265
|
|
|
244
|
-
|
|
245
|
-
remove or otherwise modify args
|
|
266
|
+
Scripts run in sequence from command -> subcommand -> sub sub command -> ... and each may add to,
|
|
267
|
+
remove or otherwise modify `args` and `ctx` to enrich or modify the behaviour of subsequent scripts.
|
|
246
268
|
|
|
247
269
|
## Sigil CLI Commands
|
|
248
270
|
|
|
@@ -251,16 +273,18 @@ remove or otherwise modify args.namespace and ctx to enrich or modify the behavi
|
|
|
251
273
|
| Command | Purpose |
|
|
252
274
|
| --- | --- |
|
|
253
275
|
| `sigil init [project_name]` | Creates a new project folder with a sample ready-to-run Python entrypoint. |
|
|
254
|
-
| `sigil validate [project_path]` | Checks your sigil definition for schema errors and missing references. Run this after heavy edits to catch mistakes early. |
|
|
255
|
-
| `sigil tree [project_path]` | Print the command structure of a sigil. |
|
|
276
|
+
| `sigil validate [project_path, default '.']` | Checks your sigil definition for schema errors and missing references. Run this after heavy edits to catch mistakes early. |
|
|
277
|
+
| `sigil tree [project_path, default '.']` | Print the command structure of a sigil. |
|
|
278
|
+
| `sigil requirements [project_path, default '.']` | Generate a requirements.txt file from active subcommands in the sigil. |
|
|
256
279
|
|
|
257
|
-
|
|
258
|
-
|
|
280
|
+
> [!NOTE]
|
|
281
|
+
> Your generated CLI (the one you build with Sigil) is completely separate from the `sigil` management
|
|
282
|
+
> commands above. You alias and run `main.py`. The `sigil` prefix is a different namespace.
|
|
259
283
|
|
|
260
284
|
### Misc
|
|
261
285
|
|
|
262
|
-
`
|
|
263
|
-
(deprecation, development, etc) or for non schema-compliant objects at the top level of a file
|
|
286
|
+
`load: False` may be used to detach commands from the command tree for any purpose
|
|
287
|
+
(deprecation, development, etc) or for non schema-compliant objects at the top level of a file. This may be useful to
|
|
264
288
|
define anchors or references that should not directly be read as a command.
|
|
265
289
|
|
|
266
290
|
## Tab‑Completion (argcomplete)
|
|
@@ -274,23 +298,23 @@ pip install argcomplete
|
|
|
274
298
|
activate-global-python-argcomplete
|
|
275
299
|
```
|
|
276
300
|
|
|
277
|
-
Then run your script and hit <kbd>Tab</kbd>
|
|
301
|
+
Then run your script and hit <kbd>Tab</kbd> - subcommands and flags will complete.
|
|
278
302
|
|
|
279
303
|
## Pluggable Backends
|
|
280
304
|
|
|
281
|
-
Sigil uses
|
|
305
|
+
Sigil uses YAML by default, but you can supply any datasource whose output can be converted into `ParserConfig`:
|
|
282
306
|
|
|
283
307
|
```python
|
|
284
308
|
from sigil import run_from_config
|
|
309
|
+
from pathlib import Path
|
|
285
310
|
|
|
286
311
|
# Use JSON instead:
|
|
287
312
|
class JsonReader:
|
|
288
|
-
|
|
289
|
-
def read_manifest(cls, config_root: Path, target: str) -> list | None:
|
|
313
|
+
def read_manifest(self, root_path: Path, target: str) -> list | None:
|
|
290
314
|
# read target paths for loading configuration
|
|
291
315
|
...
|
|
292
316
|
|
|
293
|
-
def read_configuration(
|
|
317
|
+
def read_configuration(self, root_path: Path, target: str) -> dict | None:
|
|
294
318
|
# read *.json, parse, convert to dict of raw data
|
|
295
319
|
...
|
|
296
320
|
|
|
@@ -301,5 +325,6 @@ run_from_config("/path/to/config", datasource=JsonReader)
|
|
|
301
325
|
You can also pass a pre‑loaded dictionary directly by wrapping it:
|
|
302
326
|
|
|
303
327
|
```python
|
|
328
|
+
# exact dictreader implementation deliberately omitted
|
|
304
329
|
run_from_config(my_dict, datasource=DictReader)
|
|
305
330
|
```
|
|
@@ -25,17 +25,25 @@ It plays nicely with `argcomplete` out of the box.
|
|
|
25
25
|
- Declarative command hierarchies (parents, subparsers, defaults)
|
|
26
26
|
- Each command can point to a dynamically imported Python script
|
|
27
27
|
- `argcomplete` integration for tab‑completion
|
|
28
|
-
- Pluggable data sources
|
|
28
|
+
- Pluggable data sources - YAML is the default, but JSON, a dict or custom datasource are trivial to swap in
|
|
29
29
|
- No boilerplate argparse code in your main logic
|
|
30
30
|
|
|
31
31
|
## The alternatives
|
|
32
32
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
33
|
+
[Click](https://click.palletsprojects.com/) and [Typer](https://typer.tiangolo.com/) define commands in Python
|
|
34
|
+
(decorators, type hints). Sigil
|
|
35
|
+
defines the command tree as data (YAML by default; JSON or a dict work
|
|
36
|
+
too, or whatever datasource you decide to wire up), and each command points to a script module loaded by name.
|
|
36
37
|
|
|
37
|
-
Sigil
|
|
38
|
-
|
|
38
|
+
**Consider Sigil when** you have many subcommands, the tree changes more
|
|
39
|
+
often than the logic, you want it generated or merged from several files
|
|
40
|
+
or you want to stay on the standard library's argparse without the boilerplate.
|
|
41
|
+
Arguments map 1:1 to argparse `add_argument` kwargs, so there's no new API
|
|
42
|
+
to learn, and `sigil validate` / `sigil tree` help you check the config.
|
|
43
|
+
|
|
44
|
+
**Stick with Click or Typer when** you have a small app, want type-hint
|
|
45
|
+
driven arguments (`type:` here only supports Python builtins), or need their
|
|
46
|
+
ecosystem and plugins.
|
|
39
47
|
|
|
40
48
|
## Quick Start
|
|
41
49
|
|
|
@@ -56,7 +64,7 @@ cd demo
|
|
|
56
64
|
python main.py --help
|
|
57
65
|
```
|
|
58
66
|
|
|
59
|
-
For a full walkthrough with custom commands and arguments,
|
|
67
|
+
For a full walkthrough with custom commands and arguments, see steps 0-4 below.
|
|
60
68
|
|
|
61
69
|
### 0. Recommended file structure
|
|
62
70
|
|
|
@@ -73,7 +81,9 @@ project_root/
|
|
|
73
81
|
└── ... # other scripts
|
|
74
82
|
```
|
|
75
83
|
|
|
76
|
-
|
|
84
|
+
> [!Important]
|
|
85
|
+
> Don't shoot yourself in the foot, don't symlink the bootstrap script.
|
|
86
|
+
> if using a venv remember to use/alias the right python runtime
|
|
77
87
|
|
|
78
88
|
### 1. Entry script
|
|
79
89
|
|
|
@@ -158,6 +168,9 @@ chmod +x mycli.py
|
|
|
158
168
|
| `name` | Program name (used as `prog` in argparse) |
|
|
159
169
|
| `script_dir` | Directory (relative to the config root) where command scripts are located |
|
|
160
170
|
|
|
171
|
+
> [!NOTE]
|
|
172
|
+
> this section contains only sigil-specific configurations, other argparse arguments still apply
|
|
173
|
+
|
|
161
174
|
### Command
|
|
162
175
|
|
|
163
176
|
| Field | Description |
|
|
@@ -169,14 +182,20 @@ chmod +x mycli.py
|
|
|
169
182
|
| `args` | List of argument definitions (see below) |
|
|
170
183
|
| `default` | If `True`, this subcommand is used when no subcommand is given |
|
|
171
184
|
| `load` | If `False` skips this command (or top level object) from being loaded into the command tree (default `True`) |
|
|
185
|
+
| `requirements` | (Optional) List of pip requirements that this subcommand requires. |
|
|
172
186
|
| any other parser kwarg | except for `dest`, `parents` and `formatter_class` they are all supported |
|
|
173
187
|
|
|
174
|
-
|
|
175
|
-
|
|
188
|
+
> [!NOTE]
|
|
189
|
+
> this section contains only sigil-specific configurations, other argparse arguments still apply
|
|
190
|
+
<!---->
|
|
191
|
+
> [!IMPORTANT]
|
|
192
|
+
> `parent` does not refer to argparse's `parents` parameter but is only used to resolve the parser tree.
|
|
193
|
+
> Parser (multi-)inheritance isn't supported but can be (rougly) emulated by
|
|
194
|
+
> adding arguments to `parent` commands in the tree.
|
|
176
195
|
|
|
177
196
|
### Argument
|
|
178
197
|
|
|
179
|
-
Each argument entry can be a plain dict which maps 1-to-1 with argparse `add_argument`, except name which maps
|
|
198
|
+
Each argument entry can be a plain dict which maps 1-to-1 with argparse `add_argument`, except name which maps its `*args`
|
|
180
199
|
|
|
181
200
|
```yaml
|
|
182
201
|
- name: ["-p", "--port"] # or a single string, e.g. "positional"
|
|
@@ -185,7 +204,7 @@ Each argument entry can be a plain dict which maps 1-to-1 with argparse `add_arg
|
|
|
185
204
|
help: "port number"
|
|
186
205
|
```
|
|
187
206
|
|
|
188
|
-
Groups and mutex groups are also
|
|
207
|
+
Groups and mutex groups are also supported via the "kind" parameter (defaults to `argument`)
|
|
189
208
|
|
|
190
209
|
```yaml
|
|
191
210
|
# mutex group
|
|
@@ -202,17 +221,16 @@ Groups and mutex groups are also suppored via the "kind" parameter (defaults to
|
|
|
202
221
|
The `name` field can be `--flag` for flags or a string for positional arguments.
|
|
203
222
|
Both literal string and list of strings are supported.
|
|
204
223
|
|
|
205
|
-
Types (`type:`) only
|
|
224
|
+
Types (`type:`) only support Python builtins
|
|
206
225
|
|
|
207
226
|
### Script files
|
|
208
227
|
|
|
209
|
-
Each script
|
|
210
|
-
`def run(args: argparse.Namespace, ctx: dict[str, Any]) -> None` method.
|
|
228
|
+
Each script file must define a `def run(args: argparse.Namespace, ctx: dict[str, Any]) -> None` method.
|
|
211
229
|
|
|
212
|
-
|
|
230
|
+
Args is the namespace supplied by argparse (parsed with parse_known_args). Any additional args can be found in `ctx['other_args']`.
|
|
213
231
|
|
|
214
|
-
|
|
215
|
-
remove or otherwise modify args
|
|
232
|
+
Scripts run in sequence from command -> subcommand -> sub sub command -> ... and each may add to,
|
|
233
|
+
remove or otherwise modify `args` and `ctx` to enrich or modify the behaviour of subsequent scripts.
|
|
216
234
|
|
|
217
235
|
## Sigil CLI Commands
|
|
218
236
|
|
|
@@ -221,16 +239,18 @@ remove or otherwise modify args.namespace and ctx to enrich or modify the behavi
|
|
|
221
239
|
| Command | Purpose |
|
|
222
240
|
| --- | --- |
|
|
223
241
|
| `sigil init [project_name]` | Creates a new project folder with a sample ready-to-run Python entrypoint. |
|
|
224
|
-
| `sigil validate [project_path]` | Checks your sigil definition for schema errors and missing references. Run this after heavy edits to catch mistakes early. |
|
|
225
|
-
| `sigil tree [project_path]` | Print the command structure of a sigil. |
|
|
242
|
+
| `sigil validate [project_path, default '.']` | Checks your sigil definition for schema errors and missing references. Run this after heavy edits to catch mistakes early. |
|
|
243
|
+
| `sigil tree [project_path, default '.']` | Print the command structure of a sigil. |
|
|
244
|
+
| `sigil requirements [project_path, default '.']` | Generate a requirements.txt file from active subcommands in the sigil. |
|
|
226
245
|
|
|
227
|
-
|
|
228
|
-
|
|
246
|
+
> [!NOTE]
|
|
247
|
+
> Your generated CLI (the one you build with Sigil) is completely separate from the `sigil` management
|
|
248
|
+
> commands above. You alias and run `main.py`. The `sigil` prefix is a different namespace.
|
|
229
249
|
|
|
230
250
|
### Misc
|
|
231
251
|
|
|
232
|
-
`
|
|
233
|
-
(deprecation, development, etc) or for non schema-compliant objects at the top level of a file
|
|
252
|
+
`load: False` may be used to detach commands from the command tree for any purpose
|
|
253
|
+
(deprecation, development, etc) or for non schema-compliant objects at the top level of a file. This may be useful to
|
|
234
254
|
define anchors or references that should not directly be read as a command.
|
|
235
255
|
|
|
236
256
|
## Tab‑Completion (argcomplete)
|
|
@@ -244,23 +264,23 @@ pip install argcomplete
|
|
|
244
264
|
activate-global-python-argcomplete
|
|
245
265
|
```
|
|
246
266
|
|
|
247
|
-
Then run your script and hit <kbd>Tab</kbd>
|
|
267
|
+
Then run your script and hit <kbd>Tab</kbd> - subcommands and flags will complete.
|
|
248
268
|
|
|
249
269
|
## Pluggable Backends
|
|
250
270
|
|
|
251
|
-
Sigil uses
|
|
271
|
+
Sigil uses YAML by default, but you can supply any datasource whose output can be converted into `ParserConfig`:
|
|
252
272
|
|
|
253
273
|
```python
|
|
254
274
|
from sigil import run_from_config
|
|
275
|
+
from pathlib import Path
|
|
255
276
|
|
|
256
277
|
# Use JSON instead:
|
|
257
278
|
class JsonReader:
|
|
258
|
-
|
|
259
|
-
def read_manifest(cls, config_root: Path, target: str) -> list | None:
|
|
279
|
+
def read_manifest(self, root_path: Path, target: str) -> list | None:
|
|
260
280
|
# read target paths for loading configuration
|
|
261
281
|
...
|
|
262
282
|
|
|
263
|
-
def read_configuration(
|
|
283
|
+
def read_configuration(self, root_path: Path, target: str) -> dict | None:
|
|
264
284
|
# read *.json, parse, convert to dict of raw data
|
|
265
285
|
...
|
|
266
286
|
|
|
@@ -271,5 +291,6 @@ run_from_config("/path/to/config", datasource=JsonReader)
|
|
|
271
291
|
You can also pass a pre‑loaded dictionary directly by wrapping it:
|
|
272
292
|
|
|
273
293
|
```python
|
|
294
|
+
# exact dictreader implementation deliberately omitted
|
|
274
295
|
run_from_config(my_dict, datasource=DictReader)
|
|
275
296
|
```
|
|
@@ -4,22 +4,26 @@ build-backend = "setuptools.build_meta"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "sigil-cli"
|
|
7
|
-
version = "1.5.
|
|
7
|
+
version = "1.5.4"
|
|
8
8
|
description = "Configuration driven CLI builder with subcommands and script loading"
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
requires-python = ">=3.10"
|
|
11
11
|
license = {text = "MIT"}
|
|
12
12
|
authors = [{name = "Kenzo Staelens", email = "kenzostael@gmail.com"}]
|
|
13
13
|
classifiers = [
|
|
14
|
+
"Development Status :: 5 - Production/Stable",
|
|
15
|
+
"License :: OSI Approved :: MIT License",
|
|
14
16
|
"Programming Language :: Python :: 3",
|
|
15
17
|
"Programming Language :: Python :: 3.10",
|
|
16
18
|
"Programming Language :: Python :: 3.11",
|
|
17
19
|
"Programming Language :: Python :: 3.12",
|
|
18
20
|
"Programming Language :: Python :: 3.13",
|
|
19
21
|
"Programming Language :: Python :: 3.14",
|
|
20
|
-
"Topic :: Software Development :: User Interfaces",
|
|
21
|
-
"License :: OSI Approved :: MIT License",
|
|
22
22
|
"Operating System :: OS Independent",
|
|
23
|
+
'Environment :: Console',
|
|
24
|
+
"Intended Audience :: Developers",
|
|
25
|
+
"Intended Audience :: System Administrators",
|
|
26
|
+
"Typing :: Typed",
|
|
23
27
|
]
|
|
24
28
|
dependencies = [
|
|
25
29
|
"pyyaml>=6.0",
|
|
@@ -5,8 +5,13 @@ __version__ = version('sigil-cli')
|
|
|
5
5
|
from .datasource import (
|
|
6
6
|
DataSource,
|
|
7
7
|
JSONSource,
|
|
8
|
-
YmlSource,
|
|
9
8
|
)
|
|
9
|
+
|
|
10
|
+
try:
|
|
11
|
+
from .datasource import YmlSource # noqa: F401
|
|
12
|
+
yml_ok = True
|
|
13
|
+
except ImportError:
|
|
14
|
+
yml_ok = False
|
|
10
15
|
from .entrypoint import run_from_config
|
|
11
16
|
from .models import (
|
|
12
17
|
Argument,
|
|
@@ -26,7 +31,7 @@ from .stages import (
|
|
|
26
31
|
ScriptLoader,
|
|
27
32
|
)
|
|
28
33
|
|
|
29
|
-
__all__ =
|
|
34
|
+
__all__ = [
|
|
30
35
|
'run_from_config',
|
|
31
36
|
'Argument',
|
|
32
37
|
'ArgumentGroup',
|
|
@@ -39,7 +44,9 @@ __all__ = (
|
|
|
39
44
|
'ScriptLoader',
|
|
40
45
|
'DataSource',
|
|
41
46
|
'JSONSource',
|
|
42
|
-
'YmlSource',
|
|
43
47
|
'FilesystemScriptSource',
|
|
44
48
|
'ScriptSource',
|
|
45
|
-
|
|
49
|
+
]
|
|
50
|
+
|
|
51
|
+
if yml_ok:
|
|
52
|
+
__all__.append('YmlSource')
|
|
@@ -2,11 +2,18 @@ import argparse
|
|
|
2
2
|
|
|
3
3
|
from sigil import __version__
|
|
4
4
|
from sigil.cli_tools.util import COMMAND_REGISTRY, REGISTER_CALLABLES
|
|
5
|
+
from sigil.datasource import REAL_SOURCES
|
|
5
6
|
|
|
6
7
|
|
|
7
8
|
def main():
|
|
8
9
|
parser = argparse.ArgumentParser(prog='sigil')
|
|
9
10
|
parser.add_argument('--version', action='version', version=f'Sigil {__version__}')
|
|
11
|
+
parser.add_argument(
|
|
12
|
+
'--datasource',
|
|
13
|
+
default='YmlSource' if 'YmlSource' in REAL_SOURCES else 'JSONSource',
|
|
14
|
+
choices=REAL_SOURCES.keys(),
|
|
15
|
+
help='datasource for sigil tools, default to YmlSource or JSONSource'
|
|
16
|
+
)
|
|
10
17
|
sub = parser.add_subparsers(title="subcommands", dest='command')
|
|
11
18
|
for fn in REGISTER_CALLABLES:
|
|
12
19
|
fn(sub)
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# lives here to trigger registration logic without manual imports for module discovery
|
|
2
|
+
|
|
3
|
+
# Source - modified from https://stackoverflow.com/a/1057534
|
|
4
|
+
|
|
5
|
+
import glob
|
|
6
|
+
from os.path import basename, dirname, isfile, join
|
|
7
|
+
|
|
8
|
+
modules = glob.glob(join(dirname(__file__), "*.py"))
|
|
9
|
+
|
|
10
|
+
__all__ = []
|
|
11
|
+
for mod in modules:
|
|
12
|
+
if not isfile(mod):
|
|
13
|
+
continue
|
|
14
|
+
if mod.endswith('__init__.py'):
|
|
15
|
+
continue
|
|
16
|
+
with open(mod) as f:
|
|
17
|
+
if '# CLI_NO_IMPORT' in f.read():
|
|
18
|
+
continue
|
|
19
|
+
base = basename(mod)[:-3]
|
|
20
|
+
imported = __import__(f'{__name__}.{base}', globals(), locals())
|
|
21
|
+
__all__.append(base)
|
|
22
|
+
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
|
|
2
|
+
import argparse
|
|
3
|
+
import os
|
|
4
|
+
|
|
5
|
+
from sigil import Parser
|
|
6
|
+
|
|
7
|
+
from .util import get_datasource, registers
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def resolve_requirements(projectroot, datasource_name='YmlSource'):
|
|
11
|
+
datasource = get_datasource(datasource_name)
|
|
12
|
+
raw = Parser(datasource).load(projectroot)
|
|
13
|
+
reqs_list = []
|
|
14
|
+
for key, parsed_data in raw.items():
|
|
15
|
+
if not parsed_data.load:
|
|
16
|
+
continue # not loaded -> skip
|
|
17
|
+
if not parsed_data.requirements:
|
|
18
|
+
continue # nothing of value
|
|
19
|
+
if not isinstance(parsed_data.requirements, list):
|
|
20
|
+
print(
|
|
21
|
+
f'requirements for {parsed_data.name}[{key}]'
|
|
22
|
+
'not in list format, ignoring...'
|
|
23
|
+
)
|
|
24
|
+
continue # invalid format
|
|
25
|
+
reqs_list += ['',f'# {key}']
|
|
26
|
+
reqs_list += parsed_data.requirements
|
|
27
|
+
return '\n'.join(reqs_list).strip()
|
|
28
|
+
|
|
29
|
+
@registers('requirements', 'build requirements.txt from a sigil.')
|
|
30
|
+
def add_sigil_requirements(command: argparse.ArgumentParser):
|
|
31
|
+
command.add_argument(
|
|
32
|
+
'path',
|
|
33
|
+
help="target project, default '.'",
|
|
34
|
+
nargs='?',
|
|
35
|
+
default='.'
|
|
36
|
+
)
|
|
37
|
+
command.add_argument(
|
|
38
|
+
'--out',
|
|
39
|
+
'-o',
|
|
40
|
+
help="outfile",
|
|
41
|
+
default='requirements.txt',
|
|
42
|
+
)
|
|
43
|
+
def _(args: argparse.Namespace):
|
|
44
|
+
overwrite='y'
|
|
45
|
+
if os.path.exists(args.outfile):
|
|
46
|
+
overwrite = input(
|
|
47
|
+
f'{args.outfile} already exists, overwrite? [y/n]: ',
|
|
48
|
+
).lower()
|
|
49
|
+
if overwrite not in {'y', 'yes'}:
|
|
50
|
+
print('aborting')
|
|
51
|
+
return
|
|
52
|
+
reqs = resolve_requirements(args.path, args.datasource)
|
|
53
|
+
if not reqs:
|
|
54
|
+
print('no requirements detected, aborting.')
|
|
55
|
+
return
|
|
56
|
+
with open(args.outfile, 'w') as f:
|
|
57
|
+
f.write(reqs)
|
|
58
|
+
return _
|
|
@@ -1,9 +1,8 @@
|
|
|
1
1
|
import argparse
|
|
2
2
|
|
|
3
3
|
from sigil import Builder, Parser, Resolver
|
|
4
|
-
from sigil.datasource import YmlSource
|
|
5
4
|
|
|
6
|
-
from .util import registers
|
|
5
|
+
from .util import get_datasource, registers
|
|
7
6
|
|
|
8
7
|
|
|
9
8
|
# adapted from https://stackoverflow.com/questions/78166654/how-can-i-print-the-tree-structure-of-subparsers-of-an-argparse-parser-in-python/78246362#78246362
|
|
@@ -35,8 +34,9 @@ def parser_tree(
|
|
|
35
34
|
return out
|
|
36
35
|
|
|
37
36
|
|
|
38
|
-
def display_project(projectroot):
|
|
39
|
-
|
|
37
|
+
def display_project(projectroot, datasource_name='YmlSource'):
|
|
38
|
+
datasource = get_datasource(datasource_name)
|
|
39
|
+
raw = Parser(datasource).load(projectroot)
|
|
40
40
|
resolved = Resolver.resolve_inheritance(raw)
|
|
41
41
|
parser = Builder.build(resolved)
|
|
42
42
|
print(parser_tree(parser))
|
|
@@ -44,5 +44,10 @@ def display_project(projectroot):
|
|
|
44
44
|
|
|
45
45
|
@registers('tree', 'display the command structure of a sigil.')
|
|
46
46
|
def add_sigil_tree(command: argparse.ArgumentParser):
|
|
47
|
-
command.add_argument(
|
|
48
|
-
|
|
47
|
+
command.add_argument(
|
|
48
|
+
'path',
|
|
49
|
+
help="project to validate, default '.'",
|
|
50
|
+
nargs='?',
|
|
51
|
+
default='.',
|
|
52
|
+
)
|
|
53
|
+
return lambda args: display_project(args.path, args.datasource)
|
|
@@ -1,7 +1,11 @@
|
|
|
1
|
+
# CLI_NO_IMPORT
|
|
1
2
|
import argparse
|
|
2
3
|
import functools
|
|
4
|
+
import sys
|
|
3
5
|
from collections.abc import Callable
|
|
4
6
|
|
|
7
|
+
from sigil.datasource import DataSource
|
|
8
|
+
|
|
5
9
|
COMMAND_REGISTRY: 'dict[str, Callable[[argparse.Namespace]]]' = {}
|
|
6
10
|
REGISTER_CALLABLES = []
|
|
7
11
|
|
|
@@ -22,3 +26,11 @@ def registers(name: str, cmd_help: str):
|
|
|
22
26
|
REGISTER_CALLABLES.append(wrapper)
|
|
23
27
|
return wrapper
|
|
24
28
|
return decorator_fn
|
|
29
|
+
|
|
30
|
+
def get_datasource(name: str) -> type[DataSource]:
|
|
31
|
+
from sigil.datasource import REAL_SOURCES
|
|
32
|
+
if name not in REAL_SOURCES:
|
|
33
|
+
# if you somehow manage to get here
|
|
34
|
+
print(f'could not determine datasource {name}')
|
|
35
|
+
sys.exit()
|
|
36
|
+
return REAL_SOURCES.get(name)
|