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.
Files changed (49) hide show
  1. {sigil_cli-1.5.2/src/sigil_cli.egg-info → sigil_cli-1.5.4}/PKG-INFO +57 -32
  2. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/README.md +50 -29
  3. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/pyproject.toml +7 -3
  4. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/__init__.py +11 -4
  5. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/__main__.py +7 -0
  6. sigil_cli-1.5.4/src/sigil/cli_tools/__init__.py +22 -0
  7. sigil_cli-1.5.4/src/sigil/cli_tools/requirements.py +58 -0
  8. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/cli_tools/tree.py +11 -6
  9. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/cli_tools/util.py +12 -0
  10. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/cli_tools/validate.py +13 -8
  11. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/datasource/__init__.py +11 -1
  12. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/datasource/datasource.py +9 -0
  13. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/datasource/yml_source.py +0 -1
  14. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/entrypoint.py +12 -2
  15. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/models/argparser.py +7 -1
  16. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/models/command.py +1 -0
  17. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/stages/parser.py +59 -8
  18. {sigil_cli-1.5.2 → sigil_cli-1.5.4/src/sigil_cli.egg-info}/PKG-INFO +57 -32
  19. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil_cli.egg-info/SOURCES.txt +2 -0
  20. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/tests/test_cli_util.py +1 -1
  21. sigil_cli-1.5.4/tests/test_requirements.py +256 -0
  22. sigil_cli-1.5.2/src/sigil/cli_tools/__init__.py +0 -9
  23. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/LICENSE +0 -0
  24. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/setup.cfg +0 -0
  25. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/cli_tools/init.py +0 -0
  26. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/datasource/helper.py +0 -0
  27. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/datasource/json_source.py +0 -0
  28. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/models/__init__.py +0 -0
  29. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/models/argument.py +0 -0
  30. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/models/script.py +0 -0
  31. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/script_sources/__init__.py +0 -0
  32. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/script_sources/filesystem_script_source.py +0 -0
  33. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/script_sources/script_source.py +0 -0
  34. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/stages/__init__.py +0 -0
  35. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/stages/builder.py +0 -0
  36. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/stages/resolver.py +0 -0
  37. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil/stages/script_loader.py +0 -0
  38. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil_cli.egg-info/dependency_links.txt +0 -0
  39. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil_cli.egg-info/entry_points.txt +0 -0
  40. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil_cli.egg-info/requires.txt +0 -0
  41. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/src/sigil_cli.egg-info/top_level.txt +0 -0
  42. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/tests/test_builder.py +0 -0
  43. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/tests/test_cli_init.py +0 -0
  44. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/tests/test_cli_tree.py +0 -0
  45. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/tests/test_cli_validate.py +0 -0
  46. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/tests/test_integration.py +0 -0
  47. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/tests/test_reader.py +0 -0
  48. {sigil_cli-1.5.2 → sigil_cli-1.5.4}/tests/test_resolver.py +0 -0
  49. {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.2
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 – YAML is the default, but JSON, TOML, or a dict are trivial to swap in
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
- There are plenty of established options out there. [Click](https://click.palletsprojects.com/)
64
- and [Typer](https://typer.tiangolo.com/) are great libraries with their own
65
- approaches.
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
- Sigil takes a different path, focusing on reducing boilerplate while keeping
68
- your command structure modular and flexible.
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, jump to the Quick Start below.
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
- ps: don't shoot yourself in the foot, don't symlink the bootstrap script.
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
- Note that `parent` does not refer to argparse's `parents` parameter but is only used to resolve the parser tree.
205
- Parser (multi-)inheritance isn't supported but can be emulated by adding arguments to `parent` commands in the tree.
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 it's `*args`
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 suppored via the "kind" parameter (defaults to `argument`)
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 supports python builtins
258
+ Types (`type:`) only support Python builtins
236
259
 
237
260
  ### Script files
238
261
 
239
- Each script files have as only requirement that they need to define a
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
- args is the by argparse supplied namespace (parsed with parse_known_args), any additional args can be found in `ctx['other_args']`
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
- scripts run in sequence from command -> subcommand -> sub sub command -> ... and each may add to,
245
- remove or otherwise modify args.namespace and ctx to enrich or modify the behaviour of supsequent scripts.
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
- *(Note: Your generated CLI (the one you build with Sigil) is completely separate from the `sigil` management
258
- commands above. You alias and run `main.py`. the `sigil` prefix is a different namespace.)*
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
- `load_ignore` may be used to detaching commands from the command tree for any purpose
263
- (deprecation, development, etc) or for non schema-compliant objects at the top level of a file, this may be useful to
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> – subcommands and flags will complete.
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 yaml by default, but you can supply any datasource that we can convert it's output into `ParserConfig`:
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
- @classmethod
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(cls, target: Path, target: str) -> dict | None:
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 – YAML is the default, but JSON, TOML, or a dict are trivial to swap in
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
- There are plenty of established options out there. [Click](https://click.palletsprojects.com/)
34
- and [Typer](https://typer.tiangolo.com/) are great libraries with their own
35
- approaches.
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 takes a different path, focusing on reducing boilerplate while keeping
38
- your command structure modular and flexible.
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, jump to the Quick Start below.
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
- ps: don't shoot yourself in the foot, don't symlink the bootstrap script.
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
- Note that `parent` does not refer to argparse's `parents` parameter but is only used to resolve the parser tree.
175
- Parser (multi-)inheritance isn't supported but can be emulated by adding arguments to `parent` commands in the tree.
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 it's `*args`
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 suppored via the "kind" parameter (defaults to `argument`)
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 supports python builtins
224
+ Types (`type:`) only support Python builtins
206
225
 
207
226
  ### Script files
208
227
 
209
- Each script files have as only requirement that they need to define a
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
- args is the by argparse supplied namespace (parsed with parse_known_args), any additional args can be found in `ctx['other_args']`
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
- scripts run in sequence from command -> subcommand -> sub sub command -> ... and each may add to,
215
- remove or otherwise modify args.namespace and ctx to enrich or modify the behaviour of supsequent scripts.
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
- *(Note: Your generated CLI (the one you build with Sigil) is completely separate from the `sigil` management
228
- commands above. You alias and run `main.py`. the `sigil` prefix is a different namespace.)*
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_ignore` may be used to detaching commands from the command tree for any purpose
233
- (deprecation, development, etc) or for non schema-compliant objects at the top level of a file, this may be useful to
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> – subcommands and flags will complete.
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 yaml by default, but you can supply any datasource that we can convert it's output into `ParserConfig`:
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
- @classmethod
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(cls, target: Path, target: str) -> dict | None:
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.2"
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
- raw = Parser(YmlSource).load(projectroot)
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('path', help="project to validate")
48
- return lambda args: display_project(args.path)
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)