Repository navigation
feat: structured errors and exit codes - #78
Merged
Merged
Conversation
A rejected input now prints a VALIDATION_ERROR object on stdout and exits with code 2. It has one field error per pydantic error, with the dotted input path and pydantic's error type as the code. Literal and enum fields list their choices in `allowed`. pydantic validates Literal choices, so argparse never rejects them first. Refs #66
argv is now parsed with parse_known_args. Each leftover flag becomes an unknown_flag field error, and its `allowed` list holds the flags the command accepts. A word right after an unknown flag counts as that flag's value. Any other stray word becomes an unexpected_argument error. Unknown flags come first, then pydantic's errors, all in one VALIDATION_ERROR. Errors that argparse finds itself, such as a flag without its value, also give VALIDATION_ERROR and exit code 2, with argparse's message as-is. Prefix matching is off, so --epo no longer means --epochs. Refs #66
A command raises CommandError(code, message, *, retryable=False, hint=None, exit_code=1). argdantic prints it with the command's own code and exits with its exit code. The constructor raises ValueError if the code is not SCREAMING_CASE. Every error object now always has `retryable`. `hint` appears only when it is set. `message` keeps only its first line. Refs #66
An exception the command does not expect now prints an UNKNOWN error and exits with code 1. The message is the exception text, or the exception's type name when the text is empty. This also covers a result that fails to serialise. KeyboardInterrupt and other BaseExceptions pass through. The traceback goes to stderr only when ARGD_DEBUG is on. pydantic's bool parsing reads the value, and a value it cannot parse counts as off. Refs #66
A field error on a SecretStr or SecretBytes field has no `received` key, so a rejected secret never reaches stdout. The check also covers secrets inside Optional, Annotated and nested models. Refs #66
The benchmark compares structured errors against plain text errors. Setting argdantic._errors._string_errors = True makes a failed run print the text pydantic and argparse produce on their own. For CommandError and uncaught exceptions it prints the exception text. Exit codes and the output stream stay the same. The switch is not exported from argdantic. Refs #66
A field error now has `expected` when pydantic gives one, for example "'parquet' or 'webdataset'" for a Literal or enum field. That completes the structured error object. Closes #66
The package's other internal module, docstrings.py, has no underscore, and CommandError is public, so its repr should not point at a private module. The bench switch keeps its underscore: argdantic.errors._string_errors. Refs #66
app.py imported eleven names from the errors module and dispatched on exception type itself. It now imports four: EXIT_OK, InputRejected, fail and rejected_input. - InputRejected and CommandError each carry their own report, so fail() is the one place that picks a report, prints it and exits. The ARGD_DEBUG traceback moves there too, out of report construction. - rejected_input() builds the whole rejection from leftover tokens and a ValidationError, including the text the string-errors ablation prints. - FieldError and ErrorReport are pydantic models, so model_dump replaces the two hand-written to_dict methods. ErrorReport keeps only the first line of its message. The JSON output is unchanged. Refs #66
pydantic-settings raises SettingsError, not ValidationError, when a list, dict or model flag holds JSON it cannot parse. That fell through to UNKNOWN with exit 1, as if the command had failed. It is now VALIDATION_ERROR with exit 2. The field name appears only in pydantic-settings' message text, so the report carries that message and no fieldErrors. Refs #66
CommandError(exit_code=0) printed an error object and exited 0, and exit_code=2 looked like rejected input. A caller could no longer tell success, a failed command and rejected input apart from the exit code. Refs #66
A leftover "--" became unknown_flag with an empty path and swallowed the next word as its value. "-.5" became unknown_flag with path ".5". Both are now unexpected_argument, like "-1" and "-" already were. Refs #66
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
A failed run now prints one JSON error object on stdout instead of a traceback or argparse usage text. The exit code tells the cases apart: 0 ok, 1 the command failed, 2 the input was rejected.
Error object:
{code, message, retryable, hint?, fieldErrors?}. Field error:{path, code, message, expected?, received?, allowed?, source?}.pathis the dotted input path (optim.lr), not the flag spelling.allowedholds Literal and enum choices, or forunknown_flagthe flags the command accepts.receivedis left out forSecretStrandSecretBytesfields and formissing.messagekeeps only its first line.CommandErrorraisesValueErrorif its code is not SCREAMING_CASE, or if its exit code is 0 or 2, which mean success and rejected input.--sizes '[1,') raises pydantic-settings'SettingsError. It givesVALIDATION_ERRORand exit 2. pydantic-settings names the field only in its message text, so this report has nofieldErrors.ARGD_DEBUGuses pydantic's bool parsing. A value it cannot parse counts as off.allow_abbrev=False, so--epois an unknown flag instead of a silent--epochs.unexpected_argumentwithpath: "". So do-,--and negative numbers such as-1and-.5.argdantic.errors._string_errors = Trueprints pydantic's and argparse's own text instead of the object. It exists for the benchmark's structured-vs-string ablation and is not exported.New module
src/argdantic/errors.py. OnlyCommandErroris exported fromargdantic.app.pyuses four names from it:EXIT_OK,InputRejected,failandrejected_input.Evidence
add-numbers --first-value x --secnd 3exited 2 with argparse usage text on stderr, and--first 1quietly ran as--first-value 1.After:
{"code": "VALIDATION_ERROR", "message": "invalid input", "retryable": false, "fieldErrors": [ {"path": "secnd", "code": "unknown_flag", "message": "unknown flag --secnd", "received": "--secnd", "allowed": ["--first-value", "--second-value"], "source": "flag"}, {"path": "first_value", "code": "int_parsing", "message": "Input should be a valid integer, unable to parse string as an integer", "received": "x", "source": "flag"}]}tests/test_errors.pyhas one or more tests per acceptance criterion. 60 tests pass, and ruff and ty are clean.Merge Danger
Door: two-way. The output shape is new on an unreleased branch, and nothing outside this repo consumes it yet.
Blast Radius: contained. Groups (#67) and output formats (#70) build on this output and its exit codes.