tree b12c9ba57bd619291f7c36a779563321fdf3d4ac
parent e4869850b5632b29bc65cd2d549bfda9fb22d27c
author Chris Qiu <churchqq030@hotmail.com> 1779642887 +0800
committer GitHub <noreply@github.com> 1779642887 -0700
gpgsig -----BEGIN PGP SIGNATURE-----
 
 wsFcBAABCAAQBQJqEzIHCRC1aQ7uu5UhlAAAr9EQAKOHL5RfO3EywOtZeU+Z1Fnl
 si7PqxrwsqVcFXvmnYyRyPhJWUzF3a6DwN5gVAbCjp3VzbRTOMNocul00p/CXngO
 sMX3R/UVvQiDTaTVT7hfAvqVoWH+ku798NsBnf4l/CultWFIHkh25W5T9rjh0/+U
 Q7Xm5k28VVmmOHqNvvfpgI7R0pUks8qLo+6sjmVRFvsbXMhblOcb4Dxd/82fIlCR
 oOI4c+BPhzRh6bqr9A8RYzsZwBKMZFkX2c5XgkXaLdFpUkVn9m2dSr0xNpVP5JyP
 wZ2BGhaLo62A/u5Iumy2u1O1QbfwZXt63GzOCBEj6ptUaXVFAwY7oNO/S67qsgBW
 T18E4/hMUhLDzA8YTrNXCayXFyMQJyrlg2dHnKym/ez1/NhsWINk9ITTy1lTpPGu
 FbW8CI6Eb66GPDsBR6DjDy0v6sYER2Z25GTB9lb7le75jL/XBVeCQrqB0076pack
 Pg6oppmCiXVXH81jlpclPFCsgDBX9+Yl0t0fUHRqNi7GVszG4HknHfnw8haYp+0j
 /EdqGJJ6OPnVHyI5ntSzU9omOVjDqlWmBr0eSfZDock7d7/7vUVBF9mtpsWWyo+A
 GwuPOsTI+V4qrdQRm0KzWApmNMH4V/T7pdxSC3vpUKhwVqkP7ZCsjBXT65GzW3pG
 11zjtF9G1ZMirxuundlV
 =3fk0
 -----END PGP SIGNATURE-----
 

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

Closes #3160

<!--
Thanks for opening a pull request!
-->

<!-- In the case this PR will resolve an issue, please replace
${GITHUB_ISSUE_ID} below with the actual Github issue id. -->
<!-- Closes #${GITHUB_ISSUE_ID} -->

# 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.
<img width="884" height="116" alt="Screenshot 2026-03-29 at 11 47 37 pm"
src="https://github.com/user-attachments/assets/cb4fe218-3671-41a3-83db-e90933271bb1"
/>

<img width="884" height="116" alt="Screenshot 2026-03-29 at 11 59 54 pm"
src="https://github.com/user-attachments/assets/10bafeaa-9bea-4d81-b7e1-0ec2abce571e"
/>


## 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
<!-- In the case of user-facing changes, please add the changelog label.
-->

---------

Co-authored-by: Kevin Liu <kevinjqliu@users.noreply.github.com>