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.
Files changed (49) hide show
  1. {sigil_cli-1.5.3/src/sigil_cli.egg-info → sigil_cli-1.5.4}/PKG-INFO +51 -30
  2. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/README.md +50 -29
  3. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/pyproject.toml +1 -1
  4. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/__init__.py +11 -4
  5. {sigil_cli-1.5.3 → 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.3 → sigil_cli-1.5.4}/src/sigil/cli_tools/tree.py +11 -6
  9. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/cli_tools/util.py +12 -0
  10. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/cli_tools/validate.py +13 -8
  11. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/datasource/__init__.py +11 -1
  12. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/datasource/datasource.py +9 -0
  13. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/datasource/yml_source.py +0 -1
  14. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/entrypoint.py +12 -2
  15. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/models/command.py +1 -0
  16. {sigil_cli-1.5.3 → sigil_cli-1.5.4/src/sigil_cli.egg-info}/PKG-INFO +51 -30
  17. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil_cli.egg-info/SOURCES.txt +2 -0
  18. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/tests/test_cli_util.py +1 -1
  19. sigil_cli-1.5.4/tests/test_requirements.py +256 -0
  20. sigil_cli-1.5.3/src/sigil/cli_tools/__init__.py +0 -9
  21. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/LICENSE +0 -0
  22. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/setup.cfg +0 -0
  23. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/cli_tools/init.py +0 -0
  24. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/datasource/helper.py +0 -0
  25. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/datasource/json_source.py +0 -0
  26. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/models/__init__.py +0 -0
  27. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/models/argparser.py +0 -0
  28. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/models/argument.py +0 -0
  29. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/models/script.py +0 -0
  30. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/script_sources/__init__.py +0 -0
  31. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/script_sources/filesystem_script_source.py +0 -0
  32. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/script_sources/script_source.py +0 -0
  33. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/stages/__init__.py +0 -0
  34. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/stages/builder.py +0 -0
  35. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/stages/parser.py +0 -0
  36. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/stages/resolver.py +0 -0
  37. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil/stages/script_loader.py +0 -0
  38. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil_cli.egg-info/dependency_links.txt +0 -0
  39. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil_cli.egg-info/entry_points.txt +0 -0
  40. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil_cli.egg-info/requires.txt +0 -0
  41. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/src/sigil_cli.egg-info/top_level.txt +0 -0
  42. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/tests/test_builder.py +0 -0
  43. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/tests/test_cli_init.py +0 -0
  44. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/tests/test_cli_tree.py +0 -0
  45. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/tests/test_cli_validate.py +0 -0
  46. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/tests/test_integration.py +0 -0
  47. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/tests/test_reader.py +0 -0
  48. {sigil_cli-1.5.3 → sigil_cli-1.5.4}/tests/test_resolver.py +0 -0
  49. {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
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 – 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
63
63
  - No boilerplate argparse code in your main logic
64
64
 
65
65
  ## The alternatives
66
66
 
67
- There are plenty of established options out there. [Click](https://click.palletsprojects.com/)
68
- and [Typer](https://typer.tiangolo.com/) are great libraries with their own
69
- 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.
70
71
 
71
- Sigil takes a different path, focusing on reducing boilerplate while keeping
72
- your command structure modular and flexible.
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, jump to the Quick Start below.
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
- 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
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
- Note that `parent` does not refer to argparse's `parents` parameter but is only used to resolve the parser tree.
209
- 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.
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 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`
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 suppored via the "kind" parameter (defaults to `argument`)
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 supports python builtins
258
+ Types (`type:`) only support Python builtins
240
259
 
241
260
  ### Script files
242
261
 
243
- Each script files have as only requirement that they need to define a
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
- 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']`.
247
265
 
248
- scripts run in sequence from command -> subcommand -> sub sub command -> ... and each may add to,
249
- 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.
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
- *(Note: Your generated CLI (the one you build with Sigil) is completely separate from the `sigil` management
262
- 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.
263
283
 
264
284
  ### Misc
265
285
 
266
- `load: False` may be used to detaching commands from the command tree for any purpose
267
- (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
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> – subcommands and flags will complete.
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 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`:
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
- @classmethod
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(cls, target: Path, target: str) -> dict | None:
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 – 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: False` 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,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "sigil-cli"
7
- version = "1.5.3"
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"
@@ -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)
@@ -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
- raw = Parser(YmlSource).load(projectroot)
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('path', help="project to validate")
126
- return lambda args: validate_project(args.path)
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
- __all__.append('YmlSource')
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