sigil-cli 1.5.3__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.3/src/sigil_cli.egg-info → sigil_cli-1.5.4}/PKG-INFO +51 -30
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/README.md +50 -29
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/pyproject.toml +1 -1
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/__init__.py +11 -4
- {sigil_cli-1.5.3 → 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.3 → sigil_cli-1.5.4}/src/sigil/cli_tools/tree.py +11 -6
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/cli_tools/util.py +12 -0
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/cli_tools/validate.py +13 -8
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/datasource/__init__.py +11 -1
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/datasource/datasource.py +9 -0
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/datasource/yml_source.py +0 -1
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/entrypoint.py +12 -2
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/models/command.py +1 -0
- {sigil_cli-1.5.3 → sigil_cli-1.5.4/src/sigil_cli.egg-info}/PKG-INFO +51 -30
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil_cli.egg-info/SOURCES.txt +2 -0
- {sigil_cli-1.5.3 → 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.3/src/sigil/cli_tools/__init__.py +0 -9
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/LICENSE +0 -0
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/setup.cfg +0 -0
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/cli_tools/init.py +0 -0
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/datasource/helper.py +0 -0
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/datasource/json_source.py +0 -0
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/models/__init__.py +0 -0
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/models/argparser.py +0 -0
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/models/argument.py +0 -0
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/models/script.py +0 -0
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/script_sources/__init__.py +0 -0
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/script_sources/filesystem_script_source.py +0 -0
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/script_sources/script_source.py +0 -0
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/stages/__init__.py +0 -0
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/stages/builder.py +0 -0
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/stages/parser.py +0 -0
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/stages/resolver.py +0 -0
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/stages/script_loader.py +0 -0
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil_cli.egg-info/dependency_links.txt +0 -0
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil_cli.egg-info/entry_points.txt +0 -0
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil_cli.egg-info/requires.txt +0 -0
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil_cli.egg-info/top_level.txt +0 -0
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/tests/test_builder.py +0 -0
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/tests/test_cli_init.py +0 -0
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/tests/test_cli_tree.py +0 -0
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/tests/test_cli_validate.py +0 -0
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/tests/test_integration.py +0 -0
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/tests/test_reader.py +0 -0
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/tests/test_resolver.py +0 -0
- {sigil_cli-1.5.3 → sigil_cli-1.5.4}/tests/test_scriptloader.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
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
|
|
@@ -59,17 +59,25 @@ It plays nicely with `argcomplete` out of the box.
|
|
|
59
59
|
- Declarative command hierarchies (parents, subparsers, defaults)
|
|
60
60
|
- Each command can point to a dynamically imported Python script
|
|
61
61
|
- `argcomplete` integration for tab‑completion
|
|
62
|
-
- Pluggable data sources
|
|
62
|
+
- Pluggable data sources - YAML is the default, but JSON, a dict or custom datasource are trivial to swap in
|
|
63
63
|
- No boilerplate argparse code in your main logic
|
|
64
64
|
|
|
65
65
|
## The alternatives
|
|
66
66
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
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.
|
|
70
71
|
|
|
71
|
-
Sigil
|
|
72
|
-
|
|
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.
|
|
77
|
+
|
|
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.
|
|
73
81
|
|
|
74
82
|
## Quick Start
|
|
75
83
|
|
|
@@ -90,7 +98,7 @@ cd demo
|
|
|
90
98
|
python main.py --help
|
|
91
99
|
```
|
|
92
100
|
|
|
93
|
-
For a full walkthrough with custom commands and arguments,
|
|
101
|
+
For a full walkthrough with custom commands and arguments, see steps 0-4 below.
|
|
94
102
|
|
|
95
103
|
### 0. Recommended file structure
|
|
96
104
|
|
|
@@ -107,7 +115,9 @@ project_root/
|
|
|
107
115
|
└── ... # other scripts
|
|
108
116
|
```
|
|
109
117
|
|
|
110
|
-
|
|
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
|
|
111
121
|
|
|
112
122
|
### 1. Entry script
|
|
113
123
|
|
|
@@ -192,6 +202,9 @@ chmod +x mycli.py
|
|
|
192
202
|
| `name` | Program name (used as `prog` in argparse) |
|
|
193
203
|
| `script_dir` | Directory (relative to the config root) where command scripts are located |
|
|
194
204
|
|
|
205
|
+
> [!NOTE]
|
|
206
|
+
> this section contains only sigil-specific configurations, other argparse arguments still apply
|
|
207
|
+
|
|
195
208
|
### Command
|
|
196
209
|
|
|
197
210
|
| Field | Description |
|
|
@@ -203,14 +216,20 @@ chmod +x mycli.py
|
|
|
203
216
|
| `args` | List of argument definitions (see below) |
|
|
204
217
|
| `default` | If `True`, this subcommand is used when no subcommand is given |
|
|
205
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. |
|
|
206
220
|
| any other parser kwarg | except for `dest`, `parents` and `formatter_class` they are all supported |
|
|
207
221
|
|
|
208
|
-
|
|
209
|
-
|
|
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.
|
|
210
229
|
|
|
211
230
|
### Argument
|
|
212
231
|
|
|
213
|
-
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`
|
|
214
233
|
|
|
215
234
|
```yaml
|
|
216
235
|
- name: ["-p", "--port"] # or a single string, e.g. "positional"
|
|
@@ -219,7 +238,7 @@ Each argument entry can be a plain dict which maps 1-to-1 with argparse `add_arg
|
|
|
219
238
|
help: "port number"
|
|
220
239
|
```
|
|
221
240
|
|
|
222
|
-
Groups and mutex groups are also
|
|
241
|
+
Groups and mutex groups are also supported via the "kind" parameter (defaults to `argument`)
|
|
223
242
|
|
|
224
243
|
```yaml
|
|
225
244
|
# mutex group
|
|
@@ -236,17 +255,16 @@ Groups and mutex groups are also suppored via the "kind" parameter (defaults to
|
|
|
236
255
|
The `name` field can be `--flag` for flags or a string for positional arguments.
|
|
237
256
|
Both literal string and list of strings are supported.
|
|
238
257
|
|
|
239
|
-
Types (`type:`) only
|
|
258
|
+
Types (`type:`) only support Python builtins
|
|
240
259
|
|
|
241
260
|
### Script files
|
|
242
261
|
|
|
243
|
-
Each script
|
|
244
|
-
`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.
|
|
245
263
|
|
|
246
|
-
|
|
264
|
+
Args is the namespace supplied by argparse (parsed with parse_known_args). Any additional args can be found in `ctx['other_args']`.
|
|
247
265
|
|
|
248
|
-
|
|
249
|
-
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.
|
|
250
268
|
|
|
251
269
|
## Sigil CLI Commands
|
|
252
270
|
|
|
@@ -255,16 +273,18 @@ remove or otherwise modify args.namespace and ctx to enrich or modify the behavi
|
|
|
255
273
|
| Command | Purpose |
|
|
256
274
|
| --- | --- |
|
|
257
275
|
| `sigil init [project_name]` | Creates a new project folder with a sample ready-to-run Python entrypoint. |
|
|
258
|
-
| `sigil validate [project_path]` | Checks your sigil definition for schema errors and missing references. Run this after heavy edits to catch mistakes early. |
|
|
259
|
-
| `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. |
|
|
260
279
|
|
|
261
|
-
|
|
262
|
-
|
|
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.
|
|
263
283
|
|
|
264
284
|
### Misc
|
|
265
285
|
|
|
266
|
-
`load: False` may be used to
|
|
267
|
-
(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
|
|
268
288
|
define anchors or references that should not directly be read as a command.
|
|
269
289
|
|
|
270
290
|
## Tab‑Completion (argcomplete)
|
|
@@ -278,23 +298,23 @@ pip install argcomplete
|
|
|
278
298
|
activate-global-python-argcomplete
|
|
279
299
|
```
|
|
280
300
|
|
|
281
|
-
Then run your script and hit <kbd>Tab</kbd>
|
|
301
|
+
Then run your script and hit <kbd>Tab</kbd> - subcommands and flags will complete.
|
|
282
302
|
|
|
283
303
|
## Pluggable Backends
|
|
284
304
|
|
|
285
|
-
Sigil uses
|
|
305
|
+
Sigil uses YAML by default, but you can supply any datasource whose output can be converted into `ParserConfig`:
|
|
286
306
|
|
|
287
307
|
```python
|
|
288
308
|
from sigil import run_from_config
|
|
309
|
+
from pathlib import Path
|
|
289
310
|
|
|
290
311
|
# Use JSON instead:
|
|
291
312
|
class JsonReader:
|
|
292
|
-
|
|
293
|
-
def read_manifest(cls, config_root: Path, target: str) -> list | None:
|
|
313
|
+
def read_manifest(self, root_path: Path, target: str) -> list | None:
|
|
294
314
|
# read target paths for loading configuration
|
|
295
315
|
...
|
|
296
316
|
|
|
297
|
-
def read_configuration(
|
|
317
|
+
def read_configuration(self, root_path: Path, target: str) -> dict | None:
|
|
298
318
|
# read *.json, parse, convert to dict of raw data
|
|
299
319
|
...
|
|
300
320
|
|
|
@@ -305,5 +325,6 @@ run_from_config("/path/to/config", datasource=JsonReader)
|
|
|
305
325
|
You can also pass a pre‑loaded dictionary directly by wrapping it:
|
|
306
326
|
|
|
307
327
|
```python
|
|
328
|
+
# exact dictreader implementation deliberately omitted
|
|
308
329
|
run_from_config(my_dict, datasource=DictReader)
|
|
309
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
|
-
`load: False` may be used to
|
|
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
|
```
|
|
@@ -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)
|
|
@@ -5,9 +5,8 @@ import sys
|
|
|
5
5
|
from pathlib import Path
|
|
6
6
|
|
|
7
7
|
from sigil import Builder, Parser, Resolver
|
|
8
|
-
from sigil.datasource import YmlSource
|
|
9
8
|
|
|
10
|
-
from .util import registers
|
|
9
|
+
from .util import get_datasource, registers
|
|
11
10
|
|
|
12
11
|
|
|
13
12
|
# small helper to capture logs from in the guts of sigil
|
|
@@ -45,14 +44,15 @@ _logger = logging.getLogger(__name__)
|
|
|
45
44
|
|
|
46
45
|
|
|
47
46
|
# actual validation logging
|
|
48
|
-
def _validate_project(projectroot):
|
|
47
|
+
def _validate_project(projectroot, datasource_name='YmlSource'):
|
|
49
48
|
projectpath = Path(projectroot)
|
|
50
49
|
|
|
51
50
|
if not (projectpath/'manifest.yml').exists():
|
|
52
51
|
_logger.error('missing manifest.yml, aborting.')
|
|
53
52
|
sys.exit(1)
|
|
54
53
|
|
|
55
|
-
|
|
54
|
+
datasource = get_datasource(datasource_name)
|
|
55
|
+
raw = Parser(datasource).load(projectroot)
|
|
56
56
|
|
|
57
57
|
# these are easier for us to check
|
|
58
58
|
if 'root' not in raw:
|
|
@@ -86,11 +86,11 @@ def _validate_project(projectroot):
|
|
|
86
86
|
# exit code wrapper
|
|
87
87
|
# validation partially happens deep in the guts of sigil,
|
|
88
88
|
# this caputures all validation logs, counts and converts to exit code
|
|
89
|
-
def validate_project(projectroot):
|
|
89
|
+
def validate_project(projectroot, datasource_name='YmlSource'):
|
|
90
90
|
package_name = __name__.split('.', 1)[0]
|
|
91
91
|
with capture_package_warnings(package_name) as collector:
|
|
92
92
|
try:
|
|
93
|
-
_validate_project(projectroot)
|
|
93
|
+
_validate_project(projectroot, datasource_name)
|
|
94
94
|
except SystemExit: # special case to not hard exit
|
|
95
95
|
pass
|
|
96
96
|
|
|
@@ -122,5 +122,10 @@ def validate_project(projectroot):
|
|
|
122
122
|
|
|
123
123
|
@registers('validate', 'validate structure of a sigil')
|
|
124
124
|
def add_sigil_validate(command: argparse.ArgumentParser):
|
|
125
|
-
command.add_argument(
|
|
126
|
-
|
|
125
|
+
command.add_argument(
|
|
126
|
+
'path',
|
|
127
|
+
help="project to validate, default '.'",
|
|
128
|
+
nargs='?',
|
|
129
|
+
default='.',
|
|
130
|
+
)
|
|
131
|
+
return lambda args: validate_project(args.path, args.datasource)
|
|
@@ -6,10 +6,20 @@ __all__ = [
|
|
|
6
6
|
'JSONSource',
|
|
7
7
|
]
|
|
8
8
|
|
|
9
|
+
REAL_SOURCES = {
|
|
10
|
+
x: local_cls
|
|
11
|
+
for x in __all__
|
|
12
|
+
if (local_cls:=globals().get(x))
|
|
13
|
+
and issubclass(local_cls, DataSource)
|
|
14
|
+
and not local_cls.is_abstract()
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
|
|
9
18
|
try:
|
|
10
19
|
# preparation for PEP 771 or conversion to `pip install sigil-cli[yaml]` install
|
|
11
20
|
# any datasources with dependencies should import like this
|
|
12
21
|
from .yml_source import YmlSource # noqa: F401
|
|
13
|
-
|
|
22
|
+
REAL_SOURCES['YmlSource'] = YmlSource # known not abstract
|
|
23
|
+
__all__.insert(0, 'YmlSource')
|
|
14
24
|
except ImportError:
|
|
15
25
|
pass
|
|
@@ -18,3 +18,12 @@ class DataSource(ABC):
|
|
|
18
18
|
# datasources shouldn't need to validate
|
|
19
19
|
# for duplicates or malformed data
|
|
20
20
|
...
|
|
21
|
+
|
|
22
|
+
@classmethod
|
|
23
|
+
def is_abstract(cls):
|
|
24
|
+
if not hasattr(cls, "__abstractmethods__"):
|
|
25
|
+
return False # an ordinary class
|
|
26
|
+
elif len(cls.__abstractmethods__) == 0:
|
|
27
|
+
return False # a concrete implementation of an abstract class
|
|
28
|
+
else:
|
|
29
|
+
return True # an abstract class
|