sigil-cli 0.1.0__tar.gz

sigil_cli-0.1.0/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Kenzo Staelens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sigil_cli-0.1.0/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: sigil-cli
+Version: 0.1.0
+Summary: Configuration driven CLI builder with subcommands and script loading
+Author-email: Kenzo Staelens <kenzostael@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/yourusername/sigil
+Project-URL: Repository, https://github.com/yourusername/sigil
+Project-URL: Issues, https://github.com/yourusername/sigil/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: completion
+Requires-Dist: argcomplete>=3.0; extra == "completion"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# Sigil
+
+> Declarative argparse, without the CLI boilerplate.
+
+Sigil is a lightweight, declarative CLI framework for Python. Define your command tree in YAML (or any other format), and sigil builds the `argparse` parser on the fly. Complete with subcommands and dynamic script loading.  
+It plays nicely with `argcomplete` out of the box.
+
+---
+
+## Features
+
+- Declarative command hierarchies (parents, subparsers, defaults)
+- Each command can point to a dynamically imported Python script
+- `argcomplete` integration for tab‑completion
+- Pluggable data sources – YAML is the default, but JSON, TOML, or a dict are trivial to swap in
+- No boilerplate argparse code in your main logic
+
+## Quick Start
+
+### Install
+
+```bash
+pip install sigil-cli
+```
+
+or include argcomplete
+
+```bash
+pip install sigil-cli[completion]
+```
+
+### 0. Recommended file structure
+
+```text
+project_root/
+├── mycli.py              # drop‑in entry script (alias this)
+├── manifest.yml          # lists all YAML config files to load
+├── yml/                  
+│   ├── root.yml          # root command definition
+│   ├── root_run.yml      # subcommand definition(s)
+│   └── ...               
+└── scripts/              
+    ├── run.py            # implements the 'run' command
+    └── ...               # other scripts
+```
+
+### 1. Entry script
+
+Create `mycli.py`:
+
+```python
+#!/usr/bin/env python3
+from pathlib import Path
+from sigil import run_from_config
+
+if __name__ == "__main__":
+    run_from_config(Path(__file__).parent)
+```
+
+### 2. Configuration files
+
+List all your YAML definitions in `manifest.yml`:
+
+```yaml
+---
+- root.yml
+- root_run.yml
+```
+
+Define the root command in `root.yml`:
+
+```yaml
+root:
+  name: mycli
+  script_dir: scripts
+```
+
+Define a subcommand in `root_run.yml`:
+
+```yaml
+root_run:
+  name: run
+  parent: root
+  help: command utility to run containers
+  script: run
+  args:
+    - help: port to run, autoincrements from 8080
+      name:
+        - -p
+        - --port
+```
+
+### 3. Write the script
+
+Create `scripts/run.py`:
+
+```python
+import argparse
+from typing import Any
+
+def run(args: argparse.Namespace, ctx: dict[str, Any]) -> None:
+    port = getattr(args, "port", 8080)
+    port = find_next_free_port_logic(port)
+    print(f"Running container on port {port}")
+```
+
+### 4. Run it
+
+```bash
+chmod +x mycli.py
+./mycli.py run --port 9000
+# Running container on port 9000
+
+./mycli.py run
+# Running container on port 8080
+
+./mycli.py run
+# Running container on port 8081
+```
+
+## Configuration Reference
+
+### Root
+
+| Field | Description |
+| --- | --- |
+| `name` | Program name (used as `prog` in argparse) |
+| `script_dir` | Directory (relative to the config root) where command scripts are located |
+
+### Command
+
+| Field | Description |
+| --- | --- |
+| `name` | Subcommand name |
+| `parent` | Parent command (must exist elsewhere in a config) |
+| `help` | Help text for this subcommand |
+| `script` | Python module name (without `.py`) inside `script_dir` or as absolute path |
+| `args` | List of argument definitions (see below) |
+| `default` | If `true`, this subcommand is used when no subcommand is given |
+
+### Argument
+
+Each argument entry can be a plain dict which maps 1-to-1 with argparse `add_argument`, except name which maps it's `*args`
+
+```yaml
+- name: ["-p", "--port"]   # or a single string, e.g. "positional"
+  required: false
+  default: 8069
+  help: "port number"
+```
+
+The `name` field can be `--flag` for flags or a string for positional arguments.
+Both literal string and list of strings are supported.
+
+## Tab‑Completion (argcomplete)
+
+Argus registers itself with `argcomplete` automatically if available on your system.  
+To enable completion, install [argcomplete](https://github.com/kislyuk/argcomplete) and activate it for your entry script:
+
+```bash
+pip install argcomplete
+activate-global-python-argcomplete
+```
+
+Then run your script and hit <kbd>Tab</kbd> – subcommands and flags will complete.
+
+## Pluggable Backends
+
+Sigil uses yaml by default, but you can supply any loader that returns a `dict[str, ParserConfig]`:
+
+```python
+from sigil import run_from_config
+
+# Use JSON instead:
+class JsonReader:
+    @classmethod
+    def load(cls, config_root):
+        # read *.json, parse, convert to dict of ParserConfig
+        ...
+
+run_from_config("/path/to/config", loader_class=JsonReader)
+```
+
+You can also pass a pre‑loaded dictionary directly by wrapping it:
+
+```python
+run_from_config(my_dict, loader_class=DictLoader)
+```

sigil_cli-0.1.0/README.md

@@ -0,0 +1,188 @@
+# Sigil
+
+> Declarative argparse, without the CLI boilerplate.
+
+Sigil is a lightweight, declarative CLI framework for Python. Define your command tree in YAML (or any other format), and sigil builds the `argparse` parser on the fly. Complete with subcommands and dynamic script loading.  
+It plays nicely with `argcomplete` out of the box.
+
+---
+
+## Features
+
+- Declarative command hierarchies (parents, subparsers, defaults)
+- Each command can point to a dynamically imported Python script
+- `argcomplete` integration for tab‑completion
+- Pluggable data sources – YAML is the default, but JSON, TOML, or a dict are trivial to swap in
+- No boilerplate argparse code in your main logic
+
+## Quick Start
+
+### Install
+
+```bash
+pip install sigil-cli
+```
+
+or include argcomplete
+
+```bash
+pip install sigil-cli[completion]
+```
+
+### 0. Recommended file structure
+
+```text
+project_root/
+├── mycli.py              # drop‑in entry script (alias this)
+├── manifest.yml          # lists all YAML config files to load
+├── yml/                  
+│   ├── root.yml          # root command definition
+│   ├── root_run.yml      # subcommand definition(s)
+│   └── ...               
+└── scripts/              
+    ├── run.py            # implements the 'run' command
+    └── ...               # other scripts
+```
+
+### 1. Entry script
+
+Create `mycli.py`:
+
+```python
+#!/usr/bin/env python3
+from pathlib import Path
+from sigil import run_from_config
+
+if __name__ == "__main__":
+    run_from_config(Path(__file__).parent)
+```
+
+### 2. Configuration files
+
+List all your YAML definitions in `manifest.yml`:
+
+```yaml
+---
+- root.yml
+- root_run.yml
+```
+
+Define the root command in `root.yml`:
+
+```yaml
+root:
+  name: mycli
+  script_dir: scripts
+```
+
+Define a subcommand in `root_run.yml`:
+
+```yaml
+root_run:
+  name: run
+  parent: root
+  help: command utility to run containers
+  script: run
+  args:
+    - help: port to run, autoincrements from 8080
+      name:
+        - -p
+        - --port
+```
+
+### 3. Write the script
+
+Create `scripts/run.py`:
+
+```python
+import argparse
+from typing import Any
+
+def run(args: argparse.Namespace, ctx: dict[str, Any]) -> None:
+    port = getattr(args, "port", 8080)
+    port = find_next_free_port_logic(port)
+    print(f"Running container on port {port}")
+```
+
+### 4. Run it
+
+```bash
+chmod +x mycli.py
+./mycli.py run --port 9000
+# Running container on port 9000
+
+./mycli.py run
+# Running container on port 8080
+
+./mycli.py run
+# Running container on port 8081
+```
+
+## Configuration Reference
+
+### Root
+
+| Field | Description |
+| --- | --- |
+| `name` | Program name (used as `prog` in argparse) |
+| `script_dir` | Directory (relative to the config root) where command scripts are located |
+
+### Command
+
+| Field | Description |
+| --- | --- |
+| `name` | Subcommand name |
+| `parent` | Parent command (must exist elsewhere in a config) |
+| `help` | Help text for this subcommand |
+| `script` | Python module name (without `.py`) inside `script_dir` or as absolute path |
+| `args` | List of argument definitions (see below) |
+| `default` | If `true`, this subcommand is used when no subcommand is given |
+
+### Argument
+
+Each argument entry can be a plain dict which maps 1-to-1 with argparse `add_argument`, except name which maps it's `*args`
+
+```yaml
+- name: ["-p", "--port"]   # or a single string, e.g. "positional"
+  required: false
+  default: 8069
+  help: "port number"
+```
+
+The `name` field can be `--flag` for flags or a string for positional arguments.
+Both literal string and list of strings are supported.
+
+## Tab‑Completion (argcomplete)
+
+Argus registers itself with `argcomplete` automatically if available on your system.  
+To enable completion, install [argcomplete](https://github.com/kislyuk/argcomplete) and activate it for your entry script:
+
+```bash
+pip install argcomplete
+activate-global-python-argcomplete
+```
+
+Then run your script and hit <kbd>Tab</kbd> – subcommands and flags will complete.
+
+## Pluggable Backends
+
+Sigil uses yaml by default, but you can supply any loader that returns a `dict[str, ParserConfig]`:
+
+```python
+from sigil import run_from_config
+
+# Use JSON instead:
+class JsonReader:
+    @classmethod
+    def load(cls, config_root):
+        # read *.json, parse, convert to dict of ParserConfig
+        ...
+
+run_from_config("/path/to/config", loader_class=JsonReader)
+```
+
+You can also pass a pre‑loaded dictionary directly by wrapping it:
+
+```python
+run_from_config(my_dict, loader_class=DictLoader)
+```

sigil_cli-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sigil-cli"
+version = "0.1.0"
+description = "Configuration driven CLI builder with subcommands and script loading"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [{name = "Kenzo Staelens", email = "kenzostael@gmail.com"}]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+completion = ["argcomplete>=3.0"]
+dev = ["pytest", "pytest-cov", "ruff"]
+
+[project.urls]
+Homepage = "https://github.com/yourusername/sigil"
+Repository = "https://github.com/yourusername/sigil"
+Issues = "https://github.com/yourusername/sigil/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

sigil_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sigil_cli-0.1.0/src/sigil/__init__.py

@@ -0,0 +1,25 @@
+from .entrypoint import run_from_config
+from .models import (
+    Argument,
+    LibArgParser,
+    ParserConfig,
+    SubcommandModule,
+)
+from .stages import (
+    Builder,
+    Resolver,
+    ScriptLoader,
+    YamlReader,
+)
+
+__all__ = (
+    run_from_config,
+    Argument,
+    LibArgParser,
+    ParserConfig,
+    SubcommandModule,
+    YamlReader,
+    Resolver,
+    Builder,
+    ScriptLoader,
+)

sigil_cli-0.1.0/src/sigil/entrypoint.py

@@ -0,0 +1,25 @@
+from typing import Any
+
+from .stages import Builder, Resolver, ScriptLoader, YamlReader
+
+
+# default to yamlloader, use whatever datastore you feel like
+def run_from_config(config_root: str, loader_class = YamlReader):
+    raw_data = loader_class.load(config_root)
+    resolved = Resolver.resolve_inheritance(raw_data)
+    parser = Builder.build(resolved)
+    args, other_args = parser.parse_known_args()
+    scripts = ScriptLoader.get_scripts(args, 'root', parser, {'root': resolved})
+
+    execution_context: dict[str, Any] = {'other_args': other_args}
+    for script in scripts:
+        try:
+            module = ScriptLoader.import_module(
+                config_root,
+                resolved.script_dir,
+                script
+            )
+        except Exception as e:
+            print(f'failed to load script "{script}"\n\t{e}')
+            return
+        module.run(args, execution_context)

sigil_cli-0.1.0/src/sigil/models/__init__.py

@@ -0,0 +1,12 @@
+from .argparser import LibArgParser
+from .argument import Argument
+from .command import ParserConfig
+from .script import SubcommandModule
+
+__all__ = [
+    Argument,
+    LibArgParser,
+    ParserConfig,
+    ParserConfig,
+    SubcommandModule
+]

sigil_cli-0.1.0/src/sigil/models/argparser.py

@@ -0,0 +1,11 @@
+import argparse
+
+# because setting default subommands is kind of a pain in std. argparse
+
+class LibArgParser(argparse.ArgumentParser):
+    def set_default_subparser(self, name, args=None, positional_args=0):
+        for action in self._actions:
+            if not isinstance(action, argparse._SubParsersAction):
+                continue
+            if name in action._name_parser_map.keys():
+                action.default=name

sigil_cli-0.1.0/src/sigil/models/argument.py

@@ -0,0 +1,22 @@
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Argument:
+    name: list[str]
+    required: bool = False
+    default: bool = False
+    help: str | None = None
+    action: str | None = None
+    # anything we haven't explicitly defined.. yet
+    kw: dict[str, Any] = field(default_factory=dict)
+
+    # Source - https://stackoverflow.com/a/74459763
+
+    @classmethod
+    def factory(cls, **kwargs: dict):
+        name = kwargs.get('name')
+        if isinstance(name, str):
+            kwargs['name'] = [name]
+        return cls(**{k: kwargs[k] for k in kwargs if k in cls.__match_args__})

sigil_cli-0.1.0/src/sigil/models/command.py

@@ -0,0 +1,28 @@
+import logging
+from dataclasses import dataclass, field
+
+from .argument import Argument
+
+_logger = logging.getLogger(__name__)
+
+@dataclass
+class ParserConfig:
+    name: str
+    script_dir: str | None = None # only for root
+    help: str | None = None
+    args: list[Argument] = field(default_factory=list)
+    script: str | None = None
+    parent: str | None = None
+    default: bool = False
+    load: bool = True
+    subparsers: 'dict[str, ParserConfig]' = field(default_factory=dict)
+
+    @classmethod
+    def factory(cls, **kwargs):
+        for k in kwargs:
+            if k not in cls.__match_args__:
+                _logger.warning(
+                    f'found unknown key "{k}" in parser '
+                    f'"{kwargs.get("name")}", ignoring'
+                )
+        return cls(**{k: kwargs[k] for k in kwargs if k in cls.__match_args__})

sigil_cli-0.1.0/src/sigil/models/script.py

@@ -0,0 +1,8 @@
+import argparse
+from types import ModuleType
+from typing import Any
+
+
+class SubcommandModule(ModuleType):
+    @staticmethod
+    def run(args: argparse.Namespace, ctx: dict[str, Any]): ...

sigil_cli-0.1.0/src/sigil/stages/__init__.py

@@ -0,0 +1,11 @@
+from .builder import Builder
+from .resolver import Resolver
+from .script_loader import ScriptLoader
+from .yaml_reader import YamlReader
+
+__all__ = [
+    YamlReader,
+    Resolver,
+    Builder,
+    ScriptLoader,
+]

sigil_cli-0.1.0/src/sigil/stages/builder.py

@@ -0,0 +1,78 @@
+from sigil.models import Argument, LibArgParser, ParserConfig
+
+try:
+    import argcomplete
+    USE_ARGCOMPLETE = True
+except Exception:
+    USE_ARGCOMPLETE=False
+import logging
+from typing import Any
+
+_logger = logging.getLogger(__name__)
+
+class Builder:
+    # also in place modification, returning just causes more problems anyway
+    @classmethod
+    def _build_subparsers(
+        cls,
+        base_parser: LibArgParser,
+        parser_data: ParserConfig
+    ) -> None:
+        if parser_data.subparsers:
+            argparse_group = base_parser.add_subparsers(
+                dest=parser_data.name,
+                title='subcommands',
+            )
+            last_default = None  # find the last default
+            for _, subcommand in parser_data.subparsers.items():
+                subcommand_name = subcommand.name
+                subcmd_help = subcommand.help
+                argparser = argparse_group.add_parser(subcommand_name, help=subcmd_help)
+                for arg in subcommand.args:
+                    cls.attach_argument(argparser, arg)
+                if subcommand.default:
+                    if last_default:
+                        _logger.warning(
+                            f'last default {last_default} overridden '
+                            f'with {subcommand.name}'
+                        )
+                    last_default = subcommand.name
+                if subcommand.subparsers:
+                    cls._build_subparsers(argparser, subcommand)
+            if last_default:
+                base_parser.set_default_subparser(last_default)
+
+    @classmethod
+    def attach_argument(
+        cls,
+        parser: LibArgParser,
+        argument_config: Argument
+    ) -> None:
+        conditional_args: dict[str, Any] = {}
+        if any(x.startswith('-') for x in argument_config.name):
+            # if no '--name' or '-n' exists it's required by default
+            conditional_args['required']=argument_config.required
+
+        parser.add_argument(
+            *argument_config.name,
+            help=argument_config.help,
+            action=argument_config.action,
+            default=argument_config.default,
+            **(argument_config.kw | conditional_args)
+        )
+
+    @classmethod
+    def build(
+        cls,
+        root_data: ParserConfig
+    ) -> LibArgParser:
+        root_name = root_data.name
+        root_parser = LibArgParser(prog=root_name)
+        for arg in root_data.args or []:
+            cls.attach_argument(root_parser, arg)
+
+        cls._build_subparsers(root_parser, root_data)
+        if USE_ARGCOMPLETE:
+            argcomplete.autocomplete(root_parser)
+
+        return root_parser