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

pyiceberg/cli/console.py

@@ -33,6 +33,7 @@
 from pyiceberg.io import WAREHOUSE
 from pyiceberg.table import TableProperties
 from pyiceberg.table.refs import SnapshotRef, SnapshotRefType
+from pyiceberg.utils.deprecated import deprecation_message
 from pyiceberg.utils.properties import property_as_int
 
 
@@ -54,6 +55,7 @@ def wrapper(*args: Any, **kwargs: Any):  # type: ignore
 
 
 @click.group()
+@click.version_option(__version__, message="%(version)s")
 @click.option("--catalog")
 @click.option("--verbose", type=click.BOOL)
 @click.option("--output", type=click.Choice(["text", "json"]), default="text")
@@ -235,7 +237,17 @@ def location(ctx: Context, identifier: str) -> None:
 @click.pass_context
 @catch_exception()
 def version(ctx: Context) -> None:
-    """Print pyiceberg version."""
+    """Print pyiceberg's installed package number (deprecated, use ``--version`` instead)."""
+    deprecation_message(
+        deprecated_in="0.11.0",
+        removed_in="1.0.0",
+        help_message="Please use `pyiceberg --version` instead of `pyiceberg version`",
+    )
+    click.echo(
+        "Deprecation warning: the `version` command is deprecated and will be removed in 1.0.0. "
+        "Please use `pyiceberg --version` instead.",
+        err=True,
+    )
     ctx.obj["output"].version(__version__)
 
 

tests/cli/test_console.py

@@ -62,17 +62,41 @@ def test_hive_catalog_missing_uri_shows_helpful_error(mocker: MockFixture) -> No
     assert "'uri'" not in result.output
 
 
+@pytest.mark.filterwarnings(
+    "ignore:Deprecated in 0.11.0, will be removed in 1.0.0. "
+    "Please use `pyiceberg --version` instead of `pyiceberg version`:DeprecationWarning"
+)
 def test_version_does_not_load_catalog(mocker: MockFixture) -> None:
     mock_load_catalog = mocker.patch("pyiceberg.cli.console.load_catalog", side_effect=Exception("should not be called"))
 
     runner = CliRunner()
     result = runner.invoke(run, ["version"])
 
     assert result.exit_code == 0
-    assert result.output == f"{__version__}\n"
+    assert __version__ in result.output
     mock_load_catalog.assert_not_called()
 
 
+def test_version_flag() -> None:
+    runner = CliRunner()
+    result = runner.invoke(run, ["--version"])
+
+    assert result.exit_code == 0
+    assert result.output == f"{__version__}\n"
+
+
+def test_version_command_emits_deprecation_warning(mocker: MockFixture) -> None:
+    mocker.patch("pyiceberg.cli.console.load_catalog")
+
+    runner = CliRunner()
+    with pytest.warns(DeprecationWarning, match="Please use `pyiceberg --version` instead of `pyiceberg version`"):
+        result = runner.invoke(run, ["version"])
+
+    assert result.exit_code == 0
+    assert "deprecated" in result.output.lower()
+    assert "pyiceberg --version" in result.output
+
+
 @pytest.fixture(autouse=True)
 def env_vars(mocker: MockFixture) -> None:
     mocker.patch.dict(os.environ, MOCK_ENVIRONMENT)