fss-cli 0.11.0__py3-none-any.whl

fss_cli/_diagnostics.py

@@ -0,0 +1,12 @@
+"""Shared rendering for stable command diagnostics."""
+
+_ESCAPES = {code: f"\\x{code:02x}" for code in (*range(0x20), 0x7F)}
+_ESCAPES[ord("\\")] = "\\\\"
+
+
+def _render_diagnostic_value(value: str) -> str:
+    return value.translate(_ESCAPES)
+
+
+def _render_diagnostic_prefix(command: str) -> str:
+    return f"{_render_diagnostic_value(command)}:"

fss_cli/_du.py

@@ -0,0 +1,90 @@
+"""Disk-usage execution for the central ``du`` callback."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from ._command import (
+    _collate,
+    _Failure,
+    _MappedOperand,
+    _run_single_operand_text,
+    _valid_size,
+)
+from ._listing import format_size
+from ._metadata import valid_display_text
+from ._walk import _IncompatibleListingError, _ListedRow, _walk
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from fsspec.asyn import AsyncFileSystem
+
+    from ._app import AsyncFilesystemSource
+
+
+@dataclass(frozen=True)
+class _DuRequest:
+    summarize: bool
+    human_readable: bool
+    operand: _MappedOperand
+
+
+def _file_sizes(rows: list[_ListedRow]) -> dict[str, int] | None:
+    """Collect each listed file's size by reported name, or ``None`` if invalid.
+
+    Like fsspec's ``_du``, every non-directory entry counts and a name listed
+    twice counts once.
+    """
+    sizes: dict[str, int] = {}
+    try:
+        for row in rows:
+            for info in row.files.values():
+                path = info.get("name")
+                size = info.get("size")
+                if type(path) is not str or not valid_display_text(path) or not _valid_size(size):
+                    return None
+                sizes[path] = size
+    except Exception:  # noqa: BLE001 - fail closed on hostile mapping behavior.
+        return None
+    return sizes
+
+
+def _render_sizes(request: _DuRequest, sizes: Mapping[str, int]) -> str:
+    if request.summarize:
+        size = format_size(sum(sizes.values()), human_readable=request.human_readable)
+        return f"{size}\t{request.operand.path}\n"
+    return "".join(
+        f"{format_size(size, human_readable=request.human_readable)}\t{path}\n"
+        for path, size in sorted(sizes.items(), key=lambda entry: _collate(entry[0]))
+    )
+
+
+async def _measure(
+    request: _DuRequest,
+    filesystem: AsyncFileSystem,
+) -> str | _Failure:
+    try:
+        rows = await _walk(filesystem, request.operand.path)
+    except _IncompatibleListingError:
+        return _Failure(request.operand)
+    except Exception as error:  # noqa: BLE001 - classify awaited backend failure.
+        return _Failure(request.operand, backend_error=error)
+    sizes = _file_sizes(rows)
+    if sizes is None:
+        return _Failure(request.operand)
+    return _render_sizes(request, sizes)
+
+
+async def _run_du(
+    command: str,
+    request: _DuRequest,
+    sources: Mapping[str, AsyncFilesystemSource],
+) -> None:
+    await _run_single_operand_text(
+        command,
+        request.operand,
+        sources,
+        lambda filesystem: _measure(request, filesystem),
+    )

fss_cli/_find.py

@@ -0,0 +1,109 @@
+"""Recursive-find execution for the central ``find`` callback."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal, TypeGuard, cast
+
+from ._command import (
+    _call,
+    _collate,
+    _Failure,
+    _MappedOperand,
+    _run_single_operand_text,
+)
+from ._metadata import valid_display_text
+from ._walk import _IncompatibleListingError, _ListedRow, _walk
+
+if TYPE_CHECKING:
+    from fsspec.asyn import AsyncFileSystem
+
+    from ._app import AsyncFilesystemSource
+
+
+@dataclass(frozen=True)
+class _FindRequest:
+    maxdepth: int | None
+    kind: Literal["f", "d"]
+    operand: _MappedOperand
+
+
+def _render_paths(request: _FindRequest, paths: list[str]) -> str:
+    if request.maxdepth == 0:
+        root = request.operand.path.rstrip("/")
+        paths = [path for path in paths if path.rstrip("/") == root]
+    paths.sort(key=_collate)
+    return "".join(f"{path}\n" for path in dict.fromkeys(paths))
+
+
+def _selected_paths(
+    request: _FindRequest,
+    root_info: object,
+    rows: list[_ListedRow],
+) -> list[str] | None:
+    """Select displayable file or directory paths, or ``None`` if invalid.
+
+    File entries are every non-directory row entry, as fsspec's ``_find``
+    reports them; ``--type d`` reports the operand itself when it is a
+    directory plus every listed directory.
+    """
+    infos: list[Mapping[object, object]] = []
+    if request.kind == "d":
+        if not isinstance(root_info, Mapping):
+            return None
+        infos.append(cast("Mapping[object, object]", root_info))
+    for row in rows:
+        if request.kind == "d":
+            infos.extend(row.directories.values())
+        infos.extend(row.files.values())
+    paths: list[str] = []
+    try:
+        for info in infos:
+            path = info.get("name")
+            kind = info.get("type")
+            if not _valid_path(path) or type(kind) is not str:
+                return None
+            if (kind == "directory") == (request.kind == "d"):
+                paths.append(path)
+    except Exception:  # noqa: BLE001 - fail closed on hostile mapping consumption.
+        return None
+    return paths
+
+
+def _valid_path(path: object) -> TypeGuard[str]:
+    return type(path) is str and valid_display_text(path)
+
+
+async def _search(
+    request: _FindRequest,
+    filesystem: AsyncFileSystem,
+) -> str | _Failure:
+    try:
+        root_info = await _call(filesystem, "_info", request.operand.path) if request.kind == "d" else None
+        rows = await _walk(
+            filesystem,
+            request.operand.path,
+            maxdepth=1 if request.maxdepth == 0 else request.maxdepth,
+        )
+    except _IncompatibleListingError:
+        return _Failure(request.operand)
+    except Exception as error:  # noqa: BLE001 - classify awaited backend failure.
+        return _Failure(request.operand, backend_error=error)
+    paths = _selected_paths(request, root_info, rows)
+    if paths is None:
+        return _Failure(request.operand)
+    return _render_paths(request, paths)
+
+
+async def _run_find(
+    command: str,
+    request: _FindRequest,
+    sources: Mapping[str, AsyncFilesystemSource],
+) -> None:
+    await _run_single_operand_text(
+        command,
+        request.operand,
+        sources,
+        lambda filesystem: _search(request, filesystem),
+    )

fss_cli/_head_tail.py

@@ -0,0 +1,128 @@
+"""Typed ``head`` and ``tail`` runtime."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from ._command import (
+    _binary_stdout,
+    _CommandFailureError,
+    _drain_current_operation,
+    _MappedOperand,
+    _run_mapped_command,
+    _valid_size,
+    _write_binary,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from fsspec.asyn import AsyncFileSystem
+
+    from ._app import AsyncFilesystemSource
+
+
+@dataclass(frozen=True)
+class _ByteRangeRequest:
+    count: int
+    operand: _MappedOperand
+
+
+async def _read_head(
+    request: _ByteRangeRequest,
+    filesystem: AsyncFileSystem,
+) -> bytes:
+    if request.count == 0:
+        try:
+            info = await _drain_current_operation(filesystem._info(request.operand.path))
+        except Exception as error:
+            raise _CommandFailureError(request.operand, error) from error
+        if _is_file(request.operand, info):
+            return b""
+    try:
+        result = await _drain_current_operation(filesystem._cat_file(request.operand.path, start=0, end=request.count))
+    except Exception as error:
+        raise _CommandFailureError(request.operand, error) from error
+    if type(result) is not bytes or len(result) > request.count:
+        raise _CommandFailureError(request.operand)
+    return result
+
+
+def _info_field(operand: _MappedOperand, info: object, key: str) -> object:
+    if not isinstance(info, Mapping):
+        raise _CommandFailureError(operand)
+    try:
+        return info.get(key)
+    except Exception:  # noqa: BLE001 - hostile metadata mapping boundary.
+        raise _CommandFailureError(operand) from None
+
+
+def _size_from_info(operand: _MappedOperand, info: object) -> int:
+    size = _info_field(operand, info, "size")
+    if not _valid_size(size):
+        raise _CommandFailureError(operand)
+    return size
+
+
+def _is_file(operand: _MappedOperand, info: object) -> bool:
+    """Return whether ``info`` proves a regular file, so a zero read needs no bytes.
+
+    Any other kind falls back to the bounded read, so the backend still owns
+    the diagnostic for directories and other non-file operands.
+    """
+    kind = _info_field(operand, info, "type")
+    return type(kind) is str and kind == "file"
+
+
+async def _read_tail(
+    request: _ByteRangeRequest,
+    filesystem: AsyncFileSystem,
+) -> bytes:
+    try:
+        info = await _drain_current_operation(filesystem._info(request.operand.path))
+    except Exception as error:
+        raise _CommandFailureError(request.operand, error) from error
+    _size_from_info(request.operand, info)
+    if request.count == 0 and _is_file(request.operand, info):
+        return b""
+    try:
+        result = await _drain_current_operation(
+            filesystem._cat_file(request.operand.path, start=-request.count, end=None)
+        )
+    except Exception as error:
+        raise _CommandFailureError(request.operand, error) from error
+    if type(result) is not bytes or len(result) > request.count:
+        raise _CommandFailureError(request.operand)
+    return result
+
+
+def _emit(payload: bytes) -> None:
+    if not payload:
+        return
+    stdout = _binary_stdout()
+    _write_binary(stdout, payload)
+    stdout.flush()
+
+
+async def _run_byte_range(
+    command: str,
+    count: int,
+    operand: _MappedOperand,
+    sources: Mapping[str, AsyncFilesystemSource],
+    operation: Callable[
+        [_ByteRangeRequest, AsyncFileSystem],
+        Awaitable[bytes],
+    ],
+) -> None:
+    request = _ByteRangeRequest(count, operand)
+
+    async def execute(filesystems: Mapping[str, AsyncFileSystem]) -> None:
+        payload = await operation(request, filesystems[operand.name])
+        try:
+            _emit(payload)
+        except Exception as error:
+            raise _CommandFailureError(error=error) from error
+
+    await _run_mapped_command(command, (operand,), sources, execute)

fss_cli/_info.py

@@ -0,0 +1,179 @@
+"""Normalized metadata execution for typed ``info``."""
+
+from __future__ import annotations
+
+import pprint
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, cast
+
+from ._command import (
+    _binary_stdout,
+    _CommandFailureError,
+    _drain_current_operation,
+    _MappedOperand,
+    _run_mapped_command,
+    _write_binary,
+)
+from ._listing import ListingRow, to_listing
+
+if TYPE_CHECKING:
+    from fsspec.asyn import AsyncFileSystem
+
+    from ._app import AsyncFilesystemSource
+
+_PRETTY_WIDTH = 80
+
+
+@dataclass(frozen=True, order=True)
+class _StablePresentation:
+    sort_type: str
+    text: str
+
+    def __repr__(self) -> str:
+        return self.text
+
+
+def _canonical_value(value: object, active: set[int]) -> object:
+    if not isinstance(value, (Mapping, list, tuple, set, frozenset)):
+        return value
+
+    identity = id(value)
+    if identity in active:
+        message = "recursive metadata containers are not supported"
+        raise ValueError(message)
+    active.add(identity)
+    try:
+        if isinstance(value, Mapping):
+            canonical: object = _canonical_mapping(cast("Mapping[object, object]", value), active)
+        elif isinstance(value, list):
+            canonical = [_canonical_value(item, active) for item in value]
+        elif isinstance(value, tuple):
+            canonical = tuple(_canonical_value(item, active) for item in value)
+        elif isinstance(value, set):
+            canonical = _canonical_set(cast("set[object]", value), active, frozen=False)
+        else:
+            canonical = _canonical_set(value, active, frozen=True)
+        return canonical
+    finally:
+        active.remove(identity)
+
+
+def _canonical_mapping(
+    value: Mapping[object, object],
+    active: set[int],
+) -> dict[object, object]:
+    source_length = len(value)
+    entries: list[tuple[object, object]] = []
+    spellings: set[str] = set()
+    for key in value:
+        item = value[key]
+        canonical_key = _canonical_value(key, active)
+        hash(canonical_key)
+        spelling = _pretty(canonical_key)
+        if spelling in spellings:
+            message = "distinct mapping keys have the same presentation"
+            raise ValueError(message)
+        spellings.add(spelling)
+        entries.append(
+            (
+                _StablePresentation(
+                    f"{type(key).__module__}.{type(key).__qualname__}",
+                    spelling,
+                ),
+                _canonical_value(item, active),
+            )
+        )
+
+    if len(entries) != source_length:
+        message = "mapping iteration does not match its reported length"
+        raise ValueError(message)
+    canonical = dict(entries)
+    if len(canonical) != source_length:
+        message = "canonical mapping keys are not distinct"
+        raise ValueError(message)
+    return canonical
+
+
+def _canonical_set(
+    value: set[object] | frozenset[object],
+    active: set[int],
+    *,
+    frozen: bool,
+) -> _StablePresentation:
+    members = sorted(_pretty(_canonical_value(item, active)) for item in value)
+    if frozen:
+        spelling = "frozenset()" if not members else f"frozenset({{{', '.join(members)}}})"
+    else:
+        spelling = "set()" if not members else f"{{{', '.join(members)}}}"
+    return _StablePresentation(f"{type(value).__module__}.{type(value).__qualname__}", spelling)
+
+
+def _pretty(value: object) -> str:
+    return pprint.pformat(value, width=_PRETTY_WIDTH, sort_dicts=True)
+
+
+def _render_info(row: ListingRow) -> bytes:
+    values = {
+        "name": row.name,
+        "kind": row.kind,
+        "size": row.size,
+        "mtime": row.mtime,
+        "mode": row.mode,
+        "nlink": row.nlink,
+        "owner": row.owner,
+        "group": row.group,
+        "link_target": row.link_target,
+        "extra": _canonical_value(row.extra, set()),
+    }
+    rendered = _pretty(values)
+    return f"{rendered}\n".encode()
+
+
+def _normalize_info(result: object) -> bytes | None:
+    if not isinstance(result, Mapping):
+        return None
+    try:
+        if any(type(key) is not str for key in result):
+            return None
+        row = to_listing(cast("Mapping[str, object]", result))
+        return _render_info(row)
+    except Exception:  # noqa: BLE001 - malformed mapping or printable value.
+        return None
+
+
+async def _read_info(
+    operand: _MappedOperand,
+    filesystem: AsyncFileSystem,
+) -> bytes:
+    try:
+        result = await _drain_current_operation(filesystem._info(operand.path))
+    except Exception as error:
+        raise _CommandFailureError(operand, error) from error
+    payload = _normalize_info(result)
+    if payload is None:
+        raise _CommandFailureError(operand)
+    return payload
+
+
+async def _run_info(
+    command: str,
+    operand: _MappedOperand,
+    sources: Mapping[str, AsyncFilesystemSource],
+) -> None:
+    async def execute(filesystems: Mapping[str, AsyncFileSystem]) -> None:
+        payload = await _read_info(operand, filesystems[operand.name])
+        try:
+            stdout = _binary_stdout()
+            _write_binary(stdout, payload)
+            stdout.flush()
+        except Exception as error:
+            raise _CommandFailureError(error=error) from error
+
+    await _run_mapped_command(
+        command,
+        (operand,),
+        sources,
+        execute,
+        broken_pipe_exit_code=1,
+    )