babel.plural Namespace Reference

Classes
class	_Compiler
class	_GettextCompiler
class	_JavaScriptCompiler
class	_Parser
class	_PythonCompiler
class	_UnicodeCompiler
class	PluralRule
class	RuleError

Functions
tuple[decimal.Decimal|int, int, int, int, int, int, Literal[0], Literal[0]]	extract_operands (float|decimal.Decimal source)
str	to_javascript (Mapping[str, str]|Iterable[tuple[str, str]]|PluralRule rule)
Callable[[float|decimal.Decimal], str]	to_python (Mapping[str, str]|Iterable[tuple[str, str]]|PluralRule rule)
str	to_gettext (Mapping[str, str]|Iterable[tuple[str, str]]|PluralRule rule)
bool	in_range_list (float|decimal.Decimal num, Iterable[Iterable[float|decimal.Decimal]] range_list)
bool	within_range_list (float|decimal.Decimal num, Iterable[Iterable[float|decimal.Decimal]] range_list)
float	cldr_modulo (float a, float b)
list[tuple[str, str]]	tokenize_rule (str s)
list[tuple[str, str]]|bool	test_next_token (list[tuple[str, str]] tokens, str type_, str|None value=None)
	skip_token (list[tuple[str, str]] tokens, str type_, str|None value=None)
tuple[Literal[ 'value'], tuple[int]]	value_node (int value)
tuple[str, tuple[()]]	ident_node (str name)
tuple[Literal[ 'range_list'], Iterable[Iterable[float|decimal.Decimal]]]	range_list_node (Iterable[Iterable[float|decimal.Decimal]] range_list)
tuple[Literal[ 'not'], tuple[tuple[Any,...]]]	negate (tuple[Any,...] rv)
	_binary_compiler (tmpl)
	_unary_compiler (tmpl)

Variables
tuple	_plural_tags = ('zero', 'one', 'two', 'few', 'many', 'other')
str	_fallback_tag = 'other'
dict	_VARS
list	_RULES
str	compile_zero = lambda x: '0'

Detailed Description

    babel.numbers
    ~~~~~~~~~~~~~

    CLDR Plural support.  See UTS #35.

    :copyright: (c) 2013-2025 by the Babel Team.
    :license: BSD, see LICENSE for more details.

Function Documentation

_binary_compiler()

babel.plural._binary_compiler (   tmpl )

protected

Compiler factory for the `_Compiler`.

_unary_compiler()

babel.plural._unary_compiler (   tmpl )

protected

Compiler factory for the `_Compiler`.

cldr_modulo()

float babel.plural.cldr_modulo	(	float	a,
		float	b
	)

Javaish modulo.  This modulo operator returns the value with the sign
of the dividend rather than the divisor like Python does:

>>> cldr_modulo(-3, 5)
-3
>>> cldr_modulo(-3, -5)
-3
>>> cldr_modulo(3, 5)
3

extract_operands()

tuple[decimal.Decimal | int, int, int, int, int, int, Literal[0], Literal[0]] babel.plural.extract_operands

(

float | decimal.Decimal

source

)

Extract operands from a decimal, a float or an int, according to `CLDR rules`_.

The result is an 8-tuple (n, i, v, w, f, t, c, e), where those symbols are as follows:

====== ===============================================================
Symbol Value
------ ---------------------------------------------------------------
n      absolute value of the source number (integer and decimals).
i      integer digits of n.
v      number of visible fraction digits in n, with trailing zeros.
w      number of visible fraction digits in n, without trailing zeros.
f      visible fractional digits in n, with trailing zeros.
t      visible fractional digits in n, without trailing zeros.
c      compact decimal exponent value: exponent of the power of 10 used in compact decimal formatting.
e      currently, synonym for ‘c’. however, may be redefined in the future.
====== ===============================================================

.. _`CLDR rules`: https://www.unicode.org/reports/tr35/tr35-61/tr35-numbers.html#Operands

:param source: A real number
:type source: int|float|decimal.Decimal
:return: A n-i-v-w-f-t-c-e tuple
:rtype: tuple[decimal.Decimal, int, int, int, int, int, int, int]

in_range_list()

bool babel.plural.in_range_list	(	float | decimal.Decimal	num,
		Iterable[Iterable[float | decimal.Decimal]]	range_list
	)

Integer range list test.  This is the callback for the "in" operator
of the UTS #35 pluralization rule language:

>>> in_range_list(1, [(1, 3)])
True
>>> in_range_list(3, [(1, 3)])
True
>>> in_range_list(3, [(1, 3), (5, 8)])
True
>>> in_range_list(1.2, [(1, 4)])
False
>>> in_range_list(10, [(1, 4)])
False
>>> in_range_list(10, [(1, 4), (6, 8)])
False

to_gettext()

str babel.plural.to_gettext

(

Mapping[str, str] | Iterable[tuple[str, str]] | PluralRule

rule

)

The plural rule as gettext expression.  The gettext expression is
technically limited to integers and returns indices rather than tags.

>>> to_gettext({'one': 'n is 1', 'two': 'n is 2'})
'nplurals=3; plural=((n == 1) ? 0 : (n == 2) ? 1 : 2);'

:param rule: the rules as list or dict, or a `PluralRule` object
:raise RuleError: if the expression is malformed

to_javascript()

str babel.plural.to_javascript

(

Mapping[str, str] | Iterable[tuple[str, str]] | PluralRule

rule

)

Convert a list/dict of rules or a `PluralRule` object into a JavaScript
function.  This function depends on no external library:

>>> to_javascript({'one': 'n is 1'})
"(function(n) { return (n == 1) ? 'one' : 'other'; })"

Implementation detail: The function generated will probably evaluate
expressions involved into range operations multiple times.  This has the
advantage that external helper functions are not required and is not a
big performance hit for these simple calculations.

:param rule: the rules as list or dict, or a `PluralRule` object
:raise RuleError: if the expression is malformed

to_python()

Callable[[float | decimal.Decimal], str] babel.plural.to_python

(

Mapping[str, str] | Iterable[tuple[str, str]] | PluralRule

rule

)

Convert a list/dict of rules or a `PluralRule` object into a regular
Python function.  This is useful in situations where you need a real
function and don't are about the actual rule object:

>>> func = to_python({'one': 'n is 1', 'few': 'n in 2..4'})
>>> func(1)
'one'
>>> func(3)
'few'
>>> func = to_python({'one': 'n in 1,11', 'few': 'n in 3..10,13..19'})
>>> func(11)
'one'
>>> func(15)
'few'

:param rule: the rules as list or dict, or a `PluralRule` object
:raise RuleError: if the expression is malformed

within_range_list()

bool babel.plural.within_range_list	(	float | decimal.Decimal	num,
		Iterable[Iterable[float | decimal.Decimal]]	range_list
	)

Float range test.  This is the callback for the "within" operator
of the UTS #35 pluralization rule language:

>>> within_range_list(1, [(1, 3)])
True
>>> within_range_list(1.0, [(1, 3)])
True
>>> within_range_list(1.2, [(1, 4)])
True
>>> within_range_list(8.8, [(1, 4), (7, 15)])
True
>>> within_range_list(10, [(1, 4)])
False
>>> within_range_list(10.5, [(1, 4), (20, 30)])
False

Variable Documentation

_RULES

list babel.plural._RULES

protected

Initial value:

=  [
    (None, re.compile(r'\s+', re.UNICODE)),
    ('word', re.compile(fr'\b(and|or|is|(?:with)?in|not|mod|[{"".join(_VARS)}])\b')),
    ('value', re.compile(r'\d+')),
    ('symbol', re.compile(r'%|,|!=|=')),
    ('ellipsis', re.compile(r'\.{2,3}|\u2026', re.UNICODE)),  # U+2026: ELLIPSIS
]

_VARS

dict babel.plural._VARS

protected

Initial value:

=  {
    'n',  # absolute value of the source number.
    'i',  # integer digits of n.
    'v',  # number of visible fraction digits in n, with trailing zeros.*
    'w',  # number of visible fraction digits in n, without trailing zeros.*
    'f',  # visible fraction digits in n, with trailing zeros.*
    't',  # visible fraction digits in n, without trailing zeros.*
    'c',  # compact decimal exponent value: exponent of the power of 10 used in compact decimal formatting.
    'e',  # currently, synonym for `c`. however, may be redefined in the future.
}