fromargs 0.1.0__tar.gz → 0.2.0__tar.gz

{fromargs-0.1.0 → fromargs-0.2.0}/.gitignore

@@ -16,8 +16,5 @@ __pycache__/
 # Skill-creator iteration workspaces (eval runs, benchmarks, viewer HTML)
 skills/*-workspace/
 
-# file-handler skill artifact tree (local scratch space)
-.skillz/
-
 # Serena MCP — machine-local; not tracked
 .serena/

fromargs-0.2.0/CHANGELOG.md

@@ -0,0 +1,76 @@
+# Changelog
+
+This file records the notable changes to the `fromargs` distribution.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+The project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+A `0.x` minor release can contain breaking changes.
+
+The `publish fromargs` workflow reads the section for the tagged version.
+It uses that section as the GitHub release notes.
+To release, move the `Unreleased` entries into a new version section with the date.
+Then set the same version in `lib/fromargs/pyproject.toml`.
+When the minor version changes, also bump the `fromargs` range in `pyproject.toml` and `lib/pyproject.toml`.
+Then relock, and push a `fromargs-v<version>` tag after the release commit merges.
+
+## [Unreleased]
+
+## [0.2.0] - 2026-10-04
+
+### Changed
+
+- **Breaking:** require Cyclopts 5 (`cyclopts>=5,<6`).
+  Cyclopts 5 removes the v4 fuzzy command fallback.
+  A command name that differs only in dashes, underscores, or case no longer resolves.
+  It reports an `Unknown command ... Did you mean` error with exit code 2.
+- **Breaking:** `CliError` accepts only an `int` `exit_code` from 2 to 255.
+  It raises a dedicated `Exception` subclass for 0, 1, an out-of-range code, a `bool`, or a non-`int` code.
+  Cyclopts reports a `ValueError` or `TypeError` as bad input at exit 2.
+  The dedicated subclass is neither, so a bad code in a converter or validator exits 1 with a traceback.
+- **Breaking:** `App`, `App.group`, and `App.command` raise `ValueError` for the
+  Cyclopts options that `run()` never honors: `error_formatter`, `result_action`,
+  `suppress_keyboard_interrupt`, `print_error`, `exit_on_error`, `help_on_error`,
+  and `error_console`.
+- A `set` or `frozenset` result prints as a sorted JSON list. Before, it exited 1.
+- A `bytes` or iterator result raises `TypeError` with a message that names the fix.
+- **Breaking:** `SystemExit` and `KeyboardInterrupt` no longer propagate from `App.run()`.
+  `run()` catches them while it parses, runs the handler, and prints the result.
+  `sys.exit(n)` sets the exit status with an error line.
+  An `int` outside 1 to 255 reports `exited with status <code>` at exit code 1.
+  `KeyboardInterrupt` reports exit code 130.
+- The `--json` and `--full` flags are literal. Put them after `--` to pass them as data.
+- `fromargs` keeps the traceback file after the process exits.
+
+### Fixed
+
+- A converter or validator exception other than `ValueError`, `TypeError`, or
+  `AssertionError` now reports the exit code 1 error line with a `traceback` path.
+  Before, it escaped `App.run()`. Cyclopts still reports those three types as usage errors at exit code 2.
+  A quote-split repair candidate that raises such an exception counts as rejected.
+- **Breaking:** A `default_parameter` that a command inherits from its app or group now gets
+  the reserved `--json`/`--full` check. A reserved flag now raises `ValueError` at registration.
+- `--version` resolves the caller's distribution when Python lists it twice
+  (for example under `uv run --with`), and under `python -m pkg.cli`.
+- A leading `--json` or `--full` no longer hides a nested command's custom
+  `end_of_options_delimiter`.
+
+## [0.1.0] - 2026-09-26
+
+### Added
+
+- `fromargs.App`, which composes one `cyclopts.App` and registers commands
+  with `@app.command`, `@app.default`, and `app.group(name)`.
+- Forced JSON output: a non-`None` return value prints as one JSON document
+  on stdout. `None` means exit 0 with no stdout.
+- One JSON error line on stderr for every error:
+  `{"error": <message>, "exit_code": <n>}`.
+- `fromargs.CliError` (exit code 2) and `fromargs.contract_error` (exit code 3).
+- An unexpected handler exception reports exit code 1 with a `traceback` file path.
+- The global `--json` (no-op) and `--full` (no truncation) flags.
+- `limit=n` on `@app.command` and `@app.default` to truncate a sequence result.
+- A verified quote-split repair for a shell-merged option value.
+- `--version` resolution for the calling distribution, not for `fromargs`.
+- Async handlers through `asyncio.run` when the effective backend is asyncio.
+
+[Unreleased]: https://github.com/paulnsorensen/skillz-that-grillz/compare/fromargs-v0.2.0...HEAD
+[0.2.0]: https://github.com/paulnsorensen/skillz-that-grillz/compare/fromargs-v0.1.0...fromargs-v0.2.0
+[0.1.0]: https://github.com/paulnsorensen/skillz-that-grillz/releases/tag/fromargs-v0.1.0

{fromargs-0.1.0 → fromargs-0.2.0}/PKG-INFO

@@ -1,10 +1,11 @@
 Metadata-Version: 2.5
 Name: fromargs
-Version: 0.1.0
+Version: 0.2.0
 Summary: Self-healing Cyclopts CLI helpers for agent-friendly command lines.
 Project-URL: Homepage, https://github.com/paulnsorensen/skillz-that-grillz/tree/main/lib/fromargs
 Project-URL: Source, https://github.com/paulnsorensen/skillz-that-grillz/tree/main/lib/fromargs
 Project-URL: Issues, https://github.com/paulnsorensen/skillz-that-grillz/issues
+Project-URL: Changelog, https://github.com/paulnsorensen/skillz-that-grillz/blob/main/lib/fromargs/CHANGELOG.md
 Author-email: Paul Sorensen <paulnsorensen@gmail.com>
 License-Expression: MIT
 License-File: LICENSE
@@ -17,7 +18,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
-Requires-Dist: cyclopts<5,>=4.25.3
+Requires-Dist: cyclopts<6,>=5
 Description-Content-Type: text/markdown
 
 # fromargs
@@ -35,7 +36,7 @@ uv add fromargs
 pip install fromargs
 ```
 
-`fromargs` pins `cyclopts>=4.25.3,<5`; it does not yet track Cyclopts 5.
+`fromargs` pins `cyclopts>=5,<6`.
 
 ## Quick start
 
@@ -81,11 +82,31 @@ a truncated list result.
 - A handler returns data, not text. A non-`None` return value prints as one
   JSON document on stdout, then the process exits `0`.
 - A `None` return value means exit `0` with no stdout.
+- A `set` or `frozenset` prints as a sorted JSON list. Items that cannot
+  sort together order by their canonical JSON text, so the output stays
+  stable. `bytes`, `bytearray`, `memoryview`, and iterators (such as
+  generators) raise `TypeError`: return a `str` or a `list` instead.
 - Every error is one JSON line on stderr: `{"error": <message>, "exit_code": <n>}`.
-  Raise `fromargs.CliError(message)` for exit code `2`, or
-  `fromargs.contract_error(exc, context=...)` to wrap a caught exception at
-  exit code `3`. An unhandled Cyclopts parse error also reports at exit
-  code `2`.
+- Raise `fromargs.CliError(message)` for exit code `2`. Pass
+  `exit_code=n` for a code from `2` to `255`. `CliError` rejects any other
+  code with an error that is neither `ValueError` nor `TypeError`.
+  Cyclopts reports those as bad input. Exit `0` means success, and exit `1`
+  means an unexpected exception.
+- Use `fromargs.contract_error(exc, context=...)` to wrap a caught exception
+  at exit code `3`. A Cyclopts parse error reports at exit code `2`.
+- A converter or validator that raises `ValueError`, `TypeError`, or
+  `AssertionError` is a usage error at exit code `2`. Any other exception
+  from a converter, a validator, the handler, or the result serialization
+  reports at exit code `1`. Its envelope adds a `traceback` key with the
+  path of a temporary file. `fromargs` keeps the file, so the caller can
+  read it after the process exits.
+- `sys.exit(n)` sets the exit status, and `run()` catches it while it
+  parses, runs the handler, and prints the result. `0` or `None` exits `0`
+  with no output. An `int` from `1` to `255` reports an error envelope at
+  that exit code. An `int` outside that range reports
+  `exited with status <code>` at exit code `1`. Any other `sys.exit` value
+  reports its text at exit code `1`. `KeyboardInterrupt` reports
+  `{"error": "interrupted"}` at exit code `130`.
 - A quote-split repair (below) prints one plain-text `note:` line on stderr;
   it never changes stdout or the exit code.
 
@@ -100,12 +121,19 @@ anywhere before the end-of-options marker:
 
 Neither flag reaches a handler, and neither is a real Cyclopts option.
 
+The rule is literal. Every bare `--json` or `--full` token before the marker
+is global, even where a parameter would take a hyphen-leading value (for
+example `Parameter(allow_leading_hyphen=True)`). To pass one of these tokens
+as data, put it after the marker (`--` by default): `wrap jq -- --json x`.
+The `--full=1` and `--json=true` forms are not global flags. Cyclopts
+rejects them as unknown options.
+
 ## `limit`
 
-`@app.command(limit=n)` truncates a sequence result to its first `n` items,
-unless the caller passes `--full`. Truncation prints a `note:` line on
-stderr and never applies to a mapping or a string. `App.default` accepts the
-same `limit` keyword.
+`@app.command(limit=n)` truncates a sequence or set result to its first `n`
+items, unless the caller passes `--full`. A set truncates after sorting.
+Truncation prints a `note:` line on stderr and never applies to a mapping or
+a string. `App.default` accepts the same `limit` keyword.
 
 ## `App.default`
 
@@ -146,3 +174,11 @@ version of `fromargs` itself. It resolves, in order:
 `App.group(name, version=..., **cyclopts_kwargs)` forwards every extra
 keyword, including `version`, to the nested `cyclopts.App`, so a group can
 report its own version independently of the root app.
+
+## Cyclopts options
+
+`App`, `App.group`, and `App.command` forward keyword arguments to Cyclopts.
+`run()` owns error output, the exit status, and the result. So these three
+raise `ValueError` for a Cyclopts option that `run()` never honors:
+`error_formatter`, `result_action`, `suppress_keyboard_interrupt`,
+`print_error`, `exit_on_error`, `help_on_error`, and `error_console`.

{fromargs-0.1.0 → fromargs-0.2.0}/README.md

@@ -13,7 +13,7 @@ uv add fromargs
 pip install fromargs
 ```
 
-`fromargs` pins `cyclopts>=4.25.3,<5`; it does not yet track Cyclopts 5.
+`fromargs` pins `cyclopts>=5,<6`.
 
 ## Quick start
 
@@ -59,11 +59,31 @@ a truncated list result.
 - A handler returns data, not text. A non-`None` return value prints as one
   JSON document on stdout, then the process exits `0`.
 - A `None` return value means exit `0` with no stdout.
+- A `set` or `frozenset` prints as a sorted JSON list. Items that cannot
+  sort together order by their canonical JSON text, so the output stays
+  stable. `bytes`, `bytearray`, `memoryview`, and iterators (such as
+  generators) raise `TypeError`: return a `str` or a `list` instead.
 - Every error is one JSON line on stderr: `{"error": <message>, "exit_code": <n>}`.
-  Raise `fromargs.CliError(message)` for exit code `2`, or
-  `fromargs.contract_error(exc, context=...)` to wrap a caught exception at
-  exit code `3`. An unhandled Cyclopts parse error also reports at exit
-  code `2`.
+- Raise `fromargs.CliError(message)` for exit code `2`. Pass
+  `exit_code=n` for a code from `2` to `255`. `CliError` rejects any other
+  code with an error that is neither `ValueError` nor `TypeError`.
+  Cyclopts reports those as bad input. Exit `0` means success, and exit `1`
+  means an unexpected exception.
+- Use `fromargs.contract_error(exc, context=...)` to wrap a caught exception
+  at exit code `3`. A Cyclopts parse error reports at exit code `2`.
+- A converter or validator that raises `ValueError`, `TypeError`, or
+  `AssertionError` is a usage error at exit code `2`. Any other exception
+  from a converter, a validator, the handler, or the result serialization
+  reports at exit code `1`. Its envelope adds a `traceback` key with the
+  path of a temporary file. `fromargs` keeps the file, so the caller can
+  read it after the process exits.
+- `sys.exit(n)` sets the exit status, and `run()` catches it while it
+  parses, runs the handler, and prints the result. `0` or `None` exits `0`
+  with no output. An `int` from `1` to `255` reports an error envelope at
+  that exit code. An `int` outside that range reports
+  `exited with status <code>` at exit code `1`. Any other `sys.exit` value
+  reports its text at exit code `1`. `KeyboardInterrupt` reports
+  `{"error": "interrupted"}` at exit code `130`.
 - A quote-split repair (below) prints one plain-text `note:` line on stderr;
   it never changes stdout or the exit code.
 
@@ -78,12 +98,19 @@ anywhere before the end-of-options marker:
 
 Neither flag reaches a handler, and neither is a real Cyclopts option.
 
+The rule is literal. Every bare `--json` or `--full` token before the marker
+is global, even where a parameter would take a hyphen-leading value (for
+example `Parameter(allow_leading_hyphen=True)`). To pass one of these tokens
+as data, put it after the marker (`--` by default): `wrap jq -- --json x`.
+The `--full=1` and `--json=true` forms are not global flags. Cyclopts
+rejects them as unknown options.
+
 ## `limit`
 
-`@app.command(limit=n)` truncates a sequence result to its first `n` items,
-unless the caller passes `--full`. Truncation prints a `note:` line on
-stderr and never applies to a mapping or a string. `App.default` accepts the
-same `limit` keyword.
+`@app.command(limit=n)` truncates a sequence or set result to its first `n`
+items, unless the caller passes `--full`. A set truncates after sorting.
+Truncation prints a `note:` line on stderr and never applies to a mapping or
+a string. `App.default` accepts the same `limit` keyword.
 
 ## `App.default`
 
@@ -124,3 +151,11 @@ version of `fromargs` itself. It resolves, in order:
 `App.group(name, version=..., **cyclopts_kwargs)` forwards every extra
 keyword, including `version`, to the nested `cyclopts.App`, so a group can
 report its own version independently of the root app.
+
+## Cyclopts options
+
+`App`, `App.group`, and `App.command` forward keyword arguments to Cyclopts.
+`run()` owns error output, the exit status, and the result. So these three
+raise `ValueError` for a Cyclopts option that `run()` never honors:
+`error_formatter`, `result_action`, `suppress_keyboard_interrupt`,
+`print_error`, `exit_on_error`, `help_on_error`, and `error_console`.

{fromargs-0.1.0 → fromargs-0.2.0}/examples/cheese_cave.py

@@ -5,11 +5,11 @@ The CLI tracks wheels of cheese as they ripen. Run it from the repository root:
     uv run --project lib/fromargs python lib/fromargs/examples/cheese_cave.py wheels list
 
 Agents often send malformed argv. Each call below still runs the intended
-command, and ``run`` prints one ``note:`` line on stderr for each repair:
+command. ``run`` prints one ``note:`` line on stderr only for quote-split repairs:
 
     cheese_cave.py --json wheels list              # --json is a no-op, dropped
     cheese_cave.py age brie --weeks "2 --dry-run"  # splits the merged argument
-    cheese_cave.py --json age brie --weeks "2 --dry-run"  # both repairs
+    cheese_cave.py --json age brie --weeks "2 --dry-run"  # drops --json silently; notes the split
 
 Cyclopts itself binds ``--dry_run`` to ``--dry-run``. It also answers a
 misspelled command such as ``wheels lst`` with ``Did you mean "list"?``.

{fromargs-0.1.0 → fromargs-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fromargs"
-version = "0.1.0"
+version = "0.2.0"
 description = "Self-healing Cyclopts CLI helpers for agent-friendly command lines."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -17,12 +17,13 @@ classifiers = [
   "Environment :: Console",
   "Intended Audience :: Developers",
 ]
-dependencies = ["cyclopts>=4.25.3,<5"]
+dependencies = ["cyclopts>=5,<6"]
 
 [project.urls]
 Homepage = "https://github.com/paulnsorensen/skillz-that-grillz/tree/main/lib/fromargs"
 Source = "https://github.com/paulnsorensen/skillz-that-grillz/tree/main/lib/fromargs"
 Issues = "https://github.com/paulnsorensen/skillz-that-grillz/issues"
+Changelog = "https://github.com/paulnsorensen/skillz-that-grillz/blob/main/lib/fromargs/CHANGELOG.md"
 
 [dependency-groups]
 dev = ["pytest>=8", "basedpyright==1.40.1"]

{fromargs-0.1.0 → fromargs-0.2.0}/src/fromargs/_app.py

@@ -11,7 +11,7 @@ from __future__ import annotations
 
 import inspect
 import sys
-from collections.abc import Callable, Coroutine, Iterable, Sequence
+from collections.abc import Callable, Coroutine, Iterable, Mapping, Sequence
 from importlib import metadata
 from typing import TYPE_CHECKING, Literal, TextIO, TypedDict, TypeVar, Unpack, overload
 
@@ -32,8 +32,9 @@ _HelpFormat = Literal["markdown", "md", "plaintext", "restructuredtext", "rst",
 class _AppKwargs(TypedDict, total=False):
     """Keyword-only ``cyclopts.App`` constructor arguments this wrapper forwards untouched.
 
-    This mirrors the ``cyclopts.App`` constructor by hand; a future cyclopts
-    4.x release can add a keyword here before fromargs re-releases with it.
+    This mirrors the ``cyclopts.App`` constructor by hand; a new cyclopts 5.x
+    keyword needs an entry here before fromargs accepts it. This type omits
+    the options that ``run`` never honors; see ``_INERT_KWARGS``.
     """
 
     usage: str | None
@@ -50,10 +51,8 @@ class _AppKwargs(TypedDict, total=False):
     version_flags: str | Iterable[str] | None
     show: bool
     console: Console | None
-    error_console: Console | None
     help_flags: str | Iterable[str] | None
     help_format: _HelpFormat | None
-    help_on_error: bool | None
     help_prologue: str | None
     help_epilogue: str | None
     version_format: _HelpFormat | None
@@ -65,14 +64,31 @@ class _AppKwargs(TypedDict, total=False):
     name_transform: Callable[[str], str] | None
     sort_key: object
     end_of_options_delimiter: str | None
-    print_error: bool | None
-    exit_on_error: bool | None
     verbose: bool | None
-    suppress_keyboard_interrupt: bool
     backend: Literal["asyncio", "trio"] | None
     help_formatter: Literal["default", "plain"] | HelpFormatter | None
-    error_formatter: Callable[[cyclopts.CycloptsError], object] | None
-    result_action: cyclopts.ResultAction | None
+
+
+# ``run`` parses with printing, exiting, and help-on-error forced off and owns
+# all error output, the exit status, and the result, so these do nothing.
+_INERT_KWARGS = frozenset(
+    {
+        "error_formatter",
+        "result_action",
+        "suppress_keyboard_interrupt",
+        "print_error",
+        "exit_on_error",
+        "help_on_error",
+        "error_console",
+    }
+)
+
+
+def _reject_inert(kwargs: Mapping[str, object]) -> None:
+    """Raise ``ValueError`` when ``kwargs`` names a Cyclopts option that ``run`` ignores."""
+    inert = sorted(_INERT_KWARGS.intersection(kwargs))
+    if inert:
+        raise ValueError(f"cyclopts option {inert[0]!r} has no effect under fromargs; remove it")
 
 
 class App:
@@ -85,21 +101,24 @@ class App:
         help: str | None = None,
         **cyclopts_kwargs: Unpack[_AppKwargs],
     ) -> None:
+        _reject_inert(cyclopts_kwargs)
         if "version" not in cyclopts_kwargs:
             frame = inspect.currentframe()
             caller = frame.f_back if frame is not None else None
             cyclopts_kwargs["version"] = _caller_version(caller.f_globals if caller is not None else {})
         self._cyclopts: cyclopts.App = cyclopts.App(name=name, help=help, **cyclopts_kwargs)
         self._limits: dict[int, int] = {}
+        self._ancestors: tuple[cyclopts.App, ...] = ()
         if cyclopts_kwargs.get("default_command") is not None:
-            _reject_reserved(self._cyclopts)
+            _reject_reserved(self._cyclopts, self._ancestors)
 
     @classmethod
-    def _wrap(cls, cyclopts_app: cyclopts.App, limits: dict[int, int]) -> App:
-        """Wrap an existing ``cyclopts.App`` without building a new one."""
+    def _wrap(cls, cyclopts_app: cyclopts.App, limits: dict[int, int], ancestors: tuple[cyclopts.App, ...]) -> App:
+        """Wrap an existing ``cyclopts.App`` under ``ancestors`` without building a new one."""
         wrapper = cls.__new__(cls)
         wrapper._cyclopts = cyclopts_app
         wrapper._limits = limits
+        wrapper._ancestors = ancestors
         return wrapper
 
     @overload
@@ -145,13 +164,14 @@ class App:
                 return self.command(handler, name=name, limit=limit, help=help, **kwargs)
 
             return register
+        _reject_inert(kwargs)
         _check_limit(limit)
         before = set(self._cyclopts)
         _ = self._cyclopts.command(obj, name=name, help=help, **kwargs)
         registered = sorted(set(self._cyclopts) - before)
         sub_app = self._cyclopts[registered[0]]
         try:
-            _reject_reserved(sub_app)
+            _reject_reserved(sub_app, (*self._ancestors, self._cyclopts))
         except ValueError:
             for key in registered:
                 del self._cyclopts[key]
@@ -206,7 +226,7 @@ class App:
         except cyclopts.CommandCollisionError as exc:
             raise ValueError(str(exc)) from exc
         try:
-            _reject_reserved(self._cyclopts)
+            _reject_reserved(self._cyclopts, self._ancestors)
         except ValueError:
             self._cyclopts.default_command = previous
             self._cyclopts.validator = previous_validator
@@ -217,11 +237,12 @@ class App:
 
     def group(self, name: str, *, help: str | None = None, **cyclopts_kwargs: Unpack[_AppKwargs]) -> App:
         """Return a nested command group registered under this app."""
+        _reject_inert(cyclopts_kwargs)
         sub = cyclopts.App(name=name, help=help, **cyclopts_kwargs)
         if cyclopts_kwargs.get("default_command") is not None:
-            _reject_reserved(sub)
+            _reject_reserved(sub, (*self._ancestors, self._cyclopts))
         _ = self._cyclopts.command(sub)
-        return App._wrap(sub, self._limits)
+        return App._wrap(sub, self._limits, (*self._ancestors, self._cyclopts))
 
     def run(self, argv: Sequence[str] | None = None, *, stdout: TextIO | None = None) -> int:
         """Parse argv once, invoke one handler, and return its exit status."""
@@ -232,10 +253,22 @@ class App:
         sys.exit(self.run())
 
 
-def _reserved_option(app: cyclopts.App) -> str | None:
-    """The first reserved global flag name ``app``'s assembled arguments claim, or ``None``."""
+def _reserved_option(app: cyclopts.App, ancestors: tuple[cyclopts.App, ...]) -> str | None:
+    """The first reserved global flag name ``app``'s assembled arguments claim, or ``None``.
+
+    Cyclopts resolves an inherited ``default_parameter`` from the app stack,
+    which it fills only while parsing. Combine the ``default_parameter`` of
+    each ancestor so ``app`` sees the parent chain.
+    """
+    inherited = [
+        parameter
+        for parameter in (*(a.default_parameter for a in ancestors), app.default_parameter)
+        if parameter is not None
+    ]
     try:
-        arguments = app.assemble_argument_collection()
+        arguments = app.assemble_argument_collection(
+            default_parameter=cyclopts.Parameter.combine(*inherited)
+        )
     except ValueError:
         return None
     names: set[str] = set()
@@ -245,9 +278,9 @@ def _reserved_option(app: cyclopts.App) -> str | None:
     return reserved[0] if reserved else None
 
 
-def _reject_reserved(app: cyclopts.App) -> None:
+def _reject_reserved(app: cyclopts.App, ancestors: tuple[cyclopts.App, ...]) -> None:
     """Raise ``ValueError`` when ``app``'s assembled arguments claim a reserved global flag."""
-    reserved = _reserved_option(app)
+    reserved = _reserved_option(app, ancestors)
     if reserved is not None:
         raise ValueError(f"command option {reserved!r} is reserved by fromargs")
 
@@ -272,16 +305,14 @@ def _caller_version(module_globals: dict[str, object]) -> Callable[[], str]:
         spec_name = getattr(module_globals.get("__spec__"), "name", None)
         module_name = (
             spec_name
-            if caller_name == "__main__"
-            and isinstance(spec_name, str)
-            and spec_name.endswith(".__main__")
+            if caller_name == "__main__" and isinstance(spec_name, str) and spec_name
             else caller_name
         )
         root = module_name.split(".")[0]
         candidates = [root]
-        providers = metadata.packages_distributions().get(root, [])
+        providers = set(metadata.packages_distributions().get(root, []))
         if len(providers) == 1:
-            candidates.append(providers[0])
+            candidates.append(next(iter(providers)))
         for candidate in candidates:
             try:
                 return metadata.version(candidate)

{fromargs-0.1.0 → fromargs-0.2.0}/src/fromargs/_argv.py

@@ -18,8 +18,6 @@ from typing import cast, get_args, get_origin
 from cyclopts import App, CycloptsError
 from cyclopts.annotations import is_union
 
-from fromargs._errors import CliError
-
 GLOBAL_FLAGS = frozenset({"--json", "--full"})
 
 
@@ -90,10 +88,10 @@ def parse_once(app: App, argv: Sequence[str]) -> tuple[Callable[..., object], Bo
 
 
 def _parses(app: App, argv: Sequence[str]) -> bool:
-    """Probe-parse ``argv``; a converter's ``CliError`` counts as a rejection."""
+    """Probe-parse ``argv``; any converter or validator exception counts as a rejection."""
     try:
         _ = parse_once(app, argv)
-    except (CycloptsError, CliError):
+    except Exception:
         return False
     return True
 
@@ -112,9 +110,11 @@ def _options(app: App, argv: Sequence[str]) -> list[str]:
     """The tokens before the command's end-of-options marker (``--`` by default).
 
     The innermost command app with a configured marker decides, as in Cyclopts.
+    The chain resolves without the global flags, so a leading ``--full`` does
+    not hide a nested app's marker.
     """
     tokens = list(argv)
-    apps = command_chain(app, tokens) or (app,)
+    apps = command_chain(app, [t for t in tokens if t not in GLOBAL_FLAGS]) or (app,)
     configured = [
         command_app.end_of_options_delimiter
         for command_app in apps

fromargs-0.2.0/src/fromargs/_errors.py

@@ -0,0 +1,35 @@
+"""The error type that ``run`` reports as one stderr line."""
+
+from __future__ import annotations
+
+
+class InvalidExitCodeError(Exception):
+    """A ``CliError`` got an invalid ``exit_code``; a programmer bug.
+
+    It derives from ``Exception`` alone. Cyclopts reports ``ValueError``,
+    ``TypeError``, and ``AssertionError`` from a converter or validator as
+    bad user input at exit 2. This bug must not take that path. It must
+    reach ``run`` as an unexpected exception: exit 1 with a traceback.
+    """
+
+
+class CliError(Exception):
+    """One-line error; ``run`` reports it on stderr and returns ``exit_code``.
+
+    ``exit_code`` must be an ``int`` from 2 to 255. Exit 0 means success, exit 1
+    means an unexpected exception, and POSIX truncates statuses above 255.
+    Otherwise ``InvalidExitCodeError`` (not a ``ValueError`` or ``TypeError``).
+    """
+
+    def __init__(self, message: str, *, exit_code: int = 2) -> None:
+        if isinstance(exit_code, bool) or not isinstance(exit_code, int):  # pyright: ignore[reportUnnecessaryIsInstance]
+            raise InvalidExitCodeError(f"exit_code must be an int, got {type(exit_code).__name__}")
+        if not 2 <= exit_code <= 255:
+            raise InvalidExitCodeError(f"exit_code must be 2..255, got {exit_code}")
+        super().__init__(message)
+        self.exit_code: int = exit_code
+
+
+def contract_error(exc: Exception, *, context: str) -> CliError:
+    """Wrap a contract-violation exception as a ``CliError`` that exits 3."""
+    return CliError(f"{context}: {exc}", exit_code=3)

fromargs-0.2.0/src/fromargs/_output.py

@@ -0,0 +1,84 @@
+"""Serialize a command's return value as one JSON document, with truncation."""
+
+from __future__ import annotations
+
+import dataclasses
+import itertools
+import json
+import os
+import sys
+from collections.abc import Iterator, Mapping, Sequence, Set
+from typing import TextIO, cast
+
+_BYTES_LIKE = (bytes, bytearray, memoryview)
+# Sequences that serialize as one JSON value, never as a list of items.
+_SCALAR_SEQUENCES = (str, *_BYTES_LIKE)
+
+
+def write_result(
+    value: object, *, limit: int | None, full: bool, stdout: TextIO | None = None
+) -> None:
+    """Print ``value`` as one JSON document; truncate a long sequence unless ``full``.
+
+    A sequence longer than ``limit`` is cut to its first ``limit`` items and
+    stderr gets a ``note:`` line, unless ``full`` is true or ``limit`` is
+    ``None``. A set becomes a sorted list first, so it truncates the same way.
+    Truncation never applies to a mapping or a string. ``NaN`` and
+    ``Infinity`` are rejected, and a type ``_default`` cannot resolve (bytes,
+    iterators) raises ``TypeError`` instead of printing a misleading fallback.
+    """
+    stream = stdout if stdout is not None else sys.stdout
+    payload = _sorted_items(value) if isinstance(value, Set) else value
+    note: str | None = None
+    if limit is not None and isinstance(payload, Sequence) and not isinstance(payload, _SCALAR_SEQUENCES):
+        items = cast("Sequence[object]", payload)
+        total = len(items)
+        if not full and total > limit:
+            payload = list(itertools.islice(items, limit))
+            note = f"note: showing {limit} of {total}; pass --full for the rest"
+    serialized = json.dumps(payload, indent=2, default=_default, allow_nan=False)
+    if note is not None:
+        print(note, file=sys.stderr)
+    print(serialized, file=stream)
+
+
+def _sorted_items(items: object) -> list[object]:
+    """Order set items deterministically.
+
+    Use natural order when no member is a ``Set``. A ``Set`` member (``<`` means
+    subset, so natural order is not total) or a ``TypeError`` from natural order
+    sorts by canonical JSON text instead. ``repr`` is not usable here, because
+    the ``repr`` of a multi-element frozenset depends on hash order.
+    """
+    members = list(cast("Set[object]", items))
+    if not any(isinstance(member, Set) for member in members):
+        try:
+            return cast("list[object]", sorted(members))  # pyright: ignore[reportArgumentType]
+        except TypeError:
+            pass
+    return sorted(members, key=lambda item: json.dumps(item, sort_keys=True, default=_default))
+
+
+def _default(value: object) -> object:
+    """Fallback for ``json.dumps``: dataclass via ``asdict``, path via ``str``, mapping, set, or list.
+
+    A nested set becomes a sorted list. Bytes and iterators raise ``TypeError``
+    with a hint, because bytes have no unambiguous JSON form and an iterator
+    has no known length for ``limit``.
+    """
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        return dataclasses.asdict(value)
+    if isinstance(value, os.PathLike):
+        return str(value)
+    if isinstance(value, Mapping):
+        return dict(cast("Mapping[object, object]", value))
+    if isinstance(value, Set):
+        return _sorted_items(value)
+    if isinstance(value, Sequence) and not isinstance(value, _SCALAR_SEQUENCES):
+        return list(value)
+    name = type(value).__name__
+    if isinstance(value, _BYTES_LIKE):
+        raise TypeError(f"{name} is not JSON serializable; return a str (decode it) or a list of ints")
+    if isinstance(value, Iterator):
+        raise TypeError(f"{name} is not JSON serializable; return a list instead of an iterator")
+    raise TypeError(f"Object of type {name} is not JSON serializable")