Welcome to inflect documentation!#

For Enterprise

Professional support for inflect is available as part of the Tidelift Subscription. Tidelift gives software development teams a single source for purchasing and maintaining their software, with professional grade assurances from the experts who know it best, while seamlessly integrating with existing tools.

Learn more Request a Demo

inflect: english language inflection
  • correctly generate plurals, ordinals, indefinite articles

  • convert numbers to words

Copyright (C) 2010 Paul Dyson

Based upon the Perl module Lingua::EN::Inflect.

methods:

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

INFLECTIONS:

classical inflect plural plural_noun plural_verb plural_adj singular_noun compare no num a an present_participle

PLURALS:

classical inflect plural plural_noun plural_verb plural_adj singular_noun no num compare compare_nouns compare_verbs compare_adjs

COMPARISONS:

classical compare compare_nouns compare_verbs compare_adjs

ARTICLES:

classical inflect num a an

NUMERICAL:

ordinal number_to_words

USER_DEFINED:

defnoun defverb defadj defa defan

Exceptions:

UnknownClassicalModeError BadNumValueError BadChunkingOptionError NumOutOfRangeError BadUserDefinedPatternError BadRcFileError BadGenderError

exception inflect.BadChunkingOptionError#

Bases: Exception

exception inflect.BadGenderError#

Bases: Exception

exception inflect.BadNumValueError#

Bases: Exception

exception inflect.BadRcFileError#

Bases: Exception

exception inflect.BadUserDefinedPatternError#

Bases: Exception

exception inflect.NumOutOfRangeError#

Bases: Exception

exception inflect.UnknownClassicalModeError#

Bases: Exception

class inflect.Words(orig)#

Bases: str

first: str#
last: str#
lowered: str#
split_: List[str]#
inflect.bysize(words: Iterable[str]) Dict[int, set]#

From a list of words, return a dict of sets sorted by word length.

>>> words = ['ant', 'cat', 'dog', 'pig', 'frog', 'goat', 'horse', 'elephant']
>>> ret = bysize(words)
>>> sorted(ret[3])
['ant', 'cat', 'dog', 'pig']
>>> ret[5]
{'horse'}
inflect.enclose(s: str) str#
class inflect.engine#

Bases: object

a(text: str, count: str | int | Any | None = 1) str#

Return the appropriate indefinite article followed by text.

The indefinite article is either ‘a’ or ‘an’.

If count is not one, then return count followed by text instead of ‘a’ or ‘an’.

Whitespace at the start and end is preserved.

an(text: str, count: str | int | Any | None = 1) str#

Return the appropriate indefinite article followed by text.

The indefinite article is either ‘a’ or ‘an’.

If count is not one, then return count followed by text instead of ‘a’ or ‘an’.

Whitespace at the start and end is preserved.

checkpat(pattern: str | None) None#

check for errors in a regex pattern

checkpatplural(pattern: str | None) None#

check for errors in a regex replace pattern

classical(**kwargs) None#

turn classical mode on and off for various categories

turn on all classical modes: classical() classical(all=True)

turn on or off specific claassical modes: e.g. classical(herd=True) classical(names=False)

By default all classical modes are off except names.

unknown value in args or key in kwargs raises exception: UnknownClasicalModeError

compare(word1: str, word2: str) str | bool#

compare word1 and word2 for equality regardless of plurality

return values: eq - the strings are equal p:s - word1 is the plural of word2 s:p - word2 is the plural of word1 p:p - word1 and word2 are two different plural forms of the one word False - otherwise

>>> compare = engine().compare
>>> compare("egg", "eggs")
's:p'
>>> compare('egg', 'egg')
'eq'

Words should not be empty.

>>> compare('egg', '')
Traceback (most recent call last):
...
pydantic...ValidationError: ...
...
  ...at least 1 characters...
compare_adjs(word1: str, word2: str) str | bool#

compare word1 and word2 for equality regardless of plurality word1 and word2 are to be treated as adjectives

return values: eq - the strings are equal p:s - word1 is the plural of word2 s:p - word2 is the plural of word1 p:p - word1 and word2 are two different plural forms of the one word False - otherwise

compare_nouns(word1: str, word2: str) str | bool#

compare word1 and word2 for equality regardless of plurality word1 and word2 are to be treated as nouns

return values: eq - the strings are equal p:s - word1 is the plural of word2 s:p - word2 is the plural of word1 p:p - word1 and word2 are two different plural forms of the one word False - otherwise

compare_verbs(word1: str, word2: str) str | bool#

compare word1 and word2 for equality regardless of plurality word1 and word2 are to be treated as verbs

return values: eq - the strings are equal p:s - word1 is the plural of word2 s:p - word2 is the plural of word1 p:p - word1 and word2 are two different plural forms of the one word False - otherwise

defa(pattern: str | None) int#

Define the indefinite article as ‘a’ for words matching pattern.

defadj(singular: str | None, plural: str | None) int#

Set the adjective plural of singular to plural.

defan(pattern: str | None) int#

Define the indefinite article as ‘an’ for words matching pattern.

defnoun(singular: str | None, plural: str | None) int#

Set the noun plural of singular to plural.

defverb(s1: str | None, p1: str | None, s2: str | None, p2: str | None, s3: str | None, p3: str | None) int#

Set the verb plurals for s1, s2 and s3 to p1, p2 and p3 respectively.

Where 1, 2 and 3 represent the 1st, 2nd and 3rd person forms of the verb.

enword(num: str, group: int) str#
gender(gender: str) None#

set the gender for the singular of plural pronouns

can be one of: ‘neuter’ (‘they’ -> ‘it’) ‘feminine’ (‘they’ -> ‘she’) ‘masculine’ (‘they’ -> ‘he’) ‘gender-neutral’ (‘they’ -> ‘they’) ‘feminine or masculine’ (‘they’ -> ‘she or he’) ‘masculine or feminine’ (‘they’ -> ‘he or she’)

get_count(count: str | int | None = None) str | int#
group1bsub(mo: Match) str#
group1sub(mo: Match) str#
group2sub(mo: Match) str#
group3sub(mo: Match) str#
hundfn(hundreds: int, tens: int, units: int, mindex: int) str#
hundsub(mo: Match) str#
inflect(text: str) str#

Perform inflections in a string.

e.g. inflect(‘The plural of cat is plural(cat)’) returns ‘The plural of cat is cats’

can use plural, plural_noun, plural_verb, plural_adj, singular_noun, a, an, no, ordinal, number_to_words, and prespart

join(words: Sequence[str] | None, sep: str | None = None, sep_spaced: bool = True, final_sep: str | None = None, conj: str = 'and', conj_spaced: bool = True) str#

Join words into a list.

e.g. join([‘ant’, ‘bee’, ‘fly’]) returns ‘ant, bee, and fly’

options: conj: replacement for ‘and’ sep: separator. default ‘,’, unless ‘,’ is in the list then ‘;’ final_sep: final separator. default ‘,’, unless ‘,’ is in the list then ‘;’ conj_spaced: boolean. Should conj have spaces around it

millfn(ind: int = 0) str#
no(text: str, count: str | int | None = None) str#

If count is 0, no, zero or nil, return ‘no’ followed by the plural of text.

If count is one of:

1, a, an, one, each, every, this, that return count followed by text.

Otherwise return count follow by the plural of text.

In the return value count is always followed by a space.

Whitespace at the start and end is preserved.

num(count: int | None = None, show: int | None = None) str#

Set the number to be used in other method calls.

Returns count.

Set show to False to return ‘’ instead.

number_to_words(num: Number | str, wantlist: bool = False, group: int = 0, comma: Any | str = ',', andword: str = 'and', zero: str = 'zero', one: str = 'one', decimal: Any | str = 'point', threshold: int | None = None) str | List[str]#

Return a number in words.

group = 1, 2 or 3 to group numbers before turning into words comma: define comma

andword:

word for ‘and’. Can be set to ‘’. e.g. “one hundred and one” vs “one hundred one”

zero: word for ‘0’ one: word for ‘1’ decimal: word for decimal point threshold: numbers above threshold not turned into words

parameters not remembered from last call. Departure from Perl version.

ordinal(num: Number | str) str#

Return the ordinal of num.

>>> ordinal = engine().ordinal
>>> ordinal(1)
'1st'
>>> ordinal('one')
'first'
partition_word(text: str) Tuple[str, str, str]#
plural(text: str, count: str | int | Any | None = None) str#

Return the plural of text.

If count supplied, then return text if count is one of:

1, a, an, one, each, every, this, that

otherwise return the plural.

Whitespace at the start and end is preserved.

plural_adj(text: str, count: str | int | Any | None = None) str#

Return the plural of text, where text is an adjective.

If count supplied, then return text if count is one of:

1, a, an, one, each, every, this, that

otherwise return the plural.

Whitespace at the start and end is preserved.

plural_noun(text: str, count: str | int | Any | None = None) str#

Return the plural of text, where text is a noun.

If count supplied, then return text if count is one of:

1, a, an, one, each, every, this, that

otherwise return the plural.

Whitespace at the start and end is preserved.

plural_verb(text: str, count: str | int | Any | None = None) str#

Return the plural of text, where text is a verb.

If count supplied, then return text if count is one of:

1, a, an, one, each, every, this, that

otherwise return the plural.

Whitespace at the start and end is preserved.

postprocess(orig: str, inflected) str#
present_participle(word: str) str#

Return the present participle for word.

word is the 3rd person singular verb.

singular_noun(text: str, count: str | int | Any | None = None, gender: str | None = None) str | Literal[False]#

Return the singular of text, where text is a plural noun.

If count supplied, then return the singular if count is one of:

1, a, an, one, each, every, this, that or if count is None

otherwise return text unchanged.

Whitespace at the start and end is preserved.

>>> p = engine()
>>> p.singular_noun('horses')
'horse'
>>> p.singular_noun('knights')
'knight'

Returns False when a singular noun is passed.

>>> p.singular_noun('horse')
False
>>> p.singular_noun('knight')
False
>>> p.singular_noun('soldier')
False
tenfn(tens, units, mindex=0) str#
tensub(mo: Match) str#
ud_match(word: str, wordlist: Sequence[str | None]) str | None#
unitfn(units: int, mindex: int = 0) str#
unitsub(mo: Match) str#
inflect.get_si_pron(thecase, word, gender) str#
inflect.joinstem(cutpoint: int | None = 0, words: Iterable[str] | None = None) str#

Join stem of each word in words into a string for regex.

Each word is truncated at cutpoint.

Cutpoint is usually negative indicating the number of letters to remove from the end of each word.

>>> joinstem(-2, ["ephemeris", "iris", ".*itis"])
'(?:ephemer|ir|.*it)'
>>> joinstem(None, ["ephemeris"])
'(?:ephemeris)'
>>> joinstem(5, None)
'(?:)'
inflect.make_pl_si_lists(lst: Iterable[str], plending: str, siendingsize: int | None, dojoinstem: bool = True)#

given a list of singular words: lst

an ending to append to make the plural: plending

the number of characters to remove from the singular before appending plending: siendingsize

a flag whether to create a joinstem: dojoinstem

return: a list of pluralised words: si_list (called si because this is what you need to look for to make the singular)

the pluralised words as a dict of sets sorted by word length: si_bysize the singular words as a dict of sets sorted by word length: pl_bysize if dojoinstem is True: a regular expression that matches any of the stems: stem

Indices and tables#