# OVOS Number Parser
OVOS Number Parser is a tool for extracting, pronouncing, and detecting numbers from text across multiple languages. It
supports functionalities like converting numbers to their spoken forms, extracting numbers from text, identifying
fractional and ordinal numbers, and more.
## Features
- **Pronounce Numbers:** Converts numerical values to their spoken forms.
- **Pronounce Ordinals:** Converts numbers to their ordinal forms.
- **Extract Numbers:** Extracts numbers from textual inputs.
- **Detect Fractions:** Identifies fractional expressions.
- **Detect Ordinals:** Checks if a text input contains an ordinal number.
## Supported Languages
✅ - supported
❌ - not supported
🚧 - imperfect placeholder, needs rewriting
| Language Code | Pronounce Number | Pronounce Ordinal | Extract Number | numbers_to_digits |
|-------------------------|------------------|-------------------|----------------|-------------------|
| `en` (English) | ✅ | ❌ | ✅ | ✅ |
| `az` (Azerbaijani) | ✅ | ❌ | ✅ | ✅ |
| `ca` (Catalan) | ✅ | ❌ | ✅ | 🚧 |
| `cs` (Czech) | ✅ | ❌ | ✅ | ✅ |
| `da` (Danish) | ✅ | ✅ | ✅ | ❌ |
| `de` (German) | ✅ | ✅ | ✅ | ✅ |
| `es` (Spanish) | ✅ | ❌ | ✅ | 🚧 |
| `eu` (Euskara / Basque) | ✅ | ❌ | ✅ | ❌ |
| `fa` (Farsi / Persian) | ✅ | ❌ | ✅ | ❌ |
| `fr` (French) | ✅ | ❌ | ✅ | ❌ |
| `hu` (Hungarian) | ✅ | ✅ | ❌ | ❌ |
| `it` (Italian) | ✅ | ❌ | ✅ | ❌ |
| `nl` (Dutch) | ✅ | ✅ | ✅ | ✅ |
| `pl` (Polish) | ✅ | ❌ | ✅ | ✅ |
| `pt` (Portuguese) | ✅ | ❌ | ✅ | 🚧 |
| `ru` (Russian) | ✅ | ❌ | ✅ | ✅ |
| `sv` (Swedish) | ✅ | ✅ | ✅ | ❌ |
| `sl` (Slovenian) | ✅ | ❌ | ❌ | ❌ |
| `uk` (Ukrainian) | ✅ | ❌ | ✅ | ✅ |
## Installation
To install OVOS Number Parser, use:
```bash
pip install ovos-number-parser
```
## Usage
### Pronounce a Number
Convert a number to its spoken equivalent.
```python
def pronounce_number(number: Union[int, float], lang: str, places: int = 2, short_scale: bool = True,
scientific: bool = False, ordinals: bool = False) -> str:
"""
Convert a number to its spoken equivalent.
Args:
number: The number to pronounce.
lang (str): A BCP-47 language code.
places (int): Number of decimal places to express. Default is 2.
short_scale (bool): Use short (True) or long scale (False) for large numbers.
scientific (bool): Pronounce in scientific notation if True.
ordinals (bool): Pronounce as an ordinal if True.
Returns:
str: The pronounced number.
"""
```
**Example Usage:**
```python
from ovos_number_parser import pronounce_number
# Example
result = pronounce_number(123, "en")
print(result) # "one hundred and twenty-three"
```
### Pronounce an Ordinal
Convert a number to its ordinal spoken equivalent.
```python
def pronounce_ordinal(number: Union[int, float], lang: str, short_scale: bool = True) -> str:
"""
Convert an ordinal number to its spoken equivalent.
Args:
number: The number to pronounce.
lang (str): A BCP-47 language code.
short_scale (bool): Use short (True) or long scale (False) for large numbers.
Returns:
str: The pronounced ordinal number.
"""
```
**Example Usage:**
```python
from ovos_number_parser import pronounce_ordinal
# Example
result = pronounce_ordinal(5, "en")
print(result) # "fifth"
```
### Extract a Number
Extract a number from a given text string.
```python
def extract_number(text: str, lang: str, short_scale: bool = True, ordinals: bool = False) -> Union[int, float, bool]:
"""
Extract a number from text.
Args:
text (str): The string to extract a number from.
lang (str): A BCP-47 language code.
short_scale (bool): Use short scale if True, long scale if False.
ordinals (bool): Consider ordinal numbers.
Returns:
int, float, or False: The extracted number, or False if no number found.
"""
```
**Example Usage:**
```python
from ovos_number_parser import extract_number
# Example
result = extract_number("I have twenty apples", "en")
print(result) # 20
```
### Check for Fractional Numbers
Identify if the text contains a fractional number.
```python
def is_fractional(input_str: str, lang: str, short_scale: bool = True) -> Union[bool, float]:
"""
Check if the text is a fraction.
Args:
input_str (str): The string to check if fractional.
lang (str): A BCP-47 language code.
short_scale (bool): Use short scale if True, long scale if False.
Returns:
bool or float: False if not a fraction, otherwise the fraction as a float.
"""
```
**Example Usage:**
```python
from ovos_number_parser import is_fractional
# Example
result = is_fractional("half", "en")
print(result) # 0.5
```
### Check for Ordinals
Determine if the text contains an ordinal number.
```python
def is_ordinal(input_str: str, lang: str) -> Union[bool, float]:
"""
Check if the text is an ordinal number.
Args:
input_str (str): The string to check if ordinal.
lang (str): A BCP-47 language code.
Returns:
bool or float: False if not an ordinal, otherwise the ordinal as a float.
"""
```
**Example Usage:**
```python
from ovos_number_parser import is_ordinal
# Example
result = is_ordinal("third", "en")
print(result) # 3
```
## Related Projects
- [ovos-date-parser](https://github.com/OpenVoiceOS/ovos-date-parser) - for handling dates and times
- [ovos-lang-parser](https://github.com/OVOSHatchery/ovos-lang-parser) - for handling languages
- [ovos-color-parser](https://github.com/OVOSHatchery/ovos-color-parser) - for handling colors
## License
This project is licensed under the Apache License 2.0.
Raw data
{
"_id": null,
"home_page": "https://github.com/OpenVoiceOS/ovos-number-parser",
"name": "ovos-number-parser",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Mycroft AI / OVOS",
"author_email": "jarbasai@mailfence.com",
"download_url": "https://files.pythonhosted.org/packages/45/e9/4ef3bef60ea1e617d6bf235cbc6ae703d2a930253cfe6b1a8d39bad3f002/ovos-number-parser-0.0.2.tar.gz",
"platform": null,
"description": "# OVOS Number Parser\n\nOVOS Number Parser is a tool for extracting, pronouncing, and detecting numbers from text across multiple languages. It\nsupports functionalities like converting numbers to their spoken forms, extracting numbers from text, identifying\nfractional and ordinal numbers, and more.\n\n## Features\n\n- **Pronounce Numbers:** Converts numerical values to their spoken forms.\n- **Pronounce Ordinals:** Converts numbers to their ordinal forms.\n- **Extract Numbers:** Extracts numbers from textual inputs.\n- **Detect Fractions:** Identifies fractional expressions.\n- **Detect Ordinals:** Checks if a text input contains an ordinal number.\n\n## Supported Languages\n\n\u2705 - supported\n\u274c - not supported\n\ud83d\udea7 - imperfect placeholder, needs rewriting\n\n\n| Language Code | Pronounce Number | Pronounce Ordinal | Extract Number | numbers_to_digits |\n|-------------------------|------------------|-------------------|----------------|-------------------|\n| `en` (English) | \u2705 | \u274c | \u2705 | \u2705 |\n| `az` (Azerbaijani) | \u2705 | \u274c | \u2705 | \u2705 |\n| `ca` (Catalan) | \u2705 | \u274c | \u2705 | \ud83d\udea7 |\n| `cs` (Czech) | \u2705 | \u274c | \u2705 | \u2705 |\n| `da` (Danish) | \u2705 | \u2705 | \u2705 | \u274c |\n| `de` (German) | \u2705 | \u2705 | \u2705 | \u2705 |\n| `es` (Spanish) | \u2705 | \u274c | \u2705 | \ud83d\udea7 |\n| `eu` (Euskara / Basque) | \u2705 | \u274c | \u2705 | \u274c |\n| `fa` (Farsi / Persian) | \u2705 | \u274c | \u2705 | \u274c |\n| `fr` (French) | \u2705 | \u274c | \u2705 | \u274c |\n| `hu` (Hungarian) | \u2705 | \u2705 | \u274c | \u274c |\n| `it` (Italian) | \u2705 | \u274c | \u2705 | \u274c |\n| `nl` (Dutch) | \u2705 | \u2705 | \u2705 | \u2705 |\n| `pl` (Polish) | \u2705 | \u274c | \u2705 | \u2705 |\n| `pt` (Portuguese) | \u2705 | \u274c | \u2705 | \ud83d\udea7 |\n| `ru` (Russian) | \u2705 | \u274c | \u2705 | \u2705 |\n| `sv` (Swedish) | \u2705 | \u2705 | \u2705 | \u274c |\n| `sl` (Slovenian) | \u2705 | \u274c | \u274c | \u274c |\n| `uk` (Ukrainian) | \u2705 | \u274c | \u2705 | \u2705 |\n\n## Installation\n\nTo install OVOS Number Parser, use:\n\n```bash\npip install ovos-number-parser\n```\n\n## Usage\n\n### Pronounce a Number\n\nConvert a number to its spoken equivalent.\n\n```python\ndef pronounce_number(number: Union[int, float], lang: str, places: int = 2, short_scale: bool = True,\n scientific: bool = False, ordinals: bool = False) -> str:\n \"\"\"\n Convert a number to its spoken equivalent.\n\n Args:\n number: The number to pronounce.\n lang (str): A BCP-47 language code.\n places (int): Number of decimal places to express. Default is 2.\n short_scale (bool): Use short (True) or long scale (False) for large numbers.\n scientific (bool): Pronounce in scientific notation if True.\n ordinals (bool): Pronounce as an ordinal if True.\n\n Returns:\n str: The pronounced number.\n \"\"\"\n```\n\n**Example Usage:**\n\n```python\nfrom ovos_number_parser import pronounce_number\n\n# Example\nresult = pronounce_number(123, \"en\")\nprint(result) # \"one hundred and twenty-three\"\n```\n\n### Pronounce an Ordinal\n\nConvert a number to its ordinal spoken equivalent.\n\n```python\ndef pronounce_ordinal(number: Union[int, float], lang: str, short_scale: bool = True) -> str:\n \"\"\"\n Convert an ordinal number to its spoken equivalent.\n\n Args:\n number: The number to pronounce.\n lang (str): A BCP-47 language code.\n short_scale (bool): Use short (True) or long scale (False) for large numbers.\n\n Returns:\n str: The pronounced ordinal number.\n \"\"\"\n```\n\n**Example Usage:**\n\n```python\nfrom ovos_number_parser import pronounce_ordinal\n\n# Example\nresult = pronounce_ordinal(5, \"en\")\nprint(result) # \"fifth\"\n```\n\n### Extract a Number\n\nExtract a number from a given text string.\n\n```python\ndef extract_number(text: str, lang: str, short_scale: bool = True, ordinals: bool = False) -> Union[int, float, bool]:\n \"\"\"\n Extract a number from text.\n\n Args:\n text (str): The string to extract a number from.\n lang (str): A BCP-47 language code.\n short_scale (bool): Use short scale if True, long scale if False.\n ordinals (bool): Consider ordinal numbers.\n\n Returns:\n int, float, or False: The extracted number, or False if no number found.\n \"\"\"\n```\n\n**Example Usage:**\n\n```python\nfrom ovos_number_parser import extract_number\n\n# Example\nresult = extract_number(\"I have twenty apples\", \"en\")\nprint(result) # 20\n```\n\n### Check for Fractional Numbers\n\nIdentify if the text contains a fractional number.\n\n```python\ndef is_fractional(input_str: str, lang: str, short_scale: bool = True) -> Union[bool, float]:\n \"\"\"\n Check if the text is a fraction.\n\n Args:\n input_str (str): The string to check if fractional.\n lang (str): A BCP-47 language code.\n short_scale (bool): Use short scale if True, long scale if False.\n\n Returns:\n bool or float: False if not a fraction, otherwise the fraction as a float.\n \"\"\"\n```\n\n**Example Usage:**\n\n```python\nfrom ovos_number_parser import is_fractional\n\n# Example\nresult = is_fractional(\"half\", \"en\")\nprint(result) # 0.5\n```\n\n### Check for Ordinals\n\nDetermine if the text contains an ordinal number.\n\n```python\ndef is_ordinal(input_str: str, lang: str) -> Union[bool, float]:\n \"\"\"\n Check if the text is an ordinal number.\n\n Args:\n input_str (str): The string to check if ordinal.\n lang (str): A BCP-47 language code.\n\n Returns:\n bool or float: False if not an ordinal, otherwise the ordinal as a float.\n \"\"\"\n```\n\n**Example Usage:**\n\n```python\nfrom ovos_number_parser import is_ordinal\n\n# Example\nresult = is_ordinal(\"third\", \"en\")\nprint(result) # 3\n```\n\n## Related Projects\n\n- [ovos-date-parser](https://github.com/OpenVoiceOS/ovos-date-parser) - for handling dates and times\n- [ovos-lang-parser](https://github.com/OVOSHatchery/ovos-lang-parser) - for handling languages\n- [ovos-color-parser](https://github.com/OVOSHatchery/ovos-color-parser) - for handling colors\n\n## License\n\nThis project is licensed under the Apache License 2.0.\n\n",
"bugtrack_url": null,
"license": "Apache2.0",
"summary": "OpenVoiceOS's multilingual text parsing and formatting library",
"version": "0.0.2",
"project_urls": {
"Homepage": "https://github.com/OpenVoiceOS/ovos-number-parser"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6c2c02d8c9c1c81aaa44ab6e0cdc3c4a5b337efd1e47384407c27f3d14e62863",
"md5": "8583ff24c052ad62993304574e782057",
"sha256": "96ab48815210fb08114edd6be247eadc0da529eb475ceec628bfdecf82a4ef14"
},
"downloads": -1,
"filename": "ovos_number_parser-0.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8583ff24c052ad62993304574e782057",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 130744,
"upload_time": "2024-11-13T11:22:21",
"upload_time_iso_8601": "2024-11-13T11:22:21.673765Z",
"url": "https://files.pythonhosted.org/packages/6c/2c/02d8c9c1c81aaa44ab6e0cdc3c4a5b337efd1e47384407c27f3d14e62863/ovos_number_parser-0.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "45e94ef3bef60ea1e617d6bf235cbc6ae703d2a930253cfe6b1a8d39bad3f002",
"md5": "b77feedb1cc8c7a6cb8f9e1ab1dcc78f",
"sha256": "e389d085c920bcd63bb1871d1d8294974970468b4922d3826c52be341d3a94a3"
},
"downloads": -1,
"filename": "ovos-number-parser-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "b77feedb1cc8c7a6cb8f9e1ab1dcc78f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 110747,
"upload_time": "2024-11-13T11:22:23",
"upload_time_iso_8601": "2024-11-13T11:22:23.320394Z",
"url": "https://files.pythonhosted.org/packages/45/e9/4ef3bef60ea1e617d6bf235cbc6ae703d2a930253cfe6b1a8d39bad3f002/ovos-number-parser-0.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-13 11:22:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "OpenVoiceOS",
"github_project": "ovos-number-parser",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "ovos-number-parser"
}
JSON
