Metadata-Version: 2.4
Name: numbr
Version: 2.1.0
Summary: Parse and convert English cardinal, ordinal, digit, and Roman numeral representations.
Project-URL: Homepage, https://github.com/cedricmoorejr/numbr
Project-URL: Documentation, https://github.com/cedricmoorejr/numbr#readme
Project-URL: Issues, https://github.com/cedricmoorejr/numbr/issues
Project-URL: Changelog, https://github.com/cedricmoorejr/numbr/blob/main/CHANGELOG.md
Author: Cedric Moore Jr.
License-Expression: MIT
License-File: LICENSE
Keywords: nlp,numbers,ordinals,parser,roman-numerals
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Requires-Dist: twine>=5.1; extra == 'dev'
Description-Content-Type: text/markdown

# numbr

[![PyPI](https://img.shields.io/pypi/v/numbr)](https://pypi.org/project/numbr/)
[![Python](https://img.shields.io/pypi/pyversions/numbr)](https://pypi.org/project/numbr/)
[![CI](https://github.com/cedricmoorejr/numbr/actions/workflows/ci.yml/badge.svg)](https://github.com/cedricmoorejr/numbr/actions/workflows/ci.yml)
[![License](https://img.shields.io/github/license/cedricmoorejr/numbr)](LICENSE)

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

```python
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:

```bash
python -m pip install numbr
```

Or install the current development version from GitHub:

```bash
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`.

```python
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:

```python
numbr.intToWords("1.05")
# "one point zero five"
```

## Development

```bash
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](CONTRIBUTING.md), [SECURITY.md](SECURITY.md),
[CHANGELOG.md](CHANGELOG.md), and [RELEASING.md](RELEASING.md) for project
policies, release history, and the maintainer release procedure.

## License

Licensed under the [MIT License](LICENSE).
