mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/ux/path_kind.py

@@ -0,0 +1,147 @@
+"""Classify a path entry with the shared user-visible path-kind vocabulary.
+
+Classification uses one ``lstat`` and never follows links. Functions return ``None`` when the
+entry cannot be classified; callers must then use kind-neutral wording.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+from pathlib import Path
+
+# What a path can be, in plain words. A block device and a character device are one word here: the
+# difference between them changes nothing a person at a workbench would do next.
+A_FILE = "a file"
+A_FOLDER = "a folder"
+A_PIPE = "a pipe"
+A_SOCKET = "a socket"
+A_DEVICE = "a device"
+A_LINK = "a link"
+
+# What to say when the caller looked and could not tell. It is a word, not a kind: it is what fills
+# the hole in a sentence that has to be written whether or not the look succeeded.
+UNKNOWN_KIND = "something"
+
+# What to say when the caller observed that no entry exists.
+#
+# It is a separate word from `UNKNOWN_KIND` because the two are opposite findings that
+# :func:`kind_at` cannot tell apart: it answers ``None`` for a path that is not there *and* for a
+# mode it has no word for *and* for a look this account was not allowed to take. A caller that
+# needs the difference asks :func:`presence_at`, which takes the same single ``lstat`` and separates
+# them, so "there is nothing at /x" and "there is something at /x" are never guessed from one word.
+NOTHING_THERE = "nothing"
+
+_NAMES: tuple[tuple[int, str], ...] = (
+    (stat.S_IFREG, A_FILE),
+    (stat.S_IFDIR, A_FOLDER),
+    (stat.S_IFIFO, A_PIPE),
+    (stat.S_IFSOCK, A_SOCKET),
+    (stat.S_IFCHR, A_DEVICE),
+    (stat.S_IFBLK, A_DEVICE),
+    (stat.S_IFLNK, A_LINK),
+)
+
+
+def name_of_kind(mode: int | None) -> str | None:
+    """The plain noun for one ``st_mode``, or ``None`` for a mode with no word here.
+
+    Taken as a mode rather than as a path so a caller that already holds one names what it looked
+    at, without asking the filesystem a second question and getting a second answer about a later
+    moment. The four callers are the symlink refusals in :mod:`mostlyright.data_harness.pipeline`,
+    each of which decided its branch on the very ``st_mode`` it passes in here; the docstring used
+    to name the callers of :attr:`ux.plain_file.PlainFileRefusal.mode` instead, which was a claim
+    about a caller that did not exist.
+    """
+
+    if mode is None:
+        return None
+    kind = stat.S_IFMT(mode)
+    for bits, name in _NAMES:
+        if kind == bits:
+            return name
+    return None
+
+
+def kind_at(path: Path | str, *, dir_fd: int | None = None) -> str | None:
+    """The plain noun for what is at ``path``, without following a link.
+
+    ``dir_fd`` is passed through so a caller that already holds the parent open asks about the same
+    directory it was about to write into, rather than walking the name again and answering about
+    whatever is there by the time it arrives.
+
+    Every refusal is ``None``: a path that vanished between the failed write and this look is a
+    race, and a race must not become a claim.
+    """
+
+    try:
+        return name_of_kind(os.lstat(path, dir_fd=dir_fd).st_mode)
+    except (OSError, ValueError):
+        return None
+
+
+def presence_at(path: Path | str, *, dir_fd: int | None = None) -> str | None:
+    """What is at ``path`` in one word, telling "nothing is there" apart from "I cannot tell".
+
+    :func:`kind_at` answers ``None`` three ways -- the path is not there, the mode has no word
+    here, the look was refused -- and that conflation is what made a sentence about absence
+    unwritable without asking a second question. The second question every caller reached for was
+    ``Path.exists``, which **follows a link**: at a link that leads nowhere it answers false, so
+    five surfaces said "there is no folder at that path" about a link sitting right there, and told
+    the reader to check their spelling instead of to repoint or remove it.
+
+    So the difference is made here, off the same single ``lstat`` that answers everything else in
+    this module: :data:`NOTHING_THERE` when the name resolved to nothing, the plain noun when it
+    resolved to something, and ``None`` only when the look itself failed. A caller that gets
+    ``None`` still has to say something kind-neutral -- and, because ``None`` no longer means
+    absence, it must not say that nothing is there either.
+
+    Two refusals are read as the answer "nothing is there", and they are the two ``os.path.lexists``
+    reads that way: ``FileNotFoundError``, and ``NotADirectoryError`` for a name underneath
+    something that is not a folder. Neither names an entry. Every other refusal -- a permission the
+    account does not have, a name longer than the filesystem takes -- is a look that failed rather
+    than a look that found nothing, and answers ``None``.
+    """
+
+    try:
+        return entry_at(path, dir_fd=dir_fd)
+    except (OSError, ValueError):
+        return None
+
+
+def entry_at(path: Path | str, *, dir_fd: int | None = None) -> str | None:
+    """The same look as :func:`presence_at`, with a look that *failed* raised rather than worded.
+
+    The third way to ask the one question, and the one a caller needs when it has somewhere for the
+    refusal to go. :func:`kind_at` turns every failure into ``None`` and :func:`presence_at` turns
+    all but two into ``None``; both of them are answers, and an answer is exactly wrong for a
+    caller that has to *stop*. ``ux.readers`` is that caller: a listing that reported a folder this
+    account may not read as a folder with nothing built in it would invent a finding. The listing
+    therefore needs the raised refusal rather than ``Path.is_file``'s Boolean answer.
+
+    So the two errnos that name no entry are still the word :data:`NOTHING_THERE`, because they are
+    findings; everything else is the refusal itself, unchanged. It follows nothing, like everything
+    else here, and :func:`presence_at` is now this function with the refusal swallowed, so the two
+    cannot answer differently about one path.
+    """
+
+    try:
+        return name_of_kind(os.lstat(path, dir_fd=dir_fd).st_mode)
+    except (FileNotFoundError, NotADirectoryError):
+        return NOTHING_THERE
+
+
+__all__ = [
+    "A_DEVICE",
+    "A_FILE",
+    "A_FOLDER",
+    "A_LINK",
+    "A_PIPE",
+    "A_SOCKET",
+    "NOTHING_THERE",
+    "UNKNOWN_KIND",
+    "entry_at",
+    "kind_at",
+    "name_of_kind",
+    "presence_at",
+]