cellstr 0.2.1__tar.gz

cellstr-0.2.1/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Unicode data files, fetched locally by scripts/fetch_upstream.py; only the manifest is tracked.
+data/ucd/*
+!data/ucd/MANIFEST.json

cellstr-0.2.1/CHANGELOG.md

@@ -0,0 +1,53 @@
+# 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.1]
+
+### Changed
+
+- The Unicode Character Database files are no longer committed. `data/ucd/MANIFEST.json`
+  pins them to Unicode 18.0.0, plus the 15.1.0 EastAsianWidth.txt the oracle test uses
+  (URL, size, sha256, licence), and `scripts/fetch_upstream.py`
+  fetches them; the generator check and the conformance tests skip until then. The
+  generated tables stay in the package and the Unicode licence notice ships in the wheel.
+- The sdist ships only the sources, tests, scripts and docs.
+
+## [0.2.0]
+
+### Added
+
+- Grapheme-aware width: emoji ZWJ sequences, skin tone and tag sequences, keycaps and
+  regional indicator flags measure as one two-cell glyph; VS16 makes an emoji wide and
+  VS15 makes it narrow. New `iter_graphemes()` (UAX #29) and `grapheme_width()`.
+- `ambiguous=1 | 2` on every function for East Asian Ambiguous characters.
+- `tabsize=` on every function, and `expand_tabs()` that counts display cells.
+- `truncate(..., position="end" | "start" | "middle")`, `truncate_detailed()` returning
+  a `Truncation`, and `fit()` to truncate or pad to an exact width.
+- `iter_cells()` yielding typed `Cell` records (text, width, column, escape flag).
+- Recognition of DCS, SOS, PM and APC strings, charset designations and the remaining
+  single-byte escapes, alongside CSI and OSC (BEL or ST terminated).
+- The `cellstr` command: `measure`, `truncate`, `pad`, `fit` and `slice` over stdin lines.
+- Width, grapheme and emoji tables generated from a committed Unicode 18.0.0 UCD snapshot
+  by `scripts/gen_ucd_tables.py`, with the Unicode License in `LICENSE-UNICODE`.
+
+### Changed
+
+- `cell_len`, `cell_slice`, `truncate` and the padding functions measure grapheme
+  clusters, so emoji sequences change width: the family emoji was 6 cells and is now 2,
+  a flag was 2 and stays 2, an emoji with VS15 is now 1.
+- `truncate` rejects a suffix that contains a tab or a line break.
+- Width tables move from a hand-vendored Unicode 15.1 extract to generated Unicode
+  18.0.0 tables. Spacing marks (Mc) are one cell, as in Kuhn's wcwidth and glibc.
+- `cell_slice` never splits a grapheme cluster, so accents stay on their letter.
+- `ljust`, `rjust` and `center` accept any one-cell grapheme cluster as the fill.
+
+## [0.1.0]
+
+- First release: `cell_len`, `char_width`, `cell_slice`, `ljust`, `rjust`,
+  `center`, `truncate` and `strip_ansi`, with a vendored Unicode width table and
+  full type hints.

cellstr-0.2.1/CONTRIBUTING.md

@@ -0,0 +1,28 @@
+# Contributing
+
+Thanks for taking the time. This project keeps a small, predictable shape.
+
+## Setup
+
+```
+pip install -r requirements-dev.txt
+python scripts/fetch_upstream.py
+```
+
+The fetch step is optional: it downloads the Unicode data files listed in
+`data/ucd/MANIFEST.json` (checked against their sha256) into `data/ucd/`, which
+git ignores. The generator check and the tests that need them skip until they are there.
+
+## Before you open a pull request
+
+- Keep public API in `src/cellstr/__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.
+- Never edit `src/cellstr/_ucd_*.py` by hand: they are generated from the fetched `data/ucd/` files
+  by `python scripts/gen_ucd_tables.py` (see `data/ucd/MANIFEST.json`).
+- Run `scripts/check.ps1` (format, lint, types, table freshness, tests) and make sure it
+  passes. The wheel end-to-end test needs network access for the build backend;
+  offline, run `pytest -m "not e2e"`.
+- One logical change per commit, imperative subject line.
+
+Open an issue first if the change is large or shifts the public API.

cellstr-0.2.1/GUIDE.md

@@ -0,0 +1,149 @@
+# cellstr guide
+
+This guide explains how `cellstr` decides how wide text is, where terminals disagree, and
+how to pick the policy that matches yours.
+
+## The rules
+
+Width is decided per extended grapheme cluster (UAX #29), the unit a reader sees as one
+character. Escape sequences are never part of a cluster: they count as zero cells, and an
+escape sequence between two code points ends the cluster before it.
+
+**Single code points** follow Markus Kuhn's reference `wcwidth`
+(https://www.cl.cam.ac.uk/~mgk25/ucs/wcwidth.c), applied to Unicode 18.0.0 data:
+
+| Code points | Cells |
+| --- | --- |
+| U+0000, C0 and C1 controls, DEL | 0 (Kuhn returns -1 for controls; 0 is easier to add up) |
+| Nonspacing and enclosing marks (General_Category Mn, Me) | 0 |
+| Format characters (Cf), such as ZERO WIDTH SPACE and ZERO WIDTH JOINER | 0 |
+| SOFT HYPHEN U+00AD | 1, or `ambiguous` since it is East Asian Ambiguous (it is visible) |
+| Hangul medial vowels and final consonants U+1160..U+11FF, U+D7B0..U+D7FF | 0 |
+| East_Asian_Width W (wide) and F (fullwidth) | 2 |
+| East_Asian_Width A (ambiguous) | `ambiguous`, 1 by default |
+| Everything else, including spacing marks (Mc) | 1 |
+
+Unassigned code points follow the defaults in the header of EastAsianWidth.txt: wide in
+the CJK ideograph blocks and in Planes 2 and 3, narrow elsewhere.
+
+**Clusters of several code points** add up their code points, which keeps accents at zero
+and a Hangul syllable built from jamo at two, except for emoji sequences, which draw as a
+single glyph:
+
+| Cluster | Example | Cells |
+| --- | --- | --- |
+| Emoji + VS16 (U+FE0F, emoji presentation) | ❤️ | 2 |
+| Emoji + VS15 (U+FE0E, text presentation) | ⌚︎ | 1 |
+| Emoji modifier sequence (skin tone) | 👍🏽 | 2 |
+| Emoji ZWJ sequence | 👨‍👩‍👧 | 2 |
+| Emoji tag sequence (subdivision flag) | 🏴󠁧󠁢󠁳󠁣󠁴󠁿 | 2 |
+| Pair of regional indicators (flag) | 🇯🇵 | 2 |
+| Keycap sequence | 1️⃣ | 2 |
+
+```python
+from cellstr import char_width, grapheme_width
+
+char_width("❤")  # -> 1
+grapheme_width("❤️")  # -> 2
+grapheme_width("⌚︎")  # -> 1
+grapheme_width("\U0001f44d\U0001f3fd")  # -> 2
+grapheme_width("각")  # -> 2
+char_width("é"), char_width("́")  # -> (1, 0)
+```
+
+## Where terminals disagree
+
+No standard says how many cells a character takes, so terminals make different choices.
+These are the cases that matter in practice.
+
+**East Asian Ambiguous characters.** Greek and Cyrillic letters, box drawing, circled
+digits and many symbols are one cell in Western use and two in legacy CJK use. Most
+terminals let the user choose: xterm has the `cjkWidth` resource, GNOME Terminal and
+other VTE terminals have an "Ambiguous-width characters" preference, and iTerm2 can treat
+ambiguous characters as double width. Pass `ambiguous=2` (or `--ambiguous 2` on the
+command line) when your users run such a setting, typically with a CJK locale.
+
+```python
+from cellstr import cell_len, ljust
+
+cell_len("── α")  # -> 4
+cell_len("── α", ambiguous=2)  # -> 7
+ljust("ж", 3, ambiguous=2)  # -> "ж "
+```
+
+**Emoji ZWJ sequences.** A terminal that measures code point by code point, as glibc's
+`wcwidth` does, advances the cursor six cells for the family emoji (2 + 0 + 2 + 0 + 2)
+and often draws three separate faces. Terminals that segment grapheme clusters draw one
+glyph in two cells. `cellstr` measures two. If your
+terminal works per code point, measure with the recipe below.
+
+**Variation selectors.** VS16 asks for emoji presentation. Terminals that ignore it keep
+a text-default symbol such as U+2764 at one cell and let the colour glyph overflow into
+the next cell; `cellstr` measures two. VS15 asks for text presentation: `cellstr` measures
+one cell, while terminals that ignore it, and the `wcwidth` package, keep the emoji at two.
+
+**Spacing marks.** Vowel signs in Indic scripts such as U+093F are spacing marks (Mc).
+Kuhn's reference gives them one cell (only Mn, Me and Cf are zero there), the `wcwidth`
+package gives them zero. `cellstr` gives one, so कि is two cells here.
+
+**Code point by code point recipe.** For a terminal without grapheme support, add up
+single code points yourself:
+
+```python
+from cellstr import char_width, strip_ansi
+
+text = "\U0001f468‍\U0001f469‍\U0001f467"
+sum(char_width(ch) for ch in strip_ansi(text))  # -> 6
+```
+
+## Slicing, padding and truncation
+
+- `cell_slice(text, start, stop)` keeps the clusters that sit fully inside the half-open
+  column range. A wide cluster cut by either edge is dropped whole, so the result can be
+  one cell short; `fit()` pads that cell back. Every escape sequence is kept, so a
+  hyperlink or colour that opens before the range still closes after it.
+- `ljust`, `rjust` and `center` pad with a one-cell fill character and never shorten text.
+- `truncate(..., position=...)` cuts at the end (keep the start), at the start (keep the
+  end, useful for log tails) or in the middle (keep both ends, useful for paths).
+  `truncate_detailed` returns a `Truncation` with the result, its width, the original
+  width and whether anything was cut.
+- With `tabsize` set, tabs advance to the next tab stop, counted from the start of the
+  line, and become spaces in slices and padded output so the layout does not shift.
+
+```python
+from cellstr import cell_slice, fit, truncate
+
+link = "\x1b]8;;https://example.com\x1b\\docs\x1b]8;;\x1b\\"
+cell_slice(link, 0, 2)  # -> "\x1b]8;;https://example.com\x1b\\do\x1b]8;;\x1b\\"
+log = "12:00:01 worker-7 job finished"
+truncate(log, 16, position="start")  # -> "... job finished"
+fit("\x1b[1mok\x1b[0m", 4, align="center")  # -> " \x1b[1mok\x1b[0m "
+```
+
+## Differences from the wcwidth package
+
+`tests/test_oracle_wcwidth.py` compares every code point with `wcwidth` 0.2.13 (whose
+newest tables are Unicode 15.1.0). The package is only a test oracle, never a runtime
+dependency. Result: 1,112,200 of 1,114,112 code points agree (99.83 %). Every one of the
+1,912 differences has a recorded reason, and the test fails on any new one:
+
+| Reason | Code points |
+| --- | --- |
+| Assigned after Unicode 15.1 | 1,263 |
+| East_Asian_Width changed after 15.1 (for example the trigrams U+2630..U+2637 became W) | 188 |
+| General_Category changed after 15.1 (U+1171E became Mc) | 1 |
+| Spacing marks (Mc): 1 here, as in Kuhn's reference, 0 in `wcwidth` | 452 |
+| SOFT HYPHEN, LINE SEPARATOR, PARAGRAPH SEPARATOR: 1 here (Kuhn), 0 in `wcwidth` | 3 |
+| Lone skin tone modifier: 2 here (it is East Asian Wide), 0 in `wcwidth` | 5 |
+
+For strings, `cellstr` and `wcswidth` agree on ZWJ sequences, flags, skin tones, VS16
+and keycaps. They differ on VS15 and spacing marks, as described above.
+
+## Unicode data
+
+The tables are built from the Unicode 18.0.0 data files, which are not committed:
+`data/ucd/MANIFEST.json` pins their URLs, sizes and SHA-256 sums, and
+`python scripts/fetch_upstream.py` fetches them into `data/ucd/` (the tests that read them
+skip until then). To move to a new Unicode version, update the manifest, fetch, run
+`python scripts/gen_ucd_tables.py` and the test suite. `tests/test_ucd_tables.py` fails if
+the committed tables differ from a fresh run of the generator.

cellstr-0.2.1/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.

cellstr-0.2.1/LICENSE-UNICODE

@@ -0,0 +1,39 @@
+UNICODE LICENSE V3
+
+COPYRIGHT AND PERMISSION NOTICE
+
+Copyright © 1991-2026 Unicode, Inc.
+
+NOTICE TO USER: Carefully read the following legal agreement. BY
+DOWNLOADING, INSTALLING, COPYING OR OTHERWISE USING DATA FILES, AND/OR
+SOFTWARE, YOU UNEQUIVOCALLY ACCEPT, AND AGREE TO BE BOUND BY, ALL OF THE
+TERMS AND CONDITIONS OF THIS AGREEMENT. IF YOU DO NOT AGREE, DO NOT
+DOWNLOAD, INSTALL, COPY, DISTRIBUTE OR USE THE DATA FILES OR SOFTWARE.
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of data files and any associated documentation (the "Data Files") or
+software and any associated documentation (the "Software") to deal in the
+Data Files or Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, and/or sell
+copies of the Data Files or Software, and to permit persons to whom the
+Data Files or Software are furnished to do so, provided that either (a)
+this copyright and permission notice appear with all copies of the Data
+Files or Software, or (b) this copyright and permission notice appear in
+associated Documentation.
+
+THE DATA FILES AND SOFTWARE ARE 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 OF
+THIRD PARTY RIGHTS.
+
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE
+BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES,
+OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE DATA
+FILES OR SOFTWARE.
+
+Except as contained in this notice, the name of a copyright holder shall
+not be used in advertising or otherwise to promote the sale, use or other
+dealings in these Data Files or Software without prior written
+authorization of the copyright holder.

cellstr-0.2.1/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.5
+Name: cellstr
+Version: 0.2.1
+Summary: Display-width aware len, slice, pad and truncate for terminal text: wide CJK, emoji sequences, combining marks and ANSI codes
+Project-URL: Homepage, https://lianes8studio.com
+Project-URL: Repository, https://github.com/JaviLianes8/cellstr
+Project-URL: Issues, https://github.com/JaviLianes8/cellstr/issues
+Project-URL: Changelog, https://github.com/JaviLianes8/cellstr/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
+License-File: LICENSE-UNICODE
+Keywords: ansi,cli,east-asian-width,emoji,grapheme,terminal,truncate,unicode,wcwidth,width
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Terminals
+Classifier: Topic :: Text Processing
+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'
+Requires-Dist: wcwidth==0.2.13; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cellstr
+
+Display-width aware `len`, slicing, padding and truncation for terminal text: East Asian
+wide characters, emoji sequences, combining marks, zero-width characters and ANSI escape
+sequences, measured the way a terminal draws them. Typed, zero dependencies, Unicode 18.0.0.
+
+## Install
+
+```
+pip install cellstr
+```
+
+## Usage
+
+`len`, slicing and `str.ljust` count code points, so they misalign any text that carries
+colour codes, CJK characters, emoji or accents. `cellstr` counts display cells.
+
+```python
+from cellstr import cell_len, cell_slice, fit, ljust, truncate
+
+warn = "\x1b[31mWARN\x1b[0m"  # red "WARN"
+cell_len(warn)  # -> 4
+cell_len("你好")  # -> 4
+cell_len("👨‍👩‍👧")  # -> 2
+cell_len("🇯🇵")  # -> 2
+cell_len("é")  # -> 1
+
+cell_slice(warn, 0, 2)  # -> "\x1b[31mWA\x1b[0m"
+cell_slice("a你b", 0, 2)  # -> "a"
+cell_slice("x👨‍👩‍👧y", 0, 2)  # -> "x"
+
+ljust("你", 4)  # -> "你  "
+truncate("hello world", 8)  # -> "hello..."
+truncate("/usr/local/lib/python", 12, position="middle")  # -> "/usr/...thon"
+fit("张伟张伟", 5, suffix="")  # -> "张伟 "
+```
+
+What it gets right:
+
+- **Grapheme clusters.** A ZWJ family, a skin tone sequence, a flag, a keycap or a letter
+  with accents is one unit: measured once and never split by slicing or truncation.
+- **Escape sequences.** SGR colours, OSC 8 hyperlinks, cursor movement and the other
+  ECMA-48 families count as nothing and are kept in place, so styled text stays styled.
+- **Ambiguous width.** Greek, Cyrillic, box drawing and circled digits are one cell in
+  Western terminals and two in CJK ones. Pass `ambiguous=2` to any function.
+- **Tabs.** Pass `tabsize=8` to measure tab stops; slicing and padding turn tabs into the
+  spaces they cover. `expand_tabs()` does it on its own.
+- **Real Unicode data.** Tables are generated by a committed script from a committed
+  Unicode Character Database snapshot, and the full grapheme break test suite runs.
+
+```python
+from cellstr import cell_len, iter_cells, truncate_detailed
+
+cell_len("αβ─", ambiguous=2)  # -> 6
+cell_len("a\tb", tabsize=8)  # -> 9
+[c.width for c in iter_cells("a你🇯🇵")]  # -> [1, 2, 2]
+truncate_detailed("hello world", 8).truncated  # -> True
+```
+
+Public API: `cell_len`, `char_width`, `grapheme_width`, `iter_graphemes`, `iter_cells`
+(`Cell`), `cell_slice`, `ljust`, `rjust`, `center`, `fit`, `truncate`,
+`truncate_detailed` (`Truncation`), `expand_tabs`, `strip_ansi`, `UNICODE_VERSION`, and
+the `Align` and `Position` literal types. Every function is fully typed and documented.
+
+## Command line
+
+```
+$ printf 'abc\n你好\n' | cellstr measure
+3
+4
+$ printf '/usr/local/lib/python3/site-packages\n' | cellstr truncate 16 --position middle
+/usr/lo...ckages
+$ printf 'id\n12345\n' | cellstr pad 8 --align right
+      id
+   12345
+```
+
+Commands: `measure` (`--max`), `truncate N`, `pad N`, `fit N` and `slice START [STOP]`,
+all with `--ambiguous` and `--tabsize`. `cellstr --help` lists runnable examples.
+
+## Terminals disagree
+
+There is no standard for how many cells a character takes, and terminals differ on
+ambiguous-width characters, emoji ZWJ sequences and variation selectors. `cellstr`
+follows Markus Kuhn's reference `wcwidth` for single code points and
+measures emoji sequences as one glyph, as terminals with grapheme support draw them.
+[GUIDE.md](GUIDE.md) has the exact rules, concrete examples of where terminals differ, a
+recipe for code point by code point measuring, and every difference from the `wcwidth`
+package.
+
+## Why
+
+`wcwidth` measures plain-text width well, but it does not give you a typed, cohesive set
+of string operations: slicing by column that keeps escapes and graphemes intact, padding,
+fitting a table cell and width-aware truncation with a suffix at either end or in the
+middle. `strip-ansi` style tools remove escapes but know nothing about width. `cellstr`
+does all of it in one small, fully typed, zero-dependency package.
+
+## License
+
+MIT. See [LICENSE](LICENSE). The property tables in `src/cellstr/_ucd_*.py` are generated
+from the Unicode Character Database and are covered by the Unicode License v3, see [LICENSE-UNICODE](LICENSE-UNICODE).
+
+## Links
+
+- Website: https://lianes8studio.com
+- GitHub: https://github.com/JaviLianes8
+- LinkedIn: https://www.linkedin.com/in/jlianes/

cellstr-0.2.1/README.md

@@ -0,0 +1,108 @@
+# cellstr
+
+Display-width aware `len`, slicing, padding and truncation for terminal text: East Asian
+wide characters, emoji sequences, combining marks, zero-width characters and ANSI escape
+sequences, measured the way a terminal draws them. Typed, zero dependencies, Unicode 18.0.0.
+
+## Install
+
+```
+pip install cellstr
+```
+
+## Usage
+
+`len`, slicing and `str.ljust` count code points, so they misalign any text that carries
+colour codes, CJK characters, emoji or accents. `cellstr` counts display cells.
+
+```python
+from cellstr import cell_len, cell_slice, fit, ljust, truncate
+
+warn = "\x1b[31mWARN\x1b[0m"  # red "WARN"
+cell_len(warn)  # -> 4
+cell_len("你好")  # -> 4
+cell_len("👨‍👩‍👧")  # -> 2
+cell_len("🇯🇵")  # -> 2
+cell_len("é")  # -> 1
+
+cell_slice(warn, 0, 2)  # -> "\x1b[31mWA\x1b[0m"
+cell_slice("a你b", 0, 2)  # -> "a"
+cell_slice("x👨‍👩‍👧y", 0, 2)  # -> "x"
+
+ljust("你", 4)  # -> "你  "
+truncate("hello world", 8)  # -> "hello..."
+truncate("/usr/local/lib/python", 12, position="middle")  # -> "/usr/...thon"
+fit("张伟张伟", 5, suffix="")  # -> "张伟 "
+```
+
+What it gets right:
+
+- **Grapheme clusters.** A ZWJ family, a skin tone sequence, a flag, a keycap or a letter
+  with accents is one unit: measured once and never split by slicing or truncation.
+- **Escape sequences.** SGR colours, OSC 8 hyperlinks, cursor movement and the other
+  ECMA-48 families count as nothing and are kept in place, so styled text stays styled.
+- **Ambiguous width.** Greek, Cyrillic, box drawing and circled digits are one cell in
+  Western terminals and two in CJK ones. Pass `ambiguous=2` to any function.
+- **Tabs.** Pass `tabsize=8` to measure tab stops; slicing and padding turn tabs into the
+  spaces they cover. `expand_tabs()` does it on its own.
+- **Real Unicode data.** Tables are generated by a committed script from a committed
+  Unicode Character Database snapshot, and the full grapheme break test suite runs.
+
+```python
+from cellstr import cell_len, iter_cells, truncate_detailed
+
+cell_len("αβ─", ambiguous=2)  # -> 6
+cell_len("a\tb", tabsize=8)  # -> 9
+[c.width for c in iter_cells("a你🇯🇵")]  # -> [1, 2, 2]
+truncate_detailed("hello world", 8).truncated  # -> True
+```
+
+Public API: `cell_len`, `char_width`, `grapheme_width`, `iter_graphemes`, `iter_cells`
+(`Cell`), `cell_slice`, `ljust`, `rjust`, `center`, `fit`, `truncate`,
+`truncate_detailed` (`Truncation`), `expand_tabs`, `strip_ansi`, `UNICODE_VERSION`, and
+the `Align` and `Position` literal types. Every function is fully typed and documented.
+
+## Command line
+
+```
+$ printf 'abc\n你好\n' | cellstr measure
+3
+4
+$ printf '/usr/local/lib/python3/site-packages\n' | cellstr truncate 16 --position middle
+/usr/lo...ckages
+$ printf 'id\n12345\n' | cellstr pad 8 --align right
+      id
+   12345
+```
+
+Commands: `measure` (`--max`), `truncate N`, `pad N`, `fit N` and `slice START [STOP]`,
+all with `--ambiguous` and `--tabsize`. `cellstr --help` lists runnable examples.
+
+## Terminals disagree
+
+There is no standard for how many cells a character takes, and terminals differ on
+ambiguous-width characters, emoji ZWJ sequences and variation selectors. `cellstr`
+follows Markus Kuhn's reference `wcwidth` for single code points and
+measures emoji sequences as one glyph, as terminals with grapheme support draw them.
+[GUIDE.md](GUIDE.md) has the exact rules, concrete examples of where terminals differ, a
+recipe for code point by code point measuring, and every difference from the `wcwidth`
+package.
+
+## Why
+
+`wcwidth` measures plain-text width well, but it does not give you a typed, cohesive set
+of string operations: slicing by column that keeps escapes and graphemes intact, padding,
+fitting a table cell and width-aware truncation with a suffix at either end or in the
+middle. `strip-ansi` style tools remove escapes but know nothing about width. `cellstr`
+does all of it in one small, fully typed, zero-dependency package.
+
+## License
+
+MIT. See [LICENSE](LICENSE). The property tables in `src/cellstr/_ucd_*.py` are generated
+from the Unicode Character Database and are covered by the Unicode License v3, see [LICENSE-UNICODE](LICENSE-UNICODE).
+
+## Links
+
+- Website: https://lianes8studio.com
+- GitHub: https://github.com/JaviLianes8
+- LinkedIn: https://www.linkedin.com/in/jlianes/

cellstr-0.2.1/data/ucd/MANIFEST.json

@@ -0,0 +1,65 @@
+{
+  "DerivedCoreProperties.txt": {
+    "title": "Unicode Character Database 18.0.0, DerivedCoreProperties.txt",
+    "url": "https://www.unicode.org/Public/18.0.0/ucd/DerivedCoreProperties.txt",
+    "revision": "Unicode 18.0.0",
+    "fetched": "2026-10-13",
+    "size": 1159889,
+    "sha256": "09c928886a178fcafd93c29e4bd59073a058e5a100b716d425cb563ab50f68c9",
+    "licence": "Unicode License v3 (https://www.unicode.org/license.txt), see LICENSE-UNICODE"
+  },
+  "DerivedGeneralCategory.txt": {
+    "title": "Unicode Character Database 18.0.0, DerivedGeneralCategory.txt",
+    "url": "https://www.unicode.org/Public/18.0.0/ucd/extracted/DerivedGeneralCategory.txt",
+    "revision": "Unicode 18.0.0",
+    "fetched": "2026-10-13",
+    "size": 282143,
+    "sha256": "d6b151d2d40ee9b1876d26f417980f45ffae47b6055ccf7203cb31f07a030f94",
+    "licence": "Unicode License v3 (https://www.unicode.org/license.txt), see LICENSE-UNICODE"
+  },
+  "EastAsianWidth.txt": {
+    "title": "Unicode Character Database 18.0.0, EastAsianWidth.txt",
+    "url": "https://www.unicode.org/Public/18.0.0/ucd/EastAsianWidth.txt",
+    "revision": "Unicode 18.0.0",
+    "fetched": "2026-10-13",
+    "size": 204705,
+    "sha256": "a0cf29eacd00cfcaec4381c6b7c281685f18dbb4e7ff82b4076ccb342ca839aa",
+    "licence": "Unicode License v3 (https://www.unicode.org/license.txt), see LICENSE-UNICODE"
+  },
+  "GraphemeBreakProperty.txt": {
+    "title": "Unicode Character Database 18.0.0, GraphemeBreakProperty.txt",
+    "url": "https://www.unicode.org/Public/18.0.0/ucd/auxiliary/GraphemeBreakProperty.txt",
+    "revision": "Unicode 18.0.0",
+    "fetched": "2026-10-13",
+    "size": 100009,
+    "sha256": "0839dcb79e4ac639ecd538b1abf7c9d22e3f9dd265b7e182d33627aa4d75b45a",
+    "licence": "Unicode License v3 (https://www.unicode.org/license.txt), see LICENSE-UNICODE"
+  },
+  "GraphemeBreakTest.txt": {
+    "title": "Unicode Character Database 18.0.0, GraphemeBreakTest.txt",
+    "url": "https://www.unicode.org/Public/18.0.0/ucd/auxiliary/GraphemeBreakTest.txt",
+    "revision": "Unicode 18.0.0",
+    "fetched": "2026-10-13",
+    "size": 137090,
+    "sha256": "b0cf047ee94485bbdc846de2b902f5f8a815f6b674f9d04223cddadd91c9df31",
+    "licence": "Unicode License v3 (https://www.unicode.org/license.txt), see LICENSE-UNICODE"
+  },
+  "emoji-data.txt": {
+    "title": "Unicode Character Database 18.0.0, emoji-data.txt",
+    "url": "https://www.unicode.org/Public/18.0.0/ucd/emoji/emoji-data.txt",
+    "revision": "Unicode 18.0.0",
+    "fetched": "2026-10-13",
+    "size": 108719,
+    "sha256": "80d00f8e616a0ef27fd6b8de3b758c06383b5d917e2977709578e68baf733bf1",
+    "licence": "Unicode License v3 (https://www.unicode.org/license.txt), see LICENSE-UNICODE"
+  },
+  "EastAsianWidth-15.1.0.txt": {
+    "title": "Unicode Character Database 15.1.0, EastAsianWidth.txt",
+    "url": "https://www.unicode.org/Public/15.1.0/ucd/EastAsianWidth.txt",
+    "revision": "Unicode 15.1.0",
+    "fetched": "2026-10-13",
+    "size": 194188,
+    "sha256": "b08191401dc125f4e84ef262a95754faae6b737c79538e17ea9664a63434e94e",
+    "licence": "Unicode License v3 (https://www.unicode.org/license.txt), see LICENSE-UNICODE"
+  }
+}