Skip to main content

numbr

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

PyPI version Supported Python versions Downloads Powered by DOYDL Technologies

Table of contents

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/doydl-technologies/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: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 2.1.1

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.1
File Size Uploaded Provenance Actions
numbr-2.1.1.tar.gz 286.9 kB Without provenance Details for numbr-2.1.1.tar.gz

Built distribution (wheel)

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

Total release size: 303.4 kB

Release files / numbr-2.1.1.tar.gz

Download URL numbr-2.1.1.tar.gz
Size 286.9 kB
Tags Source
SHA-256 checksum
How to use checksums
95655255c333a00123113c295f191d2cc30177e5ba3f448aedef74045d00db0e
BLAKE2b-256 checksum
How to use checksums
4f6195664e5b514b42af4417a9c160d647deedf326f8ff90c70a40ef01957e15
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.1-py3-none-any.whl

Download URL numbr-2.1.1-py3-none-any.whl
Size 16.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0a82e339f144fee92cab46848fade1d41b584716264e9ab9c087822de57fd1d9
BLAKE2b-256 checksum
How to use checksums
ff94b8905512119e3eeb7d16b85c6af3a450a4f847a323f3ed6d6e1a99be3b75
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.1

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