cli-pydantic 0.1.0__tar.gz → 0.2.1__tar.gz

cli_pydantic-0.2.1/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.3
+Name: cli-pydantic
+Version: 0.2.1
+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
+from pydantic import BaseModel, Field
+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
+    profile: bool = Field(False, description="dump chrome trace")
+
+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 --profile
+```
+
+## 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!
+
+## Automatic help
+
+```bash
+$ python train.py --help
+help: Training pipeline
+
+usage: train.py [-h] [configs ...] [--overrides ...]
+
+config arguments:
+  --data.path str          (default: ./data)
+  --data.splits list[str]  (default: ['train', 'val'])
+  --model.arch str         (default: resnet50)
+  --model.lr float         (default: 0.001)
+  --model.layers list[int] (default: [64, 128, 256])
+  --epochs int             (default: 10)
+  --verbose bool           dump chrome trace (default: False)
+```

cli_pydantic-0.2.1/README.md

@@ -0,0 +1,75 @@
+# 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
+from pydantic import BaseModel, Field
+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
+    profile: bool = Field(False, description="dump chrome trace")
+
+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 --profile
+```
+
+## 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!
+
+## Automatic help
+
+```bash
+$ python train.py --help
+help: Training pipeline
+
+usage: train.py [-h] [configs ...] [--overrides ...]
+
+config arguments:
+  --data.path str          (default: ./data)
+  --data.splits list[str]  (default: ['train', 'val'])
+  --model.arch str         (default: resnet50)
+  --model.lr float         (default: 0.001)
+  --model.layers list[int] (default: [64, 128, 256])
+  --epochs int             (default: 10)
+  --verbose bool           dump chrome trace (default: False)
+```

{cli_pydantic-0.1.0 → cli_pydantic-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cli-pydantic"
-version = "0.1.0"
+version = "0.2.1"
 description = "Add your description here"
 readme = "README.md"
 authors = [
@@ -15,3 +15,8 @@ dependencies = [
 [build-system]
 requires = ["uv_build>=0.8.4,<0.9.0"]
 build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+]

cli_pydantic-0.2.1/src/cli_pydantic/__init__.py

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

cli_pydantic-0.2.1/src/cli_pydantic/lib.py

@@ -0,0 +1,184 @@
+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."""
+    cls = model_cls
+    for p in path:
+        if p not in cls.model_fields:
+            return None
+        ann = cls.model_fields[p].annotation
+        if p == path[-1]:
+            return ann
+        if isinstance(ann, type) and issubclass(ann, BaseModel):
+            cls = ann
+        else:
+            return None
+    return None
+
+
+def parse_flags(tokens: list[str], model_cls: type[BaseModel]) -> dict:
+    out = {}
+
+    def route(key: str) -> list[str]:
+        parts = key.replace("-", "_").split(".")
+        if resolve_field_type(model_cls, parts) is None:
+            raise ValueError(f"Unknown option: --{key}")
+        return parts
+
+    def put(parts: list[str], val):
+        cur = out
+        for p in parts[:-1]:
+            cur = cur.setdefault(p, {})
+
+        k = parts[-1]
+        is_list = get_origin(resolve_field_type(model_cls, parts)) is list
+
+        if is_list:
+            vals = val.split(",") if isinstance(val, str) and "," in val else [val]
+            cur.setdefault(k, []).extend(vals)
+        elif cur.get(k, val) != val:
+            raise ValueError(f"Duplicate value for {'.'.join(parts)}")
+        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("--"):
+            raise ValueError(f"Expected --key, got: {t}")
+
+        s = t[2:]
+
+        if s.startswith("no-"):  # --no-flag
+            if "=" in s or has_value():
+                raise ValueError(f"--no-* flags can't take a value: {t}")
+            key, val = s[3:], False
+        elif "=" in s:  # --k=v
+            key, val = s.split("=", 1)
+        else:  # --k v / --flag
+            key, val = s, (q.popleft() if has_value() else True)
+
+        put(route(key), val)
+
+    return out
+
+
+def deep_merge(base: dict, overrides: dict) -> dict:
+    for k, v in overrides.items():
+        if isinstance(v, dict) and isinstance(base.get(k), dict):
+            deep_merge(base[k], v)
+        else:
+            base[k] = v
+    return base
+
+
+def model_help(model: type[BaseModel], prefix: str = "") -> list[str]:
+    def ty_name(ann) -> str:
+        name = getattr(ann, "__name__", None)
+        return name if name and "[" not in str(ann) else str(ann)
+
+    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 = f" {field.description}" if field.description else ""
+                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) + 1
+    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 = []
+        if desc:
+            lines.append(f"help: {desc}\n")
+        lines.append(f"usage: {prog} [-h] [configs ...] [--overrides ...]")
+        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.1.0/PKG-INFO

@@ -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/src/cli_pydantic/__init__.py

@@ -1 +0,0 @@
-from .lib import parse_unknown_args, deep_merge, model_help

cli_pydantic-0.1.0/src/cli_pydantic/lib.py

@@ -1,101 +0,0 @@
-from collections import deque
-from typing import get_origin
-
-from pydantic import BaseModel
-from pydantic_core import PydanticUndefined
-
-
-def resolve_field_type(model_cls: type[BaseModel], path: list[str]) -> type | None:
-    """Walk a dotted path through nested BaseModels, return the leaf annotation."""
-    cls = model_cls
-    for p in path:
-        if p not in cls.model_fields:
-            return None
-        ann = cls.model_fields[p].annotation
-        if p == path[-1]:
-            return ann
-        if isinstance(ann, type) and issubclass(ann, BaseModel):
-            cls = ann
-        else:
-            return None
-    return None
-
-
-def parse_unknown_args(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(".")
-        if resolve_field_type(model_cls, parts) is None:
-            raise ValueError(f"Unknown option: --{key}")
-        return parts
-
-    def put(parts: list[str], val):
-        cur = out
-        for p in parts[:-1]:
-            cur = cur.setdefault(p, {})
-
-        k = parts[-1]
-        is_list = get_origin(resolve_field_type(model_cls, parts)) is list
-
-        if is_list:
-            vals = val.split(",") if isinstance(val, str) and "," in val else [val]
-            cur.setdefault(k, []).extend(vals)
-        elif cur.get(k, val) != val:
-            raise ValueError(f"Duplicate value for {'.'.join(parts)}")
-        else:
-            cur[k] = val
-
-    while q:
-        t = q.popleft()
-        if not t.startswith("--"):
-            raise ValueError(f"Expected --key, got: {t}")
-
-        s = t[2:]
-
-        if s.startswith("no-"):  # --no-flag
-            if "=" in s or has_value():
-                raise ValueError(f"--no-* flags can't take a value: {t}")
-            key, val = s[3:], False
-        elif "=" in s:  # --k=v
-            key, val = s.split("=", 1)
-        else:  # --k v / --flag
-            key, val = s, (q.popleft() if has_value() else True)
-
-        put(route(key), val)
-
-    return out
-
-
-def deep_merge(base: dict, overrides: dict) -> dict:
-    for k, v in overrides.items():
-        if isinstance(v, dict) and isinstance(base.get(k), dict):
-            deep_merge(base[k], v)
-        else:
-            base[k] = v
-    return base
-
-
-def model_help(model: type[BaseModel], prefix: str = "") -> list[str]:
-    def ty_name(ann) -> 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
-