words2num2 0.3.2__tar.gz → 0.3.5__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (95) hide show
  1. {words2num2-0.3.2 → words2num2-0.3.5}/PKG-INFO +234 -69
  2. words2num2-0.3.5/README.rst +587 -0
  3. words2num2-0.3.5/REFERENCE.md +498 -0
  4. {words2num2-0.3.2 → words2num2-0.3.5}/pyproject.toml +17 -1
  5. {words2num2-0.3.2 → words2num2-0.3.5}/rust/Cargo.lock +18 -69
  6. {words2num2-0.3.2 → words2num2-0.3.5}/rust/Cargo.toml +1 -1
  7. {words2num2-0.3.2 → words2num2-0.3.5}/rust/words2num2-core/Cargo.toml +4 -2
  8. words2num2-0.3.5/rust/words2num2-core/examples/probe.rs +28 -0
  9. words2num2-0.3.5/rust/words2num2-core/src/lib.rs +2886 -0
  10. words2num2-0.3.5/rust/words2num2-core/src/ord_compose.rs +201 -0
  11. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/ar.rs +121 -0
  12. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/be.rs +93 -0
  13. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/bg.rs +49 -0
  14. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/bn.rs +59 -0
  15. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/ca.rs +37 -0
  16. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/cs.rs +57 -0
  17. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/cy.rs +139 -0
  18. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/da.rs +19 -0
  19. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/el.rs +54 -0
  20. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/endings.rs +113 -0
  21. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/eo.rs +31 -0
  22. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/et.rs +53 -0
  23. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/fa.rs +40 -0
  24. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/fi.rs +55 -0
  25. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/fr.rs +35 -0
  26. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/gl.rs +71 -0
  27. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/gu.rs +28 -0
  28. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/he.rs +51 -0
  29. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/hi.rs +51 -0
  30. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/hu.rs +49 -0
  31. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/hy.rs +45 -0
  32. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/is.rs +39 -0
  33. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/ja.rs +27 -0
  34. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/ko.rs +70 -0
  35. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/la.rs +46 -0
  36. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/lt.rs +50 -0
  37. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/lv.rs +46 -0
  38. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/mn.rs +32 -0
  39. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/mod.rs +236 -0
  40. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/mr.rs +25 -0
  41. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/ms.rs +31 -0
  42. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/mt.rs +51 -0
  43. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/nb.rs +27 -0
  44. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/ne.rs +25 -0
  45. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/pa.rs +32 -0
  46. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/pl.rs +59 -0
  47. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/ro.rs +100 -0
  48. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/ru.rs +62 -0
  49. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/sh.rs +74 -0
  50. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/sk.rs +56 -0
  51. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/sl.rs +37 -0
  52. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/sq.rs +52 -0
  53. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/suffix.rs +30 -0
  54. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/sv.rs +27 -0
  55. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/sw.rs +29 -0
  56. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/tr.rs +55 -0
  57. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/uk.rs +54 -0
  58. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/ur.rs +32 -0
  59. words2num2-0.3.5/rust/words2num2-core/src/ord_forms/vi.rs +34 -0
  60. words2num2-0.3.5/rust/words2num2-core/src/w2n_currency.rs +1618 -0
  61. words2num2-0.3.5/rust/words2num2-core/src/w2n_decimal.rs +388 -0
  62. {words2num2-0.3.2 → words2num2-0.3.5}/rust/words2num2-core/src/w2n_formats.rs +314 -180
  63. words2num2-0.3.5/rust/words2num2-core/src/w2n_forms.rs +899 -0
  64. {words2num2-0.3.2 → words2num2-0.3.5}/rust/words2num2-core/src/w2n_lang_en.rs +397 -36
  65. words2num2-0.3.5/rust/words2num2-core/src/w2n_sentence/lexicon.rs +597 -0
  66. words2num2-0.3.5/rust/words2num2-core/src/w2n_sentence/tokens.rs +566 -0
  67. words2num2-0.3.5/rust/words2num2-core/src/w2n_sentence.rs +5148 -0
  68. words2num2-0.3.5/rust/words2num2-core/tests/roundtrip.rs +126 -0
  69. {words2num2-0.3.2 → words2num2-0.3.5}/rust/words2num2-py/Cargo.toml +1 -1
  70. {words2num2-0.3.2 → words2num2-0.3.5}/rust/words2num2-py/src/lib.rs +51 -28
  71. words2num2-0.3.5/tests/__init__.py +0 -0
  72. words2num2-0.3.5/tests/test_api_contract.py +139 -0
  73. words2num2-0.3.5/tests/test_auto_parse.py +355 -0
  74. words2num2-0.3.5/tests/test_dispatch.py +48 -0
  75. words2num2-0.3.5/tests/test_gil_release.py +38 -0
  76. words2num2-0.3.5/tests/test_lang_EN.py +345 -0
  77. words2num2-0.3.5/tests/test_multilang.py +246 -0
  78. words2num2-0.3.5/tests/test_ordinal_inflection.py +65 -0
  79. words2num2-0.3.5/tests/test_reference_doctest.py +48 -0
  80. words2num2-0.3.5/tests/test_sentence_audit.py +527 -0
  81. words2num2-0.3.5/tests/test_sentence_currency.py +227 -0
  82. words2num2-0.3.5/tests/test_sentence_realworld.py +425 -0
  83. {words2num2-0.3.2 → words2num2-0.3.5}/words2num2/__init__.py +57 -23
  84. words2num2-0.3.5/words2num2/__main__.py +57 -0
  85. words2num2-0.3.5/words2num2/_rust.pyi +55 -0
  86. {words2num2-0.3.2 → words2num2-0.3.5}/words2num2/_version.py +2 -2
  87. {words2num2-0.3.2 → words2num2-0.3.5}/words2num2/base.py +1 -0
  88. {words2num2-0.3.2 → words2num2-0.3.5}/words2num2/converters/auto.py +1 -0
  89. words2num2-0.3.5/words2num2/py.typed +0 -0
  90. words2num2-0.3.2/README.rst +0 -422
  91. words2num2-0.3.2/rust/words2num2-core/src/lib.rs +0 -620
  92. words2num2-0.3.2/rust/words2num2-core/src/w2n_sentence.rs +0 -2459
  93. words2num2-0.3.2/words2num2/__main__.py +0 -39
  94. {words2num2-0.3.2 → words2num2-0.3.5}/COPYING +0 -0
  95. {words2num2-0.3.2 → words2num2-0.3.5}/words2num2/converters/__init__.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: words2num2
3
- Version: 0.3.2
3
+ Version: 0.3.5
4
4
  Classifier: Development Status :: 4 - Beta
5
5
  Classifier: Intended Audience :: Developers
6
6
  Classifier: Programming Language :: Python :: 3
@@ -90,8 +90,8 @@ The inverse of `num2words2 <https://github.com/gladiaio/num2words2>`_.
90
90
 
91
91
  ``words2num2`` parses spoken-form numbers — ``"forty-two"``,
92
92
  ``"trois cent quatre"``, ``"二十三"`` — and returns numeric values.
93
- It mirrors num2words2's locale list (**100+ languages, 120 dispatch
94
- entries**) and adds a free-text *auto-parse* mode that handles
93
+ It mirrors num2words2's locale list (**100+ languages, 172 language
94
+ keys**) and adds a free-text *auto-parse* mode that handles
95
95
  currencies, units, configurable thousands/decimal separators, and
96
96
  ASR/LLM-style mixed text.
97
97
 
@@ -184,12 +184,16 @@ conversion engine is compiled in, so you do *not* need the num2words2 package).
184
184
  Prebuilt wheels are published for:
185
185
 
186
186
  * **Linux** — x86_64 and aarch64 (manylinux2014)
187
- * **macOS** — Apple Silicon (arm64); Intel (x86_64) from a later release
187
+ * **macOS** — Apple Silicon (arm64) and Intel (x86_64)
188
188
  * **Windows** — x86_64
189
189
 
190
- On any other platform (or an older release without a matching wheel), pip
191
- falls back to the source distribution and builds the extension locally — this
192
- needs a **stable Rust toolchain** (`rustup <https://rustup.rs>`_); nothing else.
190
+ The wheels are CPython ``abi3`` wheels: one per platform serves every CPython
191
+ 3.10+. **PyPy** (3.11+) is supported from source only: it cannot load ``abi3``
192
+ wheels, so pip builds the source distribution, and CI runs the full test suite
193
+ on PyPy that way. On any other platform (or an older release without a
194
+ matching wheel), pip also falls back to the source distribution and builds the
195
+ extension locally — this needs a **stable Rust toolchain**
196
+ (`rustup <https://rustup.rs>`_); nothing else.
193
197
 
194
198
  **Arch Linux / Manjaro (AUR):**
195
199
 
@@ -242,6 +246,125 @@ Quickstart
242
246
  >>> words2num_sentence("I bought twenty-three apples and fourteen pears.")
243
247
  'I bought 23 apples and 14 pears.'
244
248
 
249
+ Sentence mode
250
+ -------------
251
+
252
+ ``words2num_sentence`` is built for transcripts (ASR, LLM output): it reads
253
+ what the speaker meant and leaves everything else alone.
254
+
255
+ .. code-block:: python
256
+
257
+ >>> words2num_sentence("due on the fifteenth of march, twenty twenty five")
258
+ 'due on the 15th of march, 2025'
259
+ >>> words2num_sentence("call eight five zero eight two oh nine oh nine five")
260
+ 'call 8508209095'
261
+ >>> words2num_sentence("one thousand three hundred fifty five dollars and two point five percent")
262
+ '1355 dollars and 2.5 percent'
263
+ >>> words2num_sentence("no one answered, wait a second, one of them owes me a hundred bucks")
264
+ 'no one answered, wait a second, one of them owes me 100 bucks'
265
+ >>> words2num_sentence("un solde de deux cents euros et vingt et une personnes", lang="fr")
266
+ 'un solde de 200 euros et 21 personnes'
267
+ >>> words2num_sentence("le vingt-troisième jour, trois virgule cinq pour cent", lang="fr")
268
+ 'le 23e jour, 3,5 pour cent'
269
+ >>> words2num_sentence("el primero de mayo, cincuenta y un centavos", lang="es")
270
+ 'el 1º de mayo, 51 centavos'
271
+ >>> words2num_sentence("am zweiten April, dreiundzwanzigtausend Euro", lang="de")
272
+ 'am 2. April, 23000 Euro'
273
+
274
+ What it reads:
275
+
276
+ * **Cardinals and compounds** across scale words (``"un million deux cent
277
+ mille"``, ``"dreiundzwanzigtausend"``, ``"ventitremila"``), with the
278
+ spoken connectors (``"and"``, ``"et"``, ``"y"``) and the plural or
279
+ feminine forms speech adds (``"deux cents"``, ``"quatre vingts"``,
280
+ ``"cinquante et une"``).
281
+ * **Spoken years** (``"nineteen ninety nine"``, ``"twenty oh five"``, nl
282
+ ``"negentien negenennegentig"``) and **digit strings** read one digit at a
283
+ time in every language (phone numbers, ZIP codes, ``"double zero
284
+ seven"``), leading zeros kept.
285
+ * **Decimals** the way num2words writes them in each language, read from its
286
+ own ``to_cardinal_float`` output: a separator word (en ``"point"``, fr
287
+ ``"virgule"``, es ``"coma"`` / ``"punto"``, sv ``"komma"``, hi ``"दशमलव"``,
288
+ ko ``"점"``), or a whole-word and a denominator (ru ``"три целых
289
+ четырнадцать сотых"``, hu ``"három egész tizennégy század"``), written with
290
+ the locale's decimal character (``"3,5"``). The fraction may be digits
291
+ read one by one or one number below 1000 (fr ``"trois virgule zéro
292
+ vingt-cinq"`` -> ``"3,025"``). ``words2num`` reads them too, as a
293
+ ``Decimal``, including separators glued into one word (ja ``"三点一四"``,
294
+ tr ``"üçvirgülondört"``).
295
+ * **Ordinals**, written in the language's figures: ``21st``, fr ``1er`` /
296
+ ``2e``, es ``3º`` / ``20ª``, de ``2.``, nl ``15e``.
297
+ * **Percent phrases**: ``"vingt pour cent"`` -> ``"20 pour cent"`` (the
298
+ ``cent`` after ``pour`` is not 100).
299
+
300
+ What it leaves in words, on purpose:
301
+
302
+ * the number 1 when it is an article or a pronoun (``"one of them"``,
303
+ ``"no one"``, ``"un instant"``, ``"um momento"``), unless something counts
304
+ it: a unit or currency (``"one dollar"``, ``"une heure"``), a label
305
+ (``"press one"``, ``"option one"``, ``"tapez un"``), a month, a list;
306
+ * ``"first"`` / ``"second"`` and their translations away from a date
307
+ (``"first of all"``, ``"wait a second"``, ``"la première fois"``);
308
+ * fractions (``"two thirds"``, ``"a fifth of"``, ``"deux tiers"``) and
309
+ quantities (``"a couple of thousand"``, ``"hundreds of"``, ``"des
310
+ millions"``, ``"half a million"``);
311
+ * a decade (``"the nineteen nineties"``), a scale word after a decimal
312
+ (``"2.5 million"``), a dangling connector (``"five point"``, ``"one and a
313
+ half"``);
314
+ * anything that already holds a digit (``"850-820-9095"``, ``"$426"``).
315
+
316
+ **Currency fold** (``currency=True``, off by default): an amount spoken as
317
+ number + currency word (+ connector + subunit) is written the way the language
318
+ writes that currency — the currency picks the symbol and its side, the language
319
+ the separators (en ``1,355.28``, fr ``1 355,28``, de/es/it/pt/nl ``1.355,28``;
320
+ dollars and pesos in Spanish keep the Latin-American ``$1,234.56``).
321
+
322
+ .. code-block:: python
323
+
324
+ >>> words2num_sentence("one thousand three hundred fifty five dollars and twenty eight cents", currency=True)
325
+ '$1,355.28'
326
+ >>> words2num_sentence("ninety nine cents, twenty quid, ten thousand yen", currency=True)
327
+ '$0.99, £20, ¥10,000'
328
+ >>> words2num_sentence("quarante-trois dollars et vingt centimes", lang="fr", currency=True)
329
+ '43,20 $'
330
+ >>> words2num_sentence("mille deux cents euros cinquante", lang="fr", currency=True)
331
+ '1 200,50 €'
332
+ >>> words2num_sentence("ciento cincuenta y cuatro dólares con noventa y dos centavos", lang="es", currency=True)
333
+ '$154.92'
334
+ >>> words2num_sentence("dreiundzwanzig euro und fünfzig cent", lang="de", currency=True)
335
+ '23,50 €'
336
+ >>> words2num_sentence("duzentos reais e cinquenta centavos", lang="pt", currency=True)
337
+ 'R$ 200,50'
338
+ >>> words2num_sentence("twintig euro vijftig", lang="nl", currency=True)
339
+ '€ 20,50'
340
+
341
+ Subunits after a connector (``"and"``, ``"et"``, ``"con"``, ``"und"``, ``"e"``)
342
+ or bare (``"two euros fifty"``), or on their own (``"vingt centimes"`` ->
343
+ ``"0,20 €"``: the language's default currency — USD for en/es, BRL for pt, EUR
344
+ elsewhere). No decimals unless a subunit was spoken (``"twelve dollars"`` ->
345
+ ``"$12"``); JPY and KRW never carry any. A currency word without a number in
346
+ front stays a word (``"des euros"``, ``"a couple of dollars"``), and so does an
347
+ amount on a scale word (``"2.5 million dollars"``). Currencies: USD, EUR, GBP,
348
+ JPY, CNY, CHF, CAD (fr ``5 $ CA``, the OQLF form), AUD, NZD, MXN and the
349
+ unqualified peso (``$``), BRL, INR, KRW, RUB, TRY, PLN, SEK/NOK/DKK, XOF, MAD,
350
+ ZAR, with their names and subunits in en, fr, es, de, it, pt, nl and ca —
351
+ every name num2words writes for them, plus the colloquial ones (``bucks``,
352
+ ``quid``). A subunit of 100 or more carries (``"one hundred fifty cents"`` ->
353
+ ``"$1.50"``); a spoken fraction longer than the currency's minor unit, or a
354
+ subunit after an amount that was not folded, is left as said rather than
355
+ truncated or given a currency nobody named. ``"pounds of"`` is a weight.
356
+
357
+ ``words2num(text, to="currency")`` returns the amount itself as a ``Decimal``,
358
+ unit plus subunit, for any language whose num2words currency names it knows::
359
+
360
+ >>> words2num("twelve euros, thirty-four cents", to="currency")
361
+ Decimal('12.34')
362
+ >>> words2num("zwei Euro", lang="de", to="currency")
363
+ Decimal('2')
364
+
365
+ Text with no currency word is read as a plain cardinal; text with one that is
366
+ not an amount (``"twelve euros and change"``) raises ``Words2NumError``.
367
+
245
368
  Auto-parse mode
246
369
  ---------------
247
370
 
@@ -257,11 +380,11 @@ SI/imperial units, percent, and disambiguation hints.
257
380
 
258
381
  # Currencies
259
382
  >>> auto_parse("$12,345.00")
260
- Quantity(value=12345.0, unit='USD', kind='currency', confidence=1.0)
383
+ Quantity(value=Decimal('12345.00'), unit='USD', kind='currency', confidence=1.0)
261
384
  >>> auto_parse("$5m").value
262
385
  5000000
263
386
  >>> auto_parse("12,50 €", lang="de").value
264
- 12.5
387
+ Decimal('12.50')
265
388
 
266
389
  # Units
267
390
  >>> auto_parse("5cm")
@@ -273,9 +396,9 @@ SI/imperial units, percent, and disambiguation hints.
273
396
 
274
397
  # Configurable separators
275
398
  >>> auto_parse("1.234,56", lang="de").value
276
- 1234.56
399
+ Decimal('1234.56')
277
400
  >>> auto_parse("1 234,56", lang="fr").value
278
- 1234.56
401
+ Decimal('1234.56')
279
402
 
280
403
  # Disambiguation for ambiguous unit tokens
281
404
  >>> auto_parse("5m", prefer={"m": "mile"}).unit_long
@@ -305,29 +428,42 @@ or rely on per-locale CLDR-style defaults:
305
428
  >>> from words2num2 import parse_number_string
306
429
 
307
430
  >>> parse_number_string("12,345.67") # auto-detect
308
- 12345.67
431
+ Decimal('12345.67')
309
432
  >>> parse_number_string("12.345,67", lang="de") # German defaults
310
- 12345.67
433
+ Decimal('12345.67')
311
434
  >>> parse_number_string("1 234,56", lang="fr") # French defaults (NBSP)
312
- 1234.56
435
+ Decimal('1234.56')
436
+ >>> parse_number_string("3.14", lang="fr") # a dot decimal anywhere
437
+ Decimal('3.14')
313
438
  >>> parse_number_string("12'345.67", thousands_sep="'", decimal_sep=".") # Swiss
314
- 12345.67
439
+ Decimal('12345.67')
315
440
  >>> parse_number_string("1_234.56", thousands_sep="_") # programmer
316
- 1234.56
441
+ Decimal('1234.56')
442
+
443
+ A decimal is an exact ``Decimal``; a whole number is an ``int``.
317
444
 
318
445
  The locale defaults table covers 50+ locales: English/CJK use comma
319
446
  thousands and period decimal; French uses non-breaking-space + comma;
320
447
  Swiss French uses apostrophe + period; German/Spanish/Italian/Portuguese/
321
448
  Dutch/Romanian use period + comma; Russian/Scandinavian/Slavic use space
322
- + comma. See `words2num2/formats.py` for the full table.
323
-
324
- Auto-detection heuristic (when no override and no locale match):
325
-
326
- 1. If both ``.`` and ``,`` appear, the rightmost one is the decimal.
327
- 2. If one separator appears multiple times, it is thousands.
328
- 3. If one separator appears once with exactly 3 trailing digits, it is
329
- thousands; otherwise it is decimal.
330
- 4. Spaces, NBSP, apostrophe, and underscore are always thousands.
449
+ + comma. See ``NUMBER_FORMAT_DEFAULTS`` in
450
+ ``rust/words2num2-core/src/w2n_formats.rs`` for the full table. A locale
451
+ is read strictly — its thousands separator only between groups of exactly
452
+ three digits — and anything that does not fit is auto-detected.
453
+
454
+ Auto-detection heuristic (when no override, no locale match, or the locale
455
+ reading does not fit):
456
+
457
+ 1. Spaces, NBSP, apostrophes (``'``, ``’``) and underscore are always
458
+ thousands.
459
+ 2. If both ``.`` and ``,`` appear, the rightmost one is the decimal and the
460
+ other groups thousands in threes.
461
+ 3. If one separator appears several times, it is thousands — in groups of
462
+ three, or the string is not a number (``"1.5.2026"`` raises).
463
+ 4. If one separator appears once it is a decimal (``"3.14"``, ``"1,5"``,
464
+ ``"1234.567"``), except 1-3 digits + separator + exactly 3 digits
465
+ (``"1.234"``): there the locale's decimal separator decides, and with no
466
+ locale it is a decimal.
331
467
 
332
468
  Command line
333
469
  ------------
@@ -338,23 +474,41 @@ Command line
338
474
  42
339
475
  $ words2num2 "trois cent quatre" --lang=fr
340
476
  304
477
+ $ words2num2 --lang fr trois cent quatre
478
+ 304
341
479
  $ words2num2 "twenty-third" --to=ordinal
342
480
  23
481
+ $ words2num2 "forty zoot"
482
+ words2num2: error: unrecognized token 'zoot' in 'forty zoot'
483
+
484
+ An unparseable input or an unsupported ``--lang``/``--to`` prints one line on
485
+ stderr and exits with status 1.
343
486
 
344
487
  Supported locales
345
488
  -----------------
346
489
 
347
- ``words2num2`` mirrors num2words2's locale list — **120 dispatch
348
- entries** including:
349
-
350
- af, am, ar, as, az, ba, be, bg, bn, bo, br, bs, ca, ce, cs, cy, da,
351
- de, el, en, en_IN, en_NG, eo, es, es_CO, es_CR, es_GT, es_NI, es_VE,
352
- et, eu, fa, fi, fo, fr, fr_BE, fr_CH, fr_DZ, gl, gu, ha, haw, he, hi,
353
- hr, ht, hu, hy, id, is, it, ja, jw, ka, kk, km, kn, ko, kz, la, lb,
354
- ln, lo, lt, lv, mg, mi, mk, ml, mn, mr, ms, mt, my, ne, nl, nn, no,
355
- oc, pa, pl, ps, pt, pt_BR, ro, ru, sa, sd, si, sk, sl, sn, so, sq,
356
- sr, su, sv, sw, ta, te, tet, tg, th, tk, tl, tr, tt, uk, ur, uz, vi,
357
- wo, yi, yo, zh, zh_CN, zh_HK, zh_TW
490
+ ``words2num2`` accepts every language key of the embedded num2words2
491
+ renderer — **172 keys**, as returned by ``supported_langs()``:
492
+
493
+ af, am, ar, as, az, ba, ban, be, bg, bm, bn, bo, br, bs, ca, ce, ceb,
494
+ ckb, cn, cnh, cs, cy, cz, da, de, dk, dv, el, en, en_AERO,
495
+ en_Aero_FAA, en_Aero_ICAO, en_Aero_NATO, en_Aero_USN, en_Aero_US_Army,
496
+ en_Aero_US_Navy, en_IN, en_NE, en_NG, en_NP, en_aero_icao,
497
+ en_x_aero_icao, eo, es, es_CO, es_CR, es_GT, es_HN, es_NI, es_VE, et,
498
+ eu, fa, ff, fi, fil, fo, fr, fr_BE, fr_CH, fr_DZ, gl, gu, ha, haw, he,
499
+ hi, hmn, hr, ht, hu, hy, id, is, it, ja, jp, jv, jw, ka, ki, kk, km,
500
+ kn, ko, kok, ksw, ku, ky, kz, la, lb, lg, lij, ln, lo, lt, lus, lv,
501
+ mg, mi, miz, mk, ml, mn, mr, ms, mt, my, nb, ne, nl, nn, no, oc, om,
502
+ or, pa, pap, pl, pli, ps, pt, pt_BR, rm, rm_puter, rm_surmiran,
503
+ rm_sursilv, rm_sutsilv, rm_vallader, ro, ru, rw, sa, sd, si, sk, sl,
504
+ sn, so, sq, sr, sr_Cyrl, sr_Latn, su, sv, sw, ta, te, tet, tg, th, ti,
505
+ tk, tl, tr, tt, uk, ur, uz, uz_Cyrl, uz_cyr, vi, wo, xh, yi, yo, zh,
506
+ zh_CN, zh_HK, zh_TW, zu
507
+
508
+ Codes are case-insensitive, ``-`` and ``_`` are interchangeable, unknown
509
+ region subtags fall back to the base language (``en-US`` → ``en``) and ISO
510
+ 639-2 codes are accepted (``eng``, ``fra``). Language names (``"swedish"``)
511
+ are not, and raise ``NotImplementedError``.
358
512
 
359
513
  Aliases: ``jp`` → ``ja``, ``cn`` → ``zh_CN``.
360
514
 
@@ -368,25 +522,31 @@ enhancements.
368
522
  Conversion types
369
523
  ~~~~~~~~~~~~~~~~
370
524
 
371
- The ``to=`` parameter accepts ``cardinal``, ``ordinal``, ``ordinal_num``,
372
- ``year``, and ``currency`` — same set as ``num2words2``.
525
+ The ``to=`` parameter (``words2num`` and ``words2num_sentence``) accepts
526
+ ``cardinal``, ``ordinal``, ``ordinal_num``, ``year``, ``currency`` and
527
+ ``digits`` (listed in ``words2num2.CONVERTER_TYPES``); anything else raises
528
+ ``NotImplementedError``. ``digits`` reads a number spoken digit by digit and
529
+ concatenates it (``"two seven five"`` → ``275``). It returns an ``int``, so
530
+ leading zeros are dropped (``"zero seven"`` → ``7``); sentence mode keeps them
531
+ (``words2num_sentence("zero seven")`` → ``"07"``).
373
532
 
374
533
  How it works
375
534
  ------------
376
535
 
377
- * English (``lang_EN``) ships a hand-written recursive-descent parser
378
- that handles cardinals, ordinals, decimals, negatives, scale words to
379
- *centillion*, year mode, "and" connectors, and hyphenation.
380
- * Every other locale uses ``Words2Num_Base``, which lazily builds a
381
- ``{normalized_words: integer}`` table by calling ``num2words2`` for
382
- each integer in a configurable range (defaults to ``-1..10000``).
383
- This guarantees correctness for the lookup window for every locale
384
- supported upstream — at the cost of out-of-range values raising
385
- ``Words2NumError`` until a hand-written parser is added.
536
+ All parsing lives in the compiled Rust core (``rust/words2num2-core``,
537
+ also published on crates.io); the ``words2num2`` Python package is a thin
538
+ binder over it.
539
+
540
+ * English has a hand-written recursive-descent parser that handles
541
+ cardinals, ordinals, decimals, negatives, scale words to *centillion*,
542
+ year mode, "and" connectors, and hyphenation.
543
+ * Every other language is read through a reverse lookup table, built lazily
544
+ on first use by rendering ``-1..10000`` with the embedded num2words2
545
+ renderer (``num2words2-core``) and inverting it. Larger numbers are
546
+ composed from the language's scale words (thousand, million, …), derived
547
+ the same way.
386
548
 
387
- Hand-written grammar parsers can be added incrementally per locale by
388
- overriding ``to_cardinal`` / ``to_ordinal`` in the corresponding
389
- ``words2num2/lang_XX.py`` module — same pattern as num2words2.
549
+ To improve a language, change the core — see ``CONTRIBUTING.md``.
390
550
 
391
551
  Public API
392
552
  ----------
@@ -399,10 +559,10 @@ Function / class Purpose
399
559
  ``auto_parse(text, ...)`` Parse a single quantity (number + unit).
400
560
  ``auto_parse_sentence(text, ...)`` Replace every quantity in running text.
401
561
  ``parse_number_string(text, ...)`` Digit-form parser with separators.
562
+ ``normalize(text)`` The text normalization applied before lookup.
563
+ ``supported_langs()`` The accepted language keys.
564
+ ``CONVERTER_TYPES`` The accepted ``to=`` values.
402
565
  ``Quantity`` Dataclass returned by ``auto_parse``.
403
- ``UNITS`` / ``CURRENCIES`` Registries of recognized units and currencies.
404
- ``NUMBER_FORMAT_DEFAULTS`` Per-locale separator defaults.
405
- ``CONVERTER_CLASSES`` Per-locale converter registry.
406
566
  ``Words2NumError`` Raised when input cannot be parsed.
407
567
  ================================== =================================================
408
568
 
@@ -418,27 +578,32 @@ Development
418
578
  cd words2num2
419
579
  make install-dev
420
580
  make test # pytest
421
- make lint # black + flake8 + isort
581
+ make lint # black --check + isort --check + flake8 + mypy (what CI runs)
422
582
  make format # apply black + isort
423
583
 
584
+ Building from a checkout compiles the Rust core, so a stable Rust toolchain
585
+ is needed (``make install-dev`` runs ``pip install -e .`` through maturin).
586
+
424
587
  Releasing
425
588
  ~~~~~~~~~
426
589
 
427
- Every push of a tag matching ``v*`` triggers GitHub Actions to:
428
-
429
- 1. Build sdist + wheel.
430
- 2. Run the test installation in a clean environment.
431
- 3. Generate release notes and create a GitHub Release.
432
- 4. Publish to PyPI via Trusted Publishing (no token in CI).
433
-
434
- To cut a release::
435
-
436
- git tag vX.Y.Z
437
- git push origin vX.Y.Z
438
-
439
- A manual fallback workflow (``Publish to PyPI (manual)``) is available
440
- via ``gh workflow run`` and uses ``PYPI_API_TOKEN`` /
441
- ``TEST_PYPI_API_TOKEN`` repo secrets.
590
+ Releases are cut by bumping the version, not by hand-tagging:
591
+
592
+ 1. Bump ``version`` in ``pyproject.toml`` **and** ``words2num2/_version.py``
593
+ (they must agree) and merge to ``main``.
594
+ 2. ``auto-release.yml`` sees that the version is not on PyPI, tags the commit
595
+ ``vX.Y.Z`` (or reuses the tag if an earlier attempt failed), and dispatches
596
+ ``release.yml``, ``crates.yml`` and ``aur-publish.yml`` on it.
597
+ 3. ``release.yml`` checks that the tag, ``pyproject.toml`` and ``_version.py``
598
+ agree, builds the wheels and the sdist, installs each native wheel and the
599
+ sdist in a clean environment and runs the test suite against them, and only
600
+ then publishes to PyPI (Trusted Publishing, no token in CI) and creates the
601
+ GitHub Release.
602
+
603
+ A failed release is retried by re-running ``auto-release.yml`` (Actions →
604
+ Auto release → Run workflow): PyPI, not the tag, decides what is released.
605
+ Pushing a ``vX.Y.Z`` tag by hand still runs ``release.yml``, under the same
606
+ version check.
442
607
 
443
608
  Changelog
444
609
  ---------