wordsnum 0.2.0__py3-none-any.whl

wordsnum/__init__.py

@@ -0,0 +1,31 @@
+"""Parse spelled-out English numbers into int or float, fully typed and dependency-free.
+
+Start with ``words_to_num`` for a quick ``int``/``float``, ``parse`` for the exact value
+and kind, ``find_numbers`` to pull numbers out of free text, and ``num_to_words`` to
+spell an integer back out.
+"""
+
+from __future__ import annotations
+
+from ._errors import MisplacedWordError, UnknownWordError, WordsNumError
+from ._find import find_numbers
+from ._forms import Kind
+from ._parser import parse, words_to_decimal, words_to_fraction, words_to_num
+from ._result import ParsedNumber
+from ._spell import num_to_words
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "Kind",
+    "MisplacedWordError",
+    "ParsedNumber",
+    "UnknownWordError",
+    "WordsNumError",
+    "find_numbers",
+    "num_to_words",
+    "parse",
+    "words_to_decimal",
+    "words_to_fraction",
+    "words_to_num",
+]

wordsnum/_cardinal.py

@@ -0,0 +1,162 @@
+"""Grammar for cardinal numbers: groups below a thousand joined by decreasing scales."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from fractions import Fraction
+from typing import NoReturn
+
+from ._errors import MisplacedWordError
+from ._tokens import Token
+from ._vocab import AND, ARTICLES, HUNDRED, SCALES, TENS, UNITS
+
+
+def fail(token: Token, reason: str) -> NoReturn:
+    """Raise a ``MisplacedWordError`` that points at ``token``."""
+    raise MisplacedWordError(
+        f"{reason}: {token.raw!r} at position {token.start}",
+        word=token.raw,
+        start=token.start,
+        end=token.end,
+    )
+
+
+@dataclass
+class _Reader:
+    tokens: Sequence[Token]
+    index: int = 0
+    decimal: bool = field(default=False)
+
+    def peek(self) -> Token | None:
+        return self.tokens[self.index] if self.index < len(self.tokens) else None
+
+    def word(self) -> str | None:
+        token = self.peek()
+        return None if token is None else token.word
+
+    def take(self) -> Token:
+        token = self.tokens[self.index]
+        self.index += 1
+        return token
+
+
+def parse_cardinal(tokens: Sequence[Token]) -> tuple[Fraction, bool]:
+    """Parse a whole cardinal. Returns the value and whether a decimal digit group was used.
+
+    ``tokens`` must be non-empty and must not hold a sign word.
+    """
+    if len(tokens) == 1 and tokens[0].word == "zero":
+        return Fraction(0), False
+    reader = _Reader(tokens)
+    total = Fraction(0)
+    last_scale = 0
+    while True:
+        group_token = reader.peek()
+        assert group_token is not None
+        value, wide = _group(reader, first=last_scale == 0)
+        if last_scale and value >= 1000:
+            fail(group_token, "a group after a scale word must be below a thousand")
+        scale_token = reader.peek()
+        if scale_token is None:
+            if wide and last_scale:
+                fail(group_token, "a teen or tens hundred cannot follow a scale word")
+            return total + value, reader.decimal
+        if scale_token.word not in SCALES:
+            fail(scale_token, "unexpected word")
+        scale = SCALES[scale_token.word]
+        if last_scale and scale >= last_scale:
+            fail(scale_token, "scale words must get smaller from left to right")
+        if wide:
+            fail(scale_token, "a teen or tens hundred cannot take a scale word")
+        if value == 0:
+            fail(scale_token, "a scale word needs a non-zero number before it")
+        reader.take()
+        total += value * scale
+        last_scale = scale
+        if reader.peek() is None:
+            return total, reader.decimal
+        if reader.word() == AND:
+            and_token = reader.take()
+            target = reader.peek() or and_token
+            rest = _below_hundred(reader)
+            if not rest:
+                fail(target, "'and' after a scale word needs 1 to 99")
+            if (extra := reader.peek()) is not None:
+                fail(extra, "nothing may follow the number after 'and'")
+            return total + rest, reader.decimal
+
+
+def _group(reader: _Reader, *, first: bool) -> tuple[Fraction, bool]:
+    """Read one group. Returns its value and whether it is a wide ``nineteen hundred``."""
+    token = reader.peek()
+    assert token is not None
+    if token.word in SCALES and first:
+        return Fraction(1), False
+    if token.word in ARTICLES:
+        reader.take()
+        following = reader.word()
+        if following in SCALES:
+            return Fraction(1), False
+        if following != HUNDRED:
+            fail(token, "an article must be followed by 'hundred' or a scale word")
+        return _hundreds(reader, Fraction(1)), False
+    if token.word == HUNDRED and first:
+        return _hundreds(reader, Fraction(1)), False
+    number = token.number
+    if number is not None:
+        reader.take()
+        if "." in token.word:
+            if not first:
+                fail(token, "digits with a decimal point must start the number")
+            reader.decimal = True
+            after = reader.peek()
+            if after is not None and after.word not in SCALES:
+                fail(after, "digits with a decimal point can only take a scale word")
+            return number, False
+        if reader.word() != HUNDRED:
+            return number, False
+        prefix = number
+    else:
+        below = _below_hundred(reader)
+        if below is None:
+            fail(token, "unexpected word")
+        if below == 0:
+            fail(token, "'zero' must stand alone")
+        prefix = Fraction(below)
+        if reader.word() != HUNDRED:
+            return prefix, False
+    if not 1 <= prefix <= 99:
+        fail(token, "'hundred' needs a number from 1 to 99 before it")
+    return _hundreds(reader, prefix), prefix >= 10
+
+
+def _hundreds(reader: _Reader, prefix: Fraction) -> Fraction:
+    reader.take()
+    value = prefix * 100
+    if reader.word() == AND:
+        and_token = reader.take()
+        target = reader.peek() or and_token
+        rest = _below_hundred(reader)
+        if not rest:
+            fail(target, "'and' after 'hundred' needs 1 to 99")
+        return value + rest
+    rest = _below_hundred(reader)
+    if rest == 0:
+        fail(reader.tokens[reader.index - 1], "'zero' must stand alone")
+    return value + (rest or 0)
+
+
+def _below_hundred(reader: _Reader) -> int | None:
+    word = reader.word()
+    if word in UNITS:
+        reader.take()
+        return UNITS[word]
+    if word in TENS:
+        reader.take()
+        unit = reader.word()
+        if unit in UNITS and 1 <= UNITS[unit] <= 9:
+            reader.take()
+            return TENS[word] + UNITS[unit]
+        return TENS[word]
+    return None

wordsnum/_cli.py

@@ -0,0 +1,140 @@
+"""Command line interface: ``wordsnum parse``, ``wordsnum find`` and ``wordsnum say``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+from typing import NoReturn
+
+from . import __version__
+from ._errors import WordsNumError
+from ._find import find_numbers
+from ._parser import parse
+from ._result import ParsedNumber
+from ._spell import num_to_words
+
+_EXAMPLES = """\
+examples:
+  wordsnum parse two thousand and twenty-one       -> 2021
+  wordsnum parse three quarters --exact            -> 3/4
+  wordsnum parse "1.5 million" --json
+  echo "minus forty two" | wordsnum parse          -> -42 (one number per line)
+  echo "I owe you twenty-one pounds" | wordsnum find
+  wordsnum say 1234 --british                      -> one thousand two hundred and thirty-four
+  wordsnum say 21 --ordinal                        -> twenty-first
+
+Errors go to stderr and the exit status is 1.
+"""
+
+
+class _Parser(argparse.ArgumentParser):
+    """An argument parser whose usage errors exit with status 1, like every other error."""
+
+    def error(self, message: str) -> NoReturn:
+        self.print_usage(sys.stderr)
+        self.exit(1, f"{self.prog}: error: {message}\n")
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = _Parser(
+        prog="wordsnum",
+        description="Parse spelled-out English numbers, find them in text, or spell integers.",
+        epilog=_EXAMPLES,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"wordsnum {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True, metavar="COMMAND")
+
+    parse_cmd = commands.add_parser(
+        "parse", help="parse one number (words as arguments, or one per stdin line)"
+    )
+    parse_cmd.add_argument("words", nargs="*", help="the number words; read stdin when omitted")
+    parse_cmd.add_argument("--strict", action="store_true", help="accept only canonical spelling")
+    _add_output_flags(parse_cmd)
+
+    find_cmd = commands.add_parser("find", help="list every number in text read from stdin")
+    find_cmd.add_argument("--text", help="search this text instead of stdin")
+    _add_output_flags(find_cmd)
+
+    say_cmd = commands.add_parser("say", help="spell an integer in words")
+    say_cmd.add_argument("number", help="the integer to spell, such as 1234 or -7")
+    say_cmd.add_argument("--ordinal", action="store_true", help="spell the ordinal form")
+    say_cmd.add_argument("--british", action="store_true", help="use British 'and'")
+    return parser
+
+
+def _add_output_flags(command: argparse.ArgumentParser) -> None:
+    command.add_argument(
+        "--exact", action="store_true", help="print exact values (3/4, 3.14) instead of floats"
+    )
+    command.add_argument("--json", action="store_true", help="print JSON objects")
+
+
+def _value(match: ParsedNumber, *, exact: bool) -> str:
+    if not exact or match.kind in ("cardinal", "ordinal"):
+        return str(match.number)
+    if match.kind == "decimal":
+        return str(match.to_decimal())
+    return str(match.value)
+
+
+def _record(match: ParsedNumber, *, exact: bool) -> dict[str, object]:
+    return {
+        "value": match.number,
+        "exact": _value(match, exact=True),
+        "kind": match.kind,
+        "text": match.text,
+        "start": match.start,
+        "end": match.end,
+    }
+
+
+def _run_parse(args: argparse.Namespace) -> None:
+    if args.words:
+        lines = [" ".join(args.words)]
+    else:
+        lines = [line for line in sys.stdin.read().splitlines() if line.strip()]
+    if not lines:
+        raise WordsNumError("no input: pass number words or pipe them on stdin")
+    for line in lines:
+        match = parse(line, strict=args.strict)
+        if args.json:
+            print(json.dumps(_record(match, exact=args.exact)))
+        else:
+            print(_value(match, exact=args.exact))
+
+
+def _run_find(args: argparse.Namespace) -> None:
+    text = args.text if args.text is not None else sys.stdin.read()
+    matches = find_numbers(text)
+    if args.json:
+        print(json.dumps([_record(match, exact=args.exact) for match in matches]))
+        return
+    for match in matches:
+        print(f"{match.start}\t{match.end}\t{_value(match, exact=args.exact)}\t{match.text}")
+
+
+def _run_say(args: argparse.Namespace) -> None:
+    try:
+        number = int(args.number.replace(",", "").replace("_", ""))
+    except ValueError:
+        raise ValueError(f"not an integer: {args.number!r}") from None
+    print(num_to_words(number, ordinal=args.ordinal, british=args.british))
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the command line tool and return its exit status (0 on success, 1 on error)."""
+    args = _build_parser().parse_args(argv)
+    handlers = {"parse": _run_parse, "find": _run_find, "say": _run_say}
+    try:
+        handlers[args.command](args)
+    except (ValueError, TypeError) as error:
+        print(f"wordsnum: error: {error}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

wordsnum/_errors.py

@@ -0,0 +1,42 @@
+"""Exceptions raised when text is not a valid spelled-out number."""
+
+from __future__ import annotations
+
+
+class WordsNumError(ValueError):
+    """Raised when the text is not a valid spelled-out number.
+
+    It subclasses ``ValueError``, so ``except ValueError`` keeps working. When the
+    problem can be pinned to one word, ``word`` holds that word as written and
+    ``start``/``end`` are its offsets in the original text, so that
+    ``text[error.start:error.end] == error.word``. Otherwise all three are ``None``
+    (for example on empty input).
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        word: str | None = None,
+        start: int | None = None,
+        end: int | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.word = word
+        self.start = start
+        self.end = end
+
+
+class UnknownWordError(WordsNumError):
+    """Raised for a word that is not an English number word at all, such as ``"banana"``.
+
+    Misspellings are never guessed: ``"fourty"`` raises this error too.
+    """
+
+
+class MisplacedWordError(WordsNumError):
+    """Raised for a number word in a position the grammar does not allow.
+
+    Examples: ``"one two"``, ``"thousand million"``, ``"minus"`` with nothing after it,
+    or ``"one thirds"`` (a numerator of one takes a singular denominator).
+    """

wordsnum/_find.py

@@ -0,0 +1,108 @@
+"""Find every spelled-out number inside free text."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from ._errors import WordsNumError
+from ._forms import parse_tokens
+from ._result import ParsedNumber
+from ._tokens import Token, gap_ok, scan
+from ._vocab import COMPOUND_PLURALS, DENOMINATORS, ORDINALS, PLURAL_DENOMINATORS
+
+# No real number phrase is longer than this; the cap bounds the work on hostile input.
+_MAX_TOKENS = 160
+
+
+def find_numbers(text: str) -> list[ParsedNumber]:
+    """Return every number written in ``text``, in order, as ``ParsedNumber`` objects.
+
+    Number words, digit groups (``"3"``, ``"2,500"``, ``"1.5"``, ``"21st"``) and their
+    mixtures (``"3 million"``) are recognised, case-insensitively, when they are
+    separated only by whitespace, hyphens or commas. Each match is the longest valid
+    reading starting at its first word, so ``"one, two, three"`` gives three numbers
+    while ``"one thousand, two hundred"`` gives one. ``start`` and ``end`` are offsets
+    into ``text``.
+
+    Everyday words that are also numbers are reported too: ``"no one"`` yields 1 and
+    ``"just a second"`` yields the ordinal 2. Filter on ``kind`` or context if needed.
+
+    >>> [match.number for match in find_numbers("I paid twenty-one pounds for 3 pies")]
+    [21, 3]
+    """
+    found: list[ParsedNumber] = []
+    for run in _runs(text, scan(text)):
+        found.extend(_matches(text, run))
+    return found
+
+
+def _runs(text: str, tokens: Sequence[Token]) -> list[list[Token]]:
+    """Group known tokens that are separated only by lenient separators."""
+    runs: list[list[Token]] = []
+    current: list[Token] = []
+    for token in tokens:
+        if not token.known:
+            if current:
+                runs.append(current)
+            current = []
+            continue
+        if current and not gap_ok(text, current[-1], token):
+            runs.append(current)
+            current = []
+        current.append(token)
+    if current:
+        runs.append(current)
+    return runs
+
+
+def _matches(text: str, run: Sequence[Token]) -> list[ParsedNumber]:
+    found: list[ParsedNumber] = []
+    start = 0
+    while start < len(run):
+        end = _window_end(run, start)
+        while end > start:
+            try:
+                value, kind = parse_tokens(run[start:end])
+            except WordsNumError as error:
+                end = _shorter(run, start, end, error)
+                continue
+            first, last = run[start], run[end - 1]
+            found.append(
+                ParsedNumber(value, kind, text[first.start : last.end], first.start, last.end)
+            )
+            break
+        start = max(end, start + 1)
+    return found
+
+
+def _shorter(run: Sequence[Token], start: int, end: int, error: WordsNumError) -> int:
+    """Pick the next, shorter candidate end after a failed parse.
+
+    Words after the offending one are dropped at once. The offending word itself is
+    kept for one more try, because as the last word it may read differently.
+    """
+    for index in range(start, end - 1):
+        if run[index].start == error.start:
+            return index + 1
+    return end - 1
+
+
+def _window_end(run: Sequence[Token], start: int) -> int:
+    """The furthest candidate end from ``start``.
+
+    Ordinals, denominators and digit ordinals can only be the last word of a number,
+    so a candidate never extends past the first of them. This keeps the scan linear
+    even on long runs of such words.
+    """
+    limit = min(len(run), start + _MAX_TOKENS)
+    for index in range(start, limit):
+        if _decides_form(run[index]):
+            return index + 1
+    return limit
+
+
+def _decides_form(token: Token) -> bool:
+    word = token.word
+    if word in ORDINALS or word in DENOMINATORS or word in PLURAL_DENOMINATORS:
+        return True
+    return word in COMPOUND_PLURALS or token.digit_ordinal is not None

wordsnum/_forms.py

@@ -0,0 +1,181 @@
+"""Top-level number forms: signs, decimals, fractions, ordinals and plain cardinals."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import replace
+from fractions import Fraction
+from typing import Literal
+
+from ._cardinal import fail, parse_cardinal
+from ._errors import WordsNumError
+from ._tokens import Token
+from ._vocab import (
+    AND,
+    ARTICLES,
+    COMPOUND_PLURALS,
+    DENOMINATORS,
+    HUNDRED,
+    ORDINALS,
+    PLURAL_DENOMINATORS,
+    POINT,
+    POINT_DIGITS,
+    SCALES,
+    SIGNS,
+    TENS,
+    UNITS,
+)
+
+Kind = Literal["cardinal", "ordinal", "decimal", "fraction"]
+_SCALE_ORDINALS = frozenset(word for word, base in ORDINALS.items() if base in SCALES)
+_SCALE_ORDINALS |= {"hundredth"}
+
+
+def parse_tokens(tokens: Sequence[Token]) -> tuple[Fraction, Kind]:
+    """Parse one complete number from a non-empty token list."""
+    sign = 1
+    if tokens[0].word.startswith("-"):
+        first = tokens[0]
+        unsigned = replace(first, word=first.word[1:], raw=first.raw[1:], start=first.start + 1)
+        sign, tokens = -1, [unsigned, *tokens[1:]]
+    elif tokens[0].word in SIGNS:
+        if len(tokens) == 1:
+            fail(tokens[0], "a sign word needs a number after it")
+        sign, tokens = -1, tokens[1:]
+    for token in tokens:
+        if token.word in SIGNS or token.word.startswith("-"):
+            fail(token, "a sign can only come first")
+    value, kind = _unsigned(tokens)
+    if sign < 0 and kind == "ordinal":
+        fail(tokens[0], "an ordinal cannot be negative")
+    return sign * value, kind
+
+
+def _unsigned(tokens: Sequence[Token]) -> tuple[Fraction, Kind]:
+    if any(token.word == POINT for token in tokens):
+        return _decimal(tokens), "decimal"
+    last = tokens[-1]
+    if last.digit_ordinal is not None:
+        if len(tokens) > 1:
+            fail(last, "a digit ordinal must stand alone")
+        return Fraction(last.digit_ordinal), "ordinal"
+    fraction = _fraction(tokens)
+    if fraction is not None:
+        return fraction, "fraction"
+    if last.word in ORDINALS:
+        cardinal = replace(last, word=ORDINALS[last.word])
+        value, decimal = parse_cardinal([*tokens[:-1], cardinal])
+        if decimal:
+            fail(last, "an ordinal cannot have a decimal part")
+        return value, "ordinal"
+    value, decimal = parse_cardinal(tokens)
+    return value, "decimal" if decimal else "cardinal"
+
+
+def _decimal(tokens: Sequence[Token]) -> Fraction:
+    point = next(index for index, token in enumerate(tokens) if token.word == POINT)
+    whole_tokens, rest = tokens[:point], tokens[point + 1 :]
+    digits = ""
+    while len(digits) < len(rest) and rest[len(digits)].word in POINT_DIGITS:
+        digits += str(POINT_DIGITS[rest[len(digits)].word])
+    if not digits:
+        fail(rest[0] if rest else tokens[point], "expected a digit word after 'point'")
+    tail = rest[len(digits) :]
+    scale = 1
+    if tail:
+        scale_word = tail[0].word
+        if scale_word not in SCALES and scale_word != HUNDRED:
+            fail(tail[0], "only one-digit words or a final scale word may follow 'point'")
+        if len(tail) > 1:
+            fail(tail[1], "nothing may follow the scale word of a decimal")
+        scale = SCALES.get(scale_word, 100)
+    whole = Fraction(0)
+    if whole_tokens:
+        whole, decimal = parse_cardinal(whole_tokens)
+        if decimal:
+            fail(tokens[point], "digits with a decimal point cannot be followed by 'point'")
+        if tail and whole >= 1000:
+            fail(tail[0], "a decimal with a scale word needs a whole part below a thousand")
+    return (whole + Fraction(int(digits), 10 ** len(digits))) * scale
+
+
+def _fraction(tokens: Sequence[Token]) -> Fraction | None:
+    """Parse ``tokens`` as a fraction, or return ``None`` when they do not end in one."""
+    found = _denominator(tokens)
+    if found is None:
+        return None
+    numerator_tokens, denominator, plural = found
+    last = tokens[-1]
+    if not numerator_tokens:
+        fail(last, "a fraction needs a numerator before its denominator")
+    and_at = [index for index, token in enumerate(numerator_tokens) if token.word == AND]
+    if and_at and and_at[-1] > 0:
+        whole_tokens, part_tokens = (
+            numerator_tokens[: and_at[-1]],
+            numerator_tokens[and_at[-1] + 1 :],
+        )
+        try:
+            whole = _whole(whole_tokens)
+            part = _numerator(part_tokens, last, plural)
+        except WordsNumError:
+            pass
+        else:
+            if part < denominator:
+                return whole + Fraction(part, denominator)
+    return Fraction(_numerator(numerator_tokens, last, plural), denominator)
+
+
+def _denominator(tokens: Sequence[Token]) -> tuple[Sequence[Token], int, bool] | None:
+    """Split off a denominator. Returns numerator tokens, denominator and plurality."""
+    last, word = tokens[-1], tokens[-1].word
+    before = tokens[-2].word if len(tokens) > 1 else None
+    if last.hyphen_before and before in TENS:
+        unit = COMPOUND_PLURALS.get(word, word)
+        if unit in ORDINALS and 1 <= UNITS.get(ORDINALS[unit], 0) <= 9:
+            value = TENS[before] + UNITS[ORDINALS[unit]]
+            plural = word in COMPOUND_PLURALS
+            numerator = tokens[:-2]
+            if plural or _single_one(numerator, allow_one=True):
+                return numerator, value, plural
+            return None
+    if word in PLURAL_DENOMINATORS:
+        return tokens[:-1], DENOMINATORS[PLURAL_DENOMINATORS[word]], True
+    if word in ("half", "quarter"):
+        return tokens[:-1], DENOMINATORS[word], False
+    if word in DENOMINATORS and _single_one(tokens[:-1], allow_one=word not in _SCALE_ORDINALS):
+        return tokens[:-1], DENOMINATORS[word], False
+    return None
+
+
+def _single_one(numerator: Sequence[Token], *, allow_one: bool) -> bool:
+    """Whether the numerator ends in "a"/"an" (or "one") as a whole or after "and"."""
+    if not numerator:
+        return False
+    if len(numerator) > 1 and numerator[-2].word != AND:
+        return False
+    last = numerator[-1].word
+    return last in ARTICLES or (allow_one and last == "one")
+
+
+def _whole(tokens: Sequence[Token]) -> int:
+    value, decimal = parse_cardinal(tokens)
+    if decimal:
+        fail(tokens[-1], "the whole part of a mixed number must be an integer")
+    return int(value)
+
+
+def _numerator(tokens: Sequence[Token], denominator: Token, plural: bool) -> int:
+    if not tokens:
+        fail(denominator, "a fraction needs a numerator before its denominator")
+    if len(tokens) == 1 and tokens[0].word in ARTICLES:
+        value = 1
+    else:
+        number, decimal = parse_cardinal(tokens)
+        if decimal or number.denominator != 1:
+            fail(tokens[-1], "a numerator must be a whole number")
+        value = int(number)
+    if value == 1 and plural:
+        fail(denominator, "a numerator of one takes a singular denominator")
+    if value != 1 and not plural:
+        fail(denominator, "a numerator other than one takes a plural denominator")
+    return value