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

pyiceberg/cli/console.py

@@ -54,6 +54,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 +236,12 @@ def location(ctx: Context, identifier: str) -> None:
 @click.pass_context
 @catch_exception()
 def version(ctx: Context) -> None:
-    """Print pyiceberg version."""
+    """Print the installed pyiceberg package number (deprecated, use --version instead)."""
+    click.echo(
+        "Deprecation warning: the `version` command is deprecated and will be removed in 0.13.0. "
+        "Please use `pyiceberg --version` instead.",
+        err=True,
+    )
     ctx.obj["output"].version(__version__)
 
 

tests/cli/test_console.py

@@ -69,10 +69,28 @@ def test_version_does_not_load_catalog(mocker: MockFixture) -> None:
     result = runner.invoke(run, ["version"])
 
     assert result.exit_code == 0
-    assert result.output == f"{__version__}\n"
+    assert result.stdout == f"{__version__}\n"
     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() -> None:
+    runner = CliRunner()
+    result = runner.invoke(run, ["version"])
+
+    assert result.exit_code == 0
+    assert __version__ in result.output
+    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)