Skip to main content
Pre-release

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 UnsupportedLanguageError, a subclass of 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.12.0a1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for numtag 0.12.0a1
File Size Uploaded Provenance Actions
numtag-0.12.0a1.tar.gz 411.4 kB Without provenance Details for numtag-0.12.0a1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for numtag 0.12.0a1
File Interpreter ABI Platform Actions
numtag-0.12.0a1-py3-none-any.whl Python 3 none any Details for numtag-0.12.0a1-py3-none-any.whl

Total release size: 766.1 kB

Release files / numtag-0.12.0a1.tar.gz

Download URL numtag-0.12.0a1.tar.gz
Size 411.4 kB
Tags Source
SHA-256 checksum
How to use checksums
37233f0d7abc5c5b5ba6c1a59edd8030ba6a4ff31acd5c88fdbe76ac2e30fab6
BLAKE2b-256 checksum
How to use checksums
60eb02eaa03576985cab563a5316e7719441fd52457289fe2db05ef1e3a707cd
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.12.0a1-py3-none-any.whl

Download URL numtag-0.12.0a1-py3-none-any.whl
Size 354.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
08604142c47a2ca015de51db960630af3376b0d5b0b80942c76b8122b0336a26
BLAKE2b-256 checksum
How to use checksums
eaed79cf7148f9090cc8f622421f8007bac0a5baa7889c726c638e4e36d6e35e
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.12.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.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page