cloudcat 0.6.0__tar.gz → 0.6.2__tar.gz

{cloudcat-0.6.0 → cloudcat-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cloudcat
-Version: 0.6.0
+Version: 0.6.2
 Summary: Preview and analyze data files in Google Cloud Storage, AWS S3, and Azure Data Lake Storage Gen2 from your terminal
 Author: Jonathan Sudhakar
 License: MIT
@@ -554,7 +554,17 @@ Options:
 
   --config-profile TEXT        Named profile from ~/.config/cloudcat/config.toml
 
-  --completion [bash|zsh|fish] Print the shell completion script and exit
+  --install-completion [bash|zsh|fish]
+                               Enable completion with one command (adds one
+                               line to your shell rc file; idempotent)
+
+  --completion [bash|zsh|fish] Print the shell completion script and exit.
+                               Once enabled, TAB completes PATH too: local
+                               files natively, s3://<TAB> lists buckets,
+                               s3://bucket/dir/<TAB> lists children (uses
+                               --profile/--project if already typed).
+                               bash note: escape the URL colon issue with
+                               COMP_WORDBREAKS=${COMP_WORDBREAKS//:/}
 
   --az-access-key TEXT         Azure storage account access key
 

{cloudcat-0.6.0 → cloudcat-0.6.2}/README.md

@@ -472,7 +472,17 @@ Options:
 
   --config-profile TEXT        Named profile from ~/.config/cloudcat/config.toml
 
-  --completion [bash|zsh|fish] Print the shell completion script and exit
+  --install-completion [bash|zsh|fish]
+                               Enable completion with one command (adds one
+                               line to your shell rc file; idempotent)
+
+  --completion [bash|zsh|fish] Print the shell completion script and exit.
+                               Once enabled, TAB completes PATH too: local
+                               files natively, s3://<TAB> lists buckets,
+                               s3://bucket/dir/<TAB> lists children (uses
+                               --profile/--project if already typed).
+                               bash note: escape the URL colon issue with
+                               COMP_WORDBREAKS=${COMP_WORDBREAKS//:/}
 
   --az-access-key TEXT         Azure storage account access key
 

{cloudcat-0.6.0 → cloudcat-0.6.2}/cloudcat/__init__.py

@@ -2,4 +2,4 @@
 #!/usr/bin/env python
 """cloudcat - A CLI utility to read and display files from cloud storage."""
 
-__version__ = "0.6.0"
+__version__ = "0.6.2"

{cloudcat-0.6.0 → cloudcat-0.6.2}/cloudcat/cli.py

@@ -1,8 +1,16 @@
 #!/usr/bin/env python
-"""CloudCat CLI - Preview and analyze data files in cloud storage."""
+"""CloudCat CLI - Preview and analyze data files in cloud storage.
+
+Import discipline: this module keeps its import-time footprint light —
+heavy dependencies (pandas, pyarrow, cloud SDKs, the readers) are imported
+inside the functions that use them. Shell tab-completion re-imports this
+module on every keypress, so module import must stay fast; the guard test
+in tests/test_import_lightness.py enforces it.
+"""
+
+from __future__ import annotations
 
 import click
-import pandas as pd
 import os
 import sys
 import io
@@ -16,7 +24,7 @@ from colorama import init, Fore, Style
 # Import version
 from . import __version__
 
-# Import from modular components
+# Light modular components (no heavy transitive imports)
 from .config import cloud_config, SKIP_PATTERNS, FORMAT_EXTENSION_MAP
 from .compression import (
     detect_compression,
@@ -25,47 +33,16 @@ from .compression import (
     get_streaming_decompressor,
     supports_streaming_decompression,
 )
-from .filtering import parse_where_clause, apply_where_filter, where_columns
-from .formatters import colorize_json, format_table_with_colored_header
 from .progress import start_progress, update_progress, stop_progress
-from .storage import (
+# storage.base dispatches to the cloud SDKs lazily per call, unlike the
+# storage package __init__, which imports all of them eagerly.
+from .storage.base import (
     parse_cloud_path,
     get_stream,
     list_directory,
     get_file_size,
 )
-from .storage.gcs import get_gcs_stream, list_gcs_directory
-from .storage.s3 import get_s3_stream, list_s3_directory
-from .storage.azure import get_azure_stream, list_azure_directory
-from .readers import (
-    read_csv_data,
-    read_csv_data_streaming,
-    read_json_data,
-    read_json_data_streaming,
-    read_parquet_data,
-    read_parquet_data_streaming,
-    read_avro_data,
-    read_avro_data_streaming,
-    read_orc_data,
-    read_orc_data_streaming,
-    read_text_data,
-    read_text_data_streaming,
-    HAS_PARQUET,
-    HAS_AVRO,
-    HAS_ORC,
-)
-from .streaming import (
-    StreamingStats,
-    format_bytes,
-    get_pyarrow_filesystem,
-    supports_pyarrow_fs,
-)
-
-# Import pyarrow for parquet metadata if available
-try:
-    import pyarrow.parquet as pq
-except ImportError:
-    pq = None
+from .completion import complete_path as _complete_path
 
 
 def info(message: str) -> None:
@@ -92,15 +69,23 @@ def _configure_color(no_color: bool) -> None:
     init(strip=not use_color)
 
 
-# Map of input format -> non-streaming reader (used for multi-file reads).
-_READERS = {
-    'csv': lambda stream, n, columns, delimiter: read_csv_data(stream, n, columns, delimiter),
-    'json': lambda stream, n, columns, delimiter: read_json_data(stream, n, columns),
-    'parquet': lambda stream, n, columns, delimiter: read_parquet_data(stream, n, columns),
-    'avro': lambda stream, n, columns, delimiter: read_avro_data(stream, n, columns),
-    'orc': lambda stream, n, columns, delimiter: read_orc_data(stream, n, columns),
-    'text': lambda stream, n, columns, delimiter: read_text_data(stream, n, columns),
-}
+def _get_reader(input_format: str):
+    """Resolve the non-streaming reader for a format (lazy import).
+
+    Resolves through the readers package at call time so tests can patch
+    cloudcat.readers.read_<fmt>_data, and so importing this module never
+    pulls pandas/pyarrow.
+    """
+    from . import readers
+    table = {
+        'csv': lambda stream, n, columns, delimiter: readers.read_csv_data(stream, n, columns, delimiter),
+        'json': lambda stream, n, columns, delimiter: readers.read_json_data(stream, n, columns),
+        'parquet': lambda stream, n, columns, delimiter: readers.read_parquet_data(stream, n, columns),
+        'avro': lambda stream, n, columns, delimiter: readers.read_avro_data(stream, n, columns),
+        'orc': lambda stream, n, columns, delimiter: readers.read_orc_data(stream, n, columns),
+        'text': lambda stream, n, columns, delimiter: readers.read_text_data(stream, n, columns),
+    }
+    return table.get(input_format)
 
 
 def _list_non_empty_files(service: str, bucket: str, prefix: str) -> List[Tuple[str, int]]:
@@ -217,6 +202,35 @@ def get_files_for_multiread(
     return selected_files
 
 
+_ICEBERG_NESTED_RE = re.compile(r'(.*)/metadata/(?:v\d+|\d+-[^/]*)\.metadata\.json$')
+
+
+def _find_nested_tables(files: List[Tuple[str, int]]) -> dict:
+    """Find lakehouse table roots nested inside a directory listing.
+
+    Returns {root_path: format}. Used to guide users who point cloudcat at
+    a folder OF tables rather than at a table — merging data files across
+    different tables would silently produce wrong results.
+    """
+    tables = {}
+    for name, _size in files:
+        if '/_delta_log/' in f'/{name}':
+            root = name.split('/_delta_log/')[0]
+            if root:  # empty means the listing prefix IS the table root
+                tables.setdefault(root, 'delta')
+            continue
+        match = _ICEBERG_NESTED_RE.match(name)
+        if match and match.group(1):
+            tables.setdefault(match.group(1), 'iceberg')
+    return tables
+
+
+def _has_known_extension(name: str) -> bool:
+    """True if the filename matches any recognized data-format extension."""
+    return any(re.search(regex, name, re.IGNORECASE)
+               for regex in FORMAT_EXTENSION_MAP.values())
+
+
 def find_first_non_empty_file(
     service: str,
     bucket: str,
@@ -254,7 +268,40 @@ def find_first_non_empty_file(
         info(Fore.YELLOW + f"No files matching format '{input_format}' found in "
              f"{service}://{bucket}/{prefix}. Using first available file." + Style.RESET_ALL)
 
-    # Use the first non-empty, non-metadata file
+    # No explicit format: the selection drives format INFERENCE, so only
+    # consider files whose extension we can actually infer from.
+    if not input_format:
+        nested_tables = _find_nested_tables(non_empty_files)
+        if nested_tables:
+            listing = '\n'.join(
+                f"  {fmt}: {root}/" for root, fmt in sorted(nested_tables.items())
+            )
+            first_root = sorted(nested_tables)[0]
+            raise ValueError(
+                "this directory contains lakehouse table(s), not a single dataset:\n"
+                f"{listing}\n"
+                f"Point at a table root, e.g.: cloudcat {first_root}/ "
+                "(or pass --input-format to force reading loose files)"
+            )
+
+        for file_name, file_size in non_empty_files:
+            if any(re.search(pattern, file_name) for pattern in SKIP_PATTERNS):
+                continue
+            if not _has_known_extension(file_name):
+                continue  # e.g. catalog.db, .lock — can't infer a format from it
+            if not quiet:
+                info(Fore.BLUE + f"Selected file: {file_name} ({file_size} bytes)" + Style.RESET_ALL)
+            return file_name, file_size
+
+        sample = ', '.join(name.rsplit('/', 1)[-1] for name, _ in non_empty_files[:5])
+        raise ValueError(
+            f"no files with a recognized data format in {service}://{bucket}/{prefix} "
+            f"(found: {sample}). Formats are inferred from extensions "
+            "(.csv/.json/.parquet/.avro/.orc/.txt, optionally compressed); "
+            "pass --input-format to force one."
+        )
+
+    # Explicit format requested but unmatched: first non-metadata file.
     for file_name, file_size in non_empty_files:
         if not any(re.search(pattern, file_name) for pattern in SKIP_PATTERNS):
             if not quiet:
@@ -327,6 +374,8 @@ def read_data_from_multiple_files(
     Returns:
         Tuple of (DataFrame, schema, total_rows).
     """
+    import pandas as pd
+
     dfs = []
     schemas = []
     rows_read = 0
@@ -359,7 +408,7 @@ def read_data_from_multiple_files(
         else:
             rows_to_read_from_file = 0  # read all rows from this file
 
-        reader = _READERS.get(input_format)
+        reader = _get_reader(input_format)
         if reader is None:
             raise ValueError(f"Unsupported format: {input_format}")
         df, schema = reader(stream, rows_to_read_from_file, columns, delimiter)
@@ -477,6 +526,16 @@ def read_data_streaming(
     Returns:
         Tuple of (DataFrame, schema, StreamingStats).
     """
+    from .readers import (
+        read_csv_data_streaming,
+        read_json_data_streaming,
+        read_parquet_data_streaming,
+        read_avro_data_streaming,
+        read_orc_data_streaming,
+        read_text_data_streaming,
+    )
+    from .streaming import StreamingStats, get_pyarrow_filesystem, supports_pyarrow_fs
+
     # Get file size for stats
     try:
         file_size = get_file_size(service, bucket, object_path)
@@ -607,6 +666,14 @@ def get_record_count(
     Returns:
         Record count (int) or "Unknown" on failure.
     """
+    import pandas as pd
+    from .readers import HAS_PARQUET, HAS_AVRO, HAS_ORC
+    from .streaming import get_pyarrow_filesystem, supports_pyarrow_fs
+    try:
+        import pyarrow.parquet as pq
+    except ImportError:
+        pq = None
+
     # Lakehouse tables carry snapshot row counts in their metadata layer.
     if input_format in ('delta', 'iceberg'):
         from .tables import table_row_count
@@ -845,6 +912,44 @@ def _print_completion(ctx, param, value):
     ctx.exit()
 
 
+_COMPLETION_SNIPPETS = {
+    'zsh': ('~/.zshrc', 'eval "$(cloudcat --completion zsh)"'),
+    'bash': ('~/.bashrc',
+             'COMP_WORDBREAKS=${COMP_WORDBREAKS//:/}  # let URLs like s3:// complete\n'
+             'eval "$(cloudcat --completion bash)"'),
+    'fish': ('~/.config/fish/config.fish', 'cloudcat --completion fish | source'),
+}
+
+_COMPLETION_MARKER = '# added by cloudcat --install-completion'
+
+
+def _install_completion(ctx, param, value):
+    """Eager callback: enable shell completion in the user's rc file.
+
+    Idempotent — a marker comment prevents duplicate blocks on re-runs.
+    """
+    if not value or ctx.resilient_parsing:
+        return
+    rc_path, snippet = _COMPLETION_SNIPPETS[value]
+    rc_file = os.path.expanduser(rc_path)
+
+    existing = ''
+    if os.path.exists(rc_file):
+        with open(rc_file, 'r', encoding='utf-8', errors='replace') as f:
+            existing = f.read()
+    if _COMPLETION_MARKER in existing:
+        click.echo(f"Completion is already set up in {rc_file}")
+        ctx.exit()
+
+    os.makedirs(os.path.dirname(rc_file), exist_ok=True)
+    block = f"\n{_COMPLETION_MARKER}\n{snippet}\n"
+    with open(rc_file, 'a', encoding='utf-8') as f:
+        f.write(block)
+    click.echo(f"Added cloudcat completion to {rc_file} — restart your shell "
+               f"(or run: source {rc_path}) and try: cloudcat s3://<TAB>")
+    ctx.exit()
+
+
 # Where each agent expects personal skills (name -> path builder).
 _SKILL_DESTINATIONS = {
     'claude': lambda: os.path.join(os.path.expanduser('~'), '.claude', 'skills', 'cloudcat', 'SKILL.md'),
@@ -882,8 +987,9 @@ def _install_skill(ctx, param, value):
     ctx.exit()
 
 
-def _column_stats(df: pd.DataFrame) -> pd.DataFrame:
+def _column_stats(df):
     """Profile each column of a frame: type, nulls, distinct values, range."""
+    import pandas as pd
     rows = []
     for position, col in enumerate(df.columns):
         series = df.iloc[:, position]
@@ -908,8 +1014,9 @@ def _column_stats(df: pd.DataFrame) -> pd.DataFrame:
     return pd.DataFrame(rows)
 
 
-def _render_data(df: pd.DataFrame, output_format: str) -> str:
+def _render_data(df, output_format: str) -> str:
     """Render a DataFrame to the requested output format string."""
+    from .formatters import colorize_json, format_table_with_colored_header
     if output_format == 'table':
         return format_table_with_colored_header(df)
     elif output_format == 'jsonp':
@@ -923,7 +1030,7 @@ def _render_data(df: pd.DataFrame, output_format: str) -> str:
 
 @click.command()
 @click.version_option(version=__version__, prog_name='cloudcat')
-@click.argument('path_arg', required=False, metavar='[PATH]')
+@click.argument('path_arg', required=False, metavar='[PATH]', shell_complete=_complete_path)
 @click.option('--path', '-p', 'path_opt',
               help='Path to the file or directory (deprecated alias for the PATH argument)')
 @click.option('--output-format', '-o', type=click.Choice(['json', 'jsonp', 'csv', 'table']), default='table',
@@ -955,6 +1062,9 @@ def _render_data(df: pd.DataFrame, output_format: str) -> str:
 @click.option('--completion', type=click.Choice(['bash', 'zsh', 'fish']), is_eager=True,
               expose_value=False, callback=_print_completion,
               help='Print the shell completion script and exit (e.g. eval "$(cloudcat --completion zsh)")')
+@click.option('--install-completion', type=click.Choice(['bash', 'zsh', 'fish']), is_eager=True,
+              expose_value=False, callback=_install_completion,
+              help='Enable shell completion by adding one line to your shell rc file (idempotent)')
 @click.option('--install-skill', type=click.Choice(['claude', 'claude-project', 'codex', 'print']),
               is_eager=True, expose_value=False, callback=_install_skill,
               help='Install the bundled AI-agent skill: claude (~/.claude/skills), '
@@ -1031,6 +1141,8 @@ def main(path_arg, path_opt, output_format, output_file, input_format, columns,
         click.echo(Fore.RED + "Error: Missing PATH. Usage: cloudcat [OPTIONS] PATH" + Style.RESET_ALL, err=True)
         sys.exit(2)
 
+    from .filtering import parse_where_clause, apply_where_filter, where_columns
+
     # Enable color only for an interactive stdout; writing to a file is never
     # colored. This must run before any colored output is produced.
     _configure_color(no_color or bool(output_file))
@@ -1179,6 +1291,7 @@ def main(path_arg, path_opt, output_format, output_file, input_format, columns,
                     stop_progress()
 
                     # Calculate total size for stats
+                    from .streaming import StreamingStats
                     total_size = sum(f[1] for f in file_list)
                     streaming_stats = StreamingStats(file_size=total_size, bytes_read=total_size, format_type=input_format)
 

cloudcat-0.6.2/cloudcat/completion.py

@@ -0,0 +1,248 @@
+"""Shell tab-completion for PATH: local files, buckets, and cloud prefixes.
+
+Wired into the PATH argument via Click's shell_complete. The generated
+completion script re-invokes cloudcat on every TAB, so this module must be
+cheap to import (SDKs load lazily, guarded by tests/test_import_lightness)
+and must never hang or error the user's shell: cloud calls run with short
+timeouts, no retries, capped result counts — and any failure completes to
+nothing rather than raising.
+
+Behavior mirrors `ls` completion, scheme-aware:
+    <TAB>                  -> native file completion
+    s3://<TAB>             -> buckets (via --profile if typed earlier)
+    s3://bucket/dir/<TAB>  -> immediate children under the prefix
+"""
+
+from typing import List, Optional, Tuple
+
+import os
+
+from click.shell_completion import CompletionItem, ZshComplete, add_completion_class
+
+
+def _debug(message: str) -> None:
+    """Optionally record why a completion produced nothing.
+
+    Completion swallows every error so it can never break the shell — which
+    makes "TAB does nothing" undiagnosable. Set CLOUDCAT_COMPLETE_DEBUG=1 and
+    failures are appended to ~/.cache/cloudcat/completion.log instead.
+    """
+    if not os.environ.get('CLOUDCAT_COMPLETE_DEBUG'):
+        return
+    try:
+        import datetime
+        cache_dir = os.path.join(
+            os.environ.get('XDG_CACHE_HOME', os.path.expanduser('~/.cache')), 'cloudcat')
+        os.makedirs(cache_dir, exist_ok=True)
+        with open(os.path.join(cache_dir, 'completion.log'), 'a', encoding='utf-8') as f:
+            f.write(f"{datetime.datetime.now().isoformat()} {message}\n")
+    except Exception:
+        pass
+
+
+class CloudcatZshComplete(ZshComplete):
+    """Click's zsh completer, hardened for real-world .zshrc files.
+
+    The stock script calls compdef unconditionally; if the user evals it
+    before compinit has run, registration fails silently and TAB "does
+    nothing". This variant bootstraps compinit when needed.
+    """
+
+    name = 'zsh'
+    source_template = ZshComplete.source_template.replace(
+        "    compdef %(complete_func)s %(prog_name)s",
+        """    if ! typeset -f compdef >/dev/null 2>&1; then
+        autoload -Uz compinit && compinit -u
+    fi
+    compdef %(complete_func)s %(prog_name)s""",
+    )
+
+
+# Replace the registered zsh completer with the hardened variant.
+add_completion_class(CloudcatZshComplete)
+
+# Never return more candidates than a shell menu can usefully show.
+LIMIT = 100
+# Cloud calls must never hang a keypress.
+CONNECT_TIMEOUT = 1.0
+READ_TIMEOUT = 2.0
+
+_SCHEMES = ('s3://', 'gs://', 'gcs://', 'abfss://', 'file://')
+
+
+# --------------------------------------------------------------------------
+# per-provider listing (small, patchable seams; SDK imports stay inside)
+# --------------------------------------------------------------------------
+
+def _s3_client(profile: Optional[str]):
+    import boto3
+    from botocore.config import Config
+    config = Config(connect_timeout=CONNECT_TIMEOUT, read_timeout=READ_TIMEOUT,
+                    retries={'max_attempts': 0})
+    session = boto3.Session(profile_name=profile) if profile else boto3.Session()
+    # Without a configured region some boto3 versions raise NoRegionError at
+    # client creation; bucket listing is region-agnostic, so default it.
+    region = session.region_name or 'us-east-1'
+    return session.client('s3', region_name=region, config=config)
+
+
+def _list_s3_buckets(profile: Optional[str]) -> List[str]:
+    response = _s3_client(profile).list_buckets()
+    return [b['Name'] for b in response.get('Buckets', [])]
+
+
+def _shallow_list_s3(bucket: str, prefix: str, profile: Optional[str]) -> Tuple[List[str], List[str]]:
+    """Immediate children under a prefix: (dirs, files) as full keys."""
+    response = _s3_client(profile).list_objects_v2(
+        Bucket=bucket, Prefix=prefix, Delimiter='/', MaxKeys=LIMIT)
+    dirs = [p['Prefix'] for p in response.get('CommonPrefixes', [])]
+    files = [o['Key'] for o in response.get('Contents', []) if o['Key'] != prefix]
+    return dirs, files
+
+
+def _gcs_client(project: Optional[str], credentials: Optional[str]):
+    from google.cloud import storage
+    kwargs = {}
+    if project:
+        kwargs['project'] = project
+    if credentials:
+        from google.oauth2 import service_account
+        kwargs['credentials'] = service_account.Credentials.from_service_account_file(credentials)
+    return storage.Client(**kwargs)
+
+
+def _list_gcs_buckets(project: Optional[str], credentials: Optional[str]) -> List[str]:
+    client = _gcs_client(project, credentials)
+    return [b.name for b in client.list_buckets(max_results=LIMIT, timeout=READ_TIMEOUT)]
+
+
+def _shallow_list_gcs(bucket: str, prefix: str, project: Optional[str],
+                      credentials: Optional[str]) -> Tuple[List[str], List[str]]:
+    client = _gcs_client(project, credentials)
+    iterator = client.list_blobs(bucket, prefix=prefix, delimiter='/',
+                                 max_results=LIMIT, timeout=READ_TIMEOUT)
+    files = [b.name for b in iterator if b.name != prefix]
+    dirs = sorted(iterator.prefixes)  # populated after iteration
+    return dirs, files
+
+
+def _abfss_service(account: str, access_key: Optional[str]):
+    import os
+    from azure.storage.filedatalake import DataLakeServiceClient
+    url = f"https://{account}.dfs.core.windows.net"
+    key = access_key or os.environ.get('AZURE_STORAGE_ACCESS_KEY')
+    if key:
+        return DataLakeServiceClient(account_url=url, credential=key,
+                                     connection_timeout=CONNECT_TIMEOUT, read_timeout=READ_TIMEOUT)
+    from azure.identity import DefaultAzureCredential
+    return DataLakeServiceClient(account_url=url, credential=DefaultAzureCredential(),
+                                 connection_timeout=CONNECT_TIMEOUT, read_timeout=READ_TIMEOUT)
+
+
+def _list_abfss_containers(account: str, access_key: Optional[str]) -> List[str]:
+    from itertools import islice
+    service = _abfss_service(account, access_key)
+    return [fs.name for fs in islice(service.list_file_systems(timeout=READ_TIMEOUT), LIMIT)]
+
+
+def _shallow_list_abfss(container: str, account: str, prefix: str,
+                        access_key: Optional[str]) -> Tuple[List[str], List[str]]:
+    from itertools import islice
+    service = _abfss_service(account, access_key)
+    fs = service.get_file_system_client(container)
+    dirs, files = [], []
+    parent = prefix.rsplit('/', 1)[0] if '/' in prefix else ''
+    paths = fs.get_paths(path=parent or None, recursive=False, timeout=READ_TIMEOUT)
+    for p in islice(paths, LIMIT * 2):
+        if not p.name.startswith(prefix):
+            continue
+        (dirs if p.is_directory else files).append(p.name + ('/' if p.is_directory else ''))
+    return dirs[:LIMIT], files[:LIMIT]
+
+
+# --------------------------------------------------------------------------
+# the completer
+# --------------------------------------------------------------------------
+
+def _param(ctx, name: str) -> Optional[str]:
+    """A parsed option from the partial command line, if the shell saw it."""
+    try:
+        value = ctx.params.get(name)
+        return value if isinstance(value, str) and value else None
+    except Exception:
+        return None
+
+
+def _cloud_candidates(ctx, incomplete: str) -> List[str]:
+    """Full-word candidates for an incomplete cloud URL."""
+    scheme, rest = incomplete.split('://', 1)
+    scheme = scheme.lower()
+    profile = _param(ctx, 'profile')
+    project = _param(ctx, 'project')
+    credentials = _param(ctx, 'credentials')
+    az_key = _param(ctx, 'az_access_key')
+
+    if scheme == 'file':
+        return []  # handled by the file-completion fallback in complete_path
+
+    if '/' not in rest:
+        # Completing the bucket/container part.
+        if scheme == 's3':
+            names = _list_s3_buckets(profile)
+        elif scheme in ('gs', 'gcs'):
+            names = _list_gcs_buckets(project, credentials)
+        elif scheme == 'abfss':
+            if '@' not in rest:
+                return []  # abfss needs container@account; accounts aren't listable
+            container_part, host = rest.split('@', 1)
+            if '.' not in host:
+                return []
+            account = host.split('.')[0]
+            return [f"{scheme}://{name}@{host}/"
+                    for name in _list_abfss_containers(account, az_key)
+                    if name.startswith(container_part)][:LIMIT]
+        else:
+            return []
+        return [f"{scheme}://{name}/" for name in sorted(names)
+                if name.startswith(rest)][:LIMIT]
+
+    # Completing a key/prefix inside a bucket.
+    bucket, prefix = rest.split('/', 1)
+    if scheme == 's3':
+        dirs, files = _shallow_list_s3(bucket, prefix, profile)
+    elif scheme in ('gs', 'gcs'):
+        dirs, files = _shallow_list_gcs(bucket, prefix, project, credentials)
+    elif scheme == 'abfss' and '@' in bucket:
+        container, host = bucket.split('@', 1)
+        account = host.split('.')[0]
+        dirs, files = _shallow_list_abfss(container, account, prefix, az_key)
+    else:
+        return []
+
+    base = f"{scheme}://{bucket}/"
+    candidates = [base + d for d in dirs] + [base + f for f in files]
+    return sorted(candidates)[:LIMIT]
+
+
+def complete_path(ctx, param, incomplete: str) -> List[CompletionItem]:
+    """shell_complete callback for the PATH argument."""
+    try:
+        if '://' in incomplete:
+            return [CompletionItem(c) for c in _cloud_candidates(ctx, incomplete)]
+
+        items: List[CompletionItem] = []
+        # Offer scheme prefixes while a scheme could still be being typed
+        # (e.g. "s3" or "gc"), alongside normal file completion.
+        if incomplete and '/' not in incomplete:
+            items.extend(
+                CompletionItem(scheme)
+                for scheme in _SCHEMES
+                if scheme.startswith(incomplete)
+            )
+        items.append(CompletionItem(incomplete, type='file'))
+        return items
+    except Exception:
+        # Completion must never break the shell: no candidates beats a stack.
+        import traceback
+        _debug(f"complete_path({incomplete!r}) failed:\n{traceback.format_exc()}")
+        return []