🔢 Parses, extracts, normalizes, and converts English number words, integers, exact decimals, scientific and accounting notation, ordinal digits, and Roman numerals.
🧭 Table of contents
- 🔍 What numbr does
- 📦 Installation
- 🚀 Quick start
- 🧰 Choosing the right API
- 🎯 Exact decimal values
- 🔢 Representations
- 🛠️ Public API
- 👨💻 Development
- ⚖️ License
🔍 What numbr does
numbr gives Python applications one consistent way to understand numbers written in different forms.
For example, it recognizes that:
| Input | Representation | Numeric value |
|---|---|---|
"forty-two" |
🔤 English words | 42 |
"42" |
🔢 Integer | 42 |
"XLII" |
🏛️ Roman numeral | 42 |
All three represent the same underlying value, which can then be converted into whichever representation your application needs.
💡 When is numbr useful?
The package is especially useful when numeric data arrives as human-written text rather than a clean integer or decimal.
Common use cases include:
- 📝 Form responses and documents
- 🎙️ Transcripts and speech-to-text output
- 🌐 Web scraping and extracted text
- 🧠 NLP and text-processing pipelines
- 🏢 Imported business and financial data
✨ What can it do?
With numbr, your application can:
- 🔍 Detect the representation of a numeric value.
- 🔄 Convert between digits, English number words, ordinals, and Roman numerals.
- 🎯 Parse exact decimals, scientific notation, and accounting notation.
- 📖 Extract numeric expressions from larger passages.
- ✏️ Normalize numeric expressions while preserving surrounding text.
- 🩺 Diagnose invalid input with structured explanations.
- 📚 Process batches of values using consistent conversion rules.
⚙️ How it works
numbr is deterministic and rule-based.
It does not use:
- ❌ Language models
- ❌ Network services
- ❌ Locale databases
- ❌ Heuristic confidence scores
✅ The same supported input produces the same result on every platform.
📦 Installation
1️⃣ Install from PyPI
Install the latest published release:
python -m pip install numbr
2️⃣ Alternative: Install from GitHub
Install the current development version:
python -m pip install 'numbr @ git+ssh://git@github.com/doydl-technologies/numbr.git'
📋 Requirements
| Requirement | Details |
|---|---|
| 🐍 Python | Version 3.13 |
| 📦 Runtime dependencies | None |
| 🌐 Network service | Not required for library operations |
✅ Lightweight by design: The package has no runtime dependencies.
🚀 Quick start
Import numbr, then choose an operation based on whether you're working with one value, a passage of text, or a collection.
🔍 Identify a representation
import numbr
numbr.Type("forty-second")
# "Ordinal Word"
🔄 Convert between representations
numbr.Cast("forty-second", "Cardinal Number")
# 42
numbr.Cast("1.050", "Cardinal Word")
# "one point zero five zero"
📖 Extract values from text
numbr.extractNumericValue("She placed 2nd with 1.05 points")
# [2, Decimal("1.05")]
📍 Extract values with source positions
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', ...)]
✏️ Normalize a sentence
numbr.normalizeNumericText("She placed forty-second with 1.20e3 points")
# "She placed 42nd with 1200 points"
📚 Convert multiple values
numbr.batchCast(["one", "2", "III"], "Cardinal Number")
# [1, 2, 3]
💡 Note: The
Decimal(...)text shown above is Python's representation of the returned value. You do not need to importDecimalfor this quick-start example.
🧰 Choosing the right API
Not sure which function to use? Start here.
| Goal | API | Result |
|---|---|---|
| 🔍 Identify one value | Type(value) |
A representation name, or None |
| 🔄 Convert one value | Cast(value, target) |
Value in the requested representation |
| 🔢 Extract values | extractNumericValue(text) |
List of normalized int or Decimal values |
| 📍 Extract with details | extractNumericEntities(text) |
NumericMatch records with source information |
| ✏️ Rewrite numeric text | normalizeNumericText(text) |
Text with recognized expressions normalized |
| 🩺 Explain parsing failures | diagnoseNumeric(value) |
ParseResult containing values or diagnostics |
| 📚 Convert multiple inputs | batchCast(values, target) |
Converted values under the selected error policy |
| 📋 Diagnose multiple inputs | batchDiagnose(values, target) |
Index-stable ParseResult records |
🤔 What's the difference?
- 🔄 Conversion: Operates on one numeric value.
- 🔍 Extraction: Searches a larger string and returns the numbers it contains.
- ✏️ Normalization: Searches a larger string and returns rewritten text instead of match records.
🎯 Exact decimal values
Precision matters, especially when working with financial or structured numeric data.
Instead of Python's float, decimal parsing returns decimal.Decimal.
✅ Why Decimal?
- Avoids binary floating-point representation errors.
- Preserves meaningful fractional zeros.
- Supports exact decimal arithmetic.
For example, "1.050" retains its trailing zero.
🐍 Example: Preserve decimal precision
import numbr
value = numbr.Cast("1.050", "Decimal Number")
value
# Decimal("1.050")
numbr.Cast(value, "Cardinal Word")
# "one point zero five zero"
💡 No additional dependency needed: Decimal belongs to Python's standard library.
You only need to import it when constructing decimal values directly or performing decimal arithmetic.
💵 Example: Accounting formatting
from decimal import Decimal
import numbr
numbr.decimalToAccounting(Decimal("-1234.50"), currency="$")
# "($1,234.50)"
🔢 Representations
numbr supports eight major numeric representations.
| Representation | Meaning | Examples | Type result |
|---|---|---|---|
| 🔢 Cardinal number | Whole-number quantity written in digits | 42, "-42" |
"Cardinal Number" |
| 🎯 Decimal number | Fixed-point value with fractional digits | "1.05", Decimal("1.050") |
"Decimal Number" |
| 🧪 Scientific number | Coefficient multiplied by a power of ten | "1.20e3", "-4E-2" |
"Scientific Number" |
| 💵 Accounting number | Business notation using parentheses for negative values | "(1,234.50)", "($50.00)" |
"Accounting Number" |
| 🔤 Cardinal word | Quantity written in English | "forty-two" |
"Cardinal Word" |
| 🥈 Ordinal number | Rank written with digits and suffix | "42nd" |
"Ordinal Number" |
| 🏅 Ordinal word | Rank written in English | "forty-second" |
"Ordinal Word" |
| 🏛️ Roman numeral | Value written with Roman symbols | "XLII", "Ⅳ" |
"Roman Numeral" |
📖 Understanding word-based decimals
Decimal phrases such as "one point zero five" are cardinal-word forms.
Digits after point are interpreted individually, preserving precision and trailing zeros.
⚠️ Important: English-word parsing is designed for numeric expressions, not unrestricted natural-language interpretation.
Pass surrounding prose to an extraction or normalization API instead of directly to Type or Cast.
🏷️ Accepted representation aliases
Cast accepts display names and common aliases, including:
int, decimal, scientific, accounting, cardword, ordnum, and roman.
🐍 Conversion examples
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"
📏 Supported ranges
- 🏛️ Roman numerals: Canonical values from
1through3999. - 🔤 English number conversion: Integer components with absolute values less than
10**24.
🛠️ Public API
🔄 General conversion
Two primary functions handle individual numeric expressions.
| Function | Purpose |
|---|---|
Type(value) |
Detects the representation or returns None |
Cast(value, target, *, as_str=False) |
Converts a value to the requested representation |
⚠️ Error handling: Cast raises ValueError when the input or requested conversion is invalid.
Decimal-number conversions return decimal.Decimal, avoiding binary floating-point rounding and preserving explicitly supplied fractional zeros.
Non-integral decimals cannot be cast to integer-only cardinal, ordinal, or Roman forms.
🧪 Scientific and accounting notation
numbr supports both scientific notation and accounting-style numeric formatting.
🔬 Scientific notation
Accepts signed coefficients and exponents, including:
.5e15.e21.20e3
💵 Accounting notation
Uses parentheses to represent negative amounts and accepts supported currency tokens immediately outside or inside the parentheses.
🐍 Conversion examples
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
Use extractNumericEntities(text) to locate every recognized numeric expression in a larger passage.
Each result is an immutable NumericMatch record.
📋 What each match contains
- 📝 Original
text - 🔢 Normalized
value - 🏷️ Representation name
- 📍
startandendoffsets - 📐 Source
span - 🥈
is_ordinalflag - ➖
is_negativeflag
🐍 Example: Extract entities and positions
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"
🏛️ Roman numeral handling
Canonical Roman numerals are included by default.
However, single-letter ASCII forms such as I, V, and X are excluded because they can be ambiguous in ordinary prose.
⚙️ Options:
include_single_roman=True— include single-letter Roman numerals.include_roman=False— exclude Roman numerals entirely.
📝 Whole-text normalization
Use normalizeNumericText(text, style="digits") to replace recognized numeric expressions while preserving all surrounding characters.
🎨 Available styles
| Style | Behavior |
|---|---|
🔢 style="digits" |
Converts recognized values into digits and retains ordinal suffixes |
🔤 style="words" |
Spells recognized values in English while retaining ordinal meaning |
🐍 Example: Normalize complete sentences
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"
📌 Additional behavior
Roman-numeral options match those available on extractNumericEntities.
Values outside the supported English-word range remain unchanged when using the words style.
🩺 Rich parsing diagnostics
Instead of raising an exception for invalid input, diagnoseNumeric(value, target=None) returns an immutable ParseResult.
This provides structured information about whether parsing succeeded and why it may have failed.
✅ Successful results include
- Normalized or converted value
- Source representation
- Target representation
❌ Failed results include
One or more ParseDiagnostic objects containing:
- 🏷️ Stable error code
- 📝 Explanatory message
- 📍 Source span
- 🚦 Severity
- 💡 Suggested correction
🐍 Example: Diagnose an invalid ordinal
result = numbr.diagnoseNumeric("22st")
result.ok
# False
result.error.code, result.error.span
# ("invalid_ordinal_suffix", (0, 4))
result.error.suggestion
# "Use '22nd'."
🧰 Supported diagnostic categories
Diagnostic codes distinguish:
- Empty or unsupported input
- Malformed decimals
- Invalid scientific notation
- Invalid accounting notation
- Invalid ordinal suffixes
- Invalid numeric grouping
- Invalid English-number words
- Invalid Roman numerals
- Unknown conversion targets
- Unsupported conversions
💡 Prefer exceptions? Call result.unwrap() after inspection.
📚 Batch conversion
Use batchCast(values, target) to apply the same conversion rules to any iterable.
⚙️ Error-handling policies
| Policy | Behavior |
|---|---|
🛑 "raise" |
Raises BatchConversionError with the failing index and diagnostic result |
🟡 "coerce" |
Retains the input shape and replaces failed positions with None |
⏭️ "ignore" |
Omits failed items |
🐍 Example: Convert with error handling
numbr.batchCast(["one", "invalid", "III"], "Cardinal Number", errors="coerce")
# [1, None, 3]
🔍 Example: Diagnose a batch
results = numbr.batchDiagnose(["1e3", "bad", "(2.00)"], "Decimal Number")
[result.ok for result in results]
# [True, False, True]
📌 When to use batchDiagnose: Choose it when every input needs an index-stable structured result, regardless of success or failure.
🧩 Parsing and formatting
numbr also exposes lower-level parsing, conversion, and formatting helpers.
| Category | Available functions |
|---|---|
| 🔤 English words | wordsToInt, wordsToDecimal, ordinalWordsToInt |
| 🔢 Numeric strings | stringToInt, stringToDecimal |
| 🧪 Scientific and accounting | scientificToDecimal, accountingToDecimal |
| ✏️ Number formatting | intToWords, decimalToWords, decimalToScientific, decimalToAccounting |
| 🥈 Ordinals | intToOrdinalWords, ordinalSuffix, stripOrdinalSuffix |
| 🏛️ Roman numerals | romanToInt, romanToWords, intToRoman |
| 🔍 Text extraction | extractNumericValue, extractNumericEntities |
| 📝 Text normalization | normalizeNumericText |
| 🩺 Diagnostics | diagnoseNumeric, batchDiagnose |
| 📚 Batch operations | batchCast, batchDiagnose |
| 🧰 Utilities | insertSep, formatDecimal |
🔙 Backward compatibility
Direct cross-representation helpers from earlier releases remain available, including:
cardinalWordToOrdinalNumordinalNumToCardinalWord- Related conversion functions
🎯 Decimal formatting behavior
Lower-level parsing functions return None for invalid input.
Decimal conversion spells digits after the point individually, preserving zeros.
numbr.intToWords("1.05")
# "one point zero five"
👨💻 Development
Want to contribute or work with the source code?
1️⃣ Clone the repository
git clone git@github.com:doydl-technologies/numbr.git
cd numbr
2️⃣ Create a virtual environment
python -m venv .venv
3️⃣ Activate the environment
Linux / macOS:
source .venv/bin/activate
MSYS2 / Windows:
source .venv/Scripts/activate
4️⃣ Install development dependencies
python -m pip install -e '.[dev]'
5️⃣ Run tests and quality checks
🧪 Run the test suite
pytest
🔍 Run Ruff
ruff check .
📦 Build the distribution
python -m build
📚 Contributor resources
⚖️ License
Licensed under the MIT License.
🔢 numbr
Built for predictable numeric parsing, extraction, normalization, and conversion.
Powered by DOYDL Technologies
Metadata
Release files for numbr 3.3.4
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.3.4.tar.gz | 124.8 kB | Without provenance | Details for numbr-3.3.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| numbr-3.3.4-py3-none-any.whl | Python 3 | none | any | Details for numbr-3.3.4-py3-none-any.whl |
Total release size: 153.0 kB
Release files / numbr-3.3.4.tar.gz
| Download URL | numbr-3.3.4.tar.gz |
|---|---|
| Size | 124.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
59a84872ad040be4a27d9cd16233d06f7e0715cb98b6889c85eea1d05b7f1bbe
|
|
BLAKE2b-256 checksum How to use checksums |
6f49e7b525a1da3394a9201640c875e7c67767a3d997418352538a4a119bdf93
|
| 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.3.4-py3-none-any.whl
| Download URL | numbr-3.3.4-py3-none-any.whl |
|---|---|
| Size | 28.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f90bdc5fa325a99149d203d5f5855efe588e5c588f94cf9c6e0532a3a0151ab2
|
|
BLAKE2b-256 checksum How to use checksums |
f2d3765f014f230112bdce639d45f87ccc32083765482e0320fb5faf83858506
|
| 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.3.4
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.