strictcli 0.9.1__tar.gz → 0.10.0__tar.gz

strictcli-0.10.0/.rlsbl/changes/.validated

@@ -0,0 +1 @@
+241a0b1102d02359dc80c640d8c8a17697f05a9b

strictcli-0.10.0/.rlsbl/changes/0.10.0.jsonl

@@ -0,0 +1,6 @@
+{"commits":["faa8f348f03793084361365f15bd9f8be06046ff"],"user_facing":true,"description":"**New feature.** `--dump-schema` omits fields matching defaults and includes a top-level `defaults` object documenting what missing fields mean.","type":"feature"}
+{"commits":["ef852d540829f5fb248c380b649e8c15e56b849b"],"user_facing":true,"description":"**New feature.** `@`-prefix for string flag values: `@path` reads from file, `@-` reads from stdin, `@@` escapes. 1 MB size limit, trailing whitespace stripped.","type":"feature"}
+{"commits":["4294effc300d83eeba90c3cb90c6429fc443c929","e7e5bc79004fe8c0883fdc5c34a1f36eb8d97e75","6bf56e841883195ea6045386b21f93a4d1c8ee2d"],"user_facing":false}
+{"commits":["05d896e80e8df10ee737f50ae735e99695bbc213","1e354f1681539c39d71e4df7d57090d6b32d3f59","5f8b3d49ab264aa26dbe8c6c1d1f1bebb955d73b"],"user_facing":false}
+{"commits":["33dfbe42738b308dc01df908c8286b48eb97e12f"],"user_facing":false}
+{"commits":["f2b61b9ca7eb86207a0631d01cb672c39dcb89a0"],"user_facing":false}

strictcli-0.10.0/.rlsbl/changes/0.10.0.md

@@ -0,0 +1,6 @@
+## 0.10.0
+
+### Features
+
+- **New feature.** `--dump-schema` omits fields matching defaults and includes a top-level `defaults` object documenting what missing fields mean.
+- **New feature.** `@`-prefix for string flag values: `@path` reads from file, `@-` reads from stdin, `@@` escapes. 1 MB size limit, trailing whitespace stripped.

strictcli-0.10.0/.rlsbl/releases/v0.9.0.toml

@@ -0,0 +1,3 @@
+bump = "minor"
+include = ["pypi", "npm"]
+exclude = []

strictcli-0.10.0/.rlsbl/version

@@ -0,0 +1 @@
+0.42.0

{strictcli-0.9.1 → strictcli-0.10.0}/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 # Changelog
 
+## 0.10.0
+
+### Features
+
+- **New feature.** `--dump-schema` omits fields matching defaults and includes a top-level `defaults` object documenting what missing fields mean.
+- **New feature.** `@`-prefix for string flag values: `@path` reads from file, `@-` reads from stdin, `@@` escapes. 1 MB size limit, trailing whitespace stripped.
+
 ## 0.9.1
 
 ### Features

{strictcli-0.9.1 → strictcli-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: strictcli
-Version: 0.9.1
+Version: 0.10.0
 Summary: A strict, zero-dependency CLI framework for Python
 Project-URL: Homepage, https://github.com/smm-h/strictcli
 Project-URL: Repository, https://github.com/smm-h/strictcli

{strictcli-0.9.1 → strictcli-0.10.0}/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "strictcli",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "strictcli",
-      "version": "0.9.1",
+      "version": "0.10.0",
       "hasInstallScript": true,
       "license": "MIT"
     }

{strictcli-0.9.1 → strictcli-0.10.0}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "strictcli",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "A strict, zero-dependency CLI framework for Python (npm wrapper)",
   "main": "index.js",
   "scripts": {

{strictcli-0.9.1 → strictcli-0.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "strictcli"
-version = "0.9.1"
+version = "0.10.0"
 description = "A strict, zero-dependency CLI framework for Python"
 readme = "README.md"
 license = "MIT"

{strictcli-0.9.1 → strictcli-0.10.0}/strictcli/__init__.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-__version__ = "0.9.1"
+__version__ = "0.10.0"
 
 __all__ = [
     "App", "Flag", "Arg", "Tag", "MutexGroup", "CoRequired", "Requires",
@@ -316,6 +316,50 @@ def _float_parse_error(
     return _ParseError(f"--{flag_name}: expected float, got {raw!r}{suffix}")
 
 
+_AT_PREFIX_MAX_SIZE = 1024 * 1024  # 1 MB
+
+
+def _resolve_at_prefix(
+    flag_name: str, raw: str, stdin_consumed_by: str | None,
+) -> tuple[str, str | None]:
+    """Resolve @-prefix for string flag values.
+
+    Returns (resolved_value, updated_stdin_consumed_by).
+    """
+    if not raw.startswith("@"):
+        return raw, stdin_consumed_by
+    if raw.startswith("@@"):
+        return raw[1:], stdin_consumed_by
+    if raw == "@-":
+        if stdin_consumed_by is not None:
+            raise _ParseError(
+                f"--{flag_name}: stdin (@-) can only be used once per invocation"
+            )
+        try:
+            data = sys.stdin.read(_AT_PREFIX_MAX_SIZE + 1)
+            if len(data) > _AT_PREFIX_MAX_SIZE:
+                raise _ParseError(f"--{flag_name}: file exceeds 1 MB limit")
+            return data.rstrip(), flag_name
+        except _ParseError:
+            raise
+        except Exception:
+            raise _ParseError(f"--{flag_name}: cannot read stdin")
+    # @path -- read file
+    path = raw[1:]
+    if not os.path.exists(path):
+        raise _ParseError(f"--{flag_name}: file not found: {path}")
+    try:
+        with open(path, "r") as f:
+            data = f.read(_AT_PREFIX_MAX_SIZE + 1)
+        if len(data) > _AT_PREFIX_MAX_SIZE:
+            raise _ParseError(f"--{flag_name}: file exceeds 1 MB limit")
+        return data.rstrip(), stdin_consumed_by
+    except _ParseError:
+        raise
+    except Exception:
+        raise _ParseError(f"--{flag_name}: cannot read file: {path}")
+
+
 def _require_non_empty_str(value: str, field_name: str, class_name: str) -> None:
     if not isinstance(value, str) or not value.strip():
         raise ValueError(f"{class_name}.{field_name} must be a non-empty string")
@@ -1024,6 +1068,7 @@ class App:
             raise _DumpSchemaRequested()
 
         # Step 1.5: parse global flags before command routing
+        self._stdin_consumed_by: str | None = None
         global_values, remaining = self._parse_global_flags(argv)
         self._last_global_values = global_values
 
@@ -1092,9 +1137,13 @@ class App:
             return cmd, rest
 
         # Step 3: parse remaining tokens for the resolved command
+        # Pass stdin_consumed_by as a mutable single-element list so
+        # _parse_command can update the shared state.
+        stdin_state: list[str | None] = [self._stdin_consumed_by]
         try:
             cmd, kwargs, post_global = _parse_command(
                 cmd, rest, self._global_flags, config_data=self._config_data,
+                stdin_consumed_by=stdin_state,
             )
         except _ParseError as e:
             prefix_parts = [self.name] + path + [cmd.name]
@@ -1181,7 +1230,10 @@ class App:
                         except ValueError as e:
                             raise _float_parse_error(f.name, value_part, e)
                     else:
-                        _store_value(f, value_part)
+                        resolved, self._stdin_consumed_by = _resolve_at_prefix(
+                            f.name, value_part, self._stdin_consumed_by,
+                        )
+                        _store_value(f, resolved)
                     i += 1
                     continue
                 elif flag_part in negation_lookup:
@@ -1222,7 +1274,10 @@ class App:
                             except ValueError as e:
                                 raise _float_parse_error(f.name, raw, e)
                         else:
-                            _store_value(f, raw)
+                            resolved, self._stdin_consumed_by = _resolve_at_prefix(
+                                f.name, raw, self._stdin_consumed_by,
+                            )
+                            _store_value(f, resolved)
                         i += 2
                     else:
                         raise _ParseError(f"flag '{tok}' requires a value")
@@ -1250,7 +1305,10 @@ class App:
                             except ValueError as e:
                                 raise _float_parse_error(f.name, raw, e)
                         else:
-                            _store_value(f, raw)
+                            resolved, self._stdin_consumed_by = _resolve_at_prefix(
+                                f.name, raw, self._stdin_consumed_by,
+                            )
+                            _store_value(f, resolved)
                         i += 2
                     else:
                         raise _ParseError(f"flag '{tok}' requires a value")
@@ -1297,7 +1355,10 @@ class App:
                             raise _float_parse_error(f.name, env_val, e, env=f.env)
                         cli_set[f.name] = [coerced] if f.repeatable else coerced
                     else:
-                        cli_set[f.name] = [env_val] if f.repeatable else env_val
+                        resolved, self._stdin_consumed_by = _resolve_at_prefix(
+                            f.name, env_val, self._stdin_consumed_by,
+                        )
+                        cli_set[f.name] = [resolved] if f.repeatable else resolved
 
         # Resolve config values for global flags not set by CLI or env
         if self._config_data:
@@ -1471,12 +1532,18 @@ def _parse_command(
     tokens: list[str],
     global_flags: list[Flag] | None = None,
     config_data: dict | None = None,
+    stdin_consumed_by: list[str | None] | None = None,
 ) -> tuple[Command, dict[str, object], dict[str, object]]:
     """Parse tokens against a resolved command's flags and args.
 
     Returns (cmd, kwargs, global_cli_set) where global_cli_set contains
     any global flag values parsed from tokens appearing after the command name.
+
+    stdin_consumed_by is a mutable single-element list tracking which flag
+    has already consumed stdin via @-. Updated in-place.
     """
+    if stdin_consumed_by is None:
+        stdin_consumed_by = [None]
 
     # Build flag lookup dicts
     long_lookup: dict[str, Flag] = {}  # --flag-name -> Flag
@@ -1554,7 +1621,10 @@ def _parse_command(
                     except ValueError as e:
                         raise _float_parse_error(f.name, value_part, e)
                 else:
-                    _store_value(f, value_part)
+                    resolved, stdin_consumed_by[0] = _resolve_at_prefix(
+                        f.name, value_part, stdin_consumed_by[0],
+                    )
+                    _store_value(f, resolved)
             elif flag_part in negation_lookup:
                 raise _ParseError(
                     f"flag '{flag_part}' is a boolean negation and does not take a value"
@@ -1593,7 +1663,10 @@ def _parse_command(
                             except ValueError as e:
                                 raise _float_parse_error(f.name, raw, e)
                         else:
-                            _store_value(f, raw)
+                            resolved, stdin_consumed_by[0] = _resolve_at_prefix(
+                                f.name, raw, stdin_consumed_by[0],
+                            )
+                            _store_value(f, resolved)
                         i += 2
                     else:
                         raise _ParseError(f"flag '{tok}' requires a value")
@@ -1623,7 +1696,10 @@ def _parse_command(
                             except ValueError as e:
                                 raise _float_parse_error(f.name, raw, e)
                         else:
-                            _store_value(f, raw)
+                            resolved, stdin_consumed_by[0] = _resolve_at_prefix(
+                                f.name, raw, stdin_consumed_by[0],
+                            )
+                            _store_value(f, resolved)
                         i += 2
                     else:
                         raise _ParseError(f"flag '{tok}' requires a value")
@@ -1668,7 +1744,10 @@ def _parse_command(
                         raise _float_parse_error(f.name, env_val, e, env=f.env)
                     cli_set[f.name] = [coerced] if f.repeatable else coerced
                 else:
-                    cli_set[f.name] = [env_val] if f.repeatable else env_val
+                    resolved, stdin_consumed_by[0] = _resolve_at_prefix(
+                        f.name, env_val, stdin_consumed_by[0],
+                    )
+                    cli_set[f.name] = [resolved] if f.repeatable else resolved
 
     # Step 4.2: resolve config values for flags not set by CLI or env
     if config_data:
@@ -2870,66 +2949,158 @@ _TYPE_NAMES = {str: "str", bool: "bool", int: "int", float: "float"}
 
 
 def _serialize_flag(f: Flag) -> dict:
-    """Serialize a Flag to a JSON-serializable dict."""
-    return {
+    """Serialize a Flag to a JSON-serializable dict.
+
+    Identity fields (name, type, help) are always included.
+    Other fields are omitted when they match the schema defaults.
+    """
+    d: dict = {
         "name": f.name,
         "type": _TYPE_NAMES[f.type],
         "help": f.help,
-        "short": f.short,
-        "default": f.default,
-        "env": f.env,
-        "choices": f.choices,
-        "repeatable": f.repeatable,
-        "negatable": f.negatable if f.type is bool else None,
-        "hidden": False,
     }
+    if f.short is not None:
+        d["short"] = f.short
+    if f.default is not None:
+        d["default"] = f.default
+    if f.env is not None:
+        d["env"] = f.env
+    if f.choices is not None:
+        d["choices"] = f.choices
+    if f.repeatable:
+        d["repeatable"] = f.repeatable
+    negatable = f.negatable if f.type is bool else None
+    if negatable is not None:
+        d["negatable"] = negatable
+    # hidden is currently always False, so always omitted
+    return d
 
 
 def _serialize_arg(a: Arg) -> dict:
-    """Serialize an Arg to a JSON-serializable dict."""
-    return {
+    """Serialize an Arg to a JSON-serializable dict.
+
+    Identity fields (name, help) are always included.
+    Other fields are omitted when they match the schema defaults.
+    """
+    d: dict = {
         "name": a.name,
         "help": a.help,
-        "required": a.required,
-        "variadic": a.variadic,
     }
+    if not a.required:
+        d["required"] = a.required
+    if a.variadic:
+        d["variadic"] = a.variadic
+    return d
 
 
 def _serialize_command(cmd: Command) -> dict:
-    """Serialize a Command to a JSON-serializable dict."""
-    return {
+    """Serialize a Command to a JSON-serializable dict.
+
+    Identity fields (name, help) are always included.
+    Other fields are omitted when they match the schema defaults.
+    """
+    d: dict = {
         "name": cmd.name,
         "help": cmd.help,
-        "flags": [_serialize_flag(f) for f in cmd.flags],
-        "args": [_serialize_arg(a) for a in cmd.args],
-        "passthrough": cmd.passthrough is not None,
     }
+    if cmd.passthrough is not None:
+        d["passthrough"] = True
+    flags = [_serialize_flag(f) for f in cmd.flags]
+    if flags:
+        d["flags"] = flags
+    args = [_serialize_arg(a) for a in cmd.args]
+    if args:
+        d["args"] = args
+    return d
 
 
 def _serialize_group(group: Group) -> dict:
-    """Serialize a Group to a JSON-serializable dict (recursive)."""
-    return {
+    """Serialize a Group to a JSON-serializable dict (recursive).
+
+    Identity fields (name, help) are always included.
+    Other fields are omitted when they match the schema defaults.
+    """
+    d: dict = {
         "name": group.name,
         "help": group.help,
-        "commands": {name: _serialize_command(cmd) for name, cmd in group.commands.items()},
-        "groups": {name: _serialize_group(g) for name, g in group._groups.items()},
-        "deprecated": {name: dep.message for name, dep in group.deprecated.items()},
+    }
+    commands = {name: _serialize_command(cmd) for name, cmd in group.commands.items()}
+    if commands:
+        d["commands"] = commands
+    groups = {name: _serialize_group(g) for name, g in group._groups.items()}
+    if groups:
+        d["groups"] = groups
+    deprecated = {name: dep.message for name, dep in group.deprecated.items()}
+    if deprecated:
+        d["deprecated"] = deprecated
+    return d
+
+
+def _build_schema_defaults() -> dict:
+    """Return the defaults object documenting what 'missing' means in the schema."""
+    return {
+        "app": {
+            "env_prefix": None,
+            "config": False,
+            "global_flags": [],
+            "commands": {},
+            "groups": {},
+            "deprecated": {},
+        },
+        "flag": {
+            "short": None,
+            "default": None,
+            "env": None,
+            "choices": None,
+            "repeatable": False,
+            "negatable": None,
+            "hidden": False,
+        },
+        "arg": {
+            "required": True,
+            "variadic": False,
+        },
+        "command": {
+            "passthrough": False,
+            "flags": [],
+            "args": [],
+        },
+        "group": {
+            "commands": {},
+            "groups": {},
+            "deprecated": {},
+        },
     }
 
 
 def _dump_schema(app: App) -> dict:
-    """Produce a JSON-serializable dict representing the app's command tree."""
-    schema = {
+    """Produce a JSON-serializable dict representing the app's command tree.
+
+    Fields whose values match the schema defaults are omitted.
+    The top-level ``defaults`` key documents what each missing field means.
+    """
+    schema: dict = {
+        "defaults": _build_schema_defaults(),
         "name": app.name,
         "version": app.version,
         "help": app.help,
-        "env_prefix": app.env_prefix,
-        "config": app.config,
-        "global_flags": [_serialize_flag(f) for f in app._global_flags],
-        "commands": {name: _serialize_command(cmd) for name, cmd in app._commands.items()},
-        "groups": {name: _serialize_group(grp) for name, grp in app._groups.items()},
-        "deprecated": {name: dep.message for name, dep in app._deprecated.items()},
     }
+    if app.env_prefix is not None:
+        schema["env_prefix"] = app.env_prefix
+    if app.config:
+        schema["config"] = app.config
+    global_flags = [_serialize_flag(f) for f in app._global_flags]
+    if global_flags:
+        schema["global_flags"] = global_flags
+    commands = {name: _serialize_command(cmd) for name, cmd in app._commands.items()}
+    if commands:
+        schema["commands"] = commands
+    groups = {name: _serialize_group(grp) for name, grp in app._groups.items()}
+    if groups:
+        schema["groups"] = groups
+    deprecated = {name: dep.message for name, dep in app._deprecated.items()}
+    if deprecated:
+        schema["deprecated"] = deprecated
     if app._checks_enabled:
         schema["checks"] = {
             name: {