Metadata-Version: 2.1
Name: num2fa
Version: 2.0.0
Summary: A library to convert numbers (ints, floats, and other standard numerical types) into Persian numbers or words.
Author: Emad Rad
Author-email: codewithemad@gmail.com
License: AGPLv3
Project-URL: Code, https://github.com/iranian-github/num2fa
Project-URL: Issue tracker, https://github.com/iranian-github/num2fa/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
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
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: click==8.1.7
Provides-Extra: dev
Requires-Dist: astroid==3.0.2; extra == "dev"
Requires-Dist: attrs==23.1.0; extra == "dev"
Requires-Dist: black==23.12.1; extra == "dev"
Requires-Dist: build==1.0.3; extra == "dev"
Requires-Dist: certifi==2023.11.17; extra == "dev"
Requires-Dist: cffi==1.16.0; extra == "dev"
Requires-Dist: charset-normalizer==3.3.2; extra == "dev"
Requires-Dist: click==8.1.7; extra == "dev"
Requires-Dist: click-log==0.4.0; extra == "dev"
Requires-Dist: cryptography==41.0.7; extra == "dev"
Requires-Dist: dill==0.3.7; extra == "dev"
Requires-Dist: docutils==0.20.1; extra == "dev"
Requires-Dist: exceptiongroup==1.2.0; extra == "dev"
Requires-Dist: idna==3.6; extra == "dev"
Requires-Dist: importlib-metadata==7.0.1; extra == "dev"
Requires-Dist: iniconfig==2.0.0; extra == "dev"
Requires-Dist: isort==5.13.2; extra == "dev"
Requires-Dist: jaraco-classes==3.3.0; extra == "dev"
Requires-Dist: jeepney==0.8.0; extra == "dev"
Requires-Dist: jinja2==3.1.2; extra == "dev"
Requires-Dist: keyring==24.3.0; extra == "dev"
Requires-Dist: markdown-it-py==3.0.0; extra == "dev"
Requires-Dist: markupsafe==2.1.3; extra == "dev"
Requires-Dist: mccabe==0.7.0; extra == "dev"
Requires-Dist: mdurl==0.1.2; extra == "dev"
Requires-Dist: more-itertools==10.1.0; extra == "dev"
Requires-Dist: mypy-extensions==1.0.0; extra == "dev"
Requires-Dist: nh3==0.2.15; extra == "dev"
Requires-Dist: packaging==23.2; extra == "dev"
Requires-Dist: pathspec==0.12.1; extra == "dev"
Requires-Dist: pip-tools==7.3.0; extra == "dev"
Requires-Dist: pkginfo==1.9.6; extra == "dev"
Requires-Dist: platformdirs==4.1.0; extra == "dev"
Requires-Dist: pluggy==1.3.0; extra == "dev"
Requires-Dist: pycparser==2.21; extra == "dev"
Requires-Dist: pygments==2.17.2; extra == "dev"
Requires-Dist: pylint==3.0.3; extra == "dev"
Requires-Dist: pyproject-hooks==1.0.0; extra == "dev"
Requires-Dist: pytest==7.4.3; extra == "dev"
Requires-Dist: readme-renderer==42.0; extra == "dev"
Requires-Dist: requests==2.31.0; extra == "dev"
Requires-Dist: requests-toolbelt==1.0.0; extra == "dev"
Requires-Dist: rfc3986==2.0.0; extra == "dev"
Requires-Dist: rich==13.7.0; extra == "dev"
Requires-Dist: scriv==1.5.1; extra == "dev"
Requires-Dist: secretstorage==3.3.3; extra == "dev"
Requires-Dist: tomli==2.0.1; extra == "dev"
Requires-Dist: tomlkit==0.12.3; extra == "dev"
Requires-Dist: twine==4.0.2; extra == "dev"
Requires-Dist: typing-extensions==4.9.0; extra == "dev"
Requires-Dist: urllib3==2.1.0; extra == "dev"
Requires-Dist: wheel==0.42.0; extra == "dev"
Requires-Dist: zipp==3.17.0; extra == "dev"

# Num2Fa

[![PyPI releases](https://img.shields.io/pypi/v/num2fa?logo=python&logoColor=white)](https://pypi.python.org/pypi/num2fa)
[![MIT License](https://img.shields.io/github/license/iranian-github/num2fa.svg?style=flat-square)](https://opensource.org/license/agpl-v3/)

`num2fa` is a versatile solution that enables the conversion of numbers (integers, floats, decimals, fractions, or strings) into their corresponding number or word form in Persian.

## Installation

```bash
pip install num2fa
```

That's it!

## Usage

You can use `numbers`, `words`, and `ordinal_words` to convert numbers to their respective Persian forms, whether that be in numeric, word, or ordinal form.

```python
>>> from num2fa import numbers, words, ordinal_words
>>> numbers(1984)
'۱۹۸۴'
>>> numbers('1984')
'۱۹۸۴'
>>> numbers('1.1e-4')
>>> words(1984)
'یک هزار و نهصد و هشتاد و چهار'
>>> ordinal_words(1232)
'یک هزار و دویست و سی و دوم'
>>> ordinal_words(123)
'یکصد و بیست و سوم'
>>> words(1.1e-9)
'یک و یک دهم در ده به توان منفی نه'
```

`numbers` and `words` also accepts other common standard types:

```python

>>> from decimal import Decimal
>>> from fractions import Fraction

>>> numbers(Decimal('1.1'))
'۱٫۱'
>>> numbers(Fraction(-2, 5))
'-۲/۵'
>>> words(Decimal('1.1'))
'یک و یک دهم'
>>> words(Fraction(-2, 5))
'منفی دو پنجم'
>>> ordinal_words(123)
'یکصد و بیست و سوم'
```

## Customization

The default decimal separator for `numbers` is `٫` and for `words` is `و`. it can be changed to any other strings with `decimal_separator`:

```python
>>> numbers(19.75, decimal_separator='/')
'۱۹/۷۵'
>>> words(19.75, decimal_separator=' ممیز ')
'نوزده ممیز هفتاد و پنج صدم'
```

If you wanted to use different number characters for example `٦` instead of `۶`, you can just:

```python
from num2fa.constants import PERSIAN_DIGITS

PERSIAN_DIGITS.update({'6': '٦'})
numbers(19.66, decimal_separator='/')
'۱۹/٦٦'
```

Some people prefer, for example, "صد و هفتاد" over its other form "یکصد و هفتاد". This package uses the second form by default which is also used on official Iranian banknotes. But it can be changed:

```python
>>> from num2fa.constants import HUNDREDS
>>> words(170)
'یکصد و هفتاد'
>>> HUNDREDS[1] = 'صد'
>>> words(170)
'صد و هفتاد'
```

other customizations in `words`:

```python
>>> words(7, positive='مثبت ')
'مثبت هفت'
>>> words(-2, negative='منهای ')
'منهای دو'
>>> words('۱/۲')
'یک دوم'
>>> words('1/2', fraction_separator=' تقسیم بر ', ordinal_denominator=False)
'یک تقسیم بر دو'
>>> words(1.1e-9)
'یک و یک دهم در ده به توان منفی نه'
>>> words(1.1e-9, scientific_separator=' ضربدر ده به قوهٔ ')
'یک و یک دهم ضربدر ده به قوهٔ منفی نه'
```

`positive`, `negative`, `decimal_separator`, `fraction_separator` can be used in `numbers` too.

All above arguments can be used together. If you prefer to change the default argument values once and for all, use the `change_defaults_numbers` or `change_defaults_words` function:

```python
>>> from num2fa import change_numbers_defaults, change_words_defaults

>>> change_numbers_defaults(fraction_separator=' بر ', decimal_separator='.')
>>> numbers('1.89/23')
>>> '۱.۸۹ بر ۲۳'

>>> change_words_defaults(fraction_separator=' بخش بر ', ordinal_denominator=False)
>>> words('۱/۴')
'یک بخش بر چهار'
```

## Contributing

We welcome contributions! To learn how you can contribute, please check the [CONTRIBUTING](https://github.com/iranian-github/blob/master/docs/Contributing.md) document.

## License

This work is licensed under the terms of the [GNU Affero General Public License (AGPL)](https://github.com/iranian-github/blob/master/LICENSE.txt).
