refactor: thin num2words2 Python binder — move all logic to Rust (#127)

num2words2/ is now a pure thin binder like words2num2/: every public function is
a `return _RUST.x(...)` pass-through, with no conversion/dispatch/presentation
logic left in Python.

Moved into num2words2-core (new pyo3-free `presentation.rs`, so the crate still
publishes standalone) + the num2words2-py binder:
- `_normalize_lang` -> `presentation::resolve_lang` (locale resolution).
- `_apply_style` -> `presentation::apply_style` (style=terse/us output post-processing).
- `_normalize_cents` -> `presentation::normalize_cents` (cents kwarg handling).
- `_rust_kw_items` kwarg marshalling -> the binder (`extras_to_kwargs`).
- the whole `num2words`/`num2words_sentence` dispatch pipeline -> `#[pyfunction]`s
  (type inspection + raw-lang resolve + style, sharing the core converters).
- grouping.py: drop the pure-Python western/indian/chinese fallback; it's now a
  pass-through to `_RUST.group_digits` (which raises the same ValueError/TypeError).

__init__.py 300 -> 77 lines. num2words2-core 0.1.0 -> 0.1.1 (published).

Verified: cargo test 579; unittest OK (2780, 33 expected-failures, exit 0);
E2E 16/16; coverage source 84% / tests 98%; flake8 0; isort clean. Output parity
preserved (style/cents/lang-resolve produce identical results).

Author: jqueguiner

num2words2/__init__.py

@@ -16,18 +16,16 @@
 # MA 02110-1301 USA
 """num2words2 — a thin Python binder over the Rust conversion core.
 
-Every conversion is served by the compiled `_rust` extension: this module
-normalises the language code, maps the public keyword arguments onto the
-core's entry points, and applies the two string-level post-processing steps
-(`style=`, `cents=`) that are presentation, not conversion. There is no
-pure-Python conversion fallback — the core is authoritative, and an input it
-declines raises rather than silently diverging.
+Every conversion, and every piece of presentation logic that used to live
+here (language-code resolution, the ``style=`` post-processing, the ``cents=``
+mode mapping and the whole type dispatch), is now served by the compiled
+``_rust`` extension. This module is a pass-through: it re-exports the public
+entry points and the exception types, nothing more.
 """
 from __future__ import unicode_literals
 
-import decimal
-
-from .grouping import group_digits  # noqa: E402
+from . import _rust as _RUST
+from .grouping import group_digits  # noqa: F401  (re-exported)
 
 # Version information
 try:
@@ -37,21 +35,11 @@
     __version__ = "unknown"
     __version_tuple__ = (0, 0, 0, "unknown", 0)
 
-
-# The compiled core is mandatory: this package is a binder over it.
-from . import _rust as _RUST  # noqa: E402
-
-_RUST_LANGS = frozenset(_RUST.supported_langs())
-_RUST_TYPES = frozenset(["cardinal", "ordinal", "ordinal_num", "year"])
-# The core's "declined" signal (see rust/num2words2-py/src/lib.rs). It is
-# distinct from NotImplementedError so a genuine NotImplementedError raise
-# propagates natively; here, with no Python conversion path behind it, a
-# decline is surfaced as NotImplementedError to the caller.
-_RUST_FALLBACK = _RUST.RustFallback
-
-# bn raises NumberTooLargeError past its MAX_NUMBER. The class used to live in
-# lang_BN.py; the pure binder defines it in the core and re-exports it here so
-# `from num2words2 import NumberTooLargeError` (and `except`) keep working.
+# Exception types defined in the compiled core and re-exported so
+# ``from num2words2 import NumberTooLargeError`` (and ``except`` on it) keep
+# working. RustFallback is the core's "declined" signal, kept importable for
+# the same reason.
+RustFallback = _RUST.RustFallback
 NumberTooLargeError = _RUST.NumberTooLargeError
 
 
@@ -72,226 +60,16 @@
 CONVERTER_TYPES = CONVERTES_TYPES  # Alias for compatibility
 
 
-def maxval(lang="en"):
-    """Return the maximum integer ``num2words(..., lang=lang)`` can convert.
-
-    Issue #582 ports savoirfairelinux/num2words#582.
-    """
-    return _RUST.maxval(lang)
-
-
-def _normalize_lang(lang):
-    """Resolve a caller's language code to a core key, mirroring the historic
-    dispatcher: exact match, then hyphen->underscore, then ``xx_YY`` casing,
-    then the bare two-letter prefix. Raises NotImplementedError if none match.
-    """
-    if lang in _RUST_LANGS:
-        return lang
-    nl = lang.replace("-", "_")
-    if nl in _RUST_LANGS:
-        return nl
-    parts = nl.split("_")
-    if len(parts) >= 2:
-        candidate = "%s_%s" % (parts[0].lower(), parts[1].upper())
-        if candidate in _RUST_LANGS:
-            return candidate
-        if parts[0] in _RUST_LANGS:
-            return parts[0]
-    if nl[:2] in _RUST_LANGS:
-        return nl[:2]
-    raise NotImplementedError()
-
-
-def _rust_kw_items(kwargs):
-    """kwargs -> [(k, v)] for the core boundary, or None when a value has a
-    type the boundary cannot carry (then the call is out of the core's
-    envelope and must raise)."""
-    items = []
-    for k, v in kwargs.items():
-        if v is None or isinstance(v, (bool, int, str)):
-            items.append((k, v))
-        elif isinstance(v, (list, tuple)) and all(
-                isinstance(x, str) for x in v):
-            items.append((k, list(v)))
-        else:
-            return None
-    return items
-
-
-def _apply_style(result, style, to, lang):
-    """`style=` presentation post-processing (issues #535, #562). Operates on
-    the rendered string, so it is conversion-independent."""
-    if style == "terse" and to == "ordinal" and isinstance(result, str):
-        for prefix in ("one ", "un ", "uno "):
-            if result.startswith(prefix) and len(result) > len(prefix):
-                result = result[len(prefix):]
-                break
-    if style == "us" and lang.startswith("en") and isinstance(result, str):
-        result = result.replace(" and ", " ")
-    return result
-
-
-def _normalize_cents(kwargs):
-    """`cents='omit'|'verbose'|'terse'` -> the legacy bool the core expects
-    (issue #554). Returns (cents_bool, drop_cents) where drop_cents means the
-    float value should be truncated to an int so no cents segment appears."""
-    cents_kw = kwargs.get("cents", True)
-    if cents_kw == "omit":
-        return True, True
-    if cents_kw == "verbose":
-        return True, False
-    if cents_kw == "terse":
-        return False, False
-    return cents_kw, False
-
-
 def num2words(number, ordinal=False, lang="en", to="cardinal", **kwargs):
-    # Captured before any normalisation: the core keys off the *arrival* type
-    # (a plain int vs a float/Decimal vs a str), not a post-parse value.
-    _plain_int = type(number) is int
-    _plain_num = isinstance(number, (float, decimal.Decimal))
-
-    lang = _normalize_lang(lang)
-    _style = kwargs.get("style")
-
-    # ---- string input: the core's from_string owns the whole pipeline
-    # (fraction strings, str_to_number incl. the ES "1ro" / pt_BR "ponto"
-    # handshakes, mixed text -> sentence, then the mode dispatch).
-    if isinstance(number, str):
-        _to_final = "ordinal" if ordinal else to
-        if _to_final not in CONVERTES_TYPES:
-            raise NotImplementedError()
-        _cents, _ = _normalize_cents(kwargs)
-        _extras = {k: v for k, v in kwargs.items()
-                   if k not in ("currency", "cents", "separator",
-                                "adjective", "style", "precision")}
-        _items = _rust_kw_items(_extras)
-        if _cents not in (True, False) or _items is None:
-            raise NotImplementedError()
-        try:
-            _kind, _out = _RUST.from_string(
-                lang, number, _to_final, kwargs.get("currency"), _cents,
-                kwargs.get("separator"), kwargs.get("adjective"), _items)
-        except _RUST_FALLBACK:
-            raise NotImplementedError()
-        if _kind != 0:
-            raise NotImplementedError()
-        return _apply_style(_out, _style, _to_final, lang)
-
-    # backwards compatible
-    if ordinal:
-        to = "ordinal"
-    if to not in CONVERTES_TYPES:
-        raise NotImplementedError()
-
-    _precision = kwargs.get("precision")
-    _extras = {k: v for k, v in kwargs.items()
-               if k not in ("style", "precision")}
-
-    # ---- integer modes with a plain int
-    if _plain_int and to in _RUST_TYPES:
-        _items = _rust_kw_items(_extras)
-        if _items is not None:
-            try:
-                if _items:
-                    result = getattr(_RUST, "to_%s_kw" % to)(
-                        lang, number, _items)
-                else:
-                    result = getattr(_RUST, "to_%s" % to)(lang, number)
-            except _RUST_FALLBACK:
-                raise NotImplementedError()
-            return _apply_style(result, _style, to, lang)
-
-    # ---- float / Decimal, all four integer modes
-    if _plain_num and to in _RUST_TYPES:
-        try:
-            _finite = float(number) == float(number) and float(
-                number) not in (float("inf"), float("-inf"))
-        except (OverflowError, ValueError):
-            _finite = False
-        _fitems = {k: v for k, v in _extras.items()
-                   if k not in ("currency", "cents", "separator", "adjective")}
-        _items = _rust_kw_items(_fitems)
-        if _finite and _items is not None:
-            _prec = abs(decimal.Decimal(str(number)).as_tuple().exponent)
-            _dec = str(number) if isinstance(number, decimal.Decimal) else ""
-            try:
-                result = _RUST.to_float(
-                    lang, to, float(number), _prec, _dec, str(number),
-                    _precision, _items)
-            except _RUST_FALLBACK:
-                raise NotImplementedError()
-            return _apply_style(result, _style, to, lang)
-
-    # ---- currency
-    if to == "currency" and isinstance(number, (int, float, decimal.Decimal)):
-        _cents, _drop = _normalize_cents(kwargs)
-        if _drop and isinstance(number, float):
-            number = int(number)  # int path drops cents naturally
-        if _cents in (True, False):
-            _citems = {k: v for k, v in _extras.items()
-                       if k not in ("currency", "cents", "separator",
-                                    "adjective")}
-            _items = _rust_kw_items(_citems)
-            if _items is not None:
-                _args = (
-                    lang, str(number), type(number) is int,
-                    isinstance(number, float) or "." in str(number),
-                    isinstance(number, float),
-                    kwargs.get("currency"), _cents,
-                    kwargs.get("separator"), kwargs.get("adjective"),
-                )
-                try:
-                    if _items:
-                        return _RUST.to_currency_kw(*_args, _items)
-                    return _RUST.to_currency(*_args)
-                except _RUST_FALLBACK:
-                    raise NotImplementedError()
-
-    if to == "cheque" and isinstance(number, (int, float, decimal.Decimal)):
-        try:
-            return _RUST.to_cheque(lang, str(number), kwargs.get("currency"))
-        except _RUST_FALLBACK:
-            raise NotImplementedError()
-
-    # to='fraction' with a non-string number: the historic dispatcher fed the
-    # value straight to converter.to_fraction(value). A single positional (the
-    # tuple ``(1, 2)``) raised TypeError where the method exists, or
-    # AttributeError where it does not (bn/dv/id have no to_fraction). Probe
-    # the core to tell them apart; genuine "n/d" fractions arrive as strings
-    # and are served by from_string above.
-    if to == "fraction":
-        try:
-            _RUST.to_fraction(lang, 1, 1)
-        except AttributeError:
-            raise
-        except Exception:  # noqa: BLE001 - probing for the method's existence
-            pass
-        raise TypeError(
-            "to_fraction() missing 1 required positional argument: "
-            "'denominator'")
-
-    raise NotImplementedError()
+    return _RUST.num2words(number, ordinal, lang, to, **kwargs)
 
 
 def num2words_sentence(sentence, lang="en", to="cardinal", **kwargs):
-    """Convert every number in a sentence to words.
+    return _RUST.num2words_sentence(sentence, lang, to, **kwargs)
 
-    `lang=None` auto-detects (lingua-rs in the full build). Handles ordinals,
-    currency, dates, temperatures and plain numbers, splicing each conversion
-    back in place.
 
-    >>> num2words_sentence("I bought 6 apples")
-    'I bought six apples'
-    >>> num2words_sentence("The 1st place winner got $100")
-    'The first place winner got one hundred dollars, zero cents'
-    """
-    if lang is None:
-        return _RUST.sentence_auto(sentence, to)
-    # The core's sentence converter does its own lang validation (and the
-    # same two-letter-prefix fallback), raising NotImplementedError for an
-    # unsupported language exactly as the historic dispatcher did.
-    return _RUST.sentence(sentence, lang, to)
+def maxval(lang="en"):
+    return _RUST.maxval(lang)
 
 
 # Aliases for num2words_sentence

num2words2/grouping.py

@@ -1,11 +1,11 @@
 # -*- coding: utf-8 -*-
 # Copyright (c) 2026, num2words2 contributors. All Rights Reserved.
 # Licensed under LGPL-2.1 (see COPYING).
-"""Number-string grouping helpers.
+"""Number-string grouping — thin binder over the Rust core.
 
 Some locales group digits in patterns other than the standard ``,###``
-Western convention.  This module exposes a single helper, :func:`group_digits`,
-that returns the locale-grouped form of an integer.
+Western convention.  :func:`group_digits` returns the locale-grouped form of an
+integer; all logic lives in the ``num2words2._rust`` extension.
 
 Currently supported groupings:
 
@@ -18,12 +18,7 @@
 
 from __future__ import unicode_literals
 
-# Independent of the package __init__ (no circular import): the extension
-# module is importable on its own. Absent -> pure-Python behaviour.
-try:
-    from . import _rust as _RUST
-except ImportError:  # pragma: no cover - depends on build
-    _RUST = None
+from . import _rust as _RUST
 
 
 def group_digits(value, locale="western", separator=","):
@@ -33,38 +28,9 @@ def group_digits(value, locale="western", separator=","):
     --------
     >>> group_digits(100000, locale="indian")
     '1,00,000'
-    >>> group_digits(12345678, locale="indian")
-    '1,23,45,678'
     >>> group_digits(1234567, locale="western")
     '1,234,567'
     >>> group_digits(12345678, locale="chinese")
     '1234,5678'
     """
-    if not isinstance(value, int):
-        raise TypeError("group_digits requires an int, got %r" % type(value))
-    # The isinstance check stays here: its TypeError message needs Python's
-    # %r of the type object. Everything after it is pure string work.
-    if _RUST is not None:
-        return _RUST.group_digits(value, locale, separator)
-    sign = "-" if value < 0 else ""
-    s = str(abs(value))
-
-    if locale == "western":
-        return sign + _group(s, 3, separator)
-    if locale == "indian":
-        # Last three digits, then groups of two on the high side.
-        if len(s) <= 3:
-            return sign + s
-        last3, rest = s[-3:], s[:-3]
-        return sign + _group(rest, 2, separator) + separator + last3
-    if locale == "chinese":
-        return sign + _group(s, 4, separator)
-    raise ValueError("Unknown locale: %r" % locale)
-
-
-def _group(s, size, separator):
-    out = []
-    while s:
-        out.append(s[-size:])
-        s = s[:-size]
-    return separator.join(reversed(out))
+    return _RUST.group_digits(value, locale, separator)

rust/Cargo.lock

@@ -3,7 +3,7 @@ members = ["num2words2-core", "num2words2-py"]
 resolver = "2"
 
 [workspace.package]
-version = "0.1.0"
+version = "0.1.1"
 edition = "2021"
 license = "MIT OR Apache-2.0"
 repository = "https://github.com/jqueguiner/num2words2"

rust/Cargo.toml

@@ -4,6 +4,7 @@
 pub mod base;
 pub mod currency;
 pub mod floatpath;
+pub mod presentation;
 pub mod strnum;
 pub mod lang_af;
 pub mod lang_am;