cli-pydantic 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

cli_pydantic/__init__.py

@@ -1 +1,3 @@
-from .lib import parse_unknown_args, deep_merge, model_help
+__all__ = ["cli"]
+
+from .lib import cli

cli_pydantic/lib.py

@@ -1,9 +1,15 @@
+import json
+import sys
 from collections import deque
+from pathlib import Path
 from typing import get_origin
 
+import yaml
 from pydantic import BaseModel
 from pydantic_core import PydanticUndefined
 
+__all__ = ["cli"]
+
 
 def resolve_field_type(model_cls: type[BaseModel], path: list[str]) -> type | None:
     """Walk a dotted path through nested BaseModels, return the leaf annotation."""
@@ -21,12 +27,8 @@ def resolve_field_type(model_cls: type[BaseModel], path: list[str]) -> type | No
     return None
 
 
-def parse_unknown_args(tokens: list[str], model_cls: type[BaseModel]) -> dict:
+def parse_flags(tokens: list[str], model_cls: type[BaseModel]) -> dict:
     out = {}
-    q = deque(tokens)
-
-    def has_value() -> bool:
-        return bool(q) and not q[0].startswith("--")
 
     def route(key: str) -> list[str]:
         parts = key.replace("-", "_").split(".")
@@ -50,6 +52,10 @@ def parse_unknown_args(tokens: list[str], model_cls: type[BaseModel]) -> dict:
         else:
             cur[k] = val
 
+    def has_value() -> bool:
+        return bool(q) and not q[0].startswith("--")
+
+    q = deque(tokens)
     while q:
         t = q.popleft()
         if not t.startswith("--"):
@@ -85,17 +91,93 @@ def model_help(model: type[BaseModel], prefix: str = "") -> list[str]:
         name = getattr(ann, "__name__", None)
         return name if name and "[" not in str(ann) else str(ann)
 
-    lines = []
-    for name, field in model.model_fields.items():
-        key = f"{prefix}{name}"
-        ann = field.annotation
-        if isinstance(ann, type) and issubclass(ann, BaseModel):
-            lines.extend(model_help(ann, prefix=f"{key}."))
-        else:
-            default = (
-                "required" if field.default is PydanticUndefined else field.default
-            )
-            desc = f"  {field.description}" if field.description else ""
-            lines.append(f"  --{key}  {ty_name(ann)} (default: {default}){desc}")
-    return lines
-
+    def entries(m, pfx):
+        out = []
+        for name, field in m.model_fields.items():
+            key = f"{pfx}{name}"
+            ann = field.annotation
+            if isinstance(ann, type) and issubclass(ann, BaseModel):
+                out.extend(entries(ann, f"{key}."))
+            else:
+                default = (
+                    ""
+                    if field.default is PydanticUndefined
+                    else f" (default: {field.default})"
+                )
+                desc = field.description or ""
+                out.append((f"--{key} {ty_name(ann)}", f"{desc}{default}"))
+        return out
+
+    items = entries(model, prefix)
+    col = max((len(f) for f, _ in items), default=0) + 2
+    return [f"  {f:<{col}}{h}" for f, h in items]
+
+
+def load_config(path: Path) -> dict:
+    if not path.exists():
+        raise ValueError(f"Config file not found: {path}")
+
+    raw = path.read_text()
+    if not raw.strip():
+        data = {}
+    elif path.suffix == ".json":
+        data = json.loads(raw)
+    elif path.suffix in {".yaml", ".yml"}:
+        data = yaml.safe_load(raw)
+    else:
+        raise ValueError(f"Unsupported config file type: {path.suffix}")
+
+    if not isinstance(data, dict):
+        raise ValueError(
+            f"Config file must contain a mapping, got {type(data).__name__}"
+        )
+    return data
+
+
+def cli[T: BaseModel](model_cls: type[T], desc: str = "") -> T:
+    """Build a CLI from a Pydantic model, merging config files and --overrides.
+
+    Positional arguments are paths to JSON/YAML config files (later files
+    override earlier ones).  Any remaining ``--key value`` flags are parsed
+    as field overrides using dot-notation (e.g. ``--model.lr 0.01``).
+
+    Args:
+        model_cls: The Pydantic model class that defines the config schema.
+        desc: Optional description shown in ``--help`` output.
+
+    Returns:
+        A validated instance of *model_cls*.
+    """
+    argv = sys.argv[1:]
+
+    def print_help():
+        prog = Path(sys.argv[0]).name
+        lines = [f"usage: {prog} [-h] [configs ...] [--overrides ...]"]
+        if desc:
+            lines.append(f"\n{desc}")
+        lines.append("\nconfig arguments:")
+        lines.extend(model_help(model_cls))
+        print("\n".join(lines))
+        raise SystemExit(0)
+
+    def split_argv() -> tuple[list[Path], list[str]]:
+        config_paths: list[Path] = []
+        for i, tok in enumerate(argv):
+            if tok.startswith("-"):
+                return config_paths, argv[i:]
+            config_paths.append(Path(tok))
+        return config_paths, []
+
+    if "-h" in argv or "--help" in argv:
+        print_help()
+
+    config_paths, flag_tokens = split_argv()
+
+    configs = [load_config(p) for p in config_paths]
+    overrides = parse_flags(flag_tokens, model_cls)
+
+    data = {}
+    for new in configs + [overrides]:
+        deep_merge(data, new)
+
+    return model_cls.model_validate(data)

cli_pydantic-0.2.0.dist-info/METADATA

@@ -0,0 +1,69 @@
+Metadata-Version: 2.3
+Name: cli-pydantic
+Version: 0.2.0
+Summary: Add your description here
+Author: Tom Pollak
+Author-email: Tom Pollak <tomp@graphcore.ai>
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pyyaml>=6.0.3
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# cli-pydantic
+
+Turn a Pydantic model into a CLI. I dislike every other CLI library so here's yet another one.
+
+- CLI defined by Pydantic
+- Use multiple YAML / JSON configs with `--flag` CLI overrides.
+
+## Install
+
+```
+pip install cli-pydantic
+```
+
+## Usage
+
+```python
+# train.py
+from pydantic import BaseModel
+from cli_pydantic import cli
+
+class Data(BaseModel):
+    path: str = "./data"
+    splits: list[str] = ["train", "val"]
+
+class Model(BaseModel):
+    arch: str = "resnet50"
+    lr: float = 1e-3
+    layers: list[int] = [64, 128, 256]
+
+class Config(BaseModel):
+    data: Data = Data()
+    model: Model = Model()
+    epochs: int = 10
+    verbose: bool = False
+
+cfg = cli(Config, desc="Training pipeline")
+```
+
+```bash
+# CLI, use default from Pydantic
+python train.py --model.arch vit_base --model.lr 3e-4 --epochs 50
+
+# From a config file
+python train.py base.yaml
+
+# Layer multiple configs, then override with flags
+python train.py base.yaml fast.yaml --model.lr 0.05 --epochs 3
+
+# Lists and booleans
+python train.py --model.layers 16,32 --verbose
+```
+
+## Semantics:
+
+- Use `--foo bar` or `--foo=bar`
+- For lists: `--nums=1,2,3` or `--nums 1 --nums=2 --nums 3`
+- For bools: `--enable` / `--no-enable`
+- Lists will _replace_ previous configs on override -- not append!

cli_pydantic-0.2.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+cli_pydantic/__init__.py,sha256=FzDWd6rL0-KFfomhD6Zfa_Au9y9g7jznspke55BFHbI,40
+cli_pydantic/lib.py,sha256=vZsv9rSlYmL-aIDKD1Y-cRE3ElhkKzdI82cpeLVmDbY,5603
+cli_pydantic/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cli_pydantic-0.2.0.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+cli_pydantic-0.2.0.dist-info/METADATA,sha256=oR2y5ZDl6-9xvRW7xoEV24iTkRhO4g2yTxrlk15kLdw,1556
+cli_pydantic-0.2.0.dist-info/RECORD,,

cli_pydantic-0.1.0.dist-info/METADATA

@@ -1,11 +0,0 @@
-Metadata-Version: 2.3
-Name: cli-pydantic
-Version: 0.1.0
-Summary: Add your description here
-Author: Tom Pollak
-Author-email: Tom Pollak <tomp@graphcore.ai>
-Requires-Dist: pydantic>=2.12.5
-Requires-Dist: pyyaml>=6.0.3
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-

cli_pydantic-0.1.0.dist-info/RECORD

@@ -1,6 +0,0 @@
-cli_pydantic/__init__.py,sha256=bQv5RB8buC5LQO5DNjDhl4ZudIi9SJFyOuesDCDWVro,60
-cli_pydantic/lib.py,sha256=V9cJVw5ZN9Cx4Y4Zy9WLx-dIdyUt9dEnr7ds-MRe3-8,3168
-cli_pydantic/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-cli_pydantic-0.1.0.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
-cli_pydantic-0.1.0.dist-info/METADATA,sha256=Vxj2rtGtWVA76_iHL0kaFtADcn1UhMXL8olXvMiyxGA,281
-cli_pydantic-0.1.0.dist-info/RECORD,,