wordsnum 0.2.0__py3-none-any.whl

wordsnum/_parser.py

@@ -0,0 +1,91 @@
+"""Parse a string that holds exactly one spelled-out English number."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from fractions import Fraction
+
+from ._errors import WordsNumError
+from ._forms import parse_tokens
+from ._result import ParsedNumber
+from ._tokens import tokenize
+
+__all__ = ["WordsNumError", "parse", "words_to_decimal", "words_to_fraction", "words_to_num"]
+
+
+def parse(text: str, *, strict: bool = False) -> ParsedNumber:
+    """Parse ``text`` as one number and return a ``ParsedNumber``.
+
+    The whole string must be a single number; surrounding whitespace is allowed in
+    lenient mode. Use ``find_numbers`` to pull numbers out of free text.
+
+    Args:
+        text: The number, such as ``"two thousand and twenty-one"``.
+        strict: When ``False`` (the default) case, runs of whitespace, hyphens and
+            commas between words are tolerated. When ``True`` only the canonical
+            spelling is accepted: lowercase words, single spaces, a hyphen exactly
+            between a tens word and a unit word, and no commas between words. Neither
+            mode guesses misspelled words.
+
+    Raises:
+        UnknownWordError: A word is not a number word (``"banana"``, ``"fourty"``).
+        MisplacedWordError: Number words appear in an order the grammar rejects.
+        WordsNumError: The text holds no number words at all.
+
+    >>> parse("three quarters").value
+    Fraction(3, 4)
+    >>> parse("twenty-first").kind
+    'ordinal'
+    """
+    tokens = tokenize(text, strict=strict)
+    value, kind = parse_tokens(tokens)
+    start, end = tokens[0].start, tokens[-1].end
+    return ParsedNumber(value, kind, text[start:end], start, end)
+
+
+def words_to_num(text: str, *, strict: bool = False) -> int | float:
+    """Convert spelled-out English to an ``int``, or a ``float`` when it is not whole.
+
+    Cardinals and ordinals return ``int`` (``"twenty-first"`` is 21). Decimals and
+    fractions return ``float`` (``"three point one four"`` is 3.14, ``"a half"`` is
+    0.5). Use ``words_to_fraction`` or ``words_to_decimal`` for exact results.
+
+    Args:
+        text: The number, such as ``"one hundred and one"`` or ``"3 million"``.
+        strict: Accept only the canonical spelling; see ``parse``.
+
+    Raises:
+        WordsNumError: The text is not a valid number (see ``parse`` for subclasses).
+
+    >>> words_to_num("two million three hundred thousand")
+    2300000
+    >>> words_to_num("minus two point five")
+    -2.5
+    """
+    return parse(text, strict=strict).number
+
+
+def words_to_fraction(text: str, *, strict: bool = False) -> Fraction:
+    """Convert spelled-out English to an exact ``Fraction``.
+
+    >>> words_to_fraction("two and three quarters")
+    Fraction(11, 4)
+    >>> words_to_fraction("zero point one")
+    Fraction(1, 10)
+    """
+    return parse(text, strict=strict).value
+
+
+def words_to_decimal(text: str, *, strict: bool = False) -> Decimal:
+    """Convert spelled-out English to a ``Decimal``.
+
+    Exact for every cardinal, ordinal and decimal (``"one point one"`` is
+    ``Decimal('1.1')``). A fraction without a terminating expansion, such as
+    ``"two thirds"``, is rounded to the precision of the current ``decimal`` context.
+
+    >>> words_to_decimal("one point one")
+    Decimal('1.1')
+    >>> words_to_decimal("seven hundredths")
+    Decimal('0.07')
+    """
+    return parse(text, strict=strict).to_decimal()

wordsnum/_result.py

@@ -0,0 +1,76 @@
+"""The structured result of parsing one number."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from decimal import Decimal
+from fractions import Fraction
+
+from ._errors import WordsNumError
+from ._forms import Kind
+
+
+@dataclass(frozen=True)
+class ParsedNumber:
+    """One parsed number with its exact value, its kind and where it was found.
+
+    Attributes:
+        value: The exact value as a ``Fraction`` (``"three point one four"`` is
+            ``Fraction(157, 50)``, never a rounded float).
+        kind: ``"cardinal"`` (``"forty two"``), ``"ordinal"`` (``"forty-second"``,
+            ``"21st"``), ``"decimal"`` (``"two point five"``, ``"1.5 million"``) or
+            ``"fraction"`` (``"three quarters"``, ``"two and a half"``).
+        text: The source text of the number, exactly as written.
+        start: Offset of the first character of the number in the parsed string.
+        end: Offset just past the last character, so ``source[start:end] == text``.
+    """
+
+    value: Fraction
+    kind: Kind
+    text: str
+    start: int
+    end: int
+
+    @property
+    def number(self) -> int | float:
+        """The value as ``words_to_num`` returns it.
+
+        An ``int`` for cardinals and ordinals, a ``float`` for decimals and fractions
+        (even when the value is whole, such as ``"four halves"``).
+
+        Raises:
+            WordsNumError: A decimal or fraction is too large for a ``float``.
+        """
+        if self.kind in ("cardinal", "ordinal"):
+            return int(self.value)
+        try:
+            return self.value.numerator / self.value.denominator
+        except OverflowError:
+            raise WordsNumError(
+                f"{self.text[:40]!r} is too large for a float; use words_to_fraction or "
+                "words_to_decimal for the exact value"
+            ) from None
+
+    def to_decimal(self) -> Decimal:
+        """The value as a ``Decimal``.
+
+        Exact whenever the value has a terminating decimal expansion, which covers every
+        cardinal, ordinal and decimal. A fraction such as ``"one third"`` is divided in
+        the current ``decimal`` context and so is rounded to its precision.
+        """
+        value = self.value
+        if value.denominator == 1:
+            return Decimal(value.numerator)
+        denominator = value.denominator
+        twos = fives = 0
+        while denominator % 2 == 0:
+            denominator //= 2
+            twos += 1
+        while denominator % 5 == 0:
+            denominator //= 5
+            fives += 1
+        if denominator != 1:
+            return Decimal(value.numerator) / Decimal(value.denominator)
+        places = max(twos, fives)
+        scaled = value.numerator * 10**places // value.denominator
+        return Decimal(f"{scaled}E-{places}")

wordsnum/_spell.py

@@ -0,0 +1,89 @@
+"""Spell an integer in English words, the inverse of the parser for whole numbers."""
+
+from __future__ import annotations
+
+from ._vocab import LARGEST_SCALE, SCALE_WORDS, TENS_WORDS, UNIT_WORDS, ordinal_of
+
+
+def num_to_words(number: int, *, ordinal: bool = False, british: bool = False) -> str:
+    """Spell ``number`` in canonical English words.
+
+    The output is exactly the canonical form that ``parse(..., strict=True)`` accepts,
+    so ``words_to_num(num_to_words(n)) == n`` for every supported ``n``, and the same
+    holds with ``ordinal=True`` (the result parses as an ordinal of value ``n``).
+
+    Args:
+        number: An ``int`` whose absolute value is below 10**66 (one thousand
+            vigintillion). ``bool`` is rejected.
+        ordinal: Spell the ordinal (``"twenty-first"``) instead of the cardinal.
+        british: Insert ``"and"`` the British way, after ``"hundred"`` and before a
+            final group below one hundred (``"one thousand and five"``).
+
+    Raises:
+        TypeError: ``number`` is not an ``int``.
+        ValueError: ``number`` is out of range, or negative with ``ordinal=True``.
+
+    >>> num_to_words(1234)
+    'one thousand two hundred thirty-four'
+    >>> num_to_words(101, british=True)
+    'one hundred and one'
+    >>> num_to_words(21, ordinal=True)
+    'twenty-first'
+    """
+    if isinstance(number, bool) or not isinstance(number, int):
+        raise TypeError(f"num_to_words() needs an int, got {type(number).__name__}")
+    if abs(number) >= LARGEST_SCALE * 1000:
+        raise ValueError("num_to_words() supports absolute values below 10**66")
+    if number < 0 and ordinal:
+        raise ValueError("an ordinal cannot be negative")
+    words = _cardinal(abs(number), british=british)
+    if ordinal:
+        words = _to_ordinal(words)
+    return f"minus {words}" if number < 0 else words
+
+
+def _cardinal(number: int, *, british: bool) -> str:
+    if number == 0:
+        return "zero"
+    groups: list[int] = []
+    while number:
+        number, group = divmod(number, 1000)
+        groups.append(group)
+    parts: list[str] = []
+    for power in range(len(groups) - 1, -1, -1):
+        group = groups[power]
+        if not group:
+            continue
+        if british and power == 0 and parts and group < 100:
+            parts.append("and")
+        parts.append(_group(group, british=british))
+        if power:
+            parts.append(SCALE_WORDS[power - 1])
+    return " ".join(parts)
+
+
+def _group(number: int, *, british: bool) -> str:
+    hundreds, rest = divmod(number, 100)
+    parts: list[str] = []
+    if hundreds:
+        parts += [UNIT_WORDS[hundreds], "hundred"]
+        if rest and british:
+            parts.append("and")
+    if rest:
+        parts.append(_below_hundred(rest))
+    return " ".join(parts)
+
+
+def _below_hundred(number: int) -> str:
+    if number < 20:
+        return UNIT_WORDS[number]
+    tens, unit = divmod(number, 10)
+    word = TENS_WORDS[tens - 2]
+    return f"{word}-{UNIT_WORDS[unit]}" if unit else word
+
+
+def _to_ordinal(words: str) -> str:
+    head, space, last = words.rpartition(" ")
+    stem, hyphen, unit = last.rpartition("-")
+    last = f"{stem}{hyphen}{ordinal_of(unit)}"
+    return f"{head}{space}{last}"

wordsnum/_tokens.py

@@ -0,0 +1,155 @@
+"""Split text into number tokens with their offsets, and check what lies between them."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from fractions import Fraction
+from itertools import pairwise
+from typing import NoReturn
+
+from ._errors import MisplacedWordError, UnknownWordError, WordsNumError
+from ._vocab import ARTICLES, COMPOUND_PLURALS, ORDINALS, TENS, UNITS, VOCABULARY
+
+_TOKEN = re.compile(
+    r"(?:(?<![^\s(])-)?"  # a minus sign glued to digits at the start of a word: -5
+    r"(?:\d{1,3}(?:,\d{3})+(?:\.\d+)?"  # 2,500 or 1,234.5
+    r"|\d+(?:\.\d+)?(?:st|nd|rd|th)?)"  # 42, 3.14, 21st
+    r"|[A-Za-z]+",
+    re.IGNORECASE | re.ASCII,
+)
+_DIGITS = re.compile(r"-?[\d,]+(?:\.\d+)?", re.ASCII)
+# Longer digit runs are not numbers anyone writes, and Python refuses to convert them.
+MAX_DIGITS = 1000
+_ORDINAL_DIGITS = re.compile(r"(\d+)(st|nd|rd|th)", re.ASCII)
+_LENIENT_GAP = re.compile(r"[\s,\-]*")
+_LENIENT_EDGE = re.compile(r"\s*")
+
+
+@dataclass(frozen=True)
+class Token:
+    """One word or digit group: lowercased ``word``, the ``raw`` text and its offsets."""
+
+    word: str
+    raw: str
+    start: int
+    end: int
+    hyphen_before: bool
+
+    @property
+    def number(self) -> Fraction | None:
+        """The value of a plain digit token such as ``2,500`` or ``1.5``, else ``None``."""
+        if len(self.word) > MAX_DIGITS or _DIGITS.fullmatch(self.word) is None:
+            return None
+        return Fraction(self.word.replace(",", ""))
+
+    @property
+    def digit_ordinal(self) -> int | None:
+        """The value of a digit ordinal with the right suffix (``21st``), else ``None``."""
+        match = _ORDINAL_DIGITS.fullmatch(self.word)
+        if match is None or len(self.word) > MAX_DIGITS:
+            return None
+        value = int(match.group(1))
+        return value if match.group(2) == _suffix(value) else None
+
+    @property
+    def known(self) -> bool:
+        """Whether this token can be part of a number."""
+        if self.word in VOCABULARY:
+            return True
+        return self.number is not None or self.digit_ordinal is not None
+
+
+def _suffix(value: int) -> str:
+    if value % 100 in (11, 12, 13):
+        return "th"
+    return {1: "st", 2: "nd", 3: "rd"}.get(value % 10, "th")
+
+
+def scan(text: str) -> list[Token]:
+    """Find every candidate token in ``text`` without validating anything."""
+    tokens: list[Token] = []
+    previous_end = 0
+    for match in _TOKEN.finditer(text):
+        gap = text[previous_end : match.start()]
+        raw = match.group()
+        tokens.append(Token(raw.lower(), raw, match.start(), match.end(), "-" in gap))
+        previous_end = match.end()
+    return tokens
+
+
+def gap_ok(text: str, left: Token, right: Token) -> bool:
+    """Whether the text between two tokens is a lenient separator."""
+    return _LENIENT_GAP.fullmatch(text, left.end, right.start) is not None
+
+
+def tokenize(text: str, *, strict: bool) -> list[Token]:
+    """Tokenize a whole string that must contain one number and nothing else."""
+    tokens = scan(text)
+    if not tokens:
+        stray = text.strip()
+        if stray:
+            start = text.index(stray[0])
+            raise UnknownWordError(
+                f"unexpected text: {stray!r}", word=stray, start=start, end=len(text.rstrip())
+            )
+        raise WordsNumError("no number words found in the input")
+    for token in tokens:
+        if not token.known:
+            raise UnknownWordError(
+                f"unexpected word: {token.raw!r} at position {token.start}",
+                word=token.raw,
+                start=token.start,
+                end=token.end,
+            )
+    _check_edges(text, tokens, strict=strict)
+    for left, right in pairwise(tokens):
+        _check_gap(text, left, right, strict=strict)
+    if strict:
+        for token, following in zip(tokens, [*tokens[1:], None], strict=True):
+            if token.raw != token.word:
+                _misplaced(token, "strict mode needs lowercase words")
+            if token.word in ARTICLES and following is not None:
+                article = "an" if following.word[0] in "aeiou" else "a"
+                if token.word != article:
+                    _misplaced(token, f"strict mode needs {article!r} before {following.raw!r}")
+    return tokens
+
+
+def _check_edges(text: str, tokens: list[Token], *, strict: bool) -> None:
+    head, tail = text[: tokens[0].start], text[tokens[-1].end :]
+    for edge, start in ((head, 0), (tail, tokens[-1].end)):
+        if edge and (strict or _LENIENT_EDGE.fullmatch(edge) is None):
+            _stray(edge, start)
+
+
+def _check_gap(text: str, left: Token, right: Token, *, strict: bool) -> None:
+    gap = text[left.end : right.start]
+    if not strict:
+        if _LENIENT_GAP.fullmatch(gap) is None:
+            _stray(gap, left.end)
+        return
+    if left.word in TENS and right.word in COMPOUND_PLURALS and gap in (" ", "-"):
+        return  # "twenty ninths" is 20/9 and "twenty-ninths" is a plural 1/29: both valid
+    joins_tens = left.word in TENS and 1 <= UNITS.get(ORDINALS.get(right.word, right.word), 0) <= 9
+    if gap == ("-" if joins_tens else " "):
+        return
+    expected = "a hyphen" if joins_tens else "a single space"
+    _misplaced(right, f"strict mode needs {expected} before {right.raw!r}")
+
+
+def _stray(gap: str, offset: int) -> NoReturn:
+    stripped = gap.strip() or gap
+    start = offset + gap.index(stripped)
+    raise UnknownWordError(
+        f"unexpected text: {stripped!r} at position {start}",
+        word=stripped,
+        start=start,
+        end=start + len(stripped),
+    )
+
+
+def _misplaced(token: Token, reason: str) -> NoReturn:
+    raise MisplacedWordError(
+        f"{reason} (at position {token.start})", word=token.raw, start=token.start, end=token.end
+    )

wordsnum/_vocab.py

@@ -0,0 +1,126 @@
+"""Vocabulary tables mapping English number words to their numeric values."""
+
+from __future__ import annotations
+
+UNIT_WORDS: tuple[str, ...] = (
+    "zero",
+    "one",
+    "two",
+    "three",
+    "four",
+    "five",
+    "six",
+    "seven",
+    "eight",
+    "nine",
+    "ten",
+    "eleven",
+    "twelve",
+    "thirteen",
+    "fourteen",
+    "fifteen",
+    "sixteen",
+    "seventeen",
+    "eighteen",
+    "nineteen",
+)
+TENS_WORDS: tuple[str, ...] = (
+    "twenty",
+    "thirty",
+    "forty",
+    "fifty",
+    "sixty",
+    "seventy",
+    "eighty",
+    "ninety",
+)
+# Short scale, one entry per power of a thousand: thousand = 10**3 ... vigintillion = 10**63.
+SCALE_WORDS: tuple[str, ...] = (
+    "thousand",
+    "million",
+    "billion",
+    "trillion",
+    "quadrillion",
+    "quintillion",
+    "sextillion",
+    "septillion",
+    "octillion",
+    "nonillion",
+    "decillion",
+    "undecillion",
+    "duodecillion",
+    "tredecillion",
+    "quattuordecillion",
+    "quindecillion",
+    "sexdecillion",
+    "septendecillion",
+    "octodecillion",
+    "novemdecillion",
+    "vigintillion",
+)
+
+UNITS: dict[str, int] = {word: value for value, word in enumerate(UNIT_WORDS)}
+TENS: dict[str, int] = {word: 20 + 10 * index for index, word in enumerate(TENS_WORDS)}
+SCALES: dict[str, int] = {word: 1000 ** (index + 1) for index, word in enumerate(SCALE_WORDS)}
+HUNDRED = "hundred"
+LARGEST_SCALE: int = 1000 ** len(SCALE_WORDS)
+
+_IRREGULAR_ORDINALS: dict[str, str] = {
+    "one": "first",
+    "two": "second",
+    "three": "third",
+    "five": "fifth",
+    "eight": "eighth",
+    "nine": "ninth",
+    "twelve": "twelfth",
+}
+
+
+def ordinal_of(word: str) -> str:
+    """Return the ordinal form of one cardinal word ("twenty" -> "twentieth")."""
+    if word in _IRREGULAR_ORDINALS:
+        return _IRREGULAR_ORDINALS[word]
+    if word.endswith("y"):
+        return word[:-1] + "ieth"
+    return word + "th"
+
+
+_CARDINAL_WORDS: tuple[str, ...] = (*UNIT_WORDS, *TENS_WORDS, HUNDRED, *SCALE_WORDS)
+# Ordinal word -> the cardinal word it stands for ("first" -> "one").
+ORDINALS: dict[str, str] = {ordinal_of(word): word for word in _CARDINAL_WORDS}
+
+# Words that name a denominator when plural ("thirds") or after "a"/"one" ("a third").
+# "first" and "second" only do so inside a hyphenated compound ("thirty-seconds").
+_NOT_DENOMINATORS = frozenset({"zeroth", "first", "second"})
+DENOMINATORS: dict[str, int] = {"half": 2, "quarter": 4}
+for _ordinal, _cardinal in ORDINALS.items():
+    if _ordinal not in _NOT_DENOMINATORS:
+        _value = UNITS.get(_cardinal) or TENS.get(_cardinal) or SCALES.get(_cardinal, 100)
+        DENOMINATORS[_ordinal] = _value
+PLURAL_DENOMINATORS: dict[str, str] = {word + "s": word for word in DENOMINATORS if word != "half"}
+PLURAL_DENOMINATORS["halves"] = "half"
+# Plural ordinal units usable only after a hyphenated tens word ("twenty-firsts").
+COMPOUND_PLURALS: dict[str, str] = {
+    ordinal_of(word) + "s": ordinal_of(word) for word in UNIT_WORDS[1:10]
+}
+
+ARTICLES: frozenset[str] = frozenset({"a", "an"})
+AND = "and"
+POINT = "point"
+SIGNS: frozenset[str] = frozenset({"minus", "negative"})
+POINT_DIGITS: dict[str, int] = {**{word: UNITS[word] for word in UNIT_WORDS[:10]}, "oh": 0}
+
+VOCABULARY: frozenset[str] = frozenset(
+    {
+        *_CARDINAL_WORDS,
+        *ORDINALS,
+        *DENOMINATORS,
+        *PLURAL_DENOMINATORS,
+        *COMPOUND_PLURALS,
+        *ARTICLES,
+        AND,
+        POINT,
+        *SIGNS,
+        "oh",
+    }
+)

wordsnum-0.2.0.dist-info/METADATA

@@ -0,0 +1,153 @@
+Metadata-Version: 2.5
+Name: wordsnum
+Version: 0.2.0
+Summary: Parse spelled-out English numbers into int or float, fully typed and dependency-free
+Project-URL: Homepage, https://lianes8studio.com
+Project-URL: Repository, https://github.com/JaviLianes8/wordsnum
+Project-URL: Issues, https://github.com/JaviLianes8/wordsnum/issues
+Project-URL: Changelog, https://github.com/JaviLianes8/wordsnum/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
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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
+
+# wordsnum
+
+Parse spelled-out English numbers into int or float, fully typed and dependency-free.
+
+## Install
+
+```
+pip install wordsnum
+```
+
+## Usage
+
+```python
+from wordsnum import words_to_num
+
+words_to_num("two hundred fifty")  # 250
+words_to_num("two thousand and twenty-one")  # 2021
+words_to_num("nineteen hundred eighty four")  # 1984
+words_to_num("a hundred")  # 100
+words_to_num("minus forty two")  # -42
+words_to_num("twenty-first")  # 21 (ordinals)
+words_to_num("three point one four")  # 3.14
+words_to_num("two point five million")  # 2500000.0
+words_to_num("two and three quarters")  # 2.75
+words_to_num("3 million")  # 3000000
+words_to_num("one decillion")  # 10**33
+```
+
+Cardinals and ordinals come back as `int`; decimals and fractions as `float`.
+
+### Exact values, kinds and spans
+
+```python
+from wordsnum import parse, words_to_decimal, words_to_fraction
+
+words_to_fraction("two thirds")  # Fraction(2, 3)
+words_to_decimal("one point one")  # Decimal('1.1')
+
+result = parse("  Seven Hundredths ")
+result.value  # Fraction(7, 100)
+result.kind  # 'fraction'  (also 'cardinal', 'ordinal', 'decimal')
+result.text, result.start, result.end  # ('Seven Hundredths', 2, 18)
+```
+
+### Numbers inside text
+
+```python
+from wordsnum import find_numbers
+
+for match in find_numbers("We sold twenty-one boxes, then 3 million more."):
+    print(match.start, match.end, match.number, match.text)
+# 8 18 21 twenty-one
+# 31 40 3000000 3 million
+```
+
+### Spelling integers
+
+```python
+from wordsnum import num_to_words
+
+num_to_words(1234)  # 'one thousand two hundred thirty-four'
+num_to_words(1005, british=True)  # 'one thousand and five'
+num_to_words(21, ordinal=True)  # 'twenty-first'
+```
+
+`num_to_words` writes exactly the canonical form that strict parsing accepts, so the
+two directions round-trip.
+
+### Strict and lenient
+
+By default case, extra spaces, hyphens and commas are tolerated. `strict=True` accepts
+only the canonical spelling (lowercase, single spaces, `twenty-one` hyphenated, no
+commas). Neither mode guesses typos: `"fourty"` is always an error.
+
+### Errors that point at the problem
+
+```python
+from wordsnum import MisplacedWordError, UnknownWordError, words_to_num
+
+try:
+    words_to_num("two hundred banana")
+except UnknownWordError as error:
+    print(error.word, error.start, error.end)  # banana 12 18
+
+try:
+    words_to_num("one thousand one million")
+except MisplacedWordError as error:
+    print(error)  # scale words must get smaller from left to right: 'million' at position 17
+```
+
+Both subclass `WordsNumError`, which subclasses `ValueError`.
+
+## Command line
+
+```
+wordsnum parse two thousand and twenty-one        # 2021
+wordsnum parse three quarters --exact             # 3/4
+echo "minus forty two" | wordsnum parse           # -42
+echo "I owe you twenty-one pounds" | wordsnum find
+wordsnum say 21 --ordinal                         # twenty-first
+```
+
+Run `wordsnum --help` for every option. Errors go to stderr with exit status 1.
+
+See [GUIDE.md](GUIDE.md) for the full grammar and the list of unsupported forms.
+
+## Why
+
+Turning words back into numbers is the reverse of spelling them out, and the existing
+options are thin. `word2number` has not seen a release since 2017, ships no type hints,
+and mishandles several common phrasings. `numerizer` is a port of a Ruby gem, is
+untyped, and returns strings rather than numbers. `text2num` is maintained but builds
+on a Rust extension, which is a heavy dependency for a small parsing job.
+
+`wordsnum` is a small, pure-Python parser with zero runtime dependencies, a `py.typed`
+marker, a clean `mypy --strict` build, a real grammar that rejects malformed input
+instead of summing words, and exact results when you need them.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Links
+
+- Website: https://lianes8studio.com
+- GitHub: https://github.com/JaviLianes8
+- LinkedIn: https://www.linkedin.com/in/jlianes/