Skip to main content

numbr

PyPI Python CI License

numbr parses and converts numbers represented as English cardinal words, English ordinal words, decimal digits, ordinal digits, and Roman numerals.

import numbr

numbr.wordsToInt("one hundred sixty-seven")
# 167

numbr.Cast("forty-ninth", "Ordinal Number")
# "49th"

numbr.Cast("Ⅳ", "Ordinal Word")
# "fourth"

numbr.extractNumericValue("He scored twenty-one of 34 attempts")
# [21, 34]

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/cedricmoorejr/numbr.git'

Python 3.8 or newer is required. The package has no runtime dependencies.

Representations

Representation Examples Type result
Cardinal number 42, "-42" "Cardinal Number"
Cardinal word "forty-two" "Cardinal Word"
Ordinal number "42nd" "Ordinal Number"
Ordinal word "forty-second" "Ordinal Word"
Roman numeral "XLII", "Ⅳ" "Roman Numeral"

Cast accepts those display names and common aliases such as int, cardword, ordnum, and roman.

numbr.Type("twenty-first")
# "Ordinal Word"

numbr.Cast("twenty-first", "Cardinal Number")
# 21

numbr.Cast(1994, "Roman Numeral")
# "MCMXCIV"

Roman output is limited to canonical values from 1 through 3999. English number conversion supports integers whose absolute value is less than 10**24.

Public API

General conversion

  • Type(value) detects the representation or returns None.
  • Cast(value, target, *, as_str=False) converts between representations and raises ValueError when the input or requested conversion is invalid.

Parsing and formatting

  • wordsToInt
  • ordinalWordsToInt
  • stringToInt
  • intToWords
  • intToOrdinalWords
  • romanToInt
  • romanToWords
  • intToRoman
  • ordinalSuffix
  • stripOrdinalSuffix
  • extractNumericValue
  • insertSep
  • formatDecimal

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:cedricmoorejr/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 2.1.0

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

Source distribution (sdist)

Source distribution for numbr 2.1.0
File Size Uploaded Provenance Actions
numbr-2.1.0.tar.gz 21.3 kB Without provenance Details for numbr-2.1.0.tar.gz

Built distribution (wheel)

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

Total release size: 37.6 kB

Release files / numbr-2.1.0.tar.gz

Download URL numbr-2.1.0.tar.gz
Size 21.3 kB
Tags Source
SHA-256 checksum
How to use checksums
9860e6f26419a8e9edd96c6084004b390bcb71af4aac4474362d02a8434c8d62
BLAKE2b-256 checksum
How to use checksums
25d89cabfded179f6db425ce3e8ebcbf2e4b95ca975f2283985a6cfeeb1b5cb1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.8.5

Release files / numbr-2.1.0-py3-none-any.whl

Download URL numbr-2.1.0-py3-none-any.whl
Size 16.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b96ceabc177423388ab50cf9b54707eed38dd5fcbef80316d88f805a5fb90b46
BLAKE2b-256 checksum
How to use checksums
15704f27bc4c2fdc596bd879cd14e20184c0002c53f80bc6638d0eaa62de601b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.8.5

Security for numbr 2.1.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.

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