xjyutping 1.1.0__tar.gz

xjyutping-1.1.0/CHANGELOG.md

@@ -0,0 +1,280 @@
+# Changelog
+
+All notable changes to xjyutping, the Python package, are recorded here. The
+format follows [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/),
+and versions follow [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
+
+This package is the Python port of the LaTeX package
+[xjyutping](https://github.com/Beyond3345/xjyutping-tex), which has its own
+version numbers and its own changelog. That changelog also holds the full
+history of how both packages were built, including the review rounds whose
+results this package inherits through the shared data. This file has the
+Python releases and the handover notes for the Python side.
+
+The version is written in three places: `version` in `pyproject.toml`,
+`__version__` in `src/xjyutping/__init__.py` (`test_version` checks that the
+two agree), and `README.md`. A release bumps all three and gets an entry in
+Part I.
+
+---
+
+# Part I: Releases
+
+## [Unreleased]
+
+Nothing yet. Add entries here under `### Added`, `### Changed`, `### Fixed`
+and so on.
+
+## [1.1.0] - 2026-09-28
+
+### Added
+
+- **More vocabulary:** the data of xjyutping-tex 1.2.0.
+  - 2,291 words from CC-Canto and the Cantonese readings of CC-CEDICT, as
+    distributed with Jyut Dictionary. They are added only where they change a
+    reading and pass consistency checks against rime-cantonese; 480 more
+    were excluded by hand.
+  - 640 characters that the other sources lack, with readings from the book
+    data of 粵音資料集叢 (jyutnet/cantonese-books-data, by 石見田).
+
+  On the corpora audited earlier nothing got worse; on new test sentences,
+  24 readings improved and 3 changed neutrally (see the LaTeX package's
+  changelog, Part II, section 7.4).
+- `test_added_vocabulary`, which checks new words, the words that must not
+  capture their neighbours, the two hand fixes and a book character.
+- README: an **Acknowledgements and attributions** section.
+  - The inspiration: [xpinyin](https://github.com/lxneng/xpinyin) by Eric Lo
+    ([lxneng](https://lxneng.com)), whose API this package follows.
+  - Visual Jyutping and the Visual Cantonese Fonts, which inspired the
+    `fancy` and `discord` styles.
+  - Every data source: LSHK, rime-cantonese, 粵音資料集叢, Jyut Dictionary
+    with CC-Canto, the CC-CEDICT readings and CC-CEDICT, and OpenCC.
+- This `CHANGELOG.md` and a `.gitignore`. Up to 1.0.0 both packages shared
+  one changelog in the folder that held them; the history is kept in
+  xjyutping-tex's.
+
+### Changed
+
+- **Readings**, as in xjyutping-tex 1.2.0, for example 機長 zoeng2, 營業額
+  ngaak2, 自由行 hang4, 研討會 wui2, 消防隊 deoi2, 冠狀病毒 gun1, 智能卡
+  kaat1. 化合物 is now faa3 hap6 mat6 and 會否 wui5 fau2.
+- **Licence of the data files** in `src/xjyutping/data/`: CC BY-SA 4.0, since
+  the added word lists are CC BY-SA 3.0 (share-alike). Before this, the data
+  carried CC BY 4.0. `LICENSE` lists every source. The code stays MIT.
+- `tests/parity.tex` compiles with XeLaTeX or LuaLaTeX.
+- `tests/parity_expected.txt` was regenerated from xjyutping-tex 1.2.0 and
+  changed in one line: 隨着 is now one word, with the same readings.
+- README: shorter, with installing from PyPI or GitHub, and links to the LaTeX
+  package's repository. The PyPI summary is now "Convert Traditional Chinese
+  text to Cantonese Jyutping (粵拼), with pronunciation chosen from context".
+- **Packaging for PyPI:** `pyproject.toml` declares the licence as the SPDX
+  expression `MIT AND CC-BY-SA-4.0` with `license-files` (PEP 639, hence
+  setuptools 77 or later to build), and has keywords, classifiers and the
+  project URLs (repository, issues, changelog, the LaTeX package).
+  `MANIFEST.in` adds `CHANGELOG.md` and the parity files to the sdist. The
+  sdist and wheel pass `twine check`.
+
+## [1.0.0] - 2026-09-28
+
+### Added
+
+- **First release** of the Python package `xjyutping`: the Python port of
+  the LaTeX package, with the API of
+  [xpinyin](https://github.com/lxneng/xpinyin). Python 3.8 or later, no
+  dependencies. Class `Jyutping(data_dir=None)`:
+  - `get_jyutping(chars, splitter='-', tone_marks='numbers', convert='lower')`
+  - `get_jyutpings(chars, splitter, tone_marks, convert, n=10)`: the reading
+    in context first, then the other readings.
+  - `annotate(text, tone_marks)`: one `(char, reading or None)` pair per
+    input character.
+  - `segment(text)`: `Segment(text, readings, type)` with the types w/u/m/s
+    of the TeX debug log.
+  - `set_jyutping(text, reading)`, the equivalent of `\setjyutping`.
+  - `get_initial(char, full=False)` and `get_initials(chars, splitter, full)`.
+  - The static methods `decode_jyutping` and `convert_jyutping`.
+- **Tone styles:** `'numbers'` (default), `None`, `'fancy'` and `'discord'`.
+  The last two use the exact code points of Visual Jyutping's web and
+  Discord tone maps: ˉ¹ ˊ² ˗₃ ˎ₄ ˏ₅ ˍ₆ and ˉ¹ ⸍² -₃ ⸜₄ ⸝₅ ˍ₆.
+- **Same readings as xjyutping-tex 1.1.0.** It uses the same data
+  (`src/xjyutping/data/*.tsv`, generated by that package's
+  `tools/build-data.py`) and the same run splitting, segmentation, variant
+  folding, run-final readings and user overrides.
+- **Tests:** 38 pytest tests, including a parity test against a frozen TeX
+  debug log (`tests/parity.tex`, `parity_corpus.txt`,
+  `parity_expected.txt`). There are 109 runs in the log and no mismatches.
+- MIT licence for the code; the data carried CC BY 4.0 (LSHK,
+  rime-cantonese) and Apache-2.0 (OpenCC).
+
+---
+
+# Part II: Handover notes
+
+## 0. Start here
+
+**Where things are:**
+
+| Path | What it is |
+| --- | --- |
+| `src/xjyutping/__init__.py` | The whole package: `Jyutping`, `Segment`, `TONE_MARKS`. |
+| `src/xjyutping/data/*.tsv` | Generated data (see below); never edit by hand. |
+| `tests/test_xjyutping.py` | pytest suite (39 tests). |
+| `tests/parity_corpus.txt`, `parity_expected.txt`, `parity.tex` | The parity test with the LaTeX package: the corpus, the frozen TeX debug log, and the document that regenerates the log. |
+| `pyproject.toml`, `MANIFEST.in` | Packaging (setuptools; the TSV files are package data; the sdist includes the parity files). |
+| `README.md`, `LICENSE`, `CHANGELOG.md` | Documentation, licences (code MIT, data CC BY-SA 4.0), this file. |
+
+**The data** is generated, together with the LaTeX package's `.def` files,
+by `tools/build-data.py` in
+[xjyutping-tex](https://github.com/Beyond3345/xjyutping-tex). It writes here
+when this repository sits next to xjyutping-tex (or with
+`--py-data DIR`). The files are:
+
+- `chars.tsv`: character, default reading, other readings, polyphone flag;
+- `finals.tsv`: reading at the end of a run;
+- `variants.tsv`: variant, canonical character;
+- `words.tsv`: word, readings.
+
+The sources and every rule for choosing readings are described in that
+repository's README and changelog.
+
+**Invariants to keep:**
+
+1. **The same readings as the LaTeX package.**
+   `test_parity_with_tex_package` compares every segment, reading and type of
+   `tests/parity_corpus.txt` with the LaTeX package's debug log.
+   - When the data or the segmentation changes on purpose, regenerate
+     `parity_expected.txt`: compile `tests/parity.tex` with
+     `TEXINPUTS=<xjyutping-tex>: LUAINPUTS=<xjyutping-tex>:` and
+     `max_print_line=10000`, then copy the `xjyutping>` lines. Check the diff
+     by hand.
+2. **Reading fixes belong in xjyutping-tex's `tools/build-data.py`**, never
+   in the TSV files or the code.
+3. **The algorithm mirrors the TeX package** (section 2). A change on one
+   side needs the same change on the other.
+4. **Python 3.8 compatibility:** no `match`, no `X | Y` unions evaluated at
+   runtime, no 3.9+ string methods.
+5. **Versioning** follows SemVer:
+   - MAJOR: an incompatible change of the API (a method, argument or return
+     value);
+   - MINOR: a backward-compatible feature, or new vocabulary (1.1.0);
+   - PATCH: bug fixes and reading corrections.
+
+**How to test:**
+
+```bash
+python3 -m pip install --upgrade pip && pip install -e '.[test]' && pytest tests
+```
+
+Without installing, run `PYTHONPATH=src python3 -m pytest tests`. All tests
+must pass, including `test_parity_with_tex_package`. To check a release,
+build the sdist and wheel and run the tests from the extracted sdist.
+
+## 1. How the port was built (with xjyutping-tex 1.1.0)
+
+The port was written by an agent against a frozen copy of the LaTeX package
+1.0.0. It took xpinyin's API and reproduced the LaTeX package's algorithm:
+runs, segmentation by dynamic programming, word and character lookup, and
+user settings. The parity with TeX was then checked on a 668-character
+corpus: 0 mismatches.
+
+Three independent reviewers then checked it, each from one angle:
+
+- reading parity with TeX, on a new 1 021-character corpus: 119 runs
+  compared line for line;
+- API, packaging and docs: the README examples run as doctests; wheel and
+  sdist contents;
+- edge cases and tone styles.
+
+Every finding was reproduced before it was fixed. The author's own 35 tests
+had passed.
+
+- **P-1. CR line ends** (reported by all three reviewers). A lone CR was not
+  counted as a line end, so `'\r\r'`, a blank line to TeX, did not end a
+  run. That changed segmentation and the run-final 呢.
+  - Fix: `_runs` counts `\n`, and `\r` not followed by `\n`.
+  - Test: `test_runs_cr_line_ends`, with expected values from a TeX log.
+- **P-2. The sdist lacked the parity files,** so its own test suite failed
+  (2 tests, FileNotFoundError). Fix: `MANIFEST.in` includes `tests/*.txt`
+  and `*.tex`.
+- **P-3. The README's editable install failed** with pip 21.2.4, since
+  editable installs need pip 21.3 or later. The README now upgrades pip
+  first.
+- **P-4. `license = {text = "MIT"}` in `pyproject.toml`** triggered a
+  setuptools deprecation that becomes a build error after 2027-02-18.
+  Removed; `License-File` and the classifier remain.
+- **P-5. The README's run-final example showed a word-list entry** instead
+  of the run-final rule. It was replaced with 呢張床好平，好麻煩呢？
+- **P-6. `set_jyutping` on a character missing from the data did nothing.**
+  TeX reads such a character without context and with type `u`. It is now
+  its own run of type `u`; test `test_set_jyutping_char_not_in_data`.
+- **P-7. `set_jyutping` rejected whitespace** that `\setjyutping` ignores.
+  It now strips spaces, tabs, CR and LF; test
+  `test_set_jyutping_ignores_spaces`.
+
+Timing on the development Mac (Python 3.9):
+
+- `Jyutping()` takes about 0.08 s;
+- `annotate` on 10 000 characters takes about 0.02 s.
+
+## 2. How the port maps to the LaTeX package
+
+| TeX (`xjyutping.sty`) | Python (`src/xjyutping/__init__.py`) |
+| --- | --- |
+| a character is Chinese iff `\xjp@c@<char>` exists | `c in self._chars` |
+| runs: spaces and single line breaks between characters continue a run; `\par`/blank line ends it | `_runs` (ASCII space, tab, CR, LF; two line ends end the run; U+3000 ends it) |
+| `\__xjyutping_flush:` (DP, 100000 per segment + 1 per single, `<=` so longer final word wins; bound `\xjp@e@` raw or canonical) | `_segment_run` (same costs and comparison; bound `_longest`, computed from `words.tsv` at load) |
+| `\__xjyutping_emit:nn` word: raw key, else canonical; type `u` if `\xjp@uw@` | same, `self._user_words` |
+| `\__xjyutping_lookup:nn` single: user, then `\xjp@f@` at run end, then default; type m/s from `\xjp@m@` | same (`_user_chars`, `_finals`, polyphone flag in `chars.tsv`) |
+| `\__xjyutping_set:nnn` / `\__xjyutping_set_word:nn` | `set_jyutping` (raw and canonical keys, longest bound) |
+| `debug` log `銀ngan4:w…` | `segment()` |
+
+Differences by design:
+
+- Python has no markup, so it has nothing like the command table, footnote
+  runs, `\xjyutping` manual readings or plain mode. The parity corpus
+  therefore has TeX's commands resolved into the runs TeX makes of them.
+- `chars.tsv` lists the other readings of every character (for
+  `get_jyutpings`), not only of flagged polyphones.
+- `Segment` has no field for the other readings. The parity test reads them
+  from `_chars`; users get them through `get_jyutpings`.
+- `get_jyutping` drops whitespace between Chinese characters, U+3000
+  included, although U+3000 ends a run for segmentation.
+
+## 3. Version 1.1.0
+
+Data only, plus documentation.
+
+- The data of xjyutping-tex 1.2.0 was copied in by its build: 640 more
+  characters, 2 291 more words and the two hand fixes.
+- The parity file was regenerated with both TeX engines, which agree.
+- `test_added_vocabulary` was added. The README examples still run
+  unchanged (24 doctests). `python -m doctest README.md` counts the closing
+  code fence as expected output, so strip the fences first:
+
+  ```bash
+  PYTHONPATH=src python3 -c "import doctest,re; t=re.sub(r'(?m)^\x60{3}.*$','',open('README.md',encoding='utf8').read()); r=doctest.DocTestRunner(optionflags=doctest.NORMALIZE_WHITESPACE); r.run(doctest.DocTestParser().get_doctest(t,{},'README','README.md',0)); print(r.summarize())"
+  ```
+- The code did not change.
+- **Release to PyPI** (the name `xjyutping` was free on 2026-09-28):
+
+  ```bash
+  python3 -m pip install --upgrade build twine
+  python3 -m build
+  python3 -m twine check dist/*
+  python3 -m twine upload dist/*
+  ```
+
+  The 1.1.0 wheel and sdist were built this way and checked: `twine check`
+  passes, the wheel installs into a clean virtual environment, and the 39
+  tests pass from the extracted sdist. `twine upload` asks for a PyPI API
+  token (user name `__token__`); upload to TestPyPI first with
+  `--repository testpypi` if in doubt.
+
+## 4. Open issues
+
+- **Readings that need more context than a word list gives** stay wrong
+  until a user sets them. The list is in the LaTeX package's changelog, Part
+  II, section 4, item 14, still open after its 1.2.0 (section 7.7), e.g. 為
+  wai4/wai6, 同行, 種花, 長得, 重未.
+- **The book characters' licence.** The 640 characters from 粵音資料集叢
+  come from data published without a licence statement; see `LICENSE` and
+  the LaTeX package's changelog, section 7.4.

xjyutping-1.1.0/LICENSE

@@ -0,0 +1,48 @@
+MIT License
+
+Copyright (c) 2026 the xjyutping authors
+
+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.
+
+-------------------------------------------------------------------------------
+Third-party material
+
+The files in src/xjyutping/data/ are generated by tools/build-data.py of
+the LaTeX package (https://github.com/Beyond3345/xjyutping-tex) and are
+distributed under Creative Commons Attribution-ShareAlike 4.0
+(CC BY-SA 4.0, https://creativecommons.org/licenses/by-sa/4.0/), because
+they adapt share-alike material. They are built from:
+
+  * the LSHK Cantonese Pronunciation List of Characters for Computers
+    (jyutping-table), Creative Commons Attribution 4.0 (CC BY 4.0);
+  * rime-cantonese jyut6ping3.chars and jyut6ping3.words, Creative Commons
+    Attribution 4.0 (CC BY 4.0);
+  * CC-Canto, Copyright (c) 2015-17 Pleco Inc., and the CC-CEDICT Cantonese
+    readings, Copyright (c) 2015 Pleco Software Inc., both Creative Commons
+    Attribution-ShareAlike 3.0 (CC BY-SA 3.0), as distributed with Jyut
+    Dictionary (https://github.com/aaronhktan/jyut-dict);
+  * OpenCC HKVariants.txt and TWVariants.txt, Apache License 2.0;
+  * readings of 640 characters from the book data of 粵音資料集叢 by 石見田
+    (https://github.com/jyutnet/cantonese-books-data), published without a
+    licence statement and used with attribution.
+
+The 'fancy' and 'discord' tone symbols (TONE_MARKS in
+src/xjyutping/__init__.py) come from Visual Jyutping
+(https://github.com/VincentTam/visual-jyutping), MIT License,
+Copyright (c) 2024 Vincent Tam.

xjyutping-1.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include CHANGELOG.md
+recursive-include tests *.txt *.tex

xjyutping-1.1.0/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: xjyutping
+Version: 1.1.0
+Summary: Convert Traditional Chinese text to Cantonese Jyutping (粵拼), with pronunciation chosen from context
+License-Expression: MIT AND CC-BY-SA-4.0
+Project-URL: Homepage, https://github.com/Beyond3345/xjyutping-py
+Project-URL: Repository, https://github.com/Beyond3345/xjyutping-py
+Project-URL: Issues, https://github.com/Beyond3345/xjyutping-py/issues
+Project-URL: Changelog, https://github.com/Beyond3345/xjyutping-py/blob/main/CHANGELOG.md
+Project-URL: LaTeX package, https://github.com/Beyond3345/xjyutping-tex
+Keywords: jyutping,cantonese,romanization,romanisation,粵拼,粵語,chinese
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Natural Language :: Chinese (Traditional)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=6.2; extra == "test"
+Dynamic: license-file
+
+# xjyutping (Python)
+
+Version 1.1.0 (2026-09-28). Versions follow
+[Semantic Versioning](https://semver.org), and the history is in
+[`CHANGELOG.md`](https://github.com/Beyond3345/xjyutping-py/blob/main/CHANGELOG.md).
+
+xjyutping converts Traditional Chinese text to Cantonese Jyutping (粵拼).
+Pronunciation is determined by looking at the context and cross-referencing
+it with a list of about 104 000 words, so 行 is *hong4* in 銀行 but *haang4*
+in 行路. It is the Python version of the LaTeX package
+[xjyutping](https://github.com/Beyond3345/xjyutping-tex) and gives the same
+readings. It was inspired by [xpinyin](https://github.com/lxneng/xpinyin),
+which converts Chinese characters to Mandarin pinyin, and follows its API.
+
+## Install
+
+Python 3.8 or later, no dependencies.
+
+```bash
+pip install xjyutping
+```
+
+or from GitHub with `pip install git+https://github.com/Beyond3345/xjyutping-py`.
+For development (editable installs need pip 21.3 or later):
+
+```bash
+python3 -m pip install --upgrade pip && pip install -e '.[test]' && pytest tests
+```
+
+## Usage
+
+```pycon
+>>> from xjyutping import Jyutping
+>>> j = Jyutping()
+>>> j.get_jyutping('我哋去銀行')          # default splitter is '-'
+'ngo5-dei6-heoi3-ngan4-hong4'
+>>> j.get_jyutping('行路返屋企', ' ')
+'haang4 lou6 faan1 uk1 kei2'
+>>> j.get_jyutping('香港', '')
+'hoeng1gong2'
+>>> j.get_jyutping('香港', convert='capitalize')    # or 'upper'; default 'lower'
+'Hoeng1-Gong2'
+>>> j.get_jyutping('Apple發布iOS7')      # other text is kept as it is
+'Apple-faat3-bou3-iOS7'
+>>> j.get_jyutping('你好 世界')           # spaces between characters are dropped
+'nei5-hou2-sai3-gaai3'
+>>> j.annotate('銀行 ATM')              # one pair per input character
+[('銀', 'ngan4'), ('行', 'hong4'), (' ', None), ('A', None), ('T', None), ('M', None)]
+```
+
+### Tone styles
+
+`tone_marks` works with `get_jyutping`, `get_jyutpings` and `annotate`:
+
+| `tone_marks` | 詩史試時市事 |
+| --- | --- |
+| `'numbers'` (default) | si1 si2 si3 si4 si5 si6 |
+| `None` | si si si si si si |
+| `'fancy'` | siˉ¹ siˊ² si˗₃ siˎ₄ siˏ₅ siˍ₆ |
+| `'discord'` | siˉ¹ si⸍² si-₃ si⸜₄ si⸝₅ siˍ₆ |
+
+`'fancy'` and `'discord'` use the tone symbols of
+[Visual Jyutping](https://github.com/VincentTam/visual-jyutping), from its web
+and Discord versions. Any other value raises `ValueError`.
+
+```pycon
+>>> j.get_jyutping('行路', ' ', tone_marks='fancy')
+'haangˎ₄ louˍ₆'
+>>> Jyutping.decode_jyutping('hou2', 'fancy')
+'houˊ²'
+```
+
+### Context and your own readings
+
+Text is split into runs of Chinese characters, and each run is split into
+the fewest words from the word list. A word takes its reading from the list,
+and a character on its own takes your reading or else its default. 呢 reads
+*ni1* inside a run but *ne1* at its end. Variant shapes such as 為/爲 and
+裡/裏 find the same words.
+
+```pycon
+>>> j.get_jyutping('校長喺學校長大')
+'haau6-zoeng2-hai2-hok6-haau6-zoeng2-daai6'
+>>> j.get_jyutping('呢張床好平，好麻煩呢？', ' ')
+'ni1 zoeng1 cong4 hou2 peng4 ， hou2 maa4 faan4 ne1 ？'
+>>> j.segment('佢重話聽日嚟')
+[Segment(text='佢', readings=['keoi5'], type='s'), Segment(text='重', readings=['cung5'], type='m'), Segment(text='話', readings=['waa6'], type='s'), Segment(text='聽日', readings=['ting1', 'jat6'], type='w'), Segment(text='嚟', readings=['lai4'], type='m')]
+```
+
+`segment` shows how a text was read, like the LaTeX package's `debug`
+option. The types are `w` for a word from the list, `u` for your setting, `m`
+for a guessed reading of a character with several, and `s` for a character
+with one reading.
+
+`set_jyutping` works like `\setjyutping` in LaTeX. One character gets a new
+default reading, and several characters (one syllable each) become a word. A
+syllable count that doesn't match raises `ValueError`. Settings belong to the
+`Jyutping` instance.
+
+```pycon
+>>> j.set_jyutping('重話', 'zung6 waa6')
+>>> j.get_jyutping('佢重話聽日嚟')
+'keoi5-zung6-waa6-ting1-jat6-lai4'
+>>> j.set_jyutping('重', 'zung6')
+>>> j.get_jyutping('佢重未嚟')
+'keoi5-zung6-mei6-lai4'
+```
+
+### Combinations
+
+`get_jyutpings` lists up to `n` (default 10) combinations of readings, with
+the reading in context first.
+
+```pycon
+>>> j.get_jyutpings('行')
+['haang4', 'hang4', 'hong4', 'hong2', 'hang6']
+>>> j.get_jyutpings('銀行', n=3)
+['ngan4-hong4', 'ngan4-haang4', 'ngan4-hang4']
+>>> j.get_jyutpings('行', tone_marks=None)
+['haang', 'hang', 'hong']
+```
+
+### Initials
+
+`get_initial` and `get_initials` give the first letter of each reading in
+capitals, and leave other text unchanged. With `full=True` they give the
+whole initial (`NG`, `GW`, `KW` ...), or an empty string for a syllable
+without one, such as 屋 *uk1* or 唔 *m4*.
+
+```pycon
+>>> j.get_initials('我哋去廣州')
+'N-D-H-G-Z'
+>>> j.get_initials('我哋去廣州', full=True)
+'NG-D-H-GW-Z'
+>>> j.get_initials('唔五屋'), j.get_initials('唔五屋', full=True)
+('M-N-U', '--')
+```
+
+## API
+
+| | |
+| --- | --- |
+| `Jyutping(data_dir=None)` | Loads the data (from the package unless `data_dir` is given). |
+| `get_jyutping(chars, splitter='-', tone_marks='numbers', convert='lower')` | Jyutping of a text. |
+| `get_jyutpings(chars, splitter='-', tone_marks='numbers', convert='lower', n=10)` | Combinations of readings. |
+| `annotate(text, tone_marks='numbers')` | `[(char, reading or None), ...]`, one per character. |
+| `segment(text)` | `[Segment(text, readings, type), ...]` for the Chinese text. |
+| `set_jyutping(text, reading)` | Your reading for a character or a word. |
+| `get_initial(char, full=False)`, `get_initials(chars, splitter='-', full=False)` | Initials. |
+| `Jyutping.decode_jyutping(syllable, tone_marks)`, `Jyutping.convert_jyutping(syllable, convert)` | Format one syllable. |
+
+## Data
+
+The data in `src/xjyutping/data/` (30 089 characters, about 104 000 words) is
+generated by `tools/build-data.py` in
+[xjyutping-tex](https://github.com/Beyond3345/xjyutping-tex), from the
+sources credited below. Fix readings there, not in the TSV files.
+
+## Tests
+
+`pytest tests` runs the tests. One of them checks that the readings match
+the LaTeX package's debug log (`tests/parity_expected.txt`), which
+`tests/parity.tex` regenerates.
+
+## Acknowledgements and attributions
+
+This project was inspired by [xpinyin](https://github.com/lxneng/xpinyin) by
+Eric Lo ([lxneng](https://lxneng.com)), a Python package that converts
+Chinese characters to pinyin. Its API is the model for this one. The LaTeX
+version of xjyutping was inspired by the LaTeX package
+[xpinyin](https://ctan.org/pkg/xpinyin) by Qing Lee (李清).
+
+The `'fancy'` and `'discord'` styles use the tone symbols of
+[Visual Jyutping](https://github.com/VincentTam/visual-jyutping) by Vincent
+Tam, which was itself inspired by the Visual Cantonese Fonts (粵語字體) by Jon
+Chui / A3I Ltd. ([canto.hk](https://canto.hk),
+[documentation](https://docs.visual-fonts.com),
+[source](https://github.com/jkwchui/visual-fonts-starlight-docs)). Thank you
+both.
+
+Thanks also to the authors of the data sources:
+
+* the Jyutping Workgroup of the Linguistic Society of Hong Kong, for the
+  *Cantonese Pronunciation List of Characters for Computers*
+  (電腦用漢字粵語拼音表,
+  [lshk-org/jyutping-table](https://github.com/lshk-org/jyutping-table),
+  CC BY 4.0), and to Prof Lu Qin and Dr Cheung Kwan Hin of the Hong Kong
+  Polytechnic University and Nathan Hammond, who are thanked there;
+* the Cantonese Computational Linguistics Infrastructure Development
+  Workgroup (CanCLID) and contributors, for
+  [rime-cantonese](https://github.com/rime/rime-cantonese) (粵語拼音輸入方案,
+  CC BY 4.0), which gives the default readings and most of the words;
+* 石見田, for 粵音資料集叢 ([jyut.net](https://jyut.net/about), data at
+  [jyutnet/cantonese-books-data](https://github.com/jyutnet/cantonese-books-data)),
+  and the authors and editors of the dictionaries it digitises: 廣州話正音字典
+  (2004), 廣州話標準音字彙 (1988), 粵語同音字典 (1974/1996), 粵語查音識字字典
+  (1985), 同音字彙 (1971), 部身字典 (1967), *The Student's Cantonese-English
+  Dictionary* (1947), 粵音韻彙 (1941), 道字典 (1941), 道漢字音 (1939),
+  民眾識字粵語拼音字彙 (1931), 廣話國語一貫未定稿 (1916) and
+  分部分音廣話九聲字宗 (1914);
+* Aaron Tan, for [Jyut Dictionary](https://github.com/aaronhktan/jyut-dict),
+  which distributes CC-Canto (© 2015–17 Pleco Inc.,
+  [cantonese.org](https://cantonese.org), CC BY-SA 3.0) and the Cantonese
+  readings for CC-CEDICT (© 2015 Pleco Software Inc., CC BY-SA 3.0), and MDBG
+  and the contributors of [CC-CEDICT](https://cc-cedict.org);
+* Carbo Kuo (BYVoid) and contributors, for
+  [OpenCC](https://github.com/BYVoid/OpenCC) (Apache-2.0), whose variant
+  tables let variant shapes find the same words.
+
+## Licence
+
+The code is under the MIT licence
+([`LICENSE`](https://github.com/Beyond3345/xjyutping-py/blob/main/LICENSE)),
+and the tone symbols in `TONE_MARKS` come from Visual Jyutping (MIT). The data
+files in `src/xjyutping/data/` are under
+[CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/), because they
+adapt the CC BY-SA 3.0 word lists above. The readings of the 640 characters
+from 粵音資料集叢 come from data published without a licence and are used with
+attribution.