Skip to main content

A tool to convert numbers (int, float) into Persian words

Project description


num2fawords is a highly customizable library which provides functions to convert a number (int, float, Decimal, Fraction, or str) into Persian word form.


  • Python 3.3+ is required

  • pip install 'setuptools>=36.2.1'

  • pip install num2fawords


>>> from num2fawords import words, ordinal_words
>>> words(1984)
'یک هزار و نهصد و هشتاد و چهار'
>>> ordinal_words(1232)
'یک هزار و دویست و سی و دوم'
>>> ordinal_words(123)
'یکصد و بیست و سوم'
>>> words(1.1e-9)
'یک و یک دهم در ده به توان منفی نه'

Obviously, words is used to convert to word form and ordinal_words is for ordinal word from.

words also accepts other common standard types:

>>> words(19.75)
'نوزده و هفتاد و پنج صدم'
>>> from decimal import Decimal
>>> words(Decimal('1.1'))
'یک و یک دهم'
>>> from fractions import Fraction
>>> words(Fraction(-2, 5))
'منفی دو پنجم'

The default decimal separator is “و” but it can be changed to “ممیز” (or any other string) as follows:

>>> words(19.75, decimal_separator=' ممیز ')
'نوزده ممیز هفتاد و پنج صدم'

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

>>> from num2fawords import HUNDREDS
>>> words(170)
'یکصد و هفتاد'
>>> HUNDREDS[1] = 'صد'
>>> words(170)
'صد و هفتاد'

Some examples for other arguments of words:

>>> 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=' ضربدر ده به قوهٔ ')
'یک و یک دهم ضربدر ده به قوهٔ منفی نه'

Of-course the above arguments can be used together.

If you prefer to change the default argument values once and for all, use the change_defaults function:

>>> from num2fawords import change_defaults, words
>>> change_defaults(fraction_separator=' بخش بر ', ordinal_denominator=False)
>>> words('۱/۴')
'یک بخش بر چهار'

That’s all. Enjoy!

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

num2fawords-1.1.tar.gz (6.9 kB view hashes)

Uploaded source

Built Distribution

num2fawords-1.1-py3-none-any.whl (9.8 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page