This release is a pre-release and may not be stable for production use.
numtag
numtag finds every number in a text. For each number it gives the exact words, their character offsets, an exact value, the kind of number and how it is written. It reads number words ("duas dúzias"), digits ("1.234,5") and both together ("2 milhões").
from numtag import tag_numbers
for m in tag_numbers("Comprou duas dúzias de ovos e ganhou um milhão de euros.", "pt-PT"):
print(m.char_span, repr(m.text), m.value, m.kind.value)
(8, 19) 'duas dúzias' 24 cardinal
(37, 46) 'um milhão' 1000000 cardinal
Install
numtag needs Python 3.11 or later and has no dependencies.
uv pip install --prerelease=allow numtag
To work on the library, install it from a clone with its test extra and run the tests:
uv pip install -e ".[test]"
pytest tests
Quickstart
tag_numbers(text, lang) returns a list of NumberMention objects in reading order. The mentions never overlap.
>>> from numtag import tag_numbers
>>> mention = tag_numbers("The tower is one hundred and twenty-five point five metres tall.", "en")[0]
>>> mention.text, mention.char_span, mention.value
('one hundred and twenty-five point five', (13, 51), '125.5')
>>> mention.kind, mention.form
(<Kind.DECIMAL: 'decimal'>, <Form.WORDS: 'words'>)
The span slices the original text, so text[start:end] is always mention.text. Use the span to replace or mark the number in place.
Values
A value is a canonical digit string, never an int or a float. It has one of three forms.
| Form | Examples |
|---|---|
| whole number | "24", "-42", "1000000" |
| decimal | "125.5", "0.75" |
| fraction in lowest terms | "1/3", "7/3" |
numtag computes each value with string arithmetic on digits, so a value has no length limit and no rounding error. Convert a value when you need a number. int() reads a whole number, decimal.Decimal() reads a whole number or a decimal, and fractions.Fraction() reads all three forms.
>>> from fractions import Fraction
>>> Fraction(tag_numbers("dois e um terço", "pt-PT")[0].value)
Fraction(7, 3)
Read docs/values.md for the full contract.
Languages
lang |
Lexicon | Default scale |
|---|---|---|
pt-BR |
Brazilian Portuguese | short: "bilhão" is 10^9 |
every other pt tag (pt, pt-PT, pt-AO) |
European Portuguese | long: "bilião" is 10^12 |
every en tag (en, en-US, en-GB) |
English | short: "billion" is 10^9 |
el, ar, he, fa, kab |
Greek, Arabic, Hebrew, Persian, Kabyle | per lexicon, in el-ar-he-fa-kab.md |
de, nl, fy, da, sv, nb (and no), nn |
German, Dutch, West Frisian, Danish, Swedish, Norwegian | per lexicon, in germanic.md |
fi, et, hu, tr, az |
Finnish, Estonian, Hungarian, Turkish, Azerbaijani | per lexicon, in uralic-turkic.md |
ru, uk, bg, pl, cs, sk, sl, hr |
Russian, Ukrainian, Bulgarian, Polish, Czech, Slovak, Slovene, Croatian | per lexicon, in slavic.md |
fr (fr-BE and fr-CH have their own lexicons), it, ro, eu, id |
French, Italian, Romanian, Basque, Indonesian | per lexicon, in fr-it-ro-eu-id.md |
es, gl, ca, ast, an, oc, mwl |
Spanish, Galician, Catalan, Asturian, Aragonese, Occitan, Mirandese | per lexicon, in ibero.md |
Each language page gives the default scale of each lexicon. Pass scale="long" or scale="short" to read the large scale words in the other scale. Another language tag raises ValueError.
Each language is one JSON file in numtag/lexicon/. Each word and each setting in the file carries the source of its rule.
Documentation
| Guide | Content |
|---|---|
| docs/index.md | The map of the documentation |
| docs/getting-started.md | First calls and common tasks |
| docs/api.md | Every public name |
| docs/values.md | The value strings and how to convert them |
| docs/number-scale.md | Long and short scale |
| docs/confidence-and-homographs.md | Articles, words with two meanings, low scores |
| docs/rulings.md | The reading rules, each with its source |
| docs/languages/ | What each language reads |
| docs/adding-a-language.md | The lexicon format and the gates for a new language |
| docs/design.md | How the tagger works inside |
| docs/benchmarks.md | Accuracy, memory and time against ovos-number-parser |
| docs/roadmap.md | Planned features |
License
Apache-2.0.
Metadata
Release files for numtag 0.9.0a1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| numtag-0.9.0a1.tar.gz | 376.8 kB | Without provenance | Details for numtag-0.9.0a1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| numtag-0.9.0a1-py3-none-any.whl | Python 3 | none | any | Details for numtag-0.9.0a1-py3-none-any.whl |
Total release size: 709.0 kB
Release files / numtag-0.9.0a1.tar.gz
| Download URL | numtag-0.9.0a1.tar.gz |
|---|---|
| Size | 376.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
30715b48084acd4180f58b1d47f44f83129450f9961d86d9df6bfc5d007c24e2
|
|
BLAKE2b-256 checksum How to use checksums |
327bead787dd71aaa86121b2e8b8c08bb67a3b8d062caf3ca754957ba3c52bad
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / numtag-0.9.0a1-py3-none-any.whl
| Download URL | numtag-0.9.0a1-py3-none-any.whl |
|---|---|
| Size | 332.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
91d2dd4cd1ae7fd90fe1f9c1221c964d5101dc0656a83ac2d2ede94858ee8736
|
|
BLAKE2b-256 checksum How to use checksums |
780e6acdafdd7df2ecc2d4d29a4a3ca51da9546fc99e437d1948d8536b4409b9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Security for numtag 0.9.0a1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.