fss-cli 0.11.0__py3-none-any.whl

fss_cli/_listing.py

@@ -0,0 +1,289 @@
+"""Pure normalization and rendering helpers for heterogeneous fsspec metadata."""
+
+from __future__ import annotations
+
+import re
+import stat
+import time
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Literal
+
+from ._accounts import group_name, owner_name
+from ._metadata import normalize_time as _normalize_time
+from ._metadata import snapshot_mapping, valid_display_text
+from ._path import _lexical_basename
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
+_INFO_FIELDS = frozenset(
+    {
+        "name",
+        "type",
+        "islink",
+        "size",
+        "mtime",
+        "LastModified",
+        "last_modified",
+        "mode",
+        "nlink",
+        "uid",
+        "gid",
+        "destination",
+        "target",
+    }
+)
+_MTIME_FIELDS = ("mtime", "LastModified", "last_modified")
+_SIZE_UNITS = ("K", "M", "G", "T", "P", "E", "Z", "Y")
+_SIZE_BASE = 1024
+_SINGLE_DECIMAL_LIMIT = 100
+# SGR 22 ends bold without resetting colors a name may carry; SGR 0 would.
+_BOLD = "\x1b[1m"
+_NORMAL_INTENSITY = "\x1b[22m"
+
+ListingKind = Literal["file", "dir", "link", "other"]
+_MODE_KIND_BY_TYPE: dict[int, ListingKind] = {
+    stat.S_IFREG: "file",
+    stat.S_IFDIR: "dir",
+    stat.S_IFLNK: "link",
+}
+
+
+@dataclass(frozen=True)
+class ListingRow:
+    """Backend-neutral metadata used by listing and information commands."""
+
+    name: str
+    kind: ListingKind
+    size: int | None
+    mtime: float | None
+    mode: int | None
+    nlink: int | None
+    owner: str | int | None
+    group: str | int | None
+    link_target: str | None
+    extra: Mapping[str, object]
+    permissions: str | None = None
+
+
+def _kind(info: Mapping[str, object]) -> ListingKind:
+    if info.get("islink") is True:
+        return "link"
+
+    value = info.get("type")
+    if value == "file":
+        return "file"
+    if value in {"dir", "directory"}:
+        return "dir"
+    if value in {"link", "symlink"}:
+        return "link"
+    return "other"
+
+
+def _non_negative_int(value: object) -> int | None:
+    return value if type(value) is int and value >= 0 else None
+
+
+def _identity(value: object) -> str | int | None:
+    if type(value) is int:
+        return value if value >= 0 else None
+    if type(value) is str:
+        if not valid_display_text(value):
+            message = "identity contains a terminal control character"
+            raise ValueError(message)
+        return value
+    return None
+
+
+def _group(info: Mapping[str, object]) -> str | int | None:
+    for field in ("group", "gid"):
+        if info.get(field) is not None:
+            return _identity(info[field])
+    if "read_groups" not in info and "write_groups" not in info:
+        return None
+    summaries = []
+    for field, prefix in (("read_groups", "r"), ("write_groups", "w")):
+        groups = info.get(field)
+        if groups is None:
+            summary = "?"
+        elif isinstance(groups, (tuple, list)) and all(
+            type(group) is str and group and valid_display_text(group) for group in groups
+        ):
+            summary = ",".join(str(group) for group in groups) if groups else "NONE"
+        else:
+            message = "invalid access group list"
+            raise ValueError(message)
+        summaries.append(f"{prefix}={summary}")
+    return ",".join(summaries)
+
+
+def _permissions(info: Mapping[str, object]) -> str | None:
+    value = info.get("permissions")
+    if value is None:
+        return None
+    if type(value) is not str or re.fullmatch(r"[-dl?][rwx?-]{9}", value) is None:
+        message = "invalid access summary"
+        raise ValueError(message)
+    return value
+
+
+def _mtime(info: Mapping[str, object]) -> float | None:
+    for field in _MTIME_FIELDS:
+        if field in info:
+            return _normalize_time(info[field])
+    return None
+
+
+def _link_target(info: Mapping[str, object]) -> str | None:
+    for field in ("destination", "target"):
+        value = info.get(field)
+        if type(value) is str:
+            if not valid_display_text(value):
+                message = "link target contains a terminal control character"
+                raise ValueError(message)
+            return value
+    return None
+
+
+def _extra(info: Mapping[str, object]) -> Mapping[str, object]:
+    values = {key: value for key, value in info.items() if type(key) is str and key not in _INFO_FIELDS}
+    return MappingProxyType(values)
+
+
+def to_listing(info: Mapping[str, object]) -> ListingRow:
+    """Normalize one fsspec ``info`` mapping without filesystem I/O."""
+    info = snapshot_mapping(info)
+    name = info.get("name")
+    if type(name) is not str or not valid_display_text(name):
+        message = "info name must be a string"
+        raise ValueError(message)
+
+    return ListingRow(
+        name=_lexical_basename(name),
+        kind=_kind(info),
+        size=_non_negative_int(info.get("size")),
+        mtime=_mtime(info),
+        mode=_non_negative_int(info.get("mode")),
+        nlink=_non_negative_int(info.get("nlink")),
+        owner=_identity(info.get("owner", info.get("uid"))),
+        group=_group(info),
+        link_target=_link_target(info),
+        extra=_extra(info),
+        permissions=_permissions(info),
+    )
+
+
+def format_size(size: int | None, *, human_readable: bool = False) -> str:
+    """Render an exact byte count, or a compact 1024-base human size."""
+    if size is None:
+        return "-"
+    if type(size) is not int or size < 0:
+        message = "size must be a non-negative integer or None"
+        raise ValueError(message)
+    if not human_readable:
+        return str(size)
+    if size < _SIZE_BASE:
+        return f"{size}B"
+
+    unit_index = 0
+    unit_size = _SIZE_BASE
+    while True:
+        tenths = (size * 10 + unit_size // 2) // unit_size
+        if tenths < _SINGLE_DECIMAL_LIMIT:
+            whole, decimal = divmod(tenths, 10)
+            rendered = str(whole) if decimal == 0 else f"{whole}.{decimal}"
+            return f"{rendered}{_SIZE_UNITS[unit_index]}"
+
+        rounded = (size + unit_size // 2) // unit_size
+        if rounded < _SIZE_BASE or unit_index == len(_SIZE_UNITS) - 1:
+            return f"{rounded}{_SIZE_UNITS[unit_index]}"
+        unit_index += 1
+        unit_size *= _SIZE_BASE
+
+
+def _format_mtime(value: float | None) -> str:
+    if value is None:
+        return "-"
+    now = time.time()
+    recent = now - 15_552_000 <= value <= now + 3600
+    return time.strftime("%b %e %H:%M" if recent else "%b %e  %Y", time.localtime(value))
+
+
+def _type_indicator(row: ListingRow) -> str:
+    if row.mode is None:
+        return row.permissions or {"file": "-", "dir": "d", "link": "l", "other": "?"}[row.kind] + "?" * 9
+    mode_kind = _MODE_KIND_BY_TYPE.get(stat.S_IFMT(row.mode), "other")
+    if mode_kind != row.kind:
+        return {"file": "-", "dir": "d", "link": "l", "other": "?"}[row.kind] + "?" * 9
+    return stat.filemode(row.mode)
+
+
+def emphasize(text: str) -> str:
+    """Wrap text in bold, leaving every character of it untouched."""
+    return f"{_BOLD}{text}{_NORMAL_INTENSITY}"
+
+
+def _display_name(row: ListingRow) -> str:
+    if row.kind == "link" and row.link_target is not None:
+        return f"{row.name} -> {row.link_target}"
+    return row.name
+
+
+def render_listing(
+    rows: Sequence[ListingRow],
+    *,
+    human_readable: bool = False,
+    emphasize_directories: bool = False,
+) -> str:
+    """Render stable shell columns with explicit gaps for unknown metadata.
+
+    With ``emphasize_directories``, directory names are bold; column widths are
+    still measured on the unstyled text.
+    """
+    if not rows:
+        return ""
+
+    owners = {
+        value: "-" if value is None else owner_name(value) if isinstance(value, int) else value
+        for value in {row.owner for row in rows}
+    }
+    groups = {
+        value: "-" if value is None else group_name(value) if isinstance(value, int) else value
+        for value in {row.group for row in rows}
+    }
+    rendered_columns: list[tuple[bool, list[str]]] = [(False, [_type_indicator(row) for row in rows])]
+    rendered_columns.extend(
+        [
+            (True, ["-" if row.nlink is None else str(row.nlink) for row in rows]),
+            (
+                False,
+                [owners[row.owner] for row in rows],
+            ),
+            (
+                False,
+                [groups[row.group] for row in rows],
+            ),
+            (
+                True,
+                [format_size(row.size, human_readable=human_readable) for row in rows],
+            ),
+            (False, [_format_mtime(row.mtime) for row in rows]),
+        ]
+    )
+    rendered_columns.append((False, [_display_name(row) for row in rows]))
+
+    widths = [max(len(cell) for cell in column) for _, column in rendered_columns]
+    lines = []
+    for index in range(len(rows)):
+        cells = []
+        for column_index, (right_aligned, column) in enumerate(rendered_columns):
+            cell = column[index]
+            if column_index == len(rendered_columns) - 1:
+                cells.append(emphasize(cell) if emphasize_directories and rows[index].kind == "dir" else cell)
+            elif right_aligned:
+                cells.append(cell.rjust(widths[column_index]))
+            else:
+                cells.append(cell.ljust(widths[column_index]))
+        lines.append("  ".join(cells))
+    return "\n".join(lines) + "\n"

fss_cli/_logging.py

@@ -0,0 +1,72 @@
+"""Standard-library transfer records for embedding hosts.
+
+Commands log under the ``fss_cli`` logger hierarchy so a host can route
+them through its own handlers; the library itself installs only a
+``NullHandler`` and never prints a record. One INFO record describes each file
+operation; DEBUG records describe content-identity decisions and staging.
+
+Records never carry credentials: every logged path or operand passes through
+:func:`_redact`, which drops URL user information, query strings, and
+fragments, and escapes control characters. Storage options are never logged.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from typing import TYPE_CHECKING
+
+from ._diagnostics import _render_diagnostic_value
+
+if TYPE_CHECKING:
+    import logging
+
+_USERINFO = re.compile(r"(?<=//)[^/?#@]*@")
+
+
+def _redact(value: str) -> str:
+    """Return ``value`` safe to log: no userinfo, query, fragment, or controls."""
+    value = value.split("?", 1)[0].split("#", 1)[0]
+    return _render_diagnostic_value(_USERINFO.sub("", value))
+
+
+def _location(name: str, path: str) -> str:
+    """Render one mapped location the way a user spells it, redacted."""
+    return _redact(f"{name}:{path}")
+
+
+def _log_file_operation(  # noqa: PLR0913 - one structured record per file.
+    logger: logging.Logger,
+    outcome: str,
+    source: str,
+    destination: str,
+    size: int | None,
+    started: float,
+) -> None:
+    """Emit the INFO record for one completed file operation.
+
+    Args:
+        logger: The emitting module's logger.
+        outcome: ``copied``, ``staged``, ``skipped``, ``moved``, or
+            ``verified``.
+        source: The redacted source location.
+        destination: The redacted destination location.
+        size: Bytes the operation concerned, when known.
+        started: The :func:`time.monotonic` value when the operation began.
+    """
+    duration = time.monotonic() - started
+    logger.info(
+        "%s %s -> %s (%s bytes, %.3fs)",
+        outcome,
+        source,
+        destination,
+        "?" if size is None else size,
+        duration,
+        extra={
+            "outcome": outcome,
+            "source": source,
+            "destination": destination,
+            "bytes": size,
+            "duration": duration,
+        },
+    )