feat(cli): deprecate version command in favor of --version flag

[chrisqiqiu]

Closes #3160

Rationale for this change

The pyiceberg version subcommand is non-standard. Most CLI tools use --version instead.
This PR adds --version via Click's built-in click.version_option() and deprecates the
old version subcommand with a visible warning message, following the project's deprecation
conventions.

Note: I chose removed_in="1.0.0" to match the existing deprecation in the REST catalog
(see pyiceberg/catalog/rest/__init__.py), but happy to adjust if a different version is preferred.

Are these changes tested?

Yes. Added two new tests:

• test_version_flag — verifies pyiceberg --version works correctly
• test_version_command_emits_deprecation_warning — verifies the old command still works but emits a DeprecationWarning and prints a visible deprecation notice to stderr

Updated the existing test_version_does_not_load_catalog to account for the deprecation warning.

Are there any user-facing changes?

Yes:

• pyiceberg --version is now available
• pyiceberg version still works but prints a deprecation warning
• Help text updated to reflect the deprecation

[rambleraptor]

This looks great to me. Thanks for this!

[geruh]

Thanks for iterating on the @chrisqiqiu! Just one small comment everything else looks good to me.

[rambleraptor]

Looks good to me! Thanks for doing this!

[github-actions]

This pull request has been marked as stale due to 30 days of inactivity. It will be closed in 1 week if no further activity occurs. If you think that's incorrect or this pull request requires a review, please simply write any comment. If closed, you can revive the PR at any time and @mention a reviewer or discuss it on the dev@iceberg.apache.org list. Thank you for your contributions.

[chrisqiqiu]

Hi @geruh , when you have a moment, could you pls take another look to see if the changes addressed your feedback? Thanks!

[kevinjqliu]

LGTM!

[kevinjqliu]

Thanks for the PR @chrisqiqiu and thank you for the review @rambleraptor @geruh