shortenpath 0.2.0__tar.gz

shortenpath-0.2.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

shortenpath-0.2.0/.github/FUNDING.yml

@@ -0,0 +1 @@
+buy_me_a_coffee: jlianesglrs

shortenpath-0.2.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Third-party sources, fetched by scripts/fetch_sources.py (see its MANIFEST.txt)
+tests/sources/*
+!tests/sources/MANIFEST.txt

shortenpath-0.2.0/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0]
+
+### Added
+
+- `flavor` (`"posix"`, `"windows"`, `"native"`) and the `Flavor` type. Windows paths keep
+  their drive, UNC share or device prefix (`\\.\`, `\\?\`, `\\?\UNC\`, `\\.\UNC\`) whole and
+  take both `\` and `/` as separators, except after an exact `\\?\`.
+- `display_width(text)`: terminal columns, with East Asian wide and fullwidth characters as
+  two, combining marks as none and a character with the emoji presentation selector as two.
+  The budget of `shorten` is now in columns.
+- Command line tool `shortenpath` (also `python -m shortenpath`), streaming paths read from
+  standard input line by line.
+- `os.PathLike` paths and homes.
+
+### Changed
+
+- The second argument is now `width`, in terminal columns.
+- Elision keeps the most whole names around the placeholder, then the most at the start,
+  and keeps the whole last name before the anchor when only one of them fits, also for a
+  path with a single name.
+- A name that cannot fit is cut in the middle, keeping its start and its extension, and
+  never between a letter and its combining marks.
+- Separator runs are kept as written.
+- `sep` is now optional and, when given, replaces the flavor's rules; the default home is
+  only used for paths of the running system.
+- The home folder folds only on whole names, never when it is relative or a bare root or
+  drive, and without regard to case or separator kind on Windows.
+
+### Fixed
+
+- A UNC share or device prefix was cut into a lone separator.
+- Wrong argument types failed deep inside; they now raise `TypeError`, and an empty
+  `placeholder` raises `ValueError`.
+
+## [0.1.0]
+
+- First release: `shorten` collapses the home directory to `~` and middle-elides a
+  path to fit a width budget, with a basename-truncation fallback and a configurable
+  separator, home and placeholder.

shortenpath-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,21 @@
+# Contributing
+
+Thanks for taking the time. This project keeps a small, predictable shape.
+
+## Setup
+
+```
+pip install -r requirements-dev.txt
+```
+
+## Before you open a pull request
+
+- Keep public API in `src/shortenpath/__init__.py`; internals live in `_`-prefixed modules.
+- Add a test for the behaviour you change. Tests inject time, disk and network; they
+  never touch the real thing.
+- Run `python scripts/fetch_sources.py` once so the tests can check the rules against the
+  Microsoft, POSIX and Unicode texts, then `scripts/check.ps1` (format, lint, types, tests)
+  and make sure it passes. `SHORTENPATH_E2E=1` adds the installed-wheel test.
+- One logical change per commit, imperative subject line.
+
+Open an issue first if the change is large or shifts the public API.

shortenpath-0.2.0/IMPROVEMENTS-round.md

@@ -0,0 +1,136 @@
+# shortenpath improvement round
+
+Progress:
+- [x] Brainstorm ranked improvements (this file)
+- [x] Path forms: POSIX roots, Windows drives, UNC, `\\?\` and `\\.\` device paths, mixed separators
+- [x] Display width: wide and fullwidth characters count two columns, combining marks none
+- [x] Home folding to `~` that respects component boundaries and Windows case rules
+- [x] File name kept whole when it can be, extension kept when the name is cut
+- [x] Deterministic elision search (most segments kept, then most head segments)
+- [x] Typed API: `Flavor` alias, `display_width`, clean `TypeError` and `ValueError`
+- [x] Command line tool (`shortenpath`, `python -m shortenpath`)
+- [x] Contracts: fetched sources, stdlib and Win32 oracles, properties, typing, README, wheel e2e
+- [x] Mutation run (guards changed one at a time, each must fail the suite)
+- [x] Docs: README, CHANGELOG, docstrings, packaging metadata
+- [x] Gates: ruff format, ruff check, mypy --strict, pytest
+- [x] Independent review findings fixed with regression tests
+- [x] Pull request opened, guard clean
+
+## Starting point
+
+`0.1.0` (not on PyPI) ships `shorten(path, max_len, *, home_tilde, home, sep, placeholder)`.
+Read as a user who puts paths in prompts, status bars, tables and logs:
+
+- One separator only, `os.sep` by default. On Windows `C:/Users/x` is one segment; on Linux a
+  Windows path from a log cannot be shortened unless the caller picks `sep="\\"`, and then
+  `/` inside it is not a separator.
+- The only root it knows is a leading separator. `\\server\share\dir\f` is elided into
+  `\...\f`, losing the server and share; `\\?\C:\x\y\f` loses the device prefix and the drive.
+- Length is `len()`. A path with CJK names or fullwidth characters takes twice the columns it
+  is budgeted for; a name with combining accents is budgeted for columns it never uses, and a
+  cut can separate a letter from its accent.
+- Home folding compares raw strings: `C:\Users\Javi` does not fold `c:\users\javi\x` on
+  Windows, and `home="C:\\"` folds every path on the drive into `~\...`.
+- When the name does not fit it keeps only its end; the start of the name is lost first.
+- No command line tool, README examples not executed, no wheel test, no ground truth in the
+  tests.
+
+## Sources (fetched 2026-10-13)
+
+- File path formats on Windows systems, dotnet/docs at 3ad903a7:
+  traditional DOS paths (`C:\`, `\dir` relative to the current drive, `C:dir` relative to the
+  current directory of drive C), UNC paths (`\\server\share` is the volume), DOS device paths
+  (`\\.\` and `\\?\`, the first segment after the prefix names the volume, `UNC\server\share`
+  for network shares), forward slashes are separators except in a path that starts exactly
+  with `\\?\`, which skips normalization.
+- Naming Files, Paths, and Namespaces, MicrosoftDocs/win32 at ca8274de: backslash and forward
+  slash are both reserved; the prefix of a path decides its namespace.
+- PathCompactPathExW, MicrosoftDocs/sdk-api at 656e9656: replaces path components with an
+  ellipsis to fit a character count, keeps `/` if the input used it, truncates a bare file
+  name at the end. Probed live through `shlwapi.dll` on Windows 11: it counts characters, not
+  columns, cuts inside the UNC server name (`\\serv...\file.txt`), cuts inside directory names (`C:\path1...\sample.txt`)
+  and drops the extension when the name is cut (`...\verylon...`).
+- POSIX.1-2024 base definitions 3.2, 3.42, 3.146, 3.170, 3.254, 3.256 and 4.16: a filename
+  never contains a slash, runs of slashes equal one, exactly two leading slashes are
+  implementation defined, three or more equal one; the home directory is `HOME`.
+- `EastAsianWidth.txt` for Unicode 13.0.0 to 17.0.0: the W and F classes, read as two
+  columns. Zero columns for combining marks, format characters and Hangul medial and final
+  jamo, and two for a character with the emoji presentation selector, are this library's own
+  convention (the one most terminals follow), not a fetched rule.
+- The texts are third-party and not committed: `scripts/fetch_sources.py` fetches them into a
+  gitignored folder checked against a tracked MANIFEST; the tests that read them skip when the
+  folder is absent.
+
+## Ranked improvements
+
+1. **Path forms.** A `flavor` (`"posix"`, `"windows"`, `"native"`) decides the separators and
+   the anchor. The anchor (drive, root, UNC server and share, device prefix and volume) is
+   never cut. Windows takes `\` and `/` everywhere except after an exact `\\?\`. Runs of
+   separators and the original separator characters are kept as written. The anchor split
+   agrees with `ntpath.splitroot` and `posixpath.splitroot` where they exist.
+2. **Display width.** `display_width(text)` counts W and F as two columns, combining marks,
+   format characters and Hangul medial and final jamo as zero, everything else as one. The
+   budget is in columns, cuts never split a base from its marks or a zero width joiner from
+   the next character, and the result never exceeds the budget.
+3. **Home folding.** Only on a component boundary, never for a home that is a bare anchor,
+   case-insensitive and separator-insensitive on Windows, keeping the separator written in the
+   path after `~`.
+4. **Name and extension.** The last segment is kept whole whenever `.../name` fits; a name that
+   cannot fit is cut in the middle, keeping its start and its extension.
+5. **Deterministic elision.** Among all forms `anchor head/.../tail` that fit, keep the most
+   segments, then the most head segments. One rule, `O(n log n)`, documented with examples.
+6. **Typed API and failures.** `Flavor` literal alias, `width` in columns, `os.PathLike`
+   accepted, `TypeError` for bytes and non-strings, `ValueError` for a width below one or an
+   empty separator or placeholder.
+7. **Command line tool.** `shortenpath [-w COLS] [--flavor] [--no-tilde] [--home] PATH...`,
+   lines from stdin without paths, terminal width by default, exit 2 on bad input, quiet on a
+   closed pipe.
+8. **Contracts that bite.** Examples from the fetched Microsoft and POSIX texts, the width table
+   of the running Unicode version, `splitroot` oracles over fuzzed paths, the live Win32
+   function on Windows as a reference, properties over fuzzed paths (fits, deterministic,
+   anchor and name kept when they fit), executed README, installed-wheel e2e, mutation run.
+9. **Docs and packaging.** README with the rules and a table of forms, CHANGELOG 0.2.0,
+   classifiers and keywords, console script.
+
+Left out on purpose: resolving `.` and `..` or symlinks (display only, never touches disk),
+grapheme clusters beyond marks and joiners (emoji sequences differ between terminals),
+ambiguous width characters as two columns (terminal setting, not data), URL schemes.
+
+## Verification
+
+- Gates: `ruff format --check .`, `ruff check .`, `mypy --strict src` (also `src tests`) and
+  `pytest` exit 0 on a second machine with Python 3.14, a fresh clone, the sources in place and
+  `SHORTENPATH_E2E=1`: 222 passed, nothing skipped. The wheel test builds the wheel and the
+  sdist, checks that no fetched source or test ships in them, installs the wheel in a fresh
+  venv, drives the API from an empty folder, and runs the installed `shortenpath` script and
+  `python -m shortenpath` (stdin included).
+- Ground truth: every example path of the two Microsoft pages is read from the fetched text
+  and split with the anchor its description gives; the rules relied on (forward slash as a
+  separator except after an exact `\\?\`, server and share as the volume of a UNC device, both
+  slashes reserved) and the POSIX leading slash, filename and home definitions are checked in
+  the fetched texts; every assigned code point of `EastAsianWidth.txt` for the running Unicode
+  version gets two columns for W and F and one otherwise.
+- Oracles: `ntpath.splitroot` and `ntpath.splitdrive` over 40000 fuzzed Windows paths (only
+  the two documented differences excluded), `posixpath.splitroot`, `os.path.splitext` for the
+  extension, a brute force reading of the elision rule, and on Windows the live
+  `PathCompactPathExW`: both keep a path that fits, and whenever it keeps the file name whole,
+  so does this library. It compacts a path exactly as long as its budget, which this one does
+  not. Properties over fuzzed paths: never wider than the budget, a fitting result is stable,
+  anchor and last name kept whole when they fit, a last name that fits alone never cut.
+- Mutations: 96 mutants (width classes and ranges, emoji presentation, clusters and cuts,
+  extension and squeeze rules, every anchor form and the verbatim prefix, separator runs,
+  home folding guards and keys, every validation, the search and its tie break, every
+  fallback, and the command line rules: width, stdin, streaming flush, option check before
+  input, closed pipe, code page), applied one at a time with the bytecode cache disabled and
+  purged before each run, baseline green before and after. Earlier runs left survivors (range
+  ends, separator runs, a home check that depended on the machine's environment, equivalent
+  branches that were then simplified); each got a test or a simpler code path. The final run
+  killed all 96.
+- Independent review: 11 findings. Fixed with regression tests: a single name that fits
+  alone was cut to keep the anchor; a separator run after a UNC share blocked the whole name;
+  a wide last stem character broke the extension rule and the start could be empty; a
+  relative home folded relative paths; the emoji presentation selector and Hangul Jamo
+  Extended-B were miscounted; the command line read all of stdin before writing; README rules
+  were incomplete; the checklist was stale; the UAX #11 line claimed an unfetched source;
+  weak Win32 and property tests were tightened. Control characters still count one column and
+  are documented.

shortenpath-0.2.0/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.

shortenpath-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,151 @@
+# 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/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "shortenpath"
+version = "0.2.0"
+description = "Shorten a filesystem path to fit a terminal column budget: home folds to ~, the root and file name stay, the middle goes"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Javier Lianes", email = "javier@lianes8studio.com" }]
+keywords = ["path", "shorten", "ellipsis", "elide", "display", "terminal", "width", "tilde", "unc", "cli"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: System :: Filesystems",
+    "Topic :: Terminals",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["ruff", "mypy", "pytest", "build", "twine"]
+
+[project.scripts]
+shortenpath = "shortenpath._cli:main"
+
+[project.urls]
+Homepage = "https://lianes8studio.com"
+Repository = "https://github.com/JaviLianes8/shortenpath"
+Issues = "https://github.com/JaviLianes8/shortenpath/issues"
+Changelog = "https://github.com/JaviLianes8/shortenpath/blob/main/CHANGELOG.md"
+LinkedIn = "https://www.linkedin.com/in/jlianes/"
+Funding = "https://buymeacoffee.com/jlianesglrs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/shortenpath"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-q"

shortenpath-0.2.0/requirements-dev.txt

@@ -0,0 +1,3 @@
+# Development dependencies: the package in editable mode plus its dev extras
+# (ruff, mypy, pytest, build, twine). Install with:  pip install -r requirements-dev.txt
+-e .[dev]