(iceberg-python) branch main updated: feat(cli): deprecate version command in favor of --version flag (#3206)

[kevinjqliu]

This is an automated email from the ASF dual-hosted git repository.

kevinjqliu pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iceberg-python.git


The following commit(s) were added to refs/heads/main by this push:
     new 55887b46c feat(cli): deprecate version command in favor of --version 
flag (#3206)
55887b46c is described below

commit 55887b46ca70a1e03419873348f2f55d8491ada5
Author: Chris Qiu <churchqq...@hotmail.com>
AuthorDate: Mon May 25 01:14:47 2026 +0800

    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 <kevinjq...@users.noreply.github.com>
---
 pyiceberg/cli/console.py  |  8 +++++++-
 tests/cli/test_console.py | 20 +++++++++++++++++++-
 2 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/pyiceberg/cli/console.py b/pyiceberg/cli/console.py
index e7a2ceb41..3feed9fb2 100644
--- a/pyiceberg/cli/console.py
+++ b/pyiceberg/cli/console.py
@@ -54,6 +54,7 @@ def catch_exception() -> Callable:  # 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 version. 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__)
 
 
diff --git a/tests/cli/test_console.py b/tests/cli/test_console.py
index 5dd1a7bc3..27a1bfebe 100644
--- a/tests/cli/test_console.py
+++ b/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 result.stdout == f"{__version__}\n"
+    assert "deprecated" in result.stderr.lower()
+    assert "pyiceberg --version" in result.stderr
+
+
 @pytest.fixture(autouse=True)
 def env_vars(mocker: MockFixture) -> None:
     mocker.patch.dict(os.environ, MOCK_ENVIRONMENT)