numbr 3.0.0__tar.gz → 3.2.3__tar.gz

{numbr-3.0.0 → numbr-3.2.3}/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -10,7 +10,7 @@ body:
     id: version
     attributes:
       label: numbr version
-      placeholder: 3.0.0
+      placeholder: 3.2.3
     validations:
       required: true
   - type: input

{numbr-3.0.0 → numbr-3.2.3}/.github/workflows/ci.yml

@@ -55,7 +55,7 @@ jobs:
         run: |
           python -m pip install --force-reinstall dist/*.whl
           cd /tmp
-          python -I -c "import numbr; assert numbr.__version__ == '3.0.0'; assert numbr.Cast('Ⅳ', 'Ordinal Word') == 'fourth'"
+          python -I -c "import numbr; assert numbr.__version__ == '3.2.3'; assert numbr.Cast('Ⅳ', 'Ordinal Word') == 'fourth'"
       - name: Upload distributions
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:

{numbr-3.0.0 → numbr-3.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: numbr
-Version: 3.0.0
+Version: 3.2.3
 Summary: Parse, diagnose, batch-convert, extract, and normalize English numbers, exact decimals, scientific and accounting notation, and Roman numerals.
 Project-URL: Homepage, https://github.com/doydl-technologies/numbr
 Project-URL: Documentation, https://github.com/doydl-technologies/numbr#readme
@@ -44,7 +44,11 @@ Description-Content-Type: text/markdown
 
 ## Table of contents
 
+- [What numbr does](#what-numbr-does)
 - [Installation](#installation)
+- [Quick start](#quick-start)
+- [Choosing the right API](#choosing-the-right-api)
+- [Exact decimal values](#exact-decimal-values)
 - [Representations](#representations)
 - [Public API](#public-api)
   - [General conversion](#general-conversion)
@@ -57,73 +61,159 @@ Description-Content-Type: text/markdown
 - [Development](#development)
 - [License](#license)
 
-```python
-from decimal import Decimal
+## What numbr does
 
-import numbr
+`numbr` gives Python applications one consistent way to understand numbers
+written in different forms. It can recognize that `"forty-two"`, `"42"`, and
+`"XLII"` represent the same value, then convert them to the representation an
+application needs.
+
+The package is useful when numeric data arrives as human-written text rather
+than a clean integer or decimal. Common examples include form responses,
+documents, transcripts, scraped text, NLP pipelines, and imported business
+data.
 
-numbr.wordsToInt("one hundred sixty-seven")
-# 167
+With `numbr`, an application can:
 
-numbr.Cast("forty-ninth", "Ordinal Number")
-# "49th"
+- identify the representation of one numeric value;
+- convert between digits, English number words, ordinals, and Roman numerals;
+- parse exact decimals, scientific notation, and accounting notation;
+- find every numeric expression in a larger passage of text;
+- replace numeric expressions while leaving the surrounding text intact;
+- receive structured explanations for invalid input; and
+- apply the same conversion or diagnostic operation to an iterable of values.
 
-numbr.Cast("Ⅳ", "Ordinal Word")
-# "fourth"
+`numbr` is deterministic and rule-based. It does not use a language model,
+network service, locale database, or heuristic confidence score. The same
+supported input produces the same result on every platform.
 
-numbr.Cast("one point zero five", "Decimal Number")
-# Decimal("1.05")
+## Installation
+
+Install the latest release from PyPI:
 
-numbr.Cast(Decimal("1.050"), "Cardinal Word")
+```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/doydl-technologies/numbr.git'
+```
+
+Python 3.13 is required. The package has no runtime dependencies.
+
+## Quick start
+
+Import `numbr`, then choose an operation based on whether the input is one
+value, a passage of text, or a collection of values.
+
+```python
+import numbr
+
+# Identify how one value is written.
+numbr.Type("forty-second")
+# "Ordinal Word"
+
+# Convert one value to a requested representation.
+numbr.Cast("forty-second", "Cardinal Number")
+# 42
+
+numbr.Cast("1.050", "Cardinal Word")
 # "one point zero five zero"
 
-numbr.extractNumericValue("He scored twenty-one of 34 attempts")
-# [21, 34]
+# Collect normalized values from a larger passage.
+numbr.extractNumericValue("She placed 2nd with 1.05 points")
+# [2, Decimal("1.05")]
 
+# Collect values together with their original text and 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', ...)]
 
+# Rewrite recognized expressions without changing the surrounding sentence.
 numbr.normalizeNumericText("She placed forty-second with 1.20e3 points")
 # "She placed 42nd with 1200 points"
 
+# Apply one conversion to several values.
 numbr.batchCast(["one", "2", "III"], "Cardinal Number")
 # [1, 2, 3]
 ```
 
-## Installation
+The `Decimal(...)` text shown above is Python's representation of the returned
+value; the quick-start example does not need to import `Decimal`.
 
-Install the latest release from PyPI:
+## Choosing the right API
 
-```bash
-python -m pip install numbr
-```
+| Goal | API | Result |
+|---|---|---|
+| Identify how one value is written | `Type(value)` | A representation name such as `"Ordinal Word"`, or `None` |
+| Convert one value | `Cast(value, target)` | The value in the requested representation |
+| Collect only values from text | `extractNumericValue(text)` | A list of normalized `int` or `Decimal` values |
+| Collect values and source details | `extractNumericEntities(text)` | A list of `NumericMatch` records with text, type, value, and position |
+| Rewrite numbers inside text | `normalizeNumericText(text)` | A new string with recognized expressions normalized |
+| Explain why parsing failed | `diagnoseNumeric(value)` | A `ParseResult` containing either a value or structured diagnostics |
+| Convert many inputs | `batchCast(values, target)` | A list of converted values using the selected error policy |
+| Diagnose many inputs | `batchDiagnose(values, target)` | One index-stable `ParseResult` per input |
 
-Or install the current development version from GitHub:
+Conversion operates on one numeric value. Extraction searches a larger string
+and returns the numbers it contains. Normalization also searches a larger
+string, but returns rewritten text instead of match records.
 
-```bash
-python -m pip install 'numbr @ git+ssh://git@github.com/doydl-technologies/numbr.git'
+## Exact decimal values
+
+Decimal parsing returns [`decimal.Decimal`](https://docs.python.org/3/library/decimal.html#decimal.Decimal)
+instead of `float`. `Decimal` is part of Python's standard library; it is not an
+additional dependency. This avoids binary floating-point rounding and preserves
+meaningful fractional zeros such as the final zero in `"1.050"`.
+
+No `Decimal` import is required when the input is a string:
+
+```python
+import numbr
+
+value = numbr.Cast("1.050", "Decimal Number")
+
+value
+# Decimal("1.050")
+
+numbr.Cast(value, "Cardinal Word")
+# "one point zero five zero"
 ```
 
-Python 3.13 is required. The package has no runtime dependencies.
+Import `Decimal` only when application code needs to construct a decimal value
+directly or perform decimal arithmetic:
+
+```python
+from decimal import Decimal
+
+import numbr
+
+numbr.decimalToAccounting(Decimal("-1234.50"), currency="$")
+# "($1,234.50)"
+```
 
 ## Representations
 
-| Representation | Examples | `Type` result |
-|---|---|---|
-| Cardinal number | `42`, `"-42"` | `"Cardinal Number"` |
-| Decimal number | `"1.05"`, `Decimal("1.050")` | `"Decimal Number"` |
-| Scientific number | `"1.20e3"`, `"-4E-2"` | `"Scientific Number"` |
-| Accounting number | `"(1,234.50)"`, `"($50.00)"` | `"Accounting Number"` |
-| Cardinal word | `"forty-two"` | `"Cardinal Word"` |
-| Ordinal number | `"42nd"` | `"Ordinal Number"` |
-| Ordinal word | `"forty-second"` | `"Ordinal Word"` |
-| Roman numeral | `"XLII"`, `"Ⅳ"` | `"Roman Numeral"` |
+| Representation | Meaning | Examples | `Type` result |
+|---|---|---|---|
+| Cardinal number | A whole-number quantity written with digits | `42`, `"-42"` | `"Cardinal Number"` |
+| Decimal number | A fixed-point value with a fractional part | `"1.05"`, `Decimal("1.050")` | `"Decimal Number"` |
+| Scientific number | A coefficient multiplied by a power of ten | `"1.20e3"`, `"-4E-2"` | `"Scientific Number"` |
+| Accounting number | A formatted business value whose parentheses indicate a negative amount | `"(1,234.50)"`, `"($50.00)"` | `"Accounting Number"` |
+| Cardinal word | A quantity written with English words | `"forty-two"` | `"Cardinal Word"` |
+| Ordinal number | A position or rank written with digits and a suffix | `"42nd"` | `"Ordinal Number"` |
+| Ordinal word | A position or rank written with English words | `"forty-second"` | `"Ordinal Word"` |
+| Roman numeral | A value written with Roman symbols | `"XLII"`, `"Ⅳ"` | `"Roman Numeral"` |
 
 Decimal phrases such as `"one point zero five"` are cardinal-word forms. Digits
 following `point` are interpreted individually so precision and trailing zeros
 are preserved.
 
+English-word parsing is intended for numeric expressions, not unrestricted
+natural-language interpretation. Surrounding prose should be passed to an
+extraction or normalization API rather than directly to `Type` or `Cast`.
+
 `Cast` accepts the display names and common aliases such as `int`, `decimal`,
 `scientific`, `accounting`, `cardword`, `ordnum`, and `roman`.
 

{numbr-3.0.0 → numbr-3.2.3}/README.md

@@ -16,7 +16,11 @@
 
 ## Table of contents
 
+- [What numbr does](#what-numbr-does)
 - [Installation](#installation)
+- [Quick start](#quick-start)
+- [Choosing the right API](#choosing-the-right-api)
+- [Exact decimal values](#exact-decimal-values)
 - [Representations](#representations)
 - [Public API](#public-api)
   - [General conversion](#general-conversion)
@@ -29,73 +33,159 @@
 - [Development](#development)
 - [License](#license)
 
-```python
-from decimal import Decimal
+## What numbr does
 
-import numbr
+`numbr` gives Python applications one consistent way to understand numbers
+written in different forms. It can recognize that `"forty-two"`, `"42"`, and
+`"XLII"` represent the same value, then convert them to the representation an
+application needs.
+
+The package is useful when numeric data arrives as human-written text rather
+than a clean integer or decimal. Common examples include form responses,
+documents, transcripts, scraped text, NLP pipelines, and imported business
+data.
 
-numbr.wordsToInt("one hundred sixty-seven")
-# 167
+With `numbr`, an application can:
 
-numbr.Cast("forty-ninth", "Ordinal Number")
-# "49th"
+- identify the representation of one numeric value;
+- convert between digits, English number words, ordinals, and Roman numerals;
+- parse exact decimals, scientific notation, and accounting notation;
+- find every numeric expression in a larger passage of text;
+- replace numeric expressions while leaving the surrounding text intact;
+- receive structured explanations for invalid input; and
+- apply the same conversion or diagnostic operation to an iterable of values.
 
-numbr.Cast("Ⅳ", "Ordinal Word")
-# "fourth"
+`numbr` is deterministic and rule-based. It does not use a language model,
+network service, locale database, or heuristic confidence score. The same
+supported input produces the same result on every platform.
 
-numbr.Cast("one point zero five", "Decimal Number")
-# Decimal("1.05")
+## Installation
+
+Install the latest release from PyPI:
 
-numbr.Cast(Decimal("1.050"), "Cardinal Word")
+```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/doydl-technologies/numbr.git'
+```
+
+Python 3.13 is required. The package has no runtime dependencies.
+
+## Quick start
+
+Import `numbr`, then choose an operation based on whether the input is one
+value, a passage of text, or a collection of values.
+
+```python
+import numbr
+
+# Identify how one value is written.
+numbr.Type("forty-second")
+# "Ordinal Word"
+
+# Convert one value to a requested representation.
+numbr.Cast("forty-second", "Cardinal Number")
+# 42
+
+numbr.Cast("1.050", "Cardinal Word")
 # "one point zero five zero"
 
-numbr.extractNumericValue("He scored twenty-one of 34 attempts")
-# [21, 34]
+# Collect normalized values from a larger passage.
+numbr.extractNumericValue("She placed 2nd with 1.05 points")
+# [2, Decimal("1.05")]
 
+# Collect values together with their original text and 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', ...)]
 
+# Rewrite recognized expressions without changing the surrounding sentence.
 numbr.normalizeNumericText("She placed forty-second with 1.20e3 points")
 # "She placed 42nd with 1200 points"
 
+# Apply one conversion to several values.
 numbr.batchCast(["one", "2", "III"], "Cardinal Number")
 # [1, 2, 3]
 ```
 
-## Installation
+The `Decimal(...)` text shown above is Python's representation of the returned
+value; the quick-start example does not need to import `Decimal`.
 
-Install the latest release from PyPI:
+## Choosing the right API
 
-```bash
-python -m pip install numbr
-```
+| Goal | API | Result |
+|---|---|---|
+| Identify how one value is written | `Type(value)` | A representation name such as `"Ordinal Word"`, or `None` |
+| Convert one value | `Cast(value, target)` | The value in the requested representation |
+| Collect only values from text | `extractNumericValue(text)` | A list of normalized `int` or `Decimal` values |
+| Collect values and source details | `extractNumericEntities(text)` | A list of `NumericMatch` records with text, type, value, and position |
+| Rewrite numbers inside text | `normalizeNumericText(text)` | A new string with recognized expressions normalized |
+| Explain why parsing failed | `diagnoseNumeric(value)` | A `ParseResult` containing either a value or structured diagnostics |
+| Convert many inputs | `batchCast(values, target)` | A list of converted values using the selected error policy |
+| Diagnose many inputs | `batchDiagnose(values, target)` | One index-stable `ParseResult` per input |
 
-Or install the current development version from GitHub:
+Conversion operates on one numeric value. Extraction searches a larger string
+and returns the numbers it contains. Normalization also searches a larger
+string, but returns rewritten text instead of match records.
 
-```bash
-python -m pip install 'numbr @ git+ssh://git@github.com/doydl-technologies/numbr.git'
+## Exact decimal values
+
+Decimal parsing returns [`decimal.Decimal`](https://docs.python.org/3/library/decimal.html#decimal.Decimal)
+instead of `float`. `Decimal` is part of Python's standard library; it is not an
+additional dependency. This avoids binary floating-point rounding and preserves
+meaningful fractional zeros such as the final zero in `"1.050"`.
+
+No `Decimal` import is required when the input is a string:
+
+```python
+import numbr
+
+value = numbr.Cast("1.050", "Decimal Number")
+
+value
+# Decimal("1.050")
+
+numbr.Cast(value, "Cardinal Word")
+# "one point zero five zero"
 ```
 
-Python 3.13 is required. The package has no runtime dependencies.
+Import `Decimal` only when application code needs to construct a decimal value
+directly or perform decimal arithmetic:
+
+```python
+from decimal import Decimal
+
+import numbr
+
+numbr.decimalToAccounting(Decimal("-1234.50"), currency="$")
+# "($1,234.50)"
+```
 
 ## Representations
 
-| Representation | Examples | `Type` result |
-|---|---|---|
-| Cardinal number | `42`, `"-42"` | `"Cardinal Number"` |
-| Decimal number | `"1.05"`, `Decimal("1.050")` | `"Decimal Number"` |
-| Scientific number | `"1.20e3"`, `"-4E-2"` | `"Scientific Number"` |
-| Accounting number | `"(1,234.50)"`, `"($50.00)"` | `"Accounting Number"` |
-| Cardinal word | `"forty-two"` | `"Cardinal Word"` |
-| Ordinal number | `"42nd"` | `"Ordinal Number"` |
-| Ordinal word | `"forty-second"` | `"Ordinal Word"` |
-| Roman numeral | `"XLII"`, `"Ⅳ"` | `"Roman Numeral"` |
+| Representation | Meaning | Examples | `Type` result |
+|---|---|---|---|
+| Cardinal number | A whole-number quantity written with digits | `42`, `"-42"` | `"Cardinal Number"` |
+| Decimal number | A fixed-point value with a fractional part | `"1.05"`, `Decimal("1.050")` | `"Decimal Number"` |
+| Scientific number | A coefficient multiplied by a power of ten | `"1.20e3"`, `"-4E-2"` | `"Scientific Number"` |
+| Accounting number | A formatted business value whose parentheses indicate a negative amount | `"(1,234.50)"`, `"($50.00)"` | `"Accounting Number"` |
+| Cardinal word | A quantity written with English words | `"forty-two"` | `"Cardinal Word"` |
+| Ordinal number | A position or rank written with digits and a suffix | `"42nd"` | `"Ordinal Number"` |
+| Ordinal word | A position or rank written with English words | `"forty-second"` | `"Ordinal Word"` |
+| Roman numeral | A value written with Roman symbols | `"XLII"`, `"Ⅳ"` | `"Roman Numeral"` |
 
 Decimal phrases such as `"one point zero five"` are cardinal-word forms. Digits
 following `point` are interpreted individually so precision and trailing zeros
 are preserved.
 
+English-word parsing is intended for numeric expressions, not unrestricted
+natural-language interpretation. Surrounding prose should be passed to an
+extraction or normalization API rather than directly to `Type` or `Cast`.
+
 `Cast` accepts the display names and common aliases such as `int`, `decimal`,
 `scientific`, `accounting`, `cardword`, `ordnum`, and `roman`.
 

{numbr-3.0.0 → numbr-3.2.3}/RELEASING.md

@@ -49,27 +49,27 @@ a long-lived PyPI API token to the repository.
    source .release-venv/Scripts/activate
    python -m pip install dist/*.whl
    cd /tmp
-   python -I -c "import numbr; assert numbr.__version__ == '3.0.0'; assert numbr.Cast('Ⅳ', 'Ordinal Word') == 'fourth'"
+   python -I -c "import numbr; assert numbr.__version__ == '3.2.3'; assert numbr.Cast('Ⅳ', 'Ordinal Word') == 'fourth'"
    ```
 
 6. Review the wheel and source archive contents. Commit the release changes and
    merge them into `main` only after all required checks pass.
 
-## Publish 3.0.0
+## Publish 3.2.3
 
 1. On GitHub, draft a new release targeting `main`.
-2. Create tag `v3.0.0` and use release title `v3.0.0`.
-3. Use the approved `v3.0.0` release notes and reconcile them with the canonical
+2. Create tag `v3.2.3` and use release title `v3.2.3`.
+3. Use the approved `v3.2.3` release notes and reconcile them with the canonical
    changelog.
 4. Save a draft if more review is needed. Publishing the release is the point
    of no return: it triggers `.github/workflows/publish.yml`.
-5. Confirm that the workflow built both `numbr-3.0.0.tar.gz` and
-   `numbr-3.0.0-py3-none-any.whl`, validated the tag/version match, and published
+5. Confirm that the workflow built both `numbr-3.2.3.tar.gz` and
+   `numbr-3.2.3-py3-none-any.whl`, validated the tag/version match, and published
    through the `pypi` environment.
 6. Confirm the new release on PyPI and install it in a fresh environment:
 
    ```bash
-   python -m pip install --no-cache-dir numbr==3.0.0
+   python -m pip install --no-cache-dir numbr==3.2.3
    python -c "import numbr; print(numbr.__version__)"
    ```
 

{numbr-3.0.0 → numbr-3.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "numbr"
-version = "3.0.0"
+version = "3.2.3"
 description = "Parse, diagnose, batch-convert, extract, and normalize English numbers, exact decimals, scientific and accounting notation, and Roman numerals."
 readme = "README.md"
 requires-python = ">=3.13,<3.14"