Add --prefix option for REST catalog (#3061)

<!-- Closes #3059 -->

# Rationale for this change
The CLI already supports `--uri` and `--credential`, but REST catalogs
that require `{prefix}` could only be configured via environment/config
file. This change adds a first-class `--prefix` CLI option and forwards
it to `load_catalog`.

## Are these changes tested?
Yes.
- Added `test_prefix_cli_option_forwarded_to_catalog` in
`tests/cli/test_console.py`.
- Verified with targeted pytest run.

## Are there any user-facing changes?
Yes.
- New CLI option: `--prefix`.
- Updated CLI docs in `mkdocs/docs/cli.md`.

Co-authored-by: Mrutunjay Kinagi <you@example.com>

Author: mrutunjay-kinagi

mkdocs/docs/cli.md

@@ -26,7 +26,7 @@ hide:
 
 Pyiceberg comes with a CLI that's available after installing the `pyiceberg` package.
 
-You can pass the path to the Catalog using the `--uri` and `--credential` argument, but it is recommended to setup a `~/.pyiceberg.yaml` config as described in the [Catalog](configuration.md) section.
+You can pass the path to the Catalog using `--uri` and `--credential`. For REST catalogs that require a path prefix, you can also set `--prefix`. It is still recommended to set up a `~/.pyiceberg.yaml` config as described in the [Catalog](configuration.md) section.
 
 ```sh
 ➜  pyiceberg --help
@@ -39,6 +39,7 @@ Options:
   --ugi TEXT
   --uri TEXT
   --credential TEXT
+  --prefix TEXT
   --help                Show this message and exit.
 
 Commands:

pyiceberg/cli/console.py

@@ -66,6 +66,7 @@ def wrapper(*args: Any, **kwargs: Any):  # type: ignore
 @click.option("--ugi")
 @click.option("--uri")
 @click.option("--credential")
+@click.option("--prefix")
 @click.pass_context
 def run(
     ctx: Context,
@@ -76,6 +77,7 @@ def run(
     ugi: str | None,
     uri: str | None,
     credential: str | None,
+    prefix: str | None,
 ) -> None:
     logging.basicConfig(
         level=getattr(logging, log_level.upper()),
@@ -89,6 +91,8 @@ def run(
         properties[URI] = uri
     if credential:
         properties["credential"] = credential
+    if prefix:
+        properties["prefix"] = prefix
 
     ctx.ensure_object(dict)
     if output == "text":

tests/cli/test_console.py

@@ -1029,3 +1029,18 @@ def test_log_level_cli_overrides_env(mocker: MockFixture) -> None:
     mock_basicConfig.assert_called_once()
     call_kwargs = mock_basicConfig.call_args[1]
     assert call_kwargs["level"] == logging.ERROR
+
+
+def test_prefix_cli_option_forwarded_to_catalog(mocker: MockFixture) -> None:
+    mock_basicConfig = mocker.patch("logging.basicConfig")
+    mock_catalog = MagicMock(spec=InMemoryCatalog)
+    mock_catalog.list_tables.return_value = []
+    mock_catalog.list_namespaces.return_value = []
+    mock_load_catalog = mocker.patch("pyiceberg.cli.console.load_catalog", return_value=mock_catalog)
+
+    runner = CliRunner()
+    result = runner.invoke(run, ["--catalog", "rest", "--uri", "https://example.invalid", "--prefix", "v1/ws", "list"])
+
+    assert result.exit_code == 0
+    mock_basicConfig.assert_called_once()
+    mock_load_catalog.assert_called_once_with("rest", uri="https://example.invalid", prefix="v1/ws")