docs: expand StringTrie documentation (#139)

Author: hiroshi-manabe

README.rst

@@ -39,6 +39,9 @@ Usage
 
 See `tutorial`_ and `API`_ for details.
 
+For immutable ``str -> str`` mappings, use ``marisa_trie.StringTrie``
+(implemented as two internal tries plus a compact ID mapping table).
+
 .. _tutorial: https://marisa-trie.readthedocs.io/en/latest/tutorial.html
 .. _API: https://marisa-trie.readthedocs.io/en/latest/api.html
 
@@ -50,7 +53,8 @@ Current limitations
   and doesn't have iterator counterpart;
 * ``read()`` and ``write()`` methods don't work with file-like objects
   (they work only with real files; pickling works fine for file-like objects);
-* there are ``keys()`` and ``items()`` methods but no ``values()`` method.
+* ``Trie``, ``BytesTrie`` and ``RecordTrie`` provide ``keys()`` and
+  ``items()`` methods but no ``values()`` method.
 
 License
 =======

docs/tutorial.rst

@@ -157,6 +157,49 @@ Two read-only accessors are available for advanced usage:
 * ``key_trie``: the internal key trie (``marisa_trie.Trie``)
 * ``value_trie``: the internal value trie (``marisa_trie.Trie``)
 
+Python equivalents of common CLI workflows:
+
+* Build and save::
+
+      >>> pairs = [("apple", "fruit"), ("app", "prefix"), ("banana", "fruit")]
+      >>> trie = marisa_trie.StringTrie(pairs)
+      >>> trie.save("my_string_trie.bin")
+
+* Exact lookup::
+
+      >>> trie.get("apple")
+      "fruit"
+      >>> trie.get("missing", "N/A")
+      "N/A"
+
+* Common prefix search (prefixes of a query key)::
+
+      >>> trie.prefixes("application")
+      ["app"]
+      >>> trie.prefix_items("application")
+      [("app", "prefix")]
+
+* Predictive search (keys/items under a prefix)::
+
+      >>> trie.keys("app")
+      ["app", "apple"]
+      >>> trie.items("app")
+      [("app", "prefix"), ("apple", "fruit")]
+
+* Dump all entries::
+
+      >>> list(trie.iteritems())
+      [("app", "prefix"), ("apple", "fruit"), ("banana", "fruit")]
+
+For large datasets, use the runnable bulk-build sample script::
+
+    $ python examples/build_string_trie.py input.tsv output.bin
+
+``input.tsv`` must be UTF-8 text with one ``key<TAB>value`` pair per line.
+You can also stream from stdin::
+
+    $ cat input.tsv | python examples/build_string_trie.py - output.bin
+
 
 Persistence
 -----------

examples/build_string_trie.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+"""Build a StringTrie from TSV input.
+
+Input format:
+    one UTF-8 line per record, with "key<TAB>value"
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from contextlib import nullcontext
+
+import marisa_trie
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Build a marisa_trie.StringTrie from TSV pairs."
+    )
+    parser.add_argument(
+        "input",
+        help="Input TSV path, or '-' for stdin.",
+    )
+    parser.add_argument(
+        "output",
+        help="Output binary path for StringTrie.save().",
+    )
+    parser.add_argument(
+        "--progress-every",
+        type=int,
+        default=0,
+        help="Print progress every N input lines (0 disables progress logs).",
+    )
+    return parser.parse_args()
+
+
+def iter_tsv_pairs(path: str, progress_every: int):
+    if path == "-":
+        ctx = nullcontext(sys.stdin)
+    else:
+        ctx = open(path, "r", encoding="utf-8", newline="")
+
+    with ctx as f:
+        for lineno, raw in enumerate(f, 1):
+            line = raw.rstrip("\n")
+            if not line:
+                continue
+            if progress_every > 0 and lineno % progress_every == 0:
+                print(f"read {lineno} lines", file=sys.stderr)
+            if "\t" not in line:
+                raise ValueError(
+                    f"line {lineno}: expected a TAB separator between key and value"
+                )
+            key, value = line.split("\t", 1)
+            yield key, value
+
+
+def main() -> int:
+    args = parse_args()
+    try:
+        trie = marisa_trie.StringTrie(
+            iter_tsv_pairs(args.input, args.progress_every)
+        )
+        trie.save(args.output)
+    except Exception as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())