This library provides a solution for working with Hebrew numbers in various contexts. Hebrew has unique rules for number representation that vary based on gender, definiteness, and usage context. This library simplify these complexities by providing functions for converting numerical values to their proper Hebrew textual representation.

Install the package using pip (or uv, poetry, etc.):

pip install hebrew-numbers

When counting without specific nouns, but rather in a general sense, we use the indefinite number.

>>> from hebrew_numbers import indefinite_number
>>> [indefinite_number(n) for n in [1, 2, 3]]
['אחת', 'שתיים', 'שָלוש']
>>> indefinite_number(0)
'אפס'
>>> indefinite_number(-3)
'מינוס שָלוש'
>>> indefinite_number(1234567890)
'מיליארד מאתיים שלושים וארבעה מיליון חמש מאות שישים ושבעה אלף שמונֶה מאות ותשעים'

A number that describes the position of an object in a series is called an ordinal number. This number can be masculine (זכר) or feminine (נקבה).

>>> from hebrew_numbers import ordinal_number
>>> [ordinal_number(n, "M") for n in [1, 2, 3]]
['ראשון', 'שני', 'שלישי']
>>> [ordinal_number(n, "F") for n in [1, 2, 3]]
['ראשונה', 'שנייה', 'שלישית']

Cardinal numbers are used to indicate quantities. Their form depends on the following factors:

• The gender of the noun (masculine or feminine).
• Whether the noun is definite (מיודע) or indefinite (סתמי).

To specify a quantity with a noun, use count_noun(n, singular_form, plural_form, gender, definite).

If you only need the numerical prefix, use count_prefix(n, gender, definite).

The number itself can be masculine (זכר) or feminine (נקבה), and absolute (נפרד) or construct (נסמך). If you know the gender and construct state, you can the number itself with cardinal_number(n, gender, construct)

• The indefinite number is the feminine-absolute form.
• The form of the number following "פי" (times/multiplied by) to be in the masculine-absolute form: פי שניים, פי שלושה, פי ארבעה.
• Use the masculine-absolute form to indicate the days of the month: אחד בכסלו, עשרה בטבת, אחד באפריל, שניים ביוני.

The library includes a Jinja2 extension for using Hebrew numbers in templates.

Install with Jinja2 support:

pip install hebrew-numbers[jinja]

>>> from jinja2 import Environment
>>> from hebrew_numbers.jinja import HebrewNumbersExtension
>>> env = Environment(extensions=[HebrewNumbersExtension])
>>> template = env.from_string("מקום {{ 1 | hebrew_ordinal('masculine') }}")
>>> template.render()
'מקום ראשון'
>>> template = env.from_string("{{ 5300 | hebrew_count('מניה', 'מניות', 'f') }}")
>>> template.render()
'חמשת אלפים ושְלוש מאות מניות'
>>> template = env.from_string("{{ 15000 | hebrew_prefix('m') }}")
>>> template.render()
'חמישה־עשר אלף'

All English filters accept flexible gender strings:

• Masculine: 'masculine', 'male', 'm'
• Feminine: 'feminine', 'female', 'f'

For Hebrew-speaking developers, the extension also provides Hebrew-named filters that accept Hebrew parameter names:

>>> # Hebrew filter names with Hebrew parameters
>>> template = env.from_string("מקום {{ 1 | מספר_סודר('ז') }}")
>>> template.render()
'מקום ראשון'
>>> template = env.from_string("{{ 5300 | כמות_של('מניה', 'מניות', 'נ') }}")
>>> template.render()
'חמשת אלפים ושְלוש מאות מניות'
>>> template = env.from_string("{{ 15000 | כמות('ז') }}")
>>> template.render()
'חמישה־עשר אלף'
>>> # Hebrew boolean values for מיודע parameter
>>> template = env.from_string("{{ 3 | כמות_של('המחברת', 'המחברות', 'נ', מיודע='כן') }}")
>>> template.render()
'שְלוש המחברות'

Hebrew filters accept Hebrew parameter names:

• מין (Gender):
  • Masculine: 'ז', 'זכר', 'זכרי'
  • Feminine: 'נ', 'נקבה', 'נקבי'
• מצב (Construct State): 'נפרד' (absolute), 'נסמך' (construct)
• מיודע (Definite): 'כן' (definite), 'לא' (indefinite), or True/False

Interested in contributing? See CONTRIBUTING.md for development setup and guideline.