fss-cli 0.11.0__py3-none-any.whl

fss_cli/_rmdir.py

@@ -0,0 +1,148 @@
+"""Typed async execution for ``rmdir``."""
+
+from __future__ import annotations
+
+import errno
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from ._command import (
+    _drain_current_operation,
+    _Failure,
+    _MappedOperand,
+    _raise_operand_failures,
+    _render_backend_failure,
+    _render_operand_diagnostic,
+    _run_mapped_command,
+)
+
+if TYPE_CHECKING:
+    from fsspec.asyn import AsyncFileSystem
+
+    from ._app import AsyncFilesystemSource
+
+
+@dataclass(frozen=True)
+class _RmdirFailure(_Failure):
+    """A failure raised on the empty-directory removal path.
+
+    Structurally identical to the base failure; the distinct type is how ``rm``
+    tells a directory-path failure from a file-path one, because the two render
+    different diagnostic vocabularies for the same condition.
+    """
+
+
+async def _require_directory(
+    operand: _MappedOperand,
+    filesystem: AsyncFileSystem,
+) -> _RmdirFailure | None:
+    try:
+        info = await _drain_current_operation(filesystem._info(operand.path))
+    except Exception as error:  # noqa: BLE001 - classify awaited backend failure.
+        return _RmdirFailure(operand, backend_error=error)
+
+    if not isinstance(info, Mapping) or not isinstance(info.get("type"), str):
+        return _RmdirFailure(operand, incompatible="result")
+
+    result_type = info["type"]
+    if result_type == "file":
+        return _RmdirFailure(operand, incompatible="directory")
+    if result_type != "directory":
+        return _RmdirFailure(operand, incompatible="result")
+    return None
+
+
+async def _observe_post_mutation(
+    operand: _MappedOperand,
+    filesystem: AsyncFileSystem,
+    mutation_error: Exception | None,
+) -> _RmdirFailure | None:
+    try:
+        await _drain_current_operation(filesystem._info(operand.path))
+    except FileNotFoundError:
+        # Absence proves success, including after a mutation-call exception.
+        return None
+    except Exception as error:  # noqa: BLE001 - never hide non-not-found errors.
+        if mutation_error is not None:
+            return _RmdirFailure(operand, backend_error=mutation_error, uncertain=True)
+        return _RmdirFailure(operand, backend_error=error, uncertain=True)
+    if mutation_error is not None:
+        # Presence after a mutation-call exception is confirmed failure.
+        return _RmdirFailure(operand, backend_error=mutation_error)
+    return _RmdirFailure(operand, incompatible="result")
+
+
+async def _remove_empty_directory(
+    operand: _MappedOperand,
+    filesystem: AsyncFileSystem,
+) -> _RmdirFailure | None:
+    directory_failure = await _require_directory(operand, filesystem)
+    if directory_failure is not None:
+        return directory_failure
+
+    rmdir = getattr(filesystem, "_rmdir", None)
+    if not callable(rmdir):
+        return _RmdirFailure(
+            operand,
+            backend_error=NotImplementedError(f"{type(filesystem).__name__} lacks async _rmdir"),
+        )
+
+    mutation_error: Exception | None = None
+    try:
+        await _drain_current_operation(rmdir(operand.path))
+    except Exception as error:  # noqa: BLE001 - mutation may leave uncertain state.
+        mutation_error = error
+
+    return await _observe_post_mutation(operand, filesystem, mutation_error)
+
+
+def _render_rmdir_backend_failure(
+    command: str,
+    operand: _MappedOperand,
+    error: Exception,
+) -> None:
+    if isinstance(error, OSError) and error.errno == errno.ENOTEMPTY:
+        _render_operand_diagnostic(command, operand, "directory not empty")
+        return
+    _render_backend_failure(command, operand, error)
+
+
+def _render_failure(command: str, failure: _RmdirFailure) -> None:
+    if failure.uncertain:
+        _render_operand_diagnostic(command, failure.operand, "uncertain state")
+    elif failure.incompatible == "directory":
+        _render_operand_diagnostic(command, failure.operand, "not a directory")
+    elif failure.incompatible == "result":
+        _render_operand_diagnostic(command, failure.operand, "incompatible result")
+    elif isinstance(failure.backend_error, NotADirectoryError):
+        _render_operand_diagnostic(command, failure.operand, "not a directory")
+    elif failure.backend_error is None:
+        _render_operand_diagnostic(command, failure.operand, "incompatible result")
+    else:
+        _render_rmdir_backend_failure(command, failure.operand, failure.backend_error)
+
+
+async def _trace_operands(
+    operands: tuple[_MappedOperand, ...],
+    filesystems: Mapping[str, AsyncFileSystem],
+) -> tuple[_RmdirFailure, ...]:
+    failures = []
+    for operand in operands:
+        result = await _remove_empty_directory(operand, filesystems[operand.name])
+        if isinstance(result, _RmdirFailure):
+            failures.append(result)
+    return tuple(failures)
+
+
+async def _run_rmdir(
+    command: str,
+    operands: tuple[_MappedOperand, ...],
+    sources: Mapping[str, AsyncFilesystemSource],
+) -> None:
+    async def operation(filesystems: Mapping[str, AsyncFileSystem]) -> None:
+        failures = await _trace_operands(operands, filesystems)
+        if failures:
+            _raise_operand_failures(command, failures, _render_failure)
+
+    await _run_mapped_command(command, operands, sources, operation)

fss_cli/_size.py

@@ -0,0 +1,95 @@
+"""Exact-size execution for typed ``size``."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import typer
+
+from ._command import (
+    _CommandFailureError,
+    _drain_current_operation,
+    _MappedOperand,
+    _run_mapped_command,
+    _valid_size,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from fsspec.asyn import AsyncFileSystem
+
+    from ._app import AsyncFilesystemSource
+
+
+def _group_operands(
+    operands: tuple[_MappedOperand, ...],
+) -> dict[str, list[tuple[int, _MappedOperand]]]:
+    groups: dict[str, list[tuple[int, _MappedOperand]]] = {}
+    for index, operand in enumerate(operands):
+        groups.setdefault(operand.name, []).append((index, operand))
+    return groups
+
+
+async def _measure(
+    operands: tuple[_MappedOperand, ...],
+    filesystems: Mapping[str, AsyncFileSystem],
+) -> str:
+    if len(operands) == 1:
+        return await _measure_one(operands[0], filesystems)
+    return await _measure_many(operands, filesystems)
+
+
+async def _measure_one(
+    operand: _MappedOperand,
+    filesystems: Mapping[str, AsyncFileSystem],
+) -> str:
+    try:
+        result = await _drain_current_operation(filesystems[operand.name]._size(operand.path))
+    except Exception as error:
+        raise _CommandFailureError(operand, error) from error
+    if not _valid_size(result):
+        raise _CommandFailureError(operand)
+    return f"{result}\t{operand.spelling}\n"
+
+
+async def _measure_many(
+    operands: tuple[_MappedOperand, ...],
+    filesystems: Mapping[str, AsyncFileSystem],
+) -> str:
+    sizes: dict[int, int] = {}
+    for name, group in _group_operands(operands).items():
+        paths = [operand.path for _, operand in group]
+        try:
+            result = await _drain_current_operation(filesystems[name]._sizes(paths))
+        except Exception as error:
+            raise _CommandFailureError(group[0][1], error) from error
+        if type(result) is not list or len(result) != len(group):
+            raise _CommandFailureError(group[0][1])
+        for (index, operand), size in zip(group, result, strict=True):
+            if not _valid_size(size):
+                raise _CommandFailureError(operand)
+            sizes[index] = size
+
+    return "".join(f"{sizes[index]}\t{operand.spelling}\n" for index, operand in enumerate(operands))
+
+
+async def _run_size(
+    command: str,
+    operands: tuple[_MappedOperand, ...],
+    sources: Mapping[str, AsyncFilesystemSource],
+) -> None:
+    async def execute(filesystems: Mapping[str, AsyncFileSystem]) -> None:
+        result = await _measure(operands, filesystems)
+        try:
+            typer.echo(result, nl=False, color=True)
+        except Exception as error:
+            raise _CommandFailureError(error=error) from error
+
+    await _run_mapped_command(
+        command,
+        operands,
+        sources,
+        execute,
+        broken_pipe_exit_code=1,
+    )

fss_cli/_sources.py

@@ -0,0 +1,178 @@
+"""Invocation-owned async filesystem source lifecycle."""
+
+from __future__ import annotations
+
+import sys
+from contextlib import AbstractAsyncContextManager
+from types import TracebackType
+from typing import TYPE_CHECKING, TypeAlias
+
+import typer
+from fsspec.asyn import AsyncFileSystem
+
+from ._diagnostics import _render_diagnostic_prefix, _render_diagnostic_value
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Mapping
+
+    from fsspec import AbstractFileSystem
+
+    from ._app import AsyncFilesystemSource
+
+_ExcInfo: TypeAlias = tuple[
+    type[BaseException] | None,
+    BaseException | None,
+    TracebackType | None,
+]
+_EMPTY_EXC_INFO: _ExcInfo = (None, None, None)
+
+
+def _source_exception(
+    command: str,
+    name: str,
+    stage: str,
+    error: Exception,
+) -> None:
+    prefix = _render_diagnostic_prefix(command)
+    rendered_name = _render_diagnostic_value(name)
+    rendered_class = _render_diagnostic_value(type(error).__name__)
+    rendered_message = _render_diagnostic_value(str(error))
+    typer.echo(
+        f"{prefix} {rendered_name}: source {stage} failure ({rendered_class}): {rendered_message}",
+        err=True,
+    )
+
+
+def _render_exit_failures(
+    command: str,
+    failures: Iterable[tuple[str, Exception]],
+    *,
+    preserve_control: bool,
+) -> BaseException | None:
+    render_control = None
+    for name, error in failures:
+        try:
+            _source_exception(command, name, "exit", error)
+        except Exception:  # noqa: BLE001, PERF203, S110 - attempt every diagnostic.
+            pass
+        except BaseException as error:  # noqa: BLE001 - preserve control flow.
+            if not preserve_control and render_control is None:
+                render_control = error
+    return render_control
+
+
+class _SourceInvocation:
+    """Acquire, expose, and release sources for one command invocation."""
+
+    def __init__(
+        self,
+        command: str,
+        sources: Mapping[str, AsyncFilesystemSource],
+    ) -> None:
+        self._command = command
+        self._sources = sources
+        self._entered: list[tuple[str, AbstractAsyncContextManager[AbstractFileSystem]]] = []
+        self._failure_exc_info: _ExcInfo = _EMPTY_EXC_INFO
+
+    async def acquire(
+        self,
+        names: Iterable[str],
+    ) -> Mapping[str, AsyncFileSystem] | None:
+        """Acquire distinct mapped names sequentially in the given order."""
+        filesystems: dict[str, AsyncFileSystem] = {}
+        for name in names:
+            try:
+                manager = self._sources[name]()
+            except Exception as error:  # noqa: BLE001 - classify source failures.
+                _source_exception(self._command, name, "factory", error)
+                self._remember_failure(error)
+                return None
+
+            if not (
+                isinstance(manager, AbstractAsyncContextManager)
+                and callable(getattr(manager, "__aenter__", None))
+                and callable(getattr(manager, "__aexit__", None))
+            ):
+                prefix = _render_diagnostic_prefix(self._command)
+                rendered_name = _render_diagnostic_value(name)
+                typer.echo(
+                    f"{prefix} {rendered_name}: source factory returned incompatible async context manager",
+                    err=True,
+                )
+                return None
+
+            try:
+                filesystem = await manager.__aenter__()
+            except Exception as error:  # noqa: BLE001 - classify source failures.
+                _source_exception(self._command, name, "entry", error)
+                self._remember_failure(error)
+                return None
+
+            self._entered.append((name, manager))
+            if not (
+                isinstance(filesystem, AsyncFileSystem)
+                and filesystem.async_impl is True
+                and filesystem.asynchronous is True
+            ):
+                prefix = _render_diagnostic_prefix(self._command)
+                rendered_name = _render_diagnostic_value(name)
+                typer.echo(
+                    f"{prefix} {rendered_name}: source yielded incompatible async filesystem",
+                    err=True,
+                )
+                return None
+            filesystems[name] = filesystem
+        return filesystems
+
+    def _remember_failure(self, error: Exception) -> None:
+        self._failure_exc_info = (type(error), error, error.__traceback__)
+
+    async def close(self, active_exc_info: _ExcInfo) -> bool:
+        """Exit every entered source and preserve control-flow precedence."""
+        exit_exc_info = active_exc_info if active_exc_info[1] is not None else self._failure_exc_info
+        primary_control = (
+            active_exc_info[1]
+            if active_exc_info[1] is not None and not isinstance(active_exc_info[1], Exception)
+            else None
+        )
+        cleanup_control = None
+        exit_failures: list[tuple[str, Exception]] = []
+        entered, self._entered = self._entered, []
+
+        for name, manager in reversed(entered):
+            try:
+                await manager.__aexit__(*exit_exc_info)
+            except Exception as error:  # noqa: BLE001, PERF203 - every exit runs.
+                exit_failures.append((name, error))
+            except BaseException as error:  # noqa: BLE001 - preserve control flow.
+                if primary_control is None and cleanup_control is None:
+                    cleanup_control = error
+
+        render_control = _render_exit_failures(
+            self._command,
+            exit_failures,
+            preserve_control=(primary_control is not None or cleanup_control is not None),
+        )
+
+        if primary_control is None:
+            if cleanup_control is not None:
+                raise cleanup_control
+            if render_control is not None:
+                raise render_control
+        return bool(exit_failures)
+
+    async def close_with_command_error(self, command_error: Exception | None) -> bool:
+        """Close after the command, letting a captured command error take precedence.
+
+        The command error is captured, not raised, so it never flows through
+        ``__aexit__``. Fold it into the exit ``exc_info`` only when no live
+        exception is propagating, or the live one is an ordinary ``Exception``.
+        """
+        active_exc_info: _ExcInfo = sys.exc_info()
+        if command_error is not None and (active_exc_info[1] is None or isinstance(active_exc_info[1], Exception)):
+            active_exc_info = (
+                type(command_error),
+                command_error,
+                command_error.__traceback__,
+            )
+        return await self.close(active_exc_info)

fss_cli/_stat.py

@@ -0,0 +1,196 @@
+"""Reduced BSD/macOS ``stat`` execution for typed callbacks.
+
+Owner and group names resolve through the local ``pwd``/``grp`` account
+databases on a best-effort basis: they describe the local namespace, not the
+remote source's, and fall back to the numeric id when a name is unknown or when
+the host lacks these POSIX-only modules.
+"""
+
+from __future__ import annotations
+
+import stat as stat_module
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass
+from functools import partial
+from typing import TYPE_CHECKING, cast
+
+from ._accounts import group_name as _group_name
+from ._accounts import owner_name as _owner_name
+from ._command import (
+    _binary_stdout,
+    _CommandFailureError,
+    _drain_current_operation,
+    _Failure,
+    _first_backend_error,
+    _MappedOperand,
+    _render_failure,
+    _run_mapped_command,
+    _write_binary,
+)
+from ._concurrent import _run_bounded
+from ._metadata import normalize_time
+
+if TYPE_CHECKING:
+    from fsspec.asyn import AsyncFileSystem
+
+    from ._app import AsyncFilesystemSource
+
+_MONTHS = (
+    "Jan",
+    "Feb",
+    "Mar",
+    "Apr",
+    "May",
+    "Jun",
+    "Jul",
+    "Aug",
+    "Sep",
+    "Oct",
+    "Nov",
+    "Dec",
+)
+
+
+@dataclass(frozen=True)
+class _StatSuccess:
+    operand: _MappedOperand
+    line: bytes
+
+
+def _format_mtime(mtime: float) -> str:
+    local = time.localtime(mtime)
+    month = _MONTHS[local.tm_mon - 1]
+    return f"{month} {local.tm_mday:2d} {local.tm_hour:02d}:{local.tm_min:02d}:{local.tm_sec:02d} {local.tm_year}"
+
+
+def _validate_info(  # noqa: C901, PLR0911 - locked Local-rich shape checks.
+    info: object,
+) -> Mapping[str, object] | None:
+    if not isinstance(info, Mapping):
+        return None
+    mapping = cast("Mapping[str, object]", info)
+    result_type = mapping.get("type")
+    if result_type not in {"file", "directory"} or type(result_type) is not str:
+        return None
+    if "islink" in mapping:
+        islink = mapping["islink"]
+        if type(islink) is not bool or islink:
+            return None
+    name = mapping.get("name")
+    if type(name) is not str:
+        return None
+    size = mapping.get("size")
+    if type(size) is not int or size < 0:
+        return None
+    mode = mapping.get("mode")
+    if type(mode) is not int:
+        return None
+    nlink = mapping.get("nlink")
+    if type(nlink) is not int or nlink < 1:
+        return None
+    uid = mapping.get("uid")
+    if type(uid) is not int or uid < 0:
+        return None
+    gid = mapping.get("gid")
+    if type(gid) is not int or gid < 0:
+        return None
+    checked_mtime = normalize_time(mapping.get("mtime"))
+    if checked_mtime is None:
+        return None
+    try:
+        time.localtime(checked_mtime)
+    except (OverflowError, OSError, ValueError):
+        return None
+    return mapping
+
+
+def _render_line(operand: _MappedOperand, info: Mapping[str, object]) -> bytes:
+    mode = cast("int", info["mode"])
+    nlink = cast("int", info["nlink"])
+    uid = cast("int", info["uid"])
+    gid = cast("int", info["gid"])
+    size = cast("int", info["size"])
+    mtime = cast("float", normalize_time(info["mtime"]))
+    line = (
+        f"{stat_module.filemode(mode)} {nlink} {_owner_name(uid)} {_group_name(gid)} "
+        f'{size} "{_format_mtime(mtime)}" {operand.path}\n'
+    )
+    return line.encode()
+
+
+def _write_line(line: bytes) -> None:
+    stdout = _binary_stdout()
+    _write_binary(stdout, line)
+    stdout.flush()
+
+
+async def _read_operand(
+    operand: _MappedOperand,
+    filesystem: AsyncFileSystem,
+) -> _StatSuccess | _Failure:
+    try:
+        info = await _drain_current_operation(filesystem._info(operand.path))
+    except Exception as error:  # noqa: BLE001 - classify awaited backend failure.
+        return _Failure(operand, backend_error=error)
+
+    validated = _validate_info(info)
+    if validated is None:
+        return _Failure(operand, incompatible="result")
+    return _StatSuccess(operand, _render_line(operand, validated))
+
+
+async def _trace_operands(
+    command: str,
+    operands: tuple[_MappedOperand, ...],
+    filesystems: Mapping[str, AsyncFileSystem],
+) -> None:
+    # Reads overlap under the shared bound; lines and diagnostics are still
+    # emitted strictly in operand order, and an operand whose read raised
+    # propagates at its own position, after every earlier operand's output.
+    outcomes = await _run_bounded([partial(_read_operand, operand, filesystems[operand.name]) for operand in operands])
+    failures: list[_Failure] = []
+    for outcome in outcomes:
+        if outcome is None:  # pragma: no cover - only after a raised read.
+            break
+        if outcome.error is not None:
+            raise outcome.error
+        result = cast("_StatSuccess | _Failure", outcome.value)
+        if isinstance(result, _Failure):
+            failures.append(result)
+            try:
+                _render_failure(command, result)
+            except Exception as error:
+                raise _CommandFailureError(
+                    error=result.backend_error,
+                    render=False,
+                    propagate=error,
+                ) from error
+            continue
+        try:
+            _write_line(result.line)
+        except Exception as error:
+            raise _CommandFailureError(error=error) from error
+
+    if failures:
+        raise _CommandFailureError(
+            error=_first_backend_error(failures),
+            render=False,
+        )
+
+
+async def _run_stat(
+    command: str,
+    operands: tuple[_MappedOperand, ...],
+    sources: Mapping[str, AsyncFilesystemSource],
+) -> None:
+    async def execute(filesystems: Mapping[str, AsyncFileSystem]) -> None:
+        await _trace_operands(command, operands, filesystems)
+
+    await _run_mapped_command(
+        command,
+        operands,
+        sources,
+        execute,
+        broken_pipe_exit_code=1,
+    )

fss_cli/_test.py

@@ -0,0 +1,59 @@
+"""Predicate execution for typed ``test``."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from ._command import (
+    _CommandFailureError,
+    _drain_current_operation,
+    _MappedOperand,
+    _run_mapped_command,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from fsspec.asyn import AsyncFileSystem
+
+    from ._app import AsyncFilesystemSource
+
+_Predicate = Literal["e", "d", "f"]
+
+
+async def _evaluate(
+    predicate: _Predicate,
+    operand: _MappedOperand,
+    filesystem: AsyncFileSystem,
+) -> object:
+    path = operand.path
+    if predicate == "e":
+        result = await _drain_current_operation(filesystem._exists(path))
+    elif predicate == "d":
+        result = await _drain_current_operation(filesystem._isdir(path))
+    else:
+        result = await _drain_current_operation(filesystem._isfile(path))
+    return result
+
+
+async def _run_test(
+    command: str,
+    predicate: _Predicate,
+    operand: _MappedOperand,
+    sources: Mapping[str, AsyncFilesystemSource],
+) -> None:
+    async def execute(filesystems: Mapping[str, AsyncFileSystem]) -> None:
+        try:
+            result = await _evaluate(
+                predicate,
+                operand,
+                filesystems[operand.name],
+            )
+        except Exception as error:
+            raise _CommandFailureError(operand, error) from error
+        if type(result) is not bool:
+            raise _CommandFailureError(operand)
+        if not result:
+            raise _CommandFailureError(render=False)
+
+    await _run_mapped_command(command, (operand,), sources, execute)