sigil-cli 0.1.0__py3-none-any.whl

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/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/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/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/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/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/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/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/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

sigil/stages/resolver.py

@@ -0,0 +1,48 @@
+import logging
+
+from sigil.models import ParserConfig
+
+_logger = logging.getLogger(__name__)
+
+class Resolver:
+    @classmethod
+    def resolve_inheritance(
+        cls,
+        raw_config: dict[str, ParserConfig],
+    ) -> ParserConfig:
+        # build the tree starting at "root", then attack items until
+        # items can no longer be attached
+        # note that this dictionary contains *references* to every resolved
+        # object, therefore editing an object at the root of this dictionary
+        # also edits it at an arbitrary nested point (because thats how references work)
+        # in the end we will just return "root"
+        resolved: dict[str, ParserConfig] = {}
+        changed = True
+
+        while changed:
+            changed = False # stays false unless something is attached
+            for internal_id, config_item in raw_config.items():
+                if internal_id in resolved: # already resolved, "del" is dangerous
+                    continue
+                if not config_item.load:
+                    continue
+
+                if internal_id == 'root':
+                    changed=True
+                    resolved[internal_id] = config_item
+                    break
+
+                parent = config_item.parent
+
+                if parent and parent in resolved:
+                    changed = True # only run a new pass if something was attached
+                    subparsers = resolved[parent].subparsers
+                    subparsers[config_item.name]= config_item
+                    resolved[parent].subparsers = subparsers
+                    resolved[internal_id] = config_item
+
+        # log unattached items:
+        for item in (raw_config.keys() - resolved.keys()):
+            _logger.warning(f'failed to resolve command path for {item}')
+
+        return resolved['root']  # one "root" is required

sigil/stages/script_loader.py

@@ -0,0 +1,55 @@
+import importlib.util
+import sys
+from argparse import Namespace
+from pathlib import Path
+
+from sigil.models import LibArgParser, ParserConfig, SubcommandModule
+
+
+class ScriptLoader:
+    @classmethod
+    def import_module(cls, config_root, path:str, module_name: str) -> SubcommandModule:
+        config_root_path = Path(config_root)
+        file_path = str(config_root_path/path/f'{module_name}.py')
+
+        spec = importlib.util.spec_from_file_location(module_name, file_path)
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+        return module
+
+    # method is somewhat messy, i'm aware
+    @classmethod
+    def get_scripts(
+        cls,
+        args: Namespace,
+        target: str,
+        root_parser: LibArgParser,
+        data: ParserConfig
+    ) -> list[SubcommandModule]:
+        found_scripts = []
+
+        target_parser: ParserConfig = data[target]
+        subparsers = target_parser.subparsers
+        script = target_parser.script
+
+        if script:
+            found_scripts.append(script)
+        if not subparsers:
+            return found_scripts
+
+        # get the name of the next subcommand
+        if target != 'root':
+            next_value = getattr(args, target)
+        else:
+            next_value = getattr(args, target_parser.name)
+
+        if next_value is None:
+            # if subcommands exist but no subcommand is used print help instead
+            root_parser.parse_args(sys.argv[1:] + ['--help'])
+            sys.exit(2) # nothing to do here
+        return found_scripts + cls.get_scripts(
+            args,
+            next_value,
+            root_parser,
+            subparsers,
+        )

sigil/stages/yaml_reader.py

@@ -0,0 +1,86 @@
+import logging
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from sigil.models import Argument, ParserConfig
+
+_logger = logging.getLogger(__name__)
+
+# This class converts raw data to dataclasses,
+# however swap it out if you want to use a different form of IO
+class YamlReader:
+    @classmethod
+    def handle_duplicates(
+        cls,
+        loaded_entry: dict[str],
+        loaded_config: dict[str],
+        entry: str
+    ):
+        # warning: in place mutation if you decide to make changes to loaded config
+        if duplicates := (loaded_entry.keys() & loaded_config.keys()):
+            for duplicate in duplicates:
+                _logger.warning(f"{entry}[{duplicate}] already defined, ignoring")
+
+    @classmethod
+    def load(
+        cls,
+        config_root: str,
+        manifest_file='manifest.yml'
+    ) -> dict[str, ParserConfig]:
+        config_root_path = Path(config_root)
+        manifest = cls.read_file(config_root_path/manifest_file)
+        loaded_config = {}
+
+        for entry in manifest:
+            loaded_entry = cls.read_file(config_root_path/entry)
+            if not loaded_entry:
+                continue
+            loaded_entry = {
+                k:v
+                for k, v in loaded_entry.items()
+                if not v.get('load_ignore')
+            }
+            cls.handle_duplicates(loaded_entry, loaded_config, entry)
+            cls.convert_args(loaded_entry)
+            # override loaded entry duplicates by already found
+            loaded_config = loaded_entry | loaded_config
+
+        for k, v in loaded_config.items():
+            try:
+                loaded_config[k] = ParserConfig.factory(**v)
+            except Exception:
+                _logger.error(f'failed to parse config {k}, ignoring')
+        # pesky "dictionary changed size during iteration"
+        loaded_config = {
+            k: v
+            for k,v in loaded_config.items()
+            if isinstance(v, ParserConfig)
+        }
+
+        return loaded_config
+
+    @classmethod
+    def convert_args(cls, loaded_entry: dict[str, dict[str, Any]]):
+        # while yes default factory this fixes the edge case where the key is defined
+        # but without values
+        for command_def in loaded_entry.values():
+            args = command_def.get('args') or []
+            build_args = []
+            for arg in args:
+                try:
+                    build_args.append(Argument.factory(**arg))
+                except Exception: # any failure is skipped
+                    _logger.error(f'invalid argument definition,\n{arg}\nskipping')
+            command_def['args'] = build_args
+
+    # actual IO, also adaptable
+    @classmethod
+    def read_file(cls, filename) -> dict:
+        try:
+            with open(filename) as f:
+                return yaml.load(f.read(), Loader=yaml.SafeLoader)
+        except FileNotFoundError:
+            _logger.error(f'failed to load file {filename}, skipping')
+            return None

sigil_cli-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,17 @@
+sigil/__init__.py,sha256=-rGz3JJx4edqboBImga1nJe38P-qmofMfl3m37iTtE0,390
+sigil/entrypoint.py,sha256=4YTtMTZydYX_ieUyv6OjsRd4B0G5X9DlhGv1dU6SN78,901
+sigil/models/__init__.py,sha256=yrYNZj2OMP94W869eKoAuqMwHlukKfLNWXwhW2hgy1M,242
+sigil/models/argparser.py,sha256=QRQ3aBJoKIVGvRrMA4w4NNhSFSofUraWEsahHxVcpmU,428
+sigil/models/argument.py,sha256=KEbh1sQaKcoBkpAx4VlH4NroRHFmsw0LQ2ysVfRUEcI,621
+sigil/models/command.py,sha256=blFlNRGoFoDW6Fw9oWbd3lD0i7JJqlSuNFt1iYtW4EM,850
+sigil/models/script.py,sha256=VxPYOT2EGknZKYwhzsgmwaVfZqloK8ujbBy64yrDcbM,188
+sigil/stages/__init__.py,sha256=x2LTIoEO732mcnohHBfFxlwHVc1c435UnCDBrJVBKg4,212
+sigil/stages/builder.py,sha256=4ftJ9YCn3FiuxSdHONilDvNHnJZqJnb7zSyy7zgN7OA,2657
+sigil/stages/resolver.py,sha256=D6op5JZqzywswO5PjL0XpYEbT5vNxsqjczqJ2AJZjJI,1851
+sigil/stages/script_loader.py,sha256=rxDR1DIUwB1_XhMaumXB5bc91cxbdrtQj8AdJHy4Ok0,1679
+sigil/stages/yaml_reader.py,sha256=iKMpq2FahJ1Oc4gxqtUCRPD6vucV6PdNOLQf9buol4c,2968
+sigil_cli-0.1.0.dist-info/licenses/LICENSE,sha256=D7GbINJ7rATMfIf14hpgr8uN92A0JszHKQqjO7MnoeY,1058
+sigil_cli-0.1.0.dist-info/METADATA,sha256=lnkhuFFDTmFopHfNjL4h1NelRuo9A69qmIOY_dxEXZ4,5402
+sigil_cli-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+sigil_cli-0.1.0.dist-info/top_level.txt,sha256=JwJchkwF1qAzvIXu8_C5lSeAVY3ib64gXRdMsx1pR40,6
+sigil_cli-0.1.0.dist-info/RECORD,,

sigil_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sigil_cli-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+sigil