arraylake 1.2.0__tar.gz → 1.5.0__tar.gz

{arraylake-1.2.0 → arraylake-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: arraylake
-Version: 1.2.0
+Version: 1.5.0
 Summary: Python client for ArrayLake
 Project-URL: Documentation, https://docs.earthmover.io/
 Project-URL: Changelog, https://docs.earthmover.io/changelog
@@ -14,25 +14,25 @@ Requires-Python: <3.15,>=3.12
 Requires-Dist: click<9.0,>=8.1.3
 Requires-Dist: donfig<1.0,>=0.7
 Requires-Dist: httpx<0.29,>=0.23
-Requires-Dist: icechunk<3.0.0,>=2.0.6
+Requires-Dist: icechunk<3.0.0,>=2.2.2
 Requires-Dist: numpy<3.0,>=1.23
 Requires-Dist: packaging<27.0,>=23.0
 Requires-Dist: pydantic[email]<3.0,>=2.9
 Requires-Dist: python-dateutil<3.0,>=2.8
 Requires-Dist: rich<16.0,>=12.6
 Requires-Dist: ruamel-yaml<1.0,>=0.17
-Requires-Dist: structlog<26.0,>=24.1
+Requires-Dist: structlog<27.0,>=24.1
 Requires-Dist: typer<1.0,>=0.12.0
 Requires-Dist: zarr<4.0,>=3.1.0
+Provides-Extra: iceberg
+Requires-Dist: pyiceberg<0.13,>=0.11; extra == 'iceberg'
 Provides-Extra: maximal
-Requires-Dist: cf-xarray>=0.10.4; extra == 'maximal'
 Requires-Dist: xarray[accel,etc,io,parallel]>=2024.10.0; extra == 'maximal'
 Provides-Extra: obstore
 Requires-Dist: obstore>=0.9.2; extra == 'obstore'
 Provides-Extra: openeo
-Requires-Dist: openeo<0.40,>=0.35.0; extra == 'openeo'
+Requires-Dist: openeo<0.52,>=0.35.0; extra == 'openeo'
 Provides-Extra: xarray
-Requires-Dist: cf-xarray>=0.10.4; extra == 'xarray'
 Requires-Dist: xarray>=2024.10.0; extra == 'xarray'
 Description-Content-Type: text/markdown
 

{arraylake-1.2.0 → arraylake-1.5.0}/arraylake/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.2.0'
-__version_tuple__ = version_tuple = (1, 2, 0)
+__version__ = version = '1.5.0'
+__version_tuple__ = version_tuple = (1, 5, 0)
 
 __commit_id__ = commit_id = None

{arraylake-1.2.0 → arraylake-1.5.0}/arraylake/api_utils.py

@@ -84,6 +84,25 @@ def _get_proxy_from_env() -> str | None:
     return None
 
 
+# Client name reported in the X-Arraylake-Client header. Defaults to the Python
+# library; the CLI entry point overrides it so server logs can tell them apart.
+_client_name: str = "python"
+
+
+def set_client_name(name: str) -> None:
+    """Override the client name sent in the ``X-Arraylake-Client`` header.
+
+    Must be called before any ``ArraylakeHttpClient`` is constructed to take effect,
+    since headers are baked in at construction time.
+    """
+    global _client_name
+    _client_name = name
+
+
+def get_client_name() -> str:
+    return _client_name
+
+
 @functools.cache
 def _get_session_id() -> str:
     """Session ID for this Python process.
@@ -116,10 +135,20 @@ class ClientKey:
 # the global cache of httpx clients
 _GLOBAL_CLIENTS: dict[ClientKey, httpx.AsyncClient] = {}
 
+# one lock per event loop, so concurrent callers on a cold cache build one client, not two
+_CLIENT_CREATION_LOCKS: dict[asyncio.AbstractEventLoop, asyncio.Lock] = {}
+
 # this is a cache to use hold asyncio tasks so they are not garbage collected before finishing
 background_tasks: set[asyncio.Task] = set()
 
 
+def _creation_lock(loop: asyncio.AbstractEventLoop) -> asyncio.Lock:
+    lock = _CLIENT_CREATION_LOCKS.get(loop)
+    if lock is None:
+        lock = _CLIENT_CREATION_LOCKS[loop] = asyncio.Lock()
+    return lock
+
+
 async def get_client(
     loop: asyncio.AbstractEventLoop,
     api_url: str,
@@ -162,7 +191,13 @@ async def get_client(
         proxy,
     )
     await logger.adebug("%i httpx clients present in cache.", len(_GLOBAL_CLIENTS))
-    if key not in _GLOBAL_CLIENTS:
+    if (client := _GLOBAL_CLIENTS.get(key)) is not None:
+        await logger.adebug("Client already present %s. Loop id %s.", key, id(loop))
+        return client
+
+    async with _creation_lock(loop):
+        if (client := _GLOBAL_CLIENTS.get(key)) is not None:
+            return client
         await logger.adebug("Creating new httpx client %s. Loop id %s.", key, id(loop))
         transport = AsyncRetryTransport(
             max_keepalive_connections=max_keepalive_connections,
@@ -180,15 +215,12 @@ async def get_client(
             verify=verify_ssl,
             cert=ssl_cafile,
         ).__aenter__()
-        weakref.finalize(client, close_client, key)
+        weakref.finalize(client, close_client, key, id(client))
         _GLOBAL_CLIENTS[key] = client
-    else:
-        await logger.adebug("Client already present %s. Loop id %s.", key, id(loop))
-    assert key in _GLOBAL_CLIENTS
-    return _GLOBAL_CLIENTS[key]
+        return client
 
 
-def close_client(key: ClientKey):
+def close_client(key: ClientKey, client_id: int) -> None:
     """
     This is a finalizer function that is called when a global client is
     garbage collected. It cleanly closes the client for the specified key.
@@ -205,11 +237,13 @@ def close_client(key: ClientKey):
     Note: logging in this function runs the risk of conflicting with pytest#5502. For
     this reason, we have removed debug log statements.
     """
-    client = _GLOBAL_CLIENTS.pop(key, None)
-
-    if client is None:
+    cached = _GLOBAL_CLIENTS.get(key)
+    # A newer client can own this key. Only the client that registered this finalizer may evict it.
+    if cached is None or id(cached) != client_id:
         return
 
+    client = _GLOBAL_CLIENTS.pop(key)
+
     if client.is_closed:
         return
 
@@ -317,6 +351,9 @@ class ArraylakeHttpClient:
             # technically we don't enforce this, for now it's for debugging purposes
             "client-name": "arraylake-python-client",
             "client-version": arraylake.__version__,
+            "x-arraylake-client": f"{get_client_name()}/{arraylake.__version__}",
+            "x-arraylake-source": get_client_name(),
+            "user-agent": f"arraylake-{get_client_name()}/{arraylake.__version__}",
             "arraylake-session-id": _get_session_id(),
         }
 
@@ -448,6 +485,7 @@ def _exception_log_debug(request: httpx.Request, response: httpx.Response):
 
 
 _emitted_deprecation_warnings: set[str] = set()
+_emitted_user_warnings: set[str] = set()
 
 
 def handle_response(response: httpx.Response):
@@ -456,6 +494,10 @@ def handle_response(response: httpx.Response):
     if deprecation_msg and deprecation_msg not in _emitted_deprecation_warnings:
         _emitted_deprecation_warnings.add(deprecation_msg)
         warnings.warn(deprecation_msg, DeprecationWarning, stacklevel=2)
+    warning_msg = response.headers.get("X-Arraylake-Warning")  # Service-sent user-facing warnings
+    if warning_msg and warning_msg not in _emitted_user_warnings:
+        _emitted_user_warnings.add(warning_msg)
+        warnings.warn(warning_msg, UserWarning, stacklevel=2)
     try:
         response.raise_for_status()
     except httpx.RequestError as exc:

{arraylake-1.2.0 → arraylake-1.5.0}/arraylake/cli/auth.py

@@ -2,7 +2,6 @@ import typer
 from rich.align import Align
 from rich.panel import Panel
 
-from arraylake import config
 from arraylake.cli.utils import (
     coro,
     error_console,
@@ -17,11 +16,26 @@ auth = typer.Typer(help="Manage Arraylake authentication")
 
 NOT_LOGGED_IN_MESSAGE = "⚠️  Not logged in, please log in with: `arraylake auth login`"
 
+SERVICE_URI_OPTION = typer.Option(
+    None,
+    "--service-uri",
+    help=(
+        "Arraylake API endpoint to act on, e.g. **https://api.dev.earthmover.io**. Defaults to the configured "
+        "**service.uri**. Tokens are stored per endpoint, so this need not be persisted to config — unless "
+        "**service.token_path** is set, which makes all endpoints share one token file."
+    ),
+)
+
+
+def _resolve_service_uri(service_uri: str | None) -> str:
+    return service_uri if service_uri else default_service_uri()
+
 
 @auth.command()
 @coro  # type: ignore
 async def login(
     browser: bool = typer.Option(True, "--browser/--no-browser", " /--nobrowser", help="Whether to automatically open a browser window."),
+    service_uri: str | None = SERVICE_URI_OPTION,
 ):
     """**Log in** to Arraylake
 
@@ -34,17 +48,23 @@ async def login(
         ```
         $ arraylake auth login --no-browser
         ```
+
+    - Log in to a non-default Arraylake deployment
+
+        ```
+        $ arraylake auth login --service-uri https://api.dev.earthmover.io
+        ```
     """
     print_logo()
-    handler = get_auth_handler(api_endpoint=default_service_uri())
+    handler = get_auth_handler(api_endpoint=_resolve_service_uri(service_uri))
     await handler.login(browser=browser)
 
 
 @auth.command()
 @coro  # type: ignore
-async def refresh() -> None:
+async def refresh(service_uri: str | None = SERVICE_URI_OPTION) -> None:
     """**Refresh** Arraylake's auth token"""
-    handler = get_auth_handler(api_endpoint=default_service_uri())
+    handler = get_auth_handler(api_endpoint=_resolve_service_uri(service_uri))
     if handler.tokens is not None:
         try:
             await handler.refresh_token()
@@ -57,7 +77,7 @@ async def refresh() -> None:
 
 @auth.command()
 @coro  # type: ignore
-async def logout() -> None:
+async def logout(service_uri: str | None = SERVICE_URI_OPTION) -> None:
     """**Logout** of Arraylake
 
     **Examples**
@@ -67,9 +87,15 @@ async def logout() -> None:
         ```
         $ arraylake auth logout
         ```
+
+    - Log out of a non-default Arraylake deployment
+
+        ```
+        $ arraylake auth logout --service-uri https://api.dev.earthmover.io
+        ```
     """
     try:
-        handler = get_auth_handler(api_endpoint=default_service_uri())
+        handler = get_auth_handler(api_endpoint=_resolve_service_uri(service_uri))
         await handler.logout()
     except AuthException as e:
         error_console.print(e)
@@ -77,14 +103,15 @@ async def logout() -> None:
 
 
 @auth.command()
-@coro
-async def status():
+@coro  # type: ignore
+async def status(service_uri: str | None = SERVICE_URI_OPTION):
     """Verify and display information about your authentication **status**"""
+    endpoint = _resolve_service_uri(service_uri)
     print_logo_mini()
-    rich_console.print(Align(Panel.fit(f"[bold]Arraylake API Endpoint[/bold]: {config.get('service.uri')}"), align="center"))
+    rich_console.print(Align(Panel.fit(f"[bold]Arraylake API Endpoint[/bold]: {endpoint}"), align="center"))
 
     try:
-        handler = get_auth_handler(api_endpoint=default_service_uri())
+        handler = get_auth_handler(api_endpoint=endpoint)
         user = await handler._get_user()  # checks that the new tokens are valid
         rich_console.print(Align(f"[green][bold]🔓 Logged in as {user.email}[/green][/bold]", align="center"))
     except AuthException:
@@ -93,9 +120,9 @@ async def status():
 
 
 @auth.command()
-def token():
+def token(service_uri: str | None = SERVICE_URI_OPTION):
     """Display your authentication **token**"""
-    handler = get_auth_handler(api_endpoint=default_service_uri())
+    handler = get_auth_handler(api_endpoint=_resolve_service_uri(service_uri))
     if handler.tokens is None:
         rich_console.print(Align(f"[yellow]{NOT_LOGGED_IN_MESSAGE}[/yellow]", align="center"))
         raise typer.Exit(code=1)

{arraylake-1.2.0 → arraylake-1.5.0}/arraylake/cli/compute.py

@@ -28,7 +28,16 @@ def _services_table(services, org):
     table.add_column("URL", justify="right", style="green", min_width=10)
     table.add_column("Status", justify="right", style="green", min_width=10)
 
-    status_colors = {"available": "green", "progressing": "yellow", "error": "red", "unknown": "grey"}
+    status_colors = {
+        "available": "green",
+        "progressing": "yellow",
+        "error": "red",
+        "quota_exceeded": "red",
+        "sleeping": "cyan",
+        "stopped": "grey",
+        "suspended": "grey",
+        "unknown": "grey",
+    }
 
     for service in services:
         table.add_row(
@@ -38,7 +47,9 @@ def _services_table(services, org):
             str(service.config.is_public),
             service.url,
             service.status,
-            style=status_colors[service.status],
+            # .get, because the API owns this vocabulary and adds to it: an older client must
+            # render a status it has never heard of, not refuse to list anything at all.
+            style=status_colors.get(service.status, "grey"),
         )
 
     return table
@@ -47,7 +58,8 @@ def _services_table(services, org):
 @app.command(name="enable")
 def enable_service(
     org: str = typer.Argument(..., help="The organization to enable the service for"),
-    protocol: str = typer.Argument(..., help="The protocol to enable. Must be one of: dap2, edr, wms, tiles, zarr"),
+    protocol: str = typer.Argument(..., help="The protocol to enable. Must be one of: dap2, edr, wms, tiles, zarr, openeo, sql"),
+    sku_code: str = typer.Option(..., "--sku-code", "-s", help="The compute shape to run the service on, e.g. xs"),
     is_public: bool = typer.Option(False, help="Whether the service is public"),
     deployment_name: str | None = typer.Option(
         None,
@@ -63,13 +75,13 @@ def enable_service(
     - Enable a new DAP service for _my-org_
 
         ```
-        $ arraylake compute enable my-org dap2
+        $ arraylake compute enable my-org dap2 --sku-code xs
         ```
 
     - Enable a tiles service with a custom deployment name
 
         ```
-        $ arraylake compute enable my-org tiles --deployment-name my-tiles
+        $ arraylake compute enable my-org tiles --sku-code s --deployment-name my-tiles
         ```
     """
     kwargs = {}
@@ -77,7 +89,7 @@ def enable_service(
         kwargs["deployment_name"] = deployment_name
 
     with simple_progress(f"Creating [bold]{protocol}[/bold] service for [bold]{org}[/bold]..."):
-        status = Client().get_services(org).enable(protocol, is_public, **kwargs)
+        status = Client().get_services(org).enable(protocol, is_public, sku_code=sku_code, **kwargs)
     rich_console.print(status["message"])
 
 
@@ -183,6 +195,44 @@ async def get_service_logs(
         raise typer.Exit(code=1)
 
 
+@app.command(name="update")
+def update_service(
+    org: str = typer.Argument(..., help="The organization that the service belongs to"),
+    service_id: str = typer.Argument(..., help="The service ID to update"),
+    sku: str | None = typer.Option(None, "--sku", help="The compute shape (SKU code) to resize the service to"),
+    min_replicas: int | None = typer.Option(None, min=0, help="The minimum number of replicas the service scales down to"),
+    max_replicas: int | None = typer.Option(None, min=1, help="The maximum number of replicas the service scales up to"),
+):
+    """**Update** a running service's shape or scaling. Omitted options keep their current values.
+
+    **Examples**
+
+    - Resize a service with ID edr-1234567 to a different compute shape
+
+        ```
+        $ arraylake compute update my-org edr-1234567 --sku medium
+        ```
+
+    - Change the scaling bounds of a service
+
+        ```
+        $ arraylake compute update my-org edr-1234567 --min-replicas 2 --max-replicas 10
+        ```
+    """
+    if sku is None and min_replicas is None and max_replicas is None:
+        rich_console.print("[bold red]Nothing to update: pass at least one of --sku, --min-replicas, --max-replicas[/bold red]")
+        raise typer.Exit(code=1)
+
+    with simple_progress(f"Updating service [bold]{service_id}[/bold]..."):
+        deployment = Client().get_services(org).update(service_id, sku_code=sku, min_replicas=min_replicas, max_replicas=max_replicas)
+
+    config = deployment.config
+    rich_console.print(
+        f"Service [bold]{deployment.name}[/bold] updated: "
+        f"sku={config.sku_code}, min_replicas={config.min_replicas}, max_replicas={config.max_replicas}"
+    )
+
+
 @app.command(name="disable")
 def disable_service(
     org: str = typer.Argument(..., help="The organization that the service belongs to"),

arraylake-1.5.0/arraylake/cli/iceberg.py

@@ -0,0 +1,255 @@
+"""Namespace administration and table discovery for Arraylake's Iceberg catalog."""
+
+import json
+import re
+from enum import StrEnum
+from typing import Any
+
+import typer
+from rich.table import Table
+
+from arraylake import Client
+from arraylake.cli.utils import rich_console
+from arraylake.types import RepoVisibility
+
+app = typer.Typer(help="Manage Iceberg namespaces and discover tables", no_args_is_help=True)
+namespace_app = typer.Typer(help="Manage Iceberg namespaces", no_args_is_help=True)
+table_app = typer.Typer(help="Discover and describe Iceberg tables", no_args_is_help=True)
+app.add_typer(namespace_app, name="namespace")
+app.add_typer(table_app, name="table")
+
+
+class Output(StrEnum):
+    rich = "rich"
+    json = "json"
+
+
+class NamespaceSort(StrEnum):
+    relevance = "relevance"
+    updated = "updated"
+    created = "created"
+    name = "name"
+    tables = "tables"
+
+
+class TableSort(StrEnum):
+    relevance = "relevance"
+    updated = "updated"
+    created = "created"
+    name = "name"
+
+
+class Direction(StrEnum):
+    asc = "asc"
+    desc = "desc"
+
+
+def _table_identifier(namespace: str, table: str) -> str:
+    """Format exact names; quoted components escape double quotes by doubling them."""
+
+    def quote(name: str) -> str:
+        return name if re.fullmatch(r"[A-Za-z0-9_-]+", name) else '"' + name.replace('"', '""') + '"'
+
+    return f"{quote(namespace)}.{quote(table)}"
+
+
+def _parse_table_identifier(identifier: str) -> tuple[str, str]:
+    # Keep this grammar in sync with the app's iceberg-identifier.ts formatter.
+    component = r'(?:[A-Za-z0-9_-]+|"(?:[^"]|"")+")'
+    match = re.fullmatch(rf"({component})\.({component})", identifier)
+    if match is None:
+        raise typer.BadParameter(
+            "Expected NAMESPACE.TABLE. Double-quote names containing dots or special characters, "
+            "and wrap the identifier in single quotes in your shell, e.g. '\"namespace.v2\".table'.",
+            param_hint="IDENTIFIER",
+        )
+    namespace, table = (part[1:-1].replace('""', '"') if part.startswith('"') else part for part in match.groups())
+    return namespace, table
+
+
+def _json_object(value: str | None, option: str) -> dict[str, Any] | None:
+    if value is None:
+        return None
+    try:
+        result = json.loads(value)
+    except ValueError as exc:
+        raise typer.BadParameter("Expected a JSON object", param_hint=option) from exc
+    if not isinstance(result, dict):
+        raise typer.BadParameter("Expected a JSON object", param_hint=option)
+    return result
+
+
+def _show(value: Any, output: Output) -> None:
+    if output == Output.json:
+        typer.echo(json.dumps(value))
+    else:
+        rich_console.print(value)
+
+
+def _show_list(rows: list[dict[str, Any]], output: Output, *, namespaces: bool) -> None:
+    if not namespaces:
+        rows = [{**row, "identifier": _table_identifier(row["namespace"], row["name"])} for row in rows]
+    if output == Output.json:
+        _show(rows, output)
+        return
+    table = Table("Name" if namespaces else "Identifier", "Updated", "Tables" if namespaces else "Storage override")
+    for row in rows:
+        table.add_row(
+            row["name"] if namespaces else row["identifier"],
+            row["updated"],
+            str(row["table_count"] if namespaces else row["has_storage_override"]),
+        )
+    rich_console.print(table)
+
+
+@namespace_app.command("list")
+def list_namespaces(
+    org: str,
+    search: str | None = None,
+    filter_metadata: str | None = typer.Option(None, help="JSON metadata filter"),
+    sort: NamespaceSort | None = None,
+    direction: Direction = Direction.desc,
+    include_ghosts: bool = False,
+    page_size: int = typer.Option(50, min=1, max=100),
+    output: Output = Output.rich,
+):
+    """List namespaces, with optional search, metadata filters, and sorting."""
+    rows = Client().list_iceberg_namespaces_paginated(
+        org,
+        search=search,
+        filter_metadata=_json_object(filter_metadata, "--filter-metadata"),
+        sort=sort.value if sort else None,
+        direction=direction.value,
+        include_ghosts=include_ghosts,
+        page_size=page_size,
+    )
+    _show_list([row.model_dump(mode="json") for row in rows], output, namespaces=True)
+
+
+@namespace_app.command("get")
+def get_namespace(org: str, name: str, output: Output = Output.rich):
+    """Show namespace storage, description, metadata, and visibility."""
+    _show(Client().get_iceberg_namespace(org, name).model_dump(mode="json"), output)
+
+
+@namespace_app.command("create")
+def create_namespace(
+    org: str,
+    name: str,
+    bucket_config_nickname: str | None = None,
+    description: str | None = None,
+    metadata: str | None = typer.Option(None, help="JSON discovery metadata"),
+    visibility: RepoVisibility = RepoVisibility.PRIVATE,
+    properties: str | None = typer.Option(None, help="JSON Iceberg properties (string values)"),
+    output: Output = Output.rich,
+):
+    """Create a namespace on the chosen or default bucket."""
+    props = _json_object(properties, "--properties")
+    if props is not None and any(not isinstance(v, str) for v in props.values()):
+        raise typer.BadParameter("Property values must be strings", param_hint="--properties")
+    result = Client().create_iceberg_namespace(
+        org,
+        name,
+        bucket_config_nickname=bucket_config_nickname,
+        description=description,
+        metadata=_json_object(metadata, "--metadata"),
+        visibility=visibility,
+        properties=props,
+    )
+    _show(result.model_dump(mode="json"), output)
+
+
+@namespace_app.command("update")
+def update_namespace(
+    org: str,
+    name: str,
+    description: str | None = None,
+    add_metadata: str | None = typer.Option(None, help="JSON metadata to add"),
+    remove_metadata: list[str] | None = typer.Option(None, help="Metadata key to remove; repeat for multiple keys"),
+    update_metadata: str | None = typer.Option(None, help="JSON metadata to update"),
+    visibility: RepoVisibility | None = None,
+    output: Output = Output.rich,
+):
+    """Update description, discovery metadata, or visibility. Use --description '' to clear."""
+    result = Client().modify_iceberg_namespace(
+        org,
+        name,
+        description=description,
+        add_metadata=_json_object(add_metadata, "--add-metadata"),
+        remove_metadata=remove_metadata,
+        update_metadata=_json_object(update_metadata, "--update-metadata"),
+        visibility=visibility,
+    )
+    _show(result.model_dump(mode="json"), output)
+
+
+@namespace_app.command("delete")
+def delete_namespace(
+    org: str,
+    name: str,
+    confirm: bool = typer.Option(False, "--confirm", help="Skip the confirmation prompt"),
+    immediate: bool = typer.Option(
+        False, "--immediate", help="Skip the recovery period: the namespace cannot be restored and its name is reusable at once"
+    ),
+    retain_data: bool = typer.Option(False, "--retain-data", help="Leave the bytes under the namespace's storage prefix in the bucket"),
+):
+    """Delete an empty namespace. A soft-delete by default: restore it during its recovery period."""
+    if not confirm:
+        verb = "Permanently delete" if immediate else "Delete"
+        typer.confirm(f"{verb} namespace {org}/{name}?", abort=True)
+    Client().delete_iceberg_namespace(org, name, imsure=True, immediate=immediate, retain_data=retain_data)
+    typer.echo(f"Deleted {org}/{name}")
+
+
+@namespace_app.command("restore")
+def restore_namespace(org: str, name: str):
+    """Restore a soft-deleted namespace."""
+    Client().restore_iceberg_namespace(org, name)
+    typer.echo(f"Restored {org}/{name}")
+
+
+@table_app.command("list")
+def list_tables(
+    org: str,
+    namespace: str,
+    search: str | None = None,
+    sort: TableSort | None = None,
+    direction: Direction = Direction.desc,
+    page_size: int = typer.Option(50, min=1, max=100),
+    output: Output = Output.rich,
+):
+    """List table summaries without fetching table metadata or recording accesses."""
+    rows = Client().list_iceberg_tables_paginated(
+        org,
+        namespace,
+        search=search,
+        sort=sort.value if sort else None,
+        direction=direction.value,
+        page_size=page_size,
+    )
+    _show_list([row.model_dump(mode="json") for row in rows], output, namespaces=False)
+
+
+@table_app.command("describe")
+def describe_table(
+    org: str,
+    identifier: str = typer.Argument(..., help="NAMESPACE.TABLE; double-quote components containing dots or special characters."),
+    output: Output = Output.rich,
+):
+    """Load a table's schema, snapshots, partitioning, and properties. Requires arraylake[iceberg]."""
+    namespace, table = _parse_table_identifier(identifier)
+    catalog = Client().get_iceberg(org)
+    try:
+        loaded = catalog.load_table((namespace, table))
+        _show(
+            {
+                "name": table,
+                "namespace": namespace,
+                "identifier": _table_identifier(namespace, table),
+                "metadata_location": loaded.metadata_location,
+                "metadata": loaded.metadata.model_dump(mode="json", by_alias=True),
+            },
+            output,
+        )
+    finally:
+        catalog.close()