feat(cli): make errors and help friendlier for new users

[latiefdole]

Description

Three small usability fixes aimed at people running the CLI for the first time. None of them change the output of a successful command, so existing scripts are unaffected.

1. Actionable API error messages

API failures printed the raw requests error, so a mistyped reference produced a bare 404 Client Error for url: ... with no indication of what to do next.

A hint is now printed under the original message for the statuses a user can act on:

• 403 - you may need to accept the competition rules first
• 404 - check the reference spelling, try kaggle search <query>
• 429 - you are rate limited, wait before retrying
• 5xx - attributed to Kaggle rather than to the user's command

The original error text is preserved in every case, and statuses without a hint are left exactly as they were.

2. Internal errors no longer surface as tracebacks

Only HTTPError / IOError / ValueError were caught in main(), so an internal KeyError or AttributeError reached the user as a Python traceback that reads like they did something wrong.

These are now caught and reported as a one-line summary plus a pointer to the issue tracker. A new --debug flag restores the full traceback for bug reports.

3. Examples in kaggle --help

kaggle --help listed the available commands but showed no examples. Added an epilog with the handful of commands a new user actually starts with: log in, list, download, submit.

Testing

• 1265 passed, 0 failed
• black --check . clean
• mypy clean on the changed files

New tests in tests/unit/test_cli_errors.py cover the hint text per status, the preserved message for statuses without a hint, the --debug behaviour (including that it is not forwarded to command functions), and that ValueError is still reported without the bug notice.

[sridipbasu]

Hello, @latiefdole

I am an external reviewer

I went through the PR and tested a few of the error cases. I noticed two things that I think might be worth fixing:

1. Some normal user errors are being shown as a CLI bug

For example, when authentication fails, the new message says:

This looks like a bug in the Kaggle CLI...

But authentication failure isn't necessarily a CLI bug. There are also some dataset errors where the API already gives a proper user-facing message, but they end up going through this same catch-all and get labelled as a CLI bug.

I feel this could be a bit confusing for users, and might also lead to unnecessary bug reports. Maybe these cases could be handled separately, or the message could be worded a little less strongly.

2. Small issue with the --debug suggestion

The error message tells the user to re-run with --debug, but putting it at the end doesn't actually work:

kaggle config view --debug

gives an unrecognized arguments error.

It actually needs to be:

kaggle --debug config view

Since a new user will probably just add --debug to the command they already ran, I think it would be better if the error message showed the exact usage, like kaggle --debug <command>, or if --debug could be accepted after the command too.

Apart from these, the changes looked good to me and the tests were passing. Just thought these two cases were worth pointing out before merging.

[latiefdole]

@sridipbasu Thanks for the review! I've updated the error message to be less strong about it being a CLI bug, and fixed the --debug suggestion to use the correct \kaggle --debug [command]\ format.

[stevemessick]

Great, thanks!

[stevemessick]

We might want better log/debug support. See line 967 of kaggle_api_extended.py.

[stevemessick]

/gcbrun