shortenpath 0.2.0__py3-none-any.whl

shortenpath/__init__.py

@@ -0,0 +1,11 @@
+"""Abbreviate a filesystem path for display within a terminal column budget."""
+
+from __future__ import annotations
+
+from ._parts import Flavor
+from ._shorten import shorten
+from ._width import display_width
+
+__version__ = "0.2.0"
+
+__all__ = ["Flavor", "display_width", "shorten"]

shortenpath/__main__.py

@@ -0,0 +1,10 @@
+"""Run the command line tool with ``python -m shortenpath``."""
+
+from __future__ import annotations
+
+import sys
+
+from shortenpath._cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

shortenpath/_cli.py

@@ -0,0 +1,107 @@
+"""Command line tool: shorten paths given as arguments or read one per line from stdin."""
+
+from __future__ import annotations
+
+import argparse
+import errno
+import io
+import os
+import shutil
+import sys
+from collections.abc import Iterable, Iterator, Sequence
+from functools import partial
+
+from ._shorten import shorten
+
+
+def _width(text: str) -> int:
+    try:
+        value = int(text)
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"width must be a whole number, not {text!r}") from None
+    if value < 1:
+        raise argparse.ArgumentTypeError(f"width must be at least 1, not {value}")
+    return value
+
+
+def _parser() -> argparse.ArgumentParser:
+    from . import __version__
+
+    parser = argparse.ArgumentParser(
+        prog="shortenpath",
+        description="Shorten paths to fit a number of terminal columns, one per line. "
+        "Without PATH arguments, paths are read one per line from standard input.",
+        epilog="examples:\n  shortenpath -w 30 /usr/local/share/doc/python3/README.md\n"
+        '  pwd | shortenpath -w 24\n  shortenpath -w 20 -- "-odd name"',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("paths", nargs="*", metavar="PATH", help="paths to shorten")
+    parser.add_argument(
+        "-w",
+        "--width",
+        type=_width,
+        metavar="COLS",
+        help="column budget (default: the terminal width)",
+    )
+    parser.add_argument(
+        "-f",
+        "--flavor",
+        choices=("native", "posix", "windows"),
+        default="native",
+        help="path rules (default: those of this system)",
+    )
+    parser.add_argument("--no-tilde", action="store_true", help="do not fold the home folder")
+    parser.add_argument("--home", help="home folder to fold to ~ (default: the current user's)")
+    parser.add_argument("--sep", help="a custom separator instead of the flavor's rules")
+    parser.add_argument("--placeholder", default="...", help="text put where segments go")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    return parser
+
+
+def _inputs(paths: list[str]) -> Iterator[str]:
+    if paths:
+        yield from paths
+        return
+    # One line at a time, so ``tail -f log | shortenpath`` prints as lines arrive.
+    for line in sys.stdin:
+        yield line.rstrip("\r\n")
+
+
+def _emit(lines: Iterable[str]) -> None:
+    if isinstance(sys.stdout, io.TextIOWrapper):
+        # A pipe on Windows may use a legacy code page; a name it cannot hold must not crash.
+        sys.stdout.reconfigure(errors="replace")
+    try:
+        for line in lines:
+            sys.stdout.write(line + "\n")
+            sys.stdout.flush()
+    except OSError as error:
+        # The reader went away (``| head``). Windows reports EINVAL rather than EPIPE.
+        if not isinstance(error, BrokenPipeError) and error.errno != errno.EINVAL:
+            raise
+        devnull = os.open(os.devnull, os.O_WRONLY)
+        os.dup2(devnull, sys.stdout.fileno())
+        os.close(devnull)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Entry point for ``shortenpath`` and ``python -m shortenpath``; returns the exit code."""
+    parser = _parser()
+    args = parser.parse_args(sys.argv[1:] if argv is None else list(argv))
+    width = args.width if args.width is not None else shutil.get_terminal_size().columns
+    shrink = partial(
+        shorten,
+        width=width,
+        flavor=args.flavor,
+        home_tilde=not args.no_tilde,
+        home=args.home,
+        sep=args.sep,
+        placeholder=args.placeholder,
+    )
+    try:
+        # Options are checked once, before any input is read.
+        shrink("")
+    except ValueError as error:
+        parser.error(str(error))
+    _emit(shrink(path) for path in _inputs(args.paths))
+    return 0

shortenpath/_name.py

@@ -0,0 +1,45 @@
+"""Cut a single name to a column budget, keeping its start and its extension."""
+
+from __future__ import annotations
+
+from ._width import clusters, display_width, head, tail
+
+
+def extension(name: str) -> str:
+    """The extension of ``name`` as ``os.path.splitext`` sees it, leading dots ignored."""
+    dot = name.rfind(".")
+    # No dot, or only dots before the last one (".bashrc", "..x"): no extension.
+    if not name[: max(dot, 0)].strip("."):
+        return ""
+    return name[dot:]
+
+
+def squeeze(name: str, budget: int, placeholder: str) -> str:
+    """Return ``name`` cut in the middle to fit ``budget`` columns.
+
+    The extension stays whole with the last character of the stem before it when that
+    leaves room for the first one; otherwise the columns are shared between start and end,
+    the start taking the odd one, and the start always gets its first character when it
+    fits (the end takes every column when it does not). Without room for the placeholder
+    the start of the name is kept alone, which is empty when not even its first character
+    fits.
+    """
+    units = clusters(name)
+    if sum(width for _, width in units) <= budget:
+        return name
+    room = budget - display_width(placeholder)
+    if room <= 0:
+        return head(units, budget)[0]
+    end_budget = room // 2
+    ext = extension(name)
+    stem = clusters(name[: len(name) - len(ext)])
+    if ext:
+        keep = display_width(ext) + stem[-1][1]
+        if room >= keep + stem[0][1]:
+            end_budget = max(keep, end_budget)
+    # The start gets at least its first character; if even that cannot fit, the end takes all.
+    first = units[0][1]
+    end_budget = min(end_budget, room - first) if first <= room else room
+    end, used = tail(units, end_budget)
+    start, _ = head(units, room - used)
+    return start + placeholder + end

shortenpath/_parts.py

@@ -0,0 +1,133 @@
+"""Split a path into its anchor and its named segments, and fold the home directory."""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+from typing import Literal
+
+Flavor = Literal["native", "posix", "windows"]
+
+_BACK = "\\"
+_VERBATIM = _BACK * 2 + "?" + _BACK
+_UNC_DEVICES = (_VERBATIM + "UNC" + _BACK, _BACK * 2 + ".\\UNC" + _BACK)
+_POSIX_RUN = re.compile(r"/+")
+_WINDOWS_RUN = re.compile(r"[\\/]+")
+_BACK_RUN = re.compile(r"\\+")
+
+
+@dataclass(frozen=True)
+class Parts:
+    """A path as anchor, names, the separator runs between names, and a trailing run.
+
+    ``root_sep`` is the separator run that ends the anchor, empty when it ends in a name.
+    """
+
+    anchor: str
+    names: tuple[str, ...]
+    seps: tuple[str, ...]
+    trailing: str
+    root_sep: str = ""
+
+    def render(self) -> str:
+        pieces = [self.anchor]
+        for index, name in enumerate(self.names):
+            if index:
+                pieces.append(self.seps[index - 1])
+            pieces.append(name)
+        pieces.append(self.trailing)
+        return "".join(pieces)
+
+
+def resolve(flavor: str) -> str:
+    """Return ``"posix"`` or ``"windows"`` for a flavor name."""
+    if flavor == "native":
+        return "windows" if os.name == "nt" else "posix"
+    if flavor in ("posix", "windows"):
+        return flavor
+    raise ValueError(f"flavor must be 'native', 'posix' or 'windows', not {flavor!r}")
+
+
+def windows_splitroot(path: str) -> tuple[str, str, str]:
+    """Split a Windows path into drive, root and tail, like ``ntpath.splitroot``.
+
+    A path that starts exactly with ``\\\\?\\`` skips normalization in Windows, so only the
+    backslash separates its parts and a forward slash is part of a name.
+    """
+    norm = path if path.startswith(_VERBATIM) else path.replace("/", _BACK)
+    if norm[:1] == _BACK:
+        if norm[1:2] != _BACK:
+            return "", path[:1], path[1:]
+        # UNC (\\server\share) or device (\\.\C:, \\?\UNC\server\share): two parts after it.
+        # Microsoft documents \\.\UNC\ as a UNC device too; ntpath.splitroot does not.
+        start = 8 if norm[:8].upper() in _UNC_DEVICES else 2
+        first = norm.find(_BACK, start)
+        second = norm.find(_BACK, first + 1) if first != -1 else -1
+        if second == -1:
+            return path, "", ""
+        return path[:second], path[second : second + 1], path[second + 1 :]
+    if norm[1:2] == ":":
+        if norm[2:3] == _BACK:
+            return path[:2], path[2:3], path[3:]
+        return path[:2], "", path[2:]
+    return "", "", path
+
+
+def split(path: str, flavor: str, sep: str | None) -> Parts:
+    """Split ``path`` into :class:`Parts` under ``flavor`` or a custom ``sep``."""
+    drive = root = ""
+    if sep is not None:
+        run = re.compile(f"(?:{re.escape(sep)})+")
+    elif flavor == "windows":
+        drive, root, _ = windows_splitroot(path)
+        run = _BACK_RUN if path.startswith(_VERBATIM) else _WINDOWS_RUN
+    else:
+        run = _POSIX_RUN
+    rest = path[len(drive + root) :]
+    lead = run.match(rest)
+    root_sep = root + (lead.group() if lead else "")
+    rest = rest[len(root_sep) - len(root) :]
+    pieces = run.split(rest)
+    gaps = run.findall(rest)
+    if pieces[-1] == "" and gaps:
+        trailing = gaps.pop()
+        pieces.pop()
+    else:
+        trailing = ""
+    names = tuple(pieces) if pieces != [""] else ()
+    return Parts(drive + root_sep, names, tuple(gaps), trailing, root_sep)
+
+
+def _anchor_key(anchor: str, flavor: str, sep: str | None) -> str:
+    if sep is not None:
+        return anchor and sep
+    if flavor == "posix":
+        # Two leading slashes are implementation defined; three or more mean one.
+        return "//" if anchor == "//" else anchor[:1]
+    if not anchor.startswith(_VERBATIM):
+        anchor = anchor.replace("/", _BACK)
+    # The anchor took in the separator run after the root; its length does not matter.
+    stripped = anchor.rstrip(_BACK)
+    return (stripped + _BACK if stripped != anchor else anchor).lower()
+
+
+def fold_home(parts: Parts, home: Parts, flavor: str, sep: str | None) -> Parts:
+    """Replace a leading ``home`` in ``parts`` with ``~``; ``parts`` unchanged otherwise."""
+    count = len(home.names)
+    if count == 0 or not home.root_sep:
+        # A relative home, or one that is only a root, says nothing about where a path is.
+        return parts
+    if _anchor_key(parts.anchor, flavor, sep) != _anchor_key(home.anchor, flavor, sep):
+        return parts
+    mine, theirs = parts.names[:count], home.names
+    if sep is None and flavor == "windows":
+        # Windows names compare without regard to case.
+        mine = tuple(name.lower() for name in mine)
+        theirs = tuple(name.lower() for name in theirs)
+    if mine != theirs:
+        return parts
+    if len(parts.names) == count:
+        return Parts("~", (), (), parts.trailing)
+    root_sep = parts.seps[count - 1]
+    return Parts("~" + root_sep, parts.names[count:], parts.seps[count:], parts.trailing, root_sep)

shortenpath/_shorten.py

@@ -0,0 +1,127 @@
+"""Width-budgeted abbreviation of filesystem paths for display."""
+
+from __future__ import annotations
+
+import os
+from bisect import bisect_right
+from itertools import accumulate
+
+from ._name import squeeze
+from ._parts import Flavor, Parts, fold_home, resolve, split
+from ._width import display_width
+
+_PLACEHOLDER = "..."
+
+
+def shorten(
+    path: str | os.PathLike[str],
+    width: int,
+    *,
+    flavor: Flavor = "native",
+    home_tilde: bool = True,
+    home: str | os.PathLike[str] | None = None,
+    sep: str | None = None,
+    placeholder: str = _PLACEHOLDER,
+) -> str:
+    """Return ``path`` shortened to fit ``width`` terminal columns.
+
+    ``flavor`` picks the path rules (``"posix"``, ``"windows"`` or ``"native"`` for the
+    running system); ``sep`` replaces them with a single custom separator. The home directory
+    collapses to ``~`` when ``home_tilde`` is set. A path still too wide keeps its anchor
+    (root, drive, UNC share or device prefix) and its last name, and as many whole segments
+    around ``placeholder`` as fit. Display only: the filesystem is never read.
+    """
+    text = _text(path, "path")
+    if isinstance(width, bool) or not isinstance(width, int):
+        raise TypeError(f"width must be int, not {type(width).__name__}")
+    if width < 1:
+        raise ValueError("width must be at least 1")
+    if sep is not None and (not isinstance(sep, str) or not sep):
+        raise ValueError("sep must be a non-empty string")
+    if not isinstance(placeholder, str) or not placeholder:
+        raise ValueError("placeholder must be a non-empty string")
+    rules = resolve(flavor)
+    parts = split(text, rules, sep)
+    if home_tilde:
+        base = _home(home, rules, sep)
+        if base:
+            parts = fold_home(parts, split(base, rules, sep), rules, sep)
+    text = parts.render()
+    if display_width(text) <= width:
+        return text
+    return _fit(parts, width, placeholder)
+
+
+def _text(value: object, label: str) -> str:
+    if isinstance(value, os.PathLike):
+        value = os.fspath(value)
+    if not isinstance(value, str):
+        raise TypeError(f"{label} must be str or os.PathLike[str], not {type(value).__name__}")
+    return value
+
+
+def _home(home: object, rules: str, sep: str | None) -> str:
+    if home is not None:
+        return _text(home, "home")
+    if sep is not None or rules != resolve("native"):
+        # The running user's home only means something for paths of the running system.
+        return ""
+    # Without a known home this gives back "~", which folds nothing that would change.
+    return os.path.expanduser("~")
+
+
+def _fit(parts: Parts, width: int, placeholder: str) -> str:
+    names, seps = parts.names, parts.seps
+    count = len(names)
+    if count == 0:
+        return squeeze(parts.render(), width, placeholder)
+    if count > 1:
+        best = _search(parts, width - display_width(parts.anchor) - display_width(placeholder))
+        if best is not None:
+            keep_head, keep_tail = best
+            start = "".join(name + seps[i] for i, name in enumerate(names[:keep_head]))
+            end = "".join(seps[i - 1] + names[i] for i in range(count - keep_tail, count))
+            return parts.anchor + start + placeholder + end + parts.trailing
+    # The whole last name is worth more than the anchor: after the placeholder and the
+    # separator as written, then a single separator, then alone.
+    before = seps[-1] if count > 1 else parts.root_sep
+    for run in dict.fromkeys((before, before[-1:])):
+        bare = placeholder + run + names[-1] + parts.trailing
+        if run and display_width(bare) <= width:
+            return bare
+    for whole in (names[-1] + parts.trailing, names[-1]):
+        if display_width(whole) <= width:
+            return whole
+    if count == 1:
+        room = width - display_width(parts.anchor) - display_width(parts.trailing)
+        if (parts.anchor or parts.trailing) and room > display_width(placeholder) + 1:
+            return parts.anchor + squeeze(names[0], room, placeholder) + parts.trailing
+    return squeeze(names[-1], width, placeholder)
+
+
+def _search(parts: Parts, room: int) -> tuple[int, int] | None:
+    """Most segments kept around the placeholder, then most at the head; None if none fit."""
+    names, seps = parts.names, parts.seps
+    count = len(names)
+    # heads[h]: columns of the first h names, each with the separator after it.
+    heads = [
+        0,
+        *accumulate(display_width(names[i]) + display_width(seps[i]) for i in range(count - 1)),
+    ]
+    # tails[t]: columns of the last t names, each with the separator before it.
+    trail = display_width(parts.trailing)
+    tails = [
+        0,
+        *accumulate(
+            display_width(seps[count - 2 - t])
+            + display_width(names[count - 1 - t])
+            + (trail if t == 0 else 0)
+            for t in range(count - 1)
+        ),
+    ]
+    best: tuple[int, int] | None = None
+    for keep_head in range(count - 1):
+        keep_tail = min(bisect_right(tails, room - heads[keep_head]) - 1, count - 1 - keep_head)
+        if keep_tail >= 1 and (best is None or keep_head + keep_tail >= sum(best)):
+            best = (keep_head, keep_tail)
+    return best

shortenpath/_width.py

@@ -0,0 +1,84 @@
+"""Terminal display width of text, and cuts that never split a character from its marks."""
+
+from __future__ import annotations
+
+import unicodedata
+
+_ZERO_WIDTH_CATEGORIES = frozenset({"Mn", "Me", "Cf"})
+_SOFT_HYPHEN = "\u00ad"
+_ZERO_WIDTH_JOINER = "\u200d"
+_EMOJI_PRESENTATION = "\ufe0f"
+
+
+def char_width(char: str) -> int:
+    """Columns taken by one code point: 0, 1 or 2."""
+    if char == _SOFT_HYPHEN:
+        # A format character, but terminals and wcwidth() show it as a visible hyphen.
+        return 1
+    if unicodedata.category(char) in _ZERO_WIDTH_CATEGORIES:
+        return 0
+    if "\u1160" <= char <= "\u11ff" or "\ud7b0" <= char <= "\ud7ff":
+        # Hangul medial vowels and final consonants (and their extension block) join the
+        # syllable before them.
+        return 0
+    if unicodedata.east_asian_width(char) in ("W", "F"):
+        return 2
+    return 1
+
+
+def display_width(text: str) -> int:
+    """Return the number of terminal columns ``text`` takes.
+
+    East Asian Wide and Fullwidth characters take two columns; combining marks, format
+    characters and Hangul medial and final jamo take none; a character followed by the
+    emoji presentation selector takes two; everything else takes one.
+    """
+    if not isinstance(text, str):
+        raise TypeError(f"text must be str, not {type(text).__name__}")
+    return sum(width for _, width in clusters(text))
+
+
+def clusters(text: str) -> list[tuple[str, int]]:
+    """Split ``text`` into cuttable units with their widths.
+
+    A unit is a character plus every zero width character after it; a zero width joiner also
+    pulls in the character it joins. A unit with the emoji presentation selector is drawn as
+    an emoji, two columns wide.
+    """
+    units: list[tuple[str, int]] = []
+    glue = False
+    for char in text:
+        width = char_width(char)
+        if units and (width == 0 or glue):
+            last, last_width = units[-1]
+            if char == _EMOJI_PRESENTATION:
+                last_width = max(last_width, 2)
+            units[-1] = (last + char, last_width + width)
+        else:
+            units.append((char, width))
+        glue = char == _ZERO_WIDTH_JOINER
+    return units
+
+
+def head(units: list[tuple[str, int]], budget: int) -> tuple[str, int]:
+    """Longest run of ``units`` from the start that fits ``budget`` columns."""
+    taken: list[str] = []
+    used = 0
+    for text, width in units:
+        if used + width > budget:
+            break
+        taken.append(text)
+        used += width
+    return "".join(taken), used
+
+
+def tail(units: list[tuple[str, int]], budget: int) -> tuple[str, int]:
+    """Longest run of ``units`` from the end that fits ``budget`` columns."""
+    taken: list[str] = []
+    used = 0
+    for text, width in reversed(units):
+        if used + width > budget:
+            break
+        taken.append(text)
+        used += width
+    return "".join(reversed(taken)), used

shortenpath-0.2.0.dist-info/METADATA

@@ -0,0 +1,189 @@
+Metadata-Version: 2.5
+Name: shortenpath
+Version: 0.2.0
+Summary: Shorten a filesystem path to fit a terminal column budget: home folds to ~, the root and file name stay, the middle goes
+Project-URL: Homepage, https://lianes8studio.com
+Project-URL: Repository, https://github.com/JaviLianes8/shortenpath
+Project-URL: Issues, https://github.com/JaviLianes8/shortenpath/issues
+Project-URL: Changelog, https://github.com/JaviLianes8/shortenpath/blob/main/CHANGELOG.md
+Project-URL: LinkedIn, https://www.linkedin.com/in/jlianes/
+Project-URL: Funding, https://buymeacoffee.com/jlianesglrs
+Author-email: Javier Lianes <javier@lianes8studio.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,display,elide,ellipsis,path,shorten,terminal,tilde,unc,width
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: Terminals
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# shortenpath
+
+Shorten a filesystem path to fit a terminal column budget for prompts, status bars, tables
+and logs. The home folder folds to `~`, the root and the file name stay, and whole folders
+in the middle give way to `...`. Display only: the filesystem is never read.
+
+## Install
+
+```
+pip install shortenpath
+```
+
+## Usage
+
+```python
+from shortenpath import shorten
+
+path = "/home/javi/projects/shop/src/cart/checkout.py"
+print(shorten(path, 60, flavor="posix", home="/home/javi"))
+print(shorten(path, 30, flavor="posix", home="/home/javi"))
+print(shorten(path, 22, flavor="posix", home="/home/javi"))
+print(shorten(path, 14, flavor="posix", home="/home/javi"))
+print(shorten(path, 9, flavor="posix", home="/home/javi"))
+# ~/projects/shop/src/cart/checkout.py
+# ~/.../src/cart/checkout.py
+# ~/.../cart/checkout.py
+# checkout.py
+# ch...t.py
+```
+
+Windows paths keep their drive, UNC share or device prefix whole, and both `\` and `/`
+separate folders (each kept as written). The home folder matches regardless of case.
+
+```python
+from shortenpath import shorten
+
+print(shorten(r"C:\Users\javi\AppData\Local\Temp\report.pdf", 24, flavor="windows"))
+print(shorten(r"\\fileserver\finance\2026\q3\budget.xlsx", 36, flavor="windows"))
+print(shorten(r"\\?\C:\very\deep\tree\of\folders\notes.txt", 26, flavor="windows"))
+print(
+    shorten("C:/Users/javi/Downloads/tools/setup.exe", 26, flavor="windows", home=r"c:\users\javi")
+)
+# C:\Users\...\report.pdf
+# \\fileserver\finance\...\budget.xlsx
+# \\?\C:\very\...\notes.txt
+# ~/Downloads/.../setup.exe
+```
+
+The budget is in terminal columns: East Asian wide characters take two, combining accents
+none, and a cut never splits a letter from its accent.
+
+```python
+from shortenpath import display_width, shorten
+
+path = "/srv/写真/2026/夏休み/海辺の夕焼け.jpg"
+print(display_width(path), len(path))
+print(shorten(path, 30, flavor="posix"))
+print(shorten(path, 24, flavor="posix"))
+# 38 27
+# /srv/写真/.../海辺の夕焼け.jpg
+# /.../海辺の夕焼け.jpg
+```
+
+Any separator and any placeholder:
+
+```python
+from shortenpath import shorten
+
+print(shorten("docs::api::v2::internal::client", 20, sep="::"))
+print(shorten("/var/log/nginx/access.log", 16, flavor="posix", placeholder="…"))
+# docs::...::client
+# /…/access.log
+```
+
+## The rules
+
+`shorten(path, width, *, flavor="native", home_tilde=True, home=None, sep=None,
+placeholder="...")` returns `path` itself when it fits, otherwise the first of these that
+fits `width` columns:
+
+1. The anchor, then as many whole folders as fit around the placeholder, then the last
+   name: the form keeping the most names wins, and between equals the one keeping more at
+   the start. The anchor is a POSIX root (`/`, `//`), a drive (`C:\`, `C:`), a UNC share
+   (`\\server\share\`), a device path (`\\.\C:\`, `\\?\Volume{...}\`,
+   `\\?\UNC\server\share\`) or `~`.
+2. The placeholder, the separator and the last name: the whole name is worth more than the
+   anchor. A run of separators that does not fit shrinks to one.
+3. The last name alone, then the anchor with the name cut in the middle (a path with a
+   single name and room for both).
+4. The last name cut in the middle: its start, the placeholder, and its end, which keeps
+   the extension and the stem character before it when there is room for them. With no
+   room for the placeholder only the start of the name is kept, and when not even its first
+   character fits the result is empty.
+
+| Option | Meaning |
+| --- | --- |
+| `flavor` | `"posix"`, `"windows"` or `"native"` (the running system). `Flavor` is its type. |
+| `home_tilde`, `home` | Fold the home folder to `~`. `home` defaults to the current user's for native paths. A relative home, or one that is only a root, never folds. |
+| `sep` | A custom separator instead of the flavor's rules, for URLs or keys. |
+| `placeholder` | What stands for the removed folders, `...` by default. |
+
+Separator runs are kept as written. On Windows a path that starts exactly with `\\?\`
+skips normalization, so there only `\` separates and `/` is part of a name.
+`display_width(text)` gives the columns of any text: East Asian wide and fullwidth
+characters and characters with the emoji presentation selector take two, combining marks,
+format characters and Hangul medial and final jamo none, everything else (control
+characters included) one. Emoji joined into one picture are counted as their parts, which
+can only overestimate. Wrong types raise `TypeError`; a
+width below one or an empty separator or placeholder raises `ValueError`.
+
+Compared with the Win32 `PathCompactPathEx` function, this never cuts inside the
+anchor or a folder name, keeps the extension of a cut name, counts columns instead of
+characters, and returns a path exactly as long as the budget unchanged.
+
+## Command line
+
+```
+$ shortenpath -w 24 -f posix --home /home/javi /home/javi/projects/shop/src/cart/checkout.py
+~/.../cart/checkout.py
+$ shortenpath -w 24 -f windows 'C:\Program Files\Common Files\system\ado\msado15.dll'
+C:\...\ado\msado15.dll
+```
+
+Paths come from the arguments, or one per line from standard input, each written as soon
+as it is read. `-w` defaults to the terminal width. Bad input exits with status 2.
+`python -m shortenpath` works too.
+
+## Why
+
+Folding a path to `~` and trimming its middle to fit a column budget is a common need,
+yet on PyPI the pieces live apart: `os.path.expanduser` only expands, and
+`textwrap.shorten` cuts words from the end, not folders from the middle. Most snippets
+that do it count characters, split on one separator and cut UNC shares in half. This one
+reads Windows and POSIX path forms, counts columns, and has no dependencies.
+
+## Development
+
+`python scripts/fetch_sources.py` downloads the Microsoft, POSIX and Unicode texts the
+tests check the rules against (listed with their hashes in `tests/sources/MANIFEST.txt`);
+without them those tests skip. `SHORTENPATH_E2E=1 pytest` also builds the wheel and tests
+the installed package. `scripts/check.ps1` runs the whole gate.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Links
+
+- Website: https://lianes8studio.com
+- GitHub: https://github.com/JaviLianes8
+- LinkedIn: https://www.linkedin.com/in/jlianes/

shortenpath-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+shortenpath/__init__.py,sha256=gDO3SBVHvPafW9Akm72uj5udJ098LBfy-fu2lvwfa7M,281
+shortenpath/__main__.py,sha256=kOBuR4dCBqcWq5AGrg66ldy2SmoEwiWCUkpWyo-QsVk,196
+shortenpath/_cli.py,sha256=mKDmUkPr_vFiAp-LrJ4NUIMe43NkZAPPHiwJ4Xmokrc,3811
+shortenpath/_name.py,sha256=Va51_kRXoqKcZ53th5XqpieB08eUONWAMEgTesqad7Y,1844
+shortenpath/_parts.py,sha256=UgK2EFqT55_BkYM2uiibsyGb2zFw4m1rH7ROnzSC-0w,5015
+shortenpath/_shorten.py,sha256=peNBPxSZ8_I7ouK_SKwFlEddpk3EdHl3iDEB0UWQKBo,5202
+shortenpath/_width.py,sha256=_iXcSUTg4qe17GWiRHX2vcZlJGHF88awBwP1mik2SPg,2923
+shortenpath/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+shortenpath-0.2.0.dist-info/METADATA,sha256=XWU5-IEsAG6R6ZclNWstfdkaFnkgFzkm6aB8_KylUh8,7910
+shortenpath-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+shortenpath-0.2.0.dist-info/entry_points.txt,sha256=iDlwLWQGAJbbB9IRGoaRcRBYALsSznZ817HxJ-0RiAk,54
+shortenpath-0.2.0.dist-info/licenses/LICENSE,sha256=_WmABlQG__oqlx4Rzp-qDJ10xND5KCLScftbhXbLC_c,1070
+shortenpath-0.2.0.dist-info/RECORD,,

shortenpath-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

shortenpath-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+shortenpath = shortenpath._cli:main

shortenpath-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javier Lianes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.