numbr

A lightweight NLP-focused Python toolkit for recognising, parsing, and transforming numbers expressed in natural-language or symbolic form.
It handles everything from “forty-two” → 42 to “Ⅳ” → “fourth” in a single call.

✨ Key capabilities

(full API listed below)

🔧 Installation

pip install numbr     
# or install from source
pip install git+https://github.com/cedricmoorejr/numbr.git

🚀 Quick start

import numbr

numbr.Type("forty-ninth")
# → 'Ordinal Word'

numbr.Cast("forty-ninth", target="Ordinal Number")
# → '49th'

numbr.Cast(512, target="Ordinal Word")
# → 'five hundred twelve th'

🧰 Public API Overview

numbr exposes a clean, top-level API designed for simplicity and readability.
All functions listed below are available directly via:

import numbr

numbr.Type("twenty-first")
numbr.Cast("Ⅳ", target="Ordinal Word")

No internal modules need to be accessed directly — everything is exposed at the package root.

1. High-Level Helpers

2. Core Conversion Functions

These functions handle numeric parsing, word formatting, Roman numeral conversion, and formatting:

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

3. Cross-Type Shorthands

These helpers provide direct one-step conversions between common forms:

• cardinalWordToOrdinalNum
• ordinalNumToCardinalWord
• ordinalWordToCardinalNum
• ...and many more.

Use these when you know the source and target types and want to avoid an intermediate call to Cast.

📝 Roadmap

• Locale & language plugins (FR, DE…)
• Currency-aware formatting
• CLI utility

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

🙌 Contributing

Issues, pull-requests and feature ideas are very welcome to improve numbr!
Clone the repo, create a branch, add tests, and open a PR.

Happy number-crunching!