icu-rbnf 0.2.0__tar.gz

icu_rbnf-0.2.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: icu_rbnf
+Version: 0.2.0
+Summary: Spell out numbers into words using ICU RBNF
+Home-page: https://github.com/OHF-voice/icu-rbnf
+Author: The Home Assistant Authors
+Author-email: hello@home-assistant.io
+Project-URL: Homepage, https://github.com/OHF-voice/icu-rbnf
+Project-URL: Issues, https://github.com/OHF-voice/icu-rbnf/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: C
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pylint; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-python
+Dynamic: summary
+
+# icu_rbnf
+
+A Python library for spelling out numbers into words using ICU's Rule-Based Number Format (RBNF).
+
+## Installation
+
+```bash
+pip install icu_rbnf
+```
+
+## Usage
+
+```python
+import icu_rbnf
+
+# Spell out numbers in words
+icu_rbnf.spellout(123, "en_US")     # "one hundred twenty-three"
+icu_rbnf.spellout(123.7, "en_US")   # "one hundred twenty-three point seven"
+icu_rbnf.spellout(123, "fr_FR")     # "cent vingt-trois"
+
+# Get ordinal form (e.g., "1st", "2nd")
+icu_rbnf.ordinal(21, "en_US")       # "21st"
+
+# Get word-based ordinal (e.g., "first", "twenty-first")
+icu_rbnf.spellout_ordinal(21, "en_US")  # "twenty-first"
+
+# Check if a locale is supported
+icu_rbnf.is_locale_supported("en_US")  # True
+```
+
+## API
+
+### `spellout(number: int | float, locale: str) -> str`
+
+Spell out a number into words for the given locale. Supports both integers and floats.
+
+### `ordinal(number: int | float, locale: str) -> str`
+
+Get the ordinal form of a number for the given locale (e.g., "1st", "2nd"). Floats are truncated to integers.
+
+### `spellout_ordinal(number: int | float, locale: str) -> str`
+
+Spell out ordinal form of a number for the given locale (e.g., "first", "twenty-first"). Floats are truncated to integers. Note: Not all locales support word-based ordinals; some may fall back to numeric format.
+
+### `is_locale_supported(locale: str) -> bool`
+
+Check if a locale is supported by ICU RBNF.
+
+### `error`
+
+Exception class raised when ICU RBNF operations fail.
+
+## Requirements
+
+- Python 3.9+
+- ICU library (dynamically linked, no separate installation required)

icu_rbnf-0.2.0/README.md

@@ -0,0 +1,56 @@
+# icu_rbnf
+
+A Python library for spelling out numbers into words using ICU's Rule-Based Number Format (RBNF).
+
+## Installation
+
+```bash
+pip install icu_rbnf
+```
+
+## Usage
+
+```python
+import icu_rbnf
+
+# Spell out numbers in words
+icu_rbnf.spellout(123, "en_US")     # "one hundred twenty-three"
+icu_rbnf.spellout(123.7, "en_US")   # "one hundred twenty-three point seven"
+icu_rbnf.spellout(123, "fr_FR")     # "cent vingt-trois"
+
+# Get ordinal form (e.g., "1st", "2nd")
+icu_rbnf.ordinal(21, "en_US")       # "21st"
+
+# Get word-based ordinal (e.g., "first", "twenty-first")
+icu_rbnf.spellout_ordinal(21, "en_US")  # "twenty-first"
+
+# Check if a locale is supported
+icu_rbnf.is_locale_supported("en_US")  # True
+```
+
+## API
+
+### `spellout(number: int | float, locale: str) -> str`
+
+Spell out a number into words for the given locale. Supports both integers and floats.
+
+### `ordinal(number: int | float, locale: str) -> str`
+
+Get the ordinal form of a number for the given locale (e.g., "1st", "2nd"). Floats are truncated to integers.
+
+### `spellout_ordinal(number: int | float, locale: str) -> str`
+
+Spell out ordinal form of a number for the given locale (e.g., "first", "twenty-first"). Floats are truncated to integers. Note: Not all locales support word-based ordinals; some may fall back to numeric format.
+
+### `is_locale_supported(locale: str) -> bool`
+
+Check if a locale is supported by ICU RBNF.
+
+### `error`
+
+Exception class raised when ICU RBNF operations fail.
+
+## Requirements
+
+- Python 3.9+
+- ICU library (dynamically linked, no separate installation required)

icu_rbnf-0.2.0/icu_rbnf/__init__.py

@@ -0,0 +1,22 @@
+"""ICU RBNF - Spell out numbers into words using ICU's Rule-Based Number Format."""
+
+from __future__ import annotations
+
+from icu_rbnf._icu import (
+    error,
+    icu_version,
+    is_locale_supported,
+    ordinal,
+    spellout,
+    spellout_ordinal,
+)
+
+__all__ = [
+    "spellout",
+    "ordinal",
+    "spellout_ordinal",
+    "is_locale_supported",
+    "icu_version",
+    "error",
+]
+__version__ = "0.2.0"

icu_rbnf-0.2.0/icu_rbnf/__init__.pyi

@@ -0,0 +1,28 @@
+"""Type stubs for icu_rbnf."""
+
+from typing import Union
+
+class RBNFError(Exception):
+    """Exception raised when ICU RBNF operations fail."""
+
+def spellout(number: Union[int, float], locale: str) -> str:
+    """Spell out a number into words for the given locale."""
+    ...
+
+def ordinal(number: Union[int, float], locale: str) -> str:
+    """Get the ordinal form of a number for the given locale (e.g., '1st', '2nd')."""
+    ...
+
+def spellout_ordinal(number: Union[int, float], locale: str) -> str:
+    """Spell out ordinal form of a number for the given locale (e.g., 'first', 'twenty-first')."""
+    ...
+
+def icu_version() -> str:
+    """Version of the ICU library this extension is linked against."""
+    ...
+
+def is_locale_supported(locale: str) -> bool:
+    """Check if a locale is supported by ICU RBNF."""
+    ...
+
+error: RBNFError

icu_rbnf-0.2.0/icu_rbnf.egg-info/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: icu_rbnf
+Version: 0.2.0
+Summary: Spell out numbers into words using ICU RBNF
+Home-page: https://github.com/OHF-voice/icu-rbnf
+Author: The Home Assistant Authors
+Author-email: hello@home-assistant.io
+Project-URL: Homepage, https://github.com/OHF-voice/icu-rbnf
+Project-URL: Issues, https://github.com/OHF-voice/icu-rbnf/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: C
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pylint; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-python
+Dynamic: summary
+
+# icu_rbnf
+
+A Python library for spelling out numbers into words using ICU's Rule-Based Number Format (RBNF).
+
+## Installation
+
+```bash
+pip install icu_rbnf
+```
+
+## Usage
+
+```python
+import icu_rbnf
+
+# Spell out numbers in words
+icu_rbnf.spellout(123, "en_US")     # "one hundred twenty-three"
+icu_rbnf.spellout(123.7, "en_US")   # "one hundred twenty-three point seven"
+icu_rbnf.spellout(123, "fr_FR")     # "cent vingt-trois"
+
+# Get ordinal form (e.g., "1st", "2nd")
+icu_rbnf.ordinal(21, "en_US")       # "21st"
+
+# Get word-based ordinal (e.g., "first", "twenty-first")
+icu_rbnf.spellout_ordinal(21, "en_US")  # "twenty-first"
+
+# Check if a locale is supported
+icu_rbnf.is_locale_supported("en_US")  # True
+```
+
+## API
+
+### `spellout(number: int | float, locale: str) -> str`
+
+Spell out a number into words for the given locale. Supports both integers and floats.
+
+### `ordinal(number: int | float, locale: str) -> str`
+
+Get the ordinal form of a number for the given locale (e.g., "1st", "2nd"). Floats are truncated to integers.
+
+### `spellout_ordinal(number: int | float, locale: str) -> str`
+
+Spell out ordinal form of a number for the given locale (e.g., "first", "twenty-first"). Floats are truncated to integers. Note: Not all locales support word-based ordinals; some may fall back to numeric format.
+
+### `is_locale_supported(locale: str) -> bool`
+
+Check if a locale is supported by ICU RBNF.
+
+### `error`
+
+Exception class raised when ICU RBNF operations fail.
+
+## Requirements
+
+- Python 3.9+
+- ICU library (dynamically linked, no separate installation required)

icu_rbnf-0.2.0/icu_rbnf.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+setup.cfg
+setup.py
+icu_rbnf/__init__.py
+icu_rbnf/__init__.pyi
+icu_rbnf/py.typed
+icu_rbnf.egg-info/PKG-INFO
+icu_rbnf.egg-info/SOURCES.txt
+icu_rbnf.egg-info/dependency_links.txt
+icu_rbnf.egg-info/requires.txt
+icu_rbnf.egg-info/top_level.txt
+src/icu_rbnf.cpp
+tests/test_icu_rbnf.py

icu_rbnf-0.2.0/icu_rbnf.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

icu_rbnf-0.2.0/icu_rbnf.egg-info/requires.txt

@@ -0,0 +1,8 @@
+
+[dev]
+black
+flake8
+mypy
+pylint
+pytest
+build

icu_rbnf-0.2.0/icu_rbnf.egg-info/top_level.txt

@@ -0,0 +1 @@
+icu_rbnf

icu_rbnf-0.2.0/pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"

icu_rbnf-0.2.0/setup.cfg

@@ -0,0 +1,24 @@
+[bdist_wheel]
+py_limited_api = cp39
+
+[flake8]
+max-line-length = 88
+ignore = 
+	E501,
+	W503,
+	E203,
+	D202,
+	W504
+
+[isort]
+multi_line_output = 3
+include_trailing_comma = True
+force_grid_wrap = 0
+use_parentheses = True
+line_length = 88
+indent = "    "
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

icu_rbnf-0.2.0/setup.py

@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+"""Setup script for icu_rbnf - uses setuptools with C extension."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from setuptools import Extension, setup
+from setuptools.command.build_ext import build_ext
+
+# Try to find ICU using pkg-config
+def get_icu_cflags():
+    """Get ICU compiler flags from pkg-config."""
+    try:
+        result = subprocess.run(
+            ["pkg-config", "--cflags", "icu-uc", "icu-i18n"],
+            capture_output=True,
+            text=True,
+            check=True
+        )
+        return result.stdout.strip().split()
+    except subprocess.CalledProcessError:
+        return []
+
+def get_icu_ldflags():
+    """Get ICU linker flags from pkg-config."""
+    try:
+        result = subprocess.run(
+            ["pkg-config", "--libs", "icu-uc", "icu-i18n"],
+            capture_output=True,
+            text=True,
+            check=True
+        )
+        return result.stdout.strip().split()
+    except subprocess.CalledProcessError:
+        return []
+
+class BuildExtWithICU(build_ext):
+    """Custom build_ext that ensures ICU is found."""
+    
+    def build_extension(self, ext):
+        # Add ICU flags if not already present
+        if not ext.extra_compile_args:
+            ext.extra_compile_args = get_icu_cflags()
+        if not ext.extra_link_args:
+            ext.extra_link_args = get_icu_ldflags()
+        
+        super().build_extension(ext)
+
+
+# Define the extension module - use C++ for ICU
+ext_modules = [
+    Extension(
+        "icu_rbnf._icu",
+        sources=["src/icu_rbnf.cpp"],
+        define_macros=[("PY_SSIZE_T_CLEAN", "1")],
+        include_dirs=[],
+        py_limited_api=True,
+        extra_compile_args=get_icu_cflags(),
+        extra_link_args=get_icu_ldflags(),
+    )
+]
+
+# Get long description from README
+readme_path = Path(__file__).parent / "README.md"
+long_description = ""
+if readme_path.exists():
+    long_description = readme_path.read_text(encoding="utf-8")
+
+setup(
+    name="icu_rbnf",
+    version="0.2.0",
+    description="Spell out numbers into words using ICU RBNF",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    author="The Home Assistant Authors",
+    author_email="hello@home-assistant.io",
+    url="https://github.com/OHF-voice/icu-rbnf",
+    project_urls={
+        "Homepage": "https://github.com/OHF-voice/icu-rbnf",
+        "Issues": "https://github.com/OHF-voice/icu-rbnf/issues",
+    },
+    packages=["icu_rbnf"],
+    package_dir={"icu_rbnf": "icu_rbnf"},
+    package_data={"icu_rbnf": ["py.typed"]},
+    ext_modules=ext_modules,
+    cmdclass={"build_ext": BuildExtWithICU},
+    python_requires=">=3.9",
+    classifiers=[
+        "Development Status :: 4 - Beta",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: Apache Software License",
+        "Operating System :: OS Independent",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Programming Language :: Python :: 3.13",
+        "Programming Language :: C",
+    ],
+    extras_require={
+        "dev": [
+            "black",
+            "flake8",
+            "mypy",
+            "pylint",
+            "pytest",
+            "build",
+        ],
+    },
+)

icu_rbnf-0.2.0/src/icu_rbnf.cpp

@@ -0,0 +1,346 @@
+#define PY_SSIZE_T_CLEAN
+#include <Python.h>
+#include <unicode/utypes.h>
+#include <unicode/uversion.h>
+#include <unicode/rbnf.h>
+#include <unicode/locid.h>
+#include <unicode/unistr.h>
+#include <unicode/ustream.h>
+
+static PyObject* icu_rbnf_error = NULL;
+
+/* Helper to convert ICU UnicodeString to Python string */
+static PyObject* unicode_string_to_pystring(const icu::UnicodeString* us) {
+    if (!us) {
+        Py_RETURN_NONE;
+    }
+
+    char* buffer = NULL;
+    int32_t len = 0;
+
+    /* Convert to UTF-8 */
+    len = us->extract(0, us->length(), NULL, 0, "UTF-8");
+    if (len < 0) {
+        PyErr_SetString(icu_rbnf_error, "Failed to get string length");
+        return NULL;
+    }
+
+    buffer = (char*)PyMem_Malloc(len + 1);
+    if (!buffer) {
+        PyErr_NoMemory();
+        return NULL;
+    }
+
+    us->extract(0, us->length(), buffer, len + 1, "UTF-8");
+    buffer[len] = '\0';
+
+    PyObject* result = PyUnicode_FromString(buffer);
+    PyMem_Free(buffer);
+    return result;
+}
+
+/* Helper to convert Python number to int64_t */
+static int parse_number(PyObject* obj, int64_t* result) {
+    /* Try int first */
+    if (PyLong_Check(obj)) {
+        *result = PyLong_AsLongLong(obj);
+        return PyErr_Occurred() ? -1 : 0;
+    }
+
+    /* Try float */
+    if (PyFloat_Check(obj)) {
+        double d = PyFloat_AsDouble(obj);
+        if (PyErr_Occurred()) {
+            return -1;
+        }
+        *result = (int64_t)d;
+        return 0;
+    }
+
+    /* Try to convert via float */
+    PyObject* float_obj = PyNumber_Float(obj);
+    if (float_obj) {
+        double d = PyFloat_AsDouble(float_obj);
+        Py_DECREF(float_obj);
+        if (PyErr_Occurred()) {
+            return -1;
+        }
+        *result = (int64_t)d;
+        return 0;
+    }
+
+    PyErr_SetString(PyExc_TypeError, "argument must be a number");
+    return -1;
+}
+
+/* Helper to convert Python number to double */
+static int parse_number_double(PyObject* obj, double* result) {
+    /* Try to convert via float */
+    PyObject* float_obj = PyNumber_Float(obj);
+    if (float_obj) {
+        *result = PyFloat_AsDouble(float_obj);
+        Py_DECREF(float_obj);
+        if (PyErr_Occurred()) {
+            return -1;
+        }
+        return 0;
+    }
+
+    PyErr_SetString(PyExc_TypeError, "argument must be a number");
+    return -1;
+}
+
+/* Check if a locale is supported by ICU RBNF */
+static PyObject* rbnf_is_locale_supported(PyObject* self, PyObject* args) {
+    const char* locale_str;
+
+    if (!PyArg_ParseTuple(args, "s", &locale_str)) {
+        return NULL;
+    }
+
+    /* ICU is very permissive and falls back to default locale for invalid inputs.
+     * We check if the locale string is syntactically valid and if ICU can create
+     * a formatter with it. Since ICU always succeeds with fallback, we just verify
+     * that the locale string is non-empty and contains valid characters.
+     *
+     * A locale string should be in the format: language[_SCRIPT][_REGION]
+     * where language is 2-3 letter ISO 639 code, SCRIPT is 4 letter ISO 15924 code,
+     * and REGION is 2-3 letter ISO 3166 code.
+     */
+
+    /* Basic validation: locale string must not be empty */
+    if (!locale_str || locale_str[0] == '\0') {
+        Py_RETURN_FALSE;
+    }
+
+    /* Check for basic validity - should contain only alphanumeric, underscore, hyphen */
+    for (const char* p = locale_str; *p; ++p) {
+        if (!isalnum((unsigned char)*p) && *p != '_' && *p != '-') {
+            Py_RETURN_FALSE;
+        }
+    }
+
+    /* Try to create a spellout formatter to verify ICU can handle it */
+    UErrorCode status = U_ZERO_ERROR;
+    icu::Locale locale(locale_str);
+
+    /* Check if the locale is valid by checking its name */
+    icu::UnicodeString locale_name = locale.getName();
+    if (locale_name.isEmpty()) {
+        Py_RETURN_FALSE;
+    }
+
+    /* Try to create a formatter */
+    icu::RuleBasedNumberFormat* rbnf = nullptr;
+    rbnf = new icu::RuleBasedNumberFormat(icu::URBNF_SPELLOUT, locale, status);
+
+    if (U_FAILURE(status) || !rbnf) {
+        delete rbnf;
+        Py_RETURN_FALSE;
+    }
+
+    delete rbnf;
+    Py_RETURN_TRUE;
+}
+
+/* Spell out a number using ICU RBNF (supports both integers and floats) */
+static PyObject* rbnf_spellout(PyObject* self, PyObject* args) {
+    PyObject* number_obj;
+    const char* locale_str;
+
+    if (!PyArg_ParseTuple(args, "Os", &number_obj, &locale_str)) {
+        return NULL;
+    }
+
+    /* Get the number as double (supports both int and float) */
+    double number;
+    if (parse_number_double(number_obj, &number) != 0) {
+        return NULL;
+    }
+
+    /* Create locale */
+    UErrorCode status = U_ZERO_ERROR;
+    icu::Locale locale(locale_str);
+
+    /* Create RBNF rules for spellout */
+    icu::RuleBasedNumberFormat* rbnf = nullptr;
+
+    /* Use the spellout format (spoken number) */
+    rbnf = new icu::RuleBasedNumberFormat(icu::URBNF_SPELLOUT, locale, status);
+
+    if (U_FAILURE(status) || !rbnf) {
+        PyErr_SetString(icu_rbnf_error, "Failed to create RBNF formatter");
+        delete rbnf;
+        return NULL;
+    }
+
+    /* Format the number - ICU handles both integers and floats */
+    icu::UnicodeString result;
+    rbnf->format(number, result);
+
+    delete rbnf;
+
+    return unicode_string_to_pystring(&result);
+}
+
+/* Get ordinal form of a number (e.g., "1st", "2nd") */
+static PyObject* rbnf_ordinal(PyObject* self, PyObject* args) {
+    PyObject* number_obj;
+    const char* locale_str;
+
+    if (!PyArg_ParseTuple(args, "Os", &number_obj, &locale_str)) {
+        return NULL;
+    }
+
+    /* Get the number as int64_t (truncate floats) */
+    int64_t number;
+    if (parse_number(number_obj, &number) != 0) {
+        return NULL;
+    }
+
+    /* Create locale */
+    UErrorCode status = U_ZERO_ERROR;
+    icu::Locale locale(locale_str);
+
+    /* Create RBNF rules for ordinal */
+    icu::RuleBasedNumberFormat* rbnf = nullptr;
+
+    /* Use the ordinal format */
+    rbnf = new icu::RuleBasedNumberFormat(icu::URBNF_ORDINAL, locale, status);
+
+    if (U_FAILURE(status) || !rbnf) {
+        PyErr_SetString(icu_rbnf_error, "Failed to create RBNF formatter");
+        delete rbnf;
+        return NULL;
+    }
+
+    /* Format the number */
+    icu::UnicodeString result;
+    rbnf->format(number, result);
+
+    delete rbnf;
+
+    return unicode_string_to_pystring(&result);
+}
+
+/* Spell out ordinal form of a number (e.g., "first", "twenty-first") */
+static PyObject* rbnf_spellout_ordinal(PyObject* self, PyObject* args) {
+    PyObject* number_obj;
+    const char* locale_str;
+
+    if (!PyArg_ParseTuple(args, "Os", &number_obj, &locale_str)) {
+        return NULL;
+    }
+
+    /* Get the number as int64_t (truncate floats) */
+    int64_t number;
+    if (parse_number(number_obj, &number) != 0) {
+        return NULL;
+    }
+
+    /* Create locale */
+    UErrorCode status = U_ZERO_ERROR;
+    icu::Locale locale(locale_str);
+
+    /* Create RBNF rules for spellout */
+    icu::RuleBasedNumberFormat* rbnf = nullptr;
+    rbnf = new icu::RuleBasedNumberFormat(icu::URBNF_SPELLOUT, locale, status);
+
+    if (U_FAILURE(status) || !rbnf) {
+        PyErr_SetString(icu_rbnf_error, "Failed to create RBNF formatter");
+        delete rbnf;
+        return NULL;
+    }
+
+    /* Try to use the %spellout-ordinal ruleset if available */
+    icu::UnicodeString result;
+    bool used_ordinal_ruleset = false;
+
+    /* Check if the ruleset exists by trying to set it */
+    icu::UnicodeString ruleset_name("%spellout-ordinal");
+    icu::UnicodeString original_default = rbnf->getDefaultRuleSetName();
+
+    status = U_ZERO_ERROR;
+    rbnf->setDefaultRuleSet(ruleset_name, status);
+
+    if (U_SUCCESS(status)) {
+        /* The ruleset exists and was set - format using it */
+        rbnf->format(number, result);
+        used_ordinal_ruleset = true;
+    }
+
+    /* Fallback to regular ordinal format if %spellout-ordinal not available */
+    if (!used_ordinal_ruleset) {
+        delete rbnf;
+        status = U_ZERO_ERROR;  /* Reset status for new formatter */
+        rbnf = new icu::RuleBasedNumberFormat(icu::URBNF_ORDINAL, locale, status);
+        if (U_FAILURE(status) || !rbnf) {
+            PyErr_SetString(icu_rbnf_error, "Failed to create RBNF formatter");
+            delete rbnf;
+            return NULL;
+        }
+        rbnf->format(number, result);
+    }
+
+    delete rbnf;
+
+    return unicode_string_to_pystring(&result);
+}
+
+/* Version of the ICU the extension was built and linked against.
+
+   Worth exposing rather than leaving implicit: the spellout rules are ICU's
+   data, so the ICU version *is* the CLDR version, and a wheel built on an old
+   base image silently ships decade-old number rules. Making it readable lets a
+   test assert a floor. */
+static PyObject* rbnf_icu_version(PyObject* self, PyObject* args) {
+    (void)self;
+    if (!PyArg_ParseTuple(args, "")) {
+        return NULL;
+    }
+
+    UVersionInfo version;
+    char buffer[U_MAX_VERSION_STRING_LENGTH];
+    u_getVersion(version);
+    u_versionToString(version, buffer);
+    return PyUnicode_FromString(buffer);
+}
+
+/* Module methods */
+static PyMethodDef IcuRbnfMethods[] = {
+    {"is_locale_supported", rbnf_is_locale_supported, METH_VARARGS, "Check if a locale is supported by ICU RBNF"},
+    {"spellout", rbnf_spellout, METH_VARARGS, "Spell out a number in words"},
+    {"icu_version", rbnf_icu_version, METH_VARARGS, "ICU library version this extension is linked against"},
+    {"ordinal", rbnf_ordinal, METH_VARARGS, "Get ordinal form of a number (e.g., '1st', '2nd')"},
+    {"spellout_ordinal", rbnf_spellout_ordinal, METH_VARARGS, "Spell out ordinal form of a number (e.g., 'first', 'twenty-first')"},
+    {NULL, NULL, 0, NULL}
+};
+
+/* Module definition */
+static struct PyModuleDef icu_rbnf_module = {
+    PyModuleDef_HEAD_INIT,
+    "_icu",
+    "ICU RBNF extension module",
+    -1,
+    IcuRbnfMethods,
+    NULL,
+    NULL,
+    NULL,
+    NULL
+};
+
+/* Module initialization */
+PyMODINIT_FUNC PyInit__icu(void) {
+    PyObject* m = PyModule_Create(&icu_rbnf_module);
+    if (!m) {
+        return NULL;
+    }
+
+    /* Create exception class */
+    icu_rbnf_error = PyErr_NewException("icu_rbnf.error", NULL, NULL);
+    if (icu_rbnf_error) {
+        PyModule_AddObject(m, "error", icu_rbnf_error);
+    }
+
+    return m;
+}

icu_rbnf-0.2.0/tests/test_icu_rbnf.py

@@ -0,0 +1,248 @@
+"""Tests for icu_rbnf library."""
+
+import icu_rbnf
+
+
+class TestSpellout:
+    """Tests for the spellout function."""
+
+    def test_english_basic(self):
+        """Test basic number spellout in English."""
+        assert icu_rbnf.spellout(0, "en_US") == "zero"
+        assert icu_rbnf.spellout(1, "en_US") == "one"
+        assert icu_rbnf.spellout(12, "en_US") == "twelve"
+        assert icu_rbnf.spellout(20, "en_US") == "twenty"
+        assert icu_rbnf.spellout(42, "en_US") == "forty-two"
+        assert icu_rbnf.spellout(100, "en_US") == "one hundred"
+        assert icu_rbnf.spellout(123, "en_US") == "one hundred twenty-three"
+        assert icu_rbnf.spellout(999, "en_US") == "nine hundred ninety-nine"
+
+    def test_french_basic(self):
+        """Test basic number spellout in French."""
+        assert icu_rbnf.spellout(0, "fr_FR") == "zéro"
+        assert icu_rbnf.spellout(1, "fr_FR") == "un"
+        assert icu_rbnf.spellout(11, "fr_FR") == "onze"
+        assert icu_rbnf.spellout(21, "fr_FR") == "vingt-et-un"
+        assert icu_rbnf.spellout(100, "fr_FR") == "cent"
+        assert icu_rbnf.spellout(123, "fr_FR") == "cent vingt-trois"
+
+    def test_german_basic(self):
+        """Test basic number spellout in German."""
+        assert icu_rbnf.spellout(0, "de_DE") == "null"
+        assert icu_rbnf.spellout(1, "de_DE") == "eins"
+        assert icu_rbnf.spellout(12, "de_DE") == "zwölf"
+        # German uses soft hyphen in some compound words (U+00AD)
+        result = icu_rbnf.spellout(21, "de_DE")
+        assert "ein" in result and "zwanzig" in result
+        # ICU may use soft hyphen in compound words
+        result_100 = icu_rbnf.spellout(100, "de_DE")
+        assert "ein" in result_100 and "hundert" in result_100
+
+    def test_large_numbers(self):
+        """Test spellout with larger numbers."""
+        assert icu_rbnf.spellout(1000, "en_US") == "one thousand"
+        assert (
+            icu_rbnf.spellout(1234, "en_US") == "one thousand two hundred thirty-four"
+        )
+        assert icu_rbnf.spellout(1000000, "en_US") == "one million"
+
+    def test_example_from_spec(self):
+        """Test the example from the specification."""
+        assert icu_rbnf.spellout(123, "en_US") == "one hundred twenty-three"
+        assert icu_rbnf.spellout(123, "fr_FR") == "cent vingt-trois"
+
+
+class TestOrdinal:
+    """Tests for the ordinal function."""
+
+    def test_english_basic(self):
+        """Test basic ordinal forms in English."""
+        assert icu_rbnf.ordinal(1, "en_US") == "1st"
+        assert icu_rbnf.ordinal(2, "en_US") == "2nd"
+        assert icu_rbnf.ordinal(3, "en_US") == "3rd"
+        assert icu_rbnf.ordinal(4, "en_US") == "4th"
+        assert icu_rbnf.ordinal(10, "en_US") == "10th"
+        assert icu_rbnf.ordinal(11, "en_US") == "11th"
+        assert icu_rbnf.ordinal(21, "en_US") == "21st"
+        assert icu_rbnf.ordinal(22, "en_US") == "22nd"
+        assert icu_rbnf.ordinal(100, "en_US") == "100th"
+        assert icu_rbnf.ordinal(101, "en_US") == "101st"
+
+    def test_french_basic(self):
+        """Test basic ordinal forms in French."""
+        assert icu_rbnf.ordinal(1, "fr_FR") == "1er"
+        assert icu_rbnf.ordinal(2, "fr_FR") == "2e"
+        assert icu_rbnf.ordinal(3, "fr_FR") == "3e"
+        assert icu_rbnf.ordinal(10, "fr_FR") == "10e"
+        assert icu_rbnf.ordinal(20, "fr_FR") == "20e"
+
+    def test_german_basic(self):
+        """Test basic ordinal forms in German."""
+        assert icu_rbnf.ordinal(1, "de_DE") == "1."
+        assert icu_rbnf.ordinal(2, "de_DE") == "2."
+        assert icu_rbnf.ordinal(3, "de_DE") == "3."
+        assert icu_rbnf.ordinal(10, "de_DE") == "10."
+
+    def test_example_from_spec(self):
+        """Test the example from the specification."""
+        assert icu_rbnf.ordinal(21, "en_US") == "21st"
+
+
+class TestEdgeCases:
+    """Tests for edge cases."""
+
+    def test_negative_numbers(self):
+        """Test spellout with negative numbers."""
+        assert icu_rbnf.spellout(-1, "en_US") == "minus one"
+        assert icu_rbnf.spellout(-42, "en_US") == "minus forty-two"
+
+    def test_float_numbers(self):
+        """Test spellout with float numbers (properly formatted)."""
+        assert (
+            icu_rbnf.spellout(123.7, "en_US") == "one hundred twenty-three point seven"
+        )
+        assert icu_rbnf.spellout(42.0, "en_US") == "forty-two"
+
+    def test_invalid_locale(self):
+        """Test behavior with invalid locale."""
+        # ICU may not raise an error for invalid locale, just use default
+        # This test verifies the error exception is available
+        assert hasattr(icu_rbnf, "error")
+
+    def test_very_large_number(self):
+        """Test with a very large number."""
+        result = icu_rbnf.spellout(999999999, "en_US")
+        assert "nine hundred ninety-nine million" in result
+
+
+class TestSpelloutOrdinal:
+    """Tests for the spellout_ordinal function."""
+
+    def test_english_basic(self):
+        """Test basic word-based ordinals in English."""
+        assert icu_rbnf.spellout_ordinal(1, "en_US") == "first"
+        assert icu_rbnf.spellout_ordinal(2, "en_US") == "second"
+        assert icu_rbnf.spellout_ordinal(3, "en_US") == "third"
+        assert icu_rbnf.spellout_ordinal(4, "en_US") == "fourth"
+        assert icu_rbnf.spellout_ordinal(10, "en_US") == "tenth"
+        assert icu_rbnf.spellout_ordinal(11, "en_US") == "eleventh"
+        assert icu_rbnf.spellout_ordinal(21, "en_US") == "twenty-first"
+        assert icu_rbnf.spellout_ordinal(22, "en_US") == "twenty-second"
+        assert icu_rbnf.spellout_ordinal(100, "en_US") == "one hundredth"
+        assert icu_rbnf.spellout_ordinal(123, "en_US") == "one hundred twenty-third"
+
+    def test_german_basic(self):
+        """Test basic word-based ordinals in German."""
+        assert icu_rbnf.spellout_ordinal(1, "de_DE") == "erste"
+        assert icu_rbnf.spellout_ordinal(2, "de_DE") == "zweite"
+        assert icu_rbnf.spellout_ordinal(3, "de_DE") == "dritte"
+        assert icu_rbnf.spellout_ordinal(10, "de_DE") == "zehnte"
+
+    def test_fallback_behavior(self):
+        """Test that spellout_ordinal falls back gracefully for locales without %spellout-ordinal."""
+        # French doesn't have %spellout-ordinal, so it should fall back to ordinal format
+        # This test verifies the fallback mechanism works
+        result = icu_rbnf.spellout_ordinal(1, "fr_FR")
+        # Should return ordinal format (1er) since word-based isn't available
+        assert "1" in result and "er" in result
+
+
+class TestIsLocaleSupported:
+    """Tests for the is_locale_supported function."""
+
+    def test_valid_locales(self):
+        """Test that valid locales are supported."""
+        assert icu_rbnf.is_locale_supported("en_US") is True
+        assert icu_rbnf.is_locale_supported("fr_FR") is True
+        assert icu_rbnf.is_locale_supported("de_DE") is True
+        assert icu_rbnf.is_locale_supported("es_ES") is True
+        assert icu_rbnf.is_locale_supported("en_GB") is True
+
+    def test_invalid_locales(self):
+        """Test that empty strings are not supported."""
+        assert icu_rbnf.is_locale_supported("") is False
+
+    def test_special_characters(self):
+        """Test that locales with invalid characters are rejected."""
+        assert icu_rbnf.is_locale_supported("en@US") is False
+        assert icu_rbnf.is_locale_supported("en US") is False
+
+
+class TestModuleAPI:
+    """Tests for module-level API."""
+
+    def test_error_exception_exists(self):
+        """Test that error exception is exposed at module level."""
+        assert hasattr(icu_rbnf, "error")
+        assert isinstance(icu_rbnf.error, type)
+
+    def test_version_exists(self):
+        """Test that version is exposed."""
+        assert hasattr(icu_rbnf, "__version__")
+        # Shape, not a literal: pinning the value here means every release
+        # bump fails a test that is not about the release.
+        parts = icu_rbnf.__version__.split(".")
+        assert len(parts) >= 2
+        assert all(p.isdigit() for p in parts[:2])
+
+    def test_spellout_ordinal_exists(self):
+        """Test that spellout_ordinal function is exposed."""
+        assert hasattr(icu_rbnf, "spellout_ordinal")
+        assert callable(icu_rbnf.spellout_ordinal)
+
+    def test_is_locale_supported_exists(self):
+        """Test that is_locale_supported function is exposed."""
+        assert hasattr(icu_rbnf, "is_locale_supported")
+        assert callable(icu_rbnf.is_locale_supported)
+
+
+class TestIcuVersion:
+    """The ICU version is the CLDR version, so it is worth asserting."""
+
+    def test_reports_a_version(self):
+        """icu_version() returns something like '78.3'."""
+        version = icu_rbnf.icu_version()
+        assert version
+        assert version[0].isdigit()
+
+    def test_is_recent_enough(self):
+        """Guard against a build picking up an ancient system ICU.
+
+        ICU 60 -- AlmaLinux 8's, and what these wheels shipped before
+        script/build-icu existed -- carries CLDR 32 from 2017. It has no rules
+        at all for several locales and silently falls back to English for them,
+        which is indistinguishable from working. ICU 77 is also the first
+        release whose RBNF parser understands CLDR's `[a >>|b]` syntax.
+        """
+        major = int(icu_rbnf.icu_version().split(".", maxsplit=1)[0])
+        assert major >= 77, f"ICU {major} is too old; see script/build-icu"
+
+
+class TestLocalesMissingFromOldIcu:
+    """Locales that ICU 60 did not have, and silently spelled in English.
+
+    Each of these returned the English word before the ICU upgrade, so they
+    double as a check that the build did not quietly regress to a system ICU.
+    """
+
+    def test_swahili(self):
+        assert icu_rbnf.spellout(1, "sw") == "moja"
+        assert icu_rbnf.spellout(2, "sw") == "mbili"
+
+    def test_luxembourgish(self):
+        assert icu_rbnf.spellout(0, "lb") == "null"
+        assert icu_rbnf.spellout(1, "lb") == "eent"
+
+    def test_kazakh(self):
+        assert icu_rbnf.spellout(0, "kk") == "нөл"
+        assert icu_rbnf.spellout(1, "kk") == "бір"
+
+    def test_nepali(self):
+        assert icu_rbnf.spellout(1, "ne") == "एक"
+
+    def test_sundanese(self):
+        assert icu_rbnf.spellout(0, "su") == "nol"
+        assert icu_rbnf.spellout(1, "su") == "hiji"
+
+    def test_quechua(self):
+        assert icu_rbnf.spellout(1, "qu") == "huk"