You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@iceberg.apache.org by "chrisqiqiu (via GitHub)" <gi...@apache.org> on 2026/03/29 15:56:05 UTC
[PR] feat(cli): deprecate version command in favor of --version flag [iceberg-python]
chrisqiqiu opened a new pull request, #3206:
URL: https://github.com/apache/iceberg-python/pull/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" />
## 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. -->
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] feat(cli): deprecate version command in favor of --version flag [iceberg-python]
Posted by "kevinjqliu (via GitHub)" <gi...@apache.org>.
kevinjqliu commented on code in PR #3206:
URL: https://github.com/apache/iceberg-python/pull/3206#discussion_r3295006759
##########
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
Review Comment:
```suggestion
assert result.stdout == f"{__version__}\n"
assert "deprecated" in result.stderr.lower()
assert "pyiceberg --version" in result.stderr
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] feat(cli): deprecate version command in favor of --version flag [iceberg-python]
Posted by "chrisqiqiu (via GitHub)" <gi...@apache.org>.
chrisqiqiu commented on code in PR #3206:
URL: https://github.com/apache/iceberg-python/pull/3206#discussion_r3028844216
##########
pyiceberg/cli/console.py:
##########
@@ -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. "
Review Comment:
i have changed it to 0.13.0
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] feat(cli): deprecate version command in favor of --version flag [iceberg-python]
Posted by "github-actions[bot] (via GitHub)" <gi...@apache.org>.
github-actions[bot] commented on PR #3206:
URL: https://github.com/apache/iceberg-python/pull/3206#issuecomment-4523584018
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.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] feat(cli): deprecate version command in favor of --version flag [iceberg-python]
Posted by "kevinjqliu (via GitHub)" <gi...@apache.org>.
kevinjqliu merged PR #3206:
URL: https://github.com/apache/iceberg-python/pull/3206
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] feat(cli): deprecate version command in favor of --version flag [iceberg-python]
Posted by "kevinjqliu (via GitHub)" <gi...@apache.org>.
kevinjqliu commented on code in PR #3206:
URL: https://github.com/apache/iceberg-python/pull/3206#discussion_r3295006759
##########
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
Review Comment:
```suggestion
assert result.stdout == f"{__version__}\n"
assert "deprecated" in result.stderr.lower()
assert "pyiceberg --version" in result.stderr
```
nit: be explicit about stdout vs stderr
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] feat(cli): deprecate version command in favor of --version flag [iceberg-python]
Posted by "chrisqiqiu (via GitHub)" <gi...@apache.org>.
chrisqiqiu commented on code in PR #3206:
URL: https://github.com/apache/iceberg-python/pull/3206#discussion_r3033255411
##########
pyiceberg/cli/console.py:
##########
@@ -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)."""
Review Comment:
i have removed deprecation_message function and backticks.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] feat(cli): deprecate version command in favor of --version flag [iceberg-python]
Posted by "chrisqiqiu (via GitHub)" <gi...@apache.org>.
chrisqiqiu commented on PR #3206:
URL: https://github.com/apache/iceberg-python/pull/3206#issuecomment-4527706533
Hi @geruh , when you have a moment, could you pls take another look to see if the changes addressed your feedback? Thanks!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] feat(cli): deprecate version command in favor of --version flag [iceberg-python]
Posted by "geruh (via GitHub)" <gi...@apache.org>.
geruh commented on code in PR #3206:
URL: https://github.com/apache/iceberg-python/pull/3206#discussion_r3012842612
##########
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")
Review Comment:
Do we still need to mock the `load_catalog` with the previous change you made in #3146?
##########
pyiceberg/cli/console.py:
##########
@@ -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)."""
Review Comment:
Feels like there's a lot of deprecation here for the CLI command.
The docstring change is good since it shows with `--help` but let's drop the backticks since they don't render in help and keep the original wording. We probably don't need deprecation_message function either since users interact via CLI and the warning would be invisible to them by default.
##########
pyiceberg/cli/console.py:
##########
@@ -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. "
Review Comment:
+1 to this!
##########
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
Review Comment:
Nit: `result.stdout` gives stdout without the err mixed in. Do we still need it?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] feat(cli): deprecate version command in favor of --version flag [iceberg-python]
Posted by "rambleraptor (via GitHub)" <gi...@apache.org>.
rambleraptor commented on code in PR #3206:
URL: https://github.com/apache/iceberg-python/pull/3206#discussion_r3012682018
##########
pyiceberg/cli/console.py:
##########
@@ -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. "
Review Comment:
In the past, we've been doing two versions. That would be a removal in 0.13.0
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] feat(cli): deprecate version command in favor of --version flag [iceberg-python]
Posted by "chrisqiqiu (via GitHub)" <gi...@apache.org>.
chrisqiqiu commented on code in PR #3206:
URL: https://github.com/apache/iceberg-python/pull/3206#discussion_r3028846458
##########
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")
Review Comment:
i have removed it
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] feat(cli): deprecate version command in favor of --version flag [iceberg-python]
Posted by "chrisqiqiu (via GitHub)" <gi...@apache.org>.
chrisqiqiu commented on code in PR #3206:
URL: https://github.com/apache/iceberg-python/pull/3206#discussion_r3028838378
##########
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
Review Comment:
You mean we'd better use result.stdout so that we can keep original exact match assertion , right? I have updated it. Happy to change if there's a preferred approach.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] feat(cli): deprecate version command in favor of --version flag [iceberg-python]
Posted by "chrisqiqiu (via GitHub)" <gi...@apache.org>.
chrisqiqiu commented on code in PR #3206:
URL: https://github.com/apache/iceberg-python/pull/3206#discussion_r3104945139
##########
pyiceberg/cli/console.py:
##########
@@ -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)."""
Review Comment:
Changed the wording.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] feat(cli): deprecate version command in favor of --version flag [iceberg-python]
Posted by "geruh (via GitHub)" <gi...@apache.org>.
geruh commented on code in PR #3206:
URL: https://github.com/apache/iceberg-python/pull/3206#discussion_r3083919393
##########
pyiceberg/cli/console.py:
##########
@@ -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)."""
Review Comment:
```suggestion
"""Print the installed pyiceberg package version (deprecated, use --version instead)."""
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] feat(cli): deprecate version command in favor of --version flag [iceberg-python]
Posted by "kevinjqliu (via GitHub)" <gi...@apache.org>.
kevinjqliu commented on PR #3206:
URL: https://github.com/apache/iceberg-python/pull/3206#issuecomment-4529446551
Thanks for the PR @chrisqiqiu and thank you for the review @rambleraptor @geruh
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org