.. image:: https://img.shields.io/pypi/v/inflect.svg :target: https://pypi.org/project/inflect

.. image:: https://img.shields.io/pypi/pyversions/inflect.svg

.. image:: https://github.com/jaraco/inflect/actions/workflows/main.yml/badge.svg :target: https://github.com/jaraco/inflect/actions?query=workflow%3A%22tests%22 :alt: tests

.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json :target: https://github.com/astral-sh/ruff :alt: Ruff

.. image:: https://readthedocs.org/projects/inflect/badge/?version=latest :target: https://inflect.readthedocs.io/en/latest/?badge=latest

.. image:: https://img.shields.io/badge/skeleton-2025-informational :target: https://blog.jaraco.com/skeleton

.. image:: https://tidelift.com/badges/package/pypi/inflect :target: https://tidelift.com/subscription/pkg/pypi-inflect?utm_source=pypi-inflect&utm_medium=readme

NAME

inflect.py - Accurately generate plurals, singular nouns, ordinals, indefinite articles, and word-based representations of numbers. This functionality is limited to English.

SYNOPSIS

.. code-block:: python

>>> import inflect
>>> p = inflect.engine()

Simple example with pluralization and word-representation of numbers:

.. code-block:: python

>>> count=1
>>> print('There', p.plural_verb('was', count), p.number_to_words(count), p.plural_noun('person', count), 'by the door.')
There was one person by the door.

When count=243, the same code will generate:

.. code-block:: python

There were two hundred and forty-three people by the door.

Methods

• plural, plural_noun, plural_verb, plural_adj, singular_noun, no, num
• compare, compare_nouns, compare_nouns, compare_adjs
• a, an
• present_participle
• ordinal, number_to_words
• join
• inflect, classical, gender
• defnoun, defverb, defadj, defa, defan

Plurality/Singularity

Unconditionally Form the Plural ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

>>> "the plural of person is " + p.plural("person")
'the plural of person is people'

Conditionally Form the Plural ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

>>> "the plural of 1 person is " + p.plural("person", 1)
'the plural of 1 person is person'

Form Plurals for Specific Parts of Speech ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

>>> p.plural_noun("I", 2)
'we'
>>> p.plural_verb("saw", 1)
'saw'
>>> p.plural_adj("my", 2)
'our'
>>> p.plural_noun("saw", 2)
'saws'

Form the Singular of Plural Nouns ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

>>> "The singular of people is " + p.singular_noun("people")
'The singular of people is person'

Select the Gender of Singular Pronouns ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

>>> p.singular_noun("they")
'it'
>>> p.gender("feminine")
>>> p.singular_noun("they")
'she'

Deal with "0/1/N" -> "no/1/N" Translation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

>>> errors = 1
>>> "There ", p.plural_verb("was", errors), p.no(" error", errors)
('There ', 'was', ' 1 error')
>>> errors = 2
>>> "There ", p.plural_verb("was", errors), p.no(" error", errors)
('There ', 'were', ' 2 errors')

Use Default Counts ^^^^^^^^^^^^^^^^^^

.. code-block:: python

>>> p.num(1, "")
''
>>> p.plural("I")
'I'
>>> p.plural_verb(" saw")
' saw'
>>> p.num(2)
'2'
>>> p.plural_noun(" saw")
' saws'
>>> "There ", p.num(errors, ""), p.plural_verb("was"), p.no(" error")
('There ', '', 'were', ' 2 errors')

Compare Two Words Number-Intensitively ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

>>> p.compare('person', 'person')
'eq'
>>> p.compare('person', 'people')
's:p'
>>> p.compare_nouns('person', 'people')
's:p'
>>> p.compare_verbs('run', 'ran')
False
>>> p.compare_verbs('run', 'running')
False
>>> p.compare_verbs('run', 'run')
'eq'
>>> p.compare_adjs('my', 'mine')
False
>>> p.compare_adjs('my', 'our')
's:p'

Add Correct a or an for a Given Word ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

>>> "Did you want ", p.a('thing'), " or ", p.a('idea')
('Did you want ', 'a thing', ' or ', 'an idea')

Convert Numerals into Ordinals ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

>>> "It was", p.ordinal(1), " from the left"
('It was', '1st', ' from the left')
>>> "It was", p.ordinal(2), " from the left"
('It was', '2nd', ' from the left')
>>> "It was", p.ordinal(3), " from the left"
('It was', '3rd', ' from the left')
>>> "It was", p.ordinal(347), " from the left"
('It was', '347th', ' from the left')

Convert Numerals to Words ^^^^^^^^^^^^^^^^^^^^^^^^^ Note: This returns a single string.

.. code-block:: python

>>> p.number_to_words(1)
'one'
>>> p.number_to_words(38)
'thirty-eight'
>>> p.number_to_words(1234)
'one thousand, two hundred and thirty-four'
>>> p.number_to_words(p.ordinal(1234))
'one thousand, two hundred and thirty-fourth'

Retrieve Words as List of Parts ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

>>> p.number_to_words(1234, wantlist=True)
['one thousand', 'two hundred and thirty-four']

Grouping Options ^^^^^^^^^^^^^^^^

.. code-block:: python

>>> p.number_to_words(12345, group=1)
'one, two, three, four, five'
>>> p.number_to_words(12345, group=2)
'twelve, thirty-four, five'
>>> p.number_to_words(12345, group=3)
'one twenty-three, forty-five'
>>> p.number_to_words(1234, andword="")
'one thousand, two hundred thirty-four'
>>> p.number_to_words(1234, andword=", plus")
'one thousand, two hundred, plus thirty-four'
>>> p.number_to_words(555_1202, group=1, zero="oh")
'five, five, five, one, two, oh, two'
>>> p.number_to_words(555_1202, group=1, one="unity")
'five, five, five, unity, two, zero, two'
>>> p.number_to_words(123.456, group=1, decimal="mark")
'one, two, three, mark, four, five, six'

Apply Threshold for Word-Representation of Numbers ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Above provided threshold, numberals will remain numerals

.. code-block:: python

>>> p.number_to_words(9, threshold=10)
'nine'
>>> p.number_to_words(10, threshold=10)
'ten'
>>> p.number_to_words(11, threshold=10)
'11'
>>> p.number_to_words(1000, threshold=10)
'1,000'

Join Words into a List ^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

>>> p.join(("apple", "banana", "carrot"))
'apple, banana, and carrot'
>>> p.join(("apple", "banana"))
'apple and banana'
>>> p.join(("apple", "banana", "carrot"), final_sep="")
'apple, banana and carrot'
>>> p.join(('apples', 'bananas', 'carrots'), conj='and even')
'apples, bananas, and even carrots'
>>> p.join(('apple', 'banana', 'carrot'), sep='/', sep_spaced=False, conj='', conj_spaced=False)
'apple/banana/carrot'

Require Classical Plurals ^^^^^^^^^^^^^^^^^^^^^^^^^ Adhere to conventions from Classical Latin and Classical Greek

.. code-block:: python

>>> p.classical()
>>> p.plural_noun("focus", 2)
'foci'
>>> p.plural_noun("cherubim", 2)
'cherubims'
>>> p.plural_noun("cherub", 2)
'cherubim'

Other options for classical plurals:

.. code-block:: python

p.classical(all=True)  # USE ALL CLASSICAL PLURALS
p.classical(all=False)  # SWITCH OFF CLASSICAL MODE

p.classical(zero=True)  #  "no error" INSTEAD OF "no errors"
p.classical(zero=False)  #  "no errors" INSTEAD OF "no error"

p.classical(herd=True)  #  "2 buffalo" INSTEAD OF "2 buffalos"
p.classical(herd=False)  #  "2 buffalos" INSTEAD OF "2 buffalo"

p.classical(persons=True)  # "2 chairpersons" INSTEAD OF "2 chairpeople"
p.classical(persons=False)  # "2 chairpeople" INSTEAD OF "2 chairpersons"

p.classical(ancient=True)  # "2 formulae" INSTEAD OF "2 formulas"
p.classical(ancient=False)  # "2 formulas" INSTEAD OF "2 formulae"

Support for interpolation ^^^^^^^^^^^^^^^^^^^^^^^^^ Supports string interpolation with the following functions: plural(), plural_noun(), plural_verb(), plural_adj(), singular_noun(), a(), an(), num() and ordinal().

.. code-block:: python

>>> p.inflect("The plural of {0} is plural('{0}')".format('car'))
'The plural of car is cars'
>>> p.inflect("The singular of {0} is singular_noun('{0}')".format('car'))
'The singular of car is car'
>>> p.inflect("I saw {0} plural('cat',{0})".format(3))
'I saw 3 cats'
>>> p.inflect(
...     "plural('I',{0}) "
...     "plural_verb('saw',{0}) "
...     "plural('a',{1}) "
...     "plural_noun('saw',{1})".format(1, 2)
... )
'I saw some saws'
>>> p.inflect(
...     "num({0}, False)plural('I') "
...     "plural_verb('saw') "
...     "num({1}, False)plural('a') "
...     "plural_noun('saw')".format(N1, 1)
... )
'I saw a saw'
>>> p.inflect(
...     "num({0}, False)plural('I') "
...     "plural_verb('saw') "
...     "num({1}, False)plural('a') "
...     "plural_noun('saw')".format(2, 2)
... )
'we saw some saws'
>>> p.inflect("I saw num({0}) plural('cat')\nnum()".format(cat_count))
'I saw 3 cats\n'
>>> p.inflect("There plural_verb('was',{0}) no('error',{0})".format(errors))
'There were 2 errors'
>>> p.inflect("There num({0}, False)plural_verb('was') no('error')".format(errors))
'There were 2 errors'
>>> p.inflect("Did you want a('{0}') or an('{1}'