This release has been yanked by its maintainers, and will be ignored by installers, except when explicitly specified.
Consider using release 3.6.5 instead.
Parses, extracts, normalizes, and converts English number words, integers, exact decimals, scientific and accounting notation, ordinal digits, and Roman numerals.
Table of contents
from decimal import Decimal
import numbr
numbr.wordsToInt("one hundred sixty-seven")
# 167
numbr.Cast("forty-ninth", "Ordinal Number")
# "49th"
numbr.Cast("Ⅳ", "Ordinal Word")
# "fourth"
numbr.Cast("one point zero five", "Decimal Number")
# Decimal("1.05")
numbr.Cast(Decimal("1.050"), "Cardinal Word")
# "one point zero five zero"
numbr.extractNumericValue("He scored twenty-one of 34 attempts")
# [21, 34]
numbr.extractNumericEntities("She placed 2nd with 1.05 points")
# [NumericMatch(text='2nd', value=2, representation='Ordinal Number', ...),
# NumericMatch(text='1.05', value=Decimal('1.05'), representation='Decimal Number', ...)]
numbr.normalizeNumericText("She placed forty-second with 1.20e3 points")
# "She placed 42nd with 1200 points"
numbr.batchCast(["one", "2", "III"], "Cardinal Number")
# [1, 2, 3]
Installation
Install the latest release from PyPI:
python -m pip install numbr
Or install the current development version from GitHub:
python -m pip install 'numbr @ git+ssh://git@github.com/doydl-technologies/numbr.git'
Python 3.13 is required. The package has no runtime dependencies.
Representations
| Representation | Examples | Type result |
|---|---|---|
| Cardinal number | 42, "-42" |
"Cardinal Number" |
| Decimal number | "1.05", Decimal("1.050") |
"Decimal Number" |
| Scientific number | "1.20e3", "-4E-2" |
"Scientific Number" |
| Accounting number | "(1,234.50)", "($50.00)" |
"Accounting Number" |
| Cardinal word | "forty-two" |
"Cardinal Word" |
| Ordinal number | "42nd" |
"Ordinal Number" |
| Ordinal word | "forty-second" |
"Ordinal Word" |
| Roman numeral | "XLII", "Ⅳ" |
"Roman Numeral" |
Decimal phrases such as "one point zero five" are cardinal-word forms. Digits
following point are interpreted individually so precision and trailing zeros
are preserved.
Cast accepts the display names and common aliases such as int, decimal,
scientific, accounting, cardword, ordnum, and roman.
numbr.Type("twenty-first")
# "Ordinal Word"
numbr.Cast("twenty-first", "Cardinal Number")
# 21
numbr.Cast(1994, "Roman Numeral")
# "MCMXCIV"
numbr.Type("-0.004")
# "Decimal Number"
numbr.Cast("-0.004", "Cardinal Word")
# "negative zero point zero zero four"
Roman output is limited to canonical values from 1 through 3999. English number
conversion supports values whose integer component has an absolute value less
than 10**24.
Public API
General conversion
Type(value)detects the representation or returnsNone.Cast(value, target, *, as_str=False)converts between representations and raisesValueErrorwhen the input or requested conversion is invalid.
Decimal-number conversions return decimal.Decimal to avoid binary floating-point
rounding and to preserve explicitly supplied fractional zeros. Non-integral
decimals cannot be cast to integer-only cardinal, ordinal, or Roman forms.
Scientific and accounting notation
Scientific notation accepts signed coefficients and exponents, including forms
such as .5e1 and 5.e2. Accounting notation uses parentheses for negative
values and accepts a supported currency token either immediately outside or
inside the parentheses.
numbr.scientificToDecimal("1.20e3")
# Decimal("1.20E+3")
numbr.accountingToDecimal("($1,234.50)")
# Decimal("-1234.50")
numbr.decimalToScientific(Decimal("1230.00"))
# "1.23e+3"
numbr.decimalToAccounting(Decimal("-1234.50"), currency="$")
# "($1,234.50)"
Both representations participate in Type, Cast, value extraction, and
structured extraction.
Structured extraction
extractNumericEntities(text) returns an immutable NumericMatch for every
recognized expression in source order. Each match provides the original text,
normalized value, representation name, start and end offsets, span, and
is_ordinal and is_negative flags.
matches = numbr.extractNumericEntities("She placed forty-second with -0.50 points in round XLII.")
matches[0].text, matches[0].value, matches[0].span
# ("forty-second", 42, (11, 23))
matches[1].value
# Decimal("-0.50")
matches[2].representation
# "Roman Numeral"
Canonical Roman numerals are included by default. Single-letter ASCII forms
such as I, V, and X are excluded because they are ambiguous in prose; pass
include_single_roman=True to include them. Pass include_roman=False to omit
Roman numerals entirely.
Whole-text normalization
normalizeNumericText(text, style="digits") replaces every recognized entity
while preserving all surrounding characters. The default style renders
cardinals as digits and retains ordinal suffixes. Use style="words" to spell
values in English while retaining ordinal meaning.
text = "She placed forty-second with 1.20e3 points and lost ($1,234.50)."
numbr.normalizeNumericText(text)
# "She placed 42nd with 1200 points and lost -1234.50."
numbr.normalizeNumericText("Ranked 2nd in round Ⅳ", style="words")
# "Ranked second in round four"
The Roman-numeral options are the same as those on extractNumericEntities.
Values outside the supported English-word range remain unchanged when using
the words style.
Rich parsing diagnostics
diagnoseNumeric(value, target=None) returns an immutable ParseResult
instead of raising for invalid input. Successful results contain the normalized
or converted value and source and target representations. Failed results contain
one or more ParseDiagnostic objects with a stable code, message, source span,
severity, and suggested correction.
result = numbr.diagnoseNumeric("22st")
result.ok
# False
result.error.code, result.error.span
# ("invalid_ordinal_suffix", (0, 4))
result.error.suggestion
# "Use '22nd'."
Diagnostic codes distinguish empty or unsupported inputs, malformed decimal,
scientific, accounting, ordinal, grouping, word, and Roman forms, unknown
targets, and unsupported conversions. Call result.unwrap() when exception
semantics are preferred after inspection.
Batch conversion
batchCast(values, target) applies the same conversion rules as Cast to any
iterable. The errors policy controls failed items:
"raise"raisesBatchConversionErrorwith the failing index and diagnostic result."coerce"retains the input shape and placesNoneat failed positions."ignore"omits failed items.
numbr.batchCast(["one", "invalid", "III"], "Cardinal Number", errors="coerce")
# [1, None, 3]
results = numbr.batchDiagnose(["1e3", "bad", "(2.00)"], "Decimal Number")
[result.ok for result in results]
# [True, False, True]
Use batchDiagnose when every input needs an index-stable structured result,
regardless of success or failure.
Parsing and formatting
wordsToIntwordsToDecimalordinalWordsToIntstringToIntstringToDecimalscientificToDecimalaccountingToDecimalintToWordsdecimalToWordsdecimalToScientificdecimalToAccountingintToOrdinalWordsromanToIntromanToWordsintToRomanordinalSuffixstripOrdinalSuffixextractNumericValueextractNumericEntitiesnormalizeNumericTextdiagnoseNumericbatchDiagnosebatchCastinsertSepformatDecimal
The direct cross-representation helpers from earlier releases remain available,
including cardinalWordToOrdinalNum, ordinalNumToCardinalWord, and related
functions.
Lower-level parsing functions return None for invalid input. Decimal conversion
spells digits after the point individually so that zeros are preserved:
numbr.intToWords("1.05")
# "one point zero five"
Development
git clone git@github.com:doydl-technologies/numbr.git
cd numbr
python -m venv .venv
source .venv/bin/activate # .venv/Scripts/activate on MSYS2/Windows
python -m pip install -e '.[dev]'
pytest
ruff check .
python -m build
See CONTRIBUTING.md, SECURITY.md, CHANGELOG.md, and RELEASING.md for project policies, release history, and the maintainer release procedure.
License
Licensed under the MIT License.
Metadata
Release files for numbr 3.0.0
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 |
|---|---|---|---|---|
| numbr-3.0.0.tar.gz | 272.0 kB | Without provenance | Details for numbr-3.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| numbr-3.0.0-py3-none-any.whl | Python 3 | none | any | Details for numbr-3.0.0-py3-none-any.whl |
Total release size: 297.5 kB
Release files / numbr-3.0.0.tar.gz
| Download URL | numbr-3.0.0.tar.gz |
|---|---|
| Size | 272.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
449d214431fc3a17ebede9f493b175e1cb2ff54ffbf5aa1bfa4399b636bc6a9b
|
|
BLAKE2b-256 checksum How to use checksums |
0521ae4ce2c05cf2c964c5f331ff50c724daa876c07ab43ef651e6b7318a7a35
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / numbr-3.0.0-py3-none-any.whl
| Download URL | numbr-3.0.0-py3-none-any.whl |
|---|---|
| Size | 25.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ec031b4d0fa7110632b53fd66b2c14e275bdb64286fc45b6575f96eec5ff7084
|
|
BLAKE2b-256 checksum How to use checksums |
98863b1887395cf7b74ffbdd5b5a16d0a0f6182b82b707d4b0e5d0d699b58424
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for numbr 3.0.0
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.