| Name | inflect JSON |
| Version |
7.4.0
JSON |
| download |
| home_page | None |
| Summary | Correctly generate plurals, singular nouns, ordinals, indefinite articles |
| upload_time | 2024-09-07 13:06:35 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
plural
inflect
participle
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
|
.. 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/charliermarsh/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-2024-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()
# 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
# UNCONDITIONALLY FORM THE PLURAL
print("The plural of ", word, " is ", p.plural(word))
# CONDITIONALLY FORM THE PLURAL
print("I saw", cat_count, p.plural("cat", cat_count))
# FORM PLURALS FOR SPECIFIC PARTS OF SPEECH
print(
p.plural_noun("I", N1),
p.plural_verb("saw", N1),
p.plural_adj("my", N2),
p.plural_noun("saw", N2),
)
# FORM THE SINGULAR OF PLURAL NOUNS
print("The singular of ", word, " is ", p.singular_noun(word))
# SELECT THE GENDER OF SINGULAR PRONOUNS
print(p.singular_noun("they")) # 'it'
p.gender("feminine")
print(p.singular_noun("they")) # 'she'
# DEAL WITH "0/1/N" -> "no/1/N" TRANSLATION:
print("There ", p.plural_verb("was", errors), p.no(" error", errors))
# USE DEFAULT COUNTS:
print(
p.num(N1, ""),
p.plural("I"),
p.plural_verb(" saw"),
p.num(N2),
p.plural_noun(" saw"),
)
print("There ", p.num(errors, ""), p.plural_verb("was"), p.no(" error"))
# COMPARE TWO WORDS "NUMBER-INSENSITIVELY":
if p.compare(word1, word2):
print("same")
if p.compare_nouns(word1, word2):
print("same noun")
if p.compare_verbs(word1, word2):
print("same verb")
if p.compare_adjs(word1, word2):
print("same adj.")
# ADD CORRECT "a" OR "an" FOR A GIVEN WORD:
print("Did you want ", p.a(thing), " or ", p.an(idea))
# CONVERT NUMERALS INTO ORDINALS (i.e. 1->1st, 2->2nd, 3->3rd, etc.)
print("It was", p.ordinal(position), " from the left\n")
# CONVERT NUMERALS TO WORDS (i.e. 1->"one", 101->"one hundred and one", etc.)
# RETURNS A SINGLE STRING...
words = p.number_to_words(1234)
# "one thousand, two hundred and thirty-four"
words = p.number_to_words(p.ordinal(1234))
# "one thousand, two hundred and thirty-fourth"
# GET BACK A LIST OF STRINGS, ONE FOR EACH "CHUNK"...
words = p.number_to_words(1234, wantlist=True)
# ("one thousand","two hundred and thirty-four")
# OPTIONAL PARAMETERS CHANGE TRANSLATION:
words = p.number_to_words(12345, group=1)
# "one, two, three, four, five"
words = p.number_to_words(12345, group=2)
# "twelve, thirty-four, five"
words = p.number_to_words(12345, group=3)
# "one twenty-three, forty-five"
words = p.number_to_words(1234, andword="")
# "one thousand, two hundred thirty-four"
words = p.number_to_words(1234, andword=", plus")
# "one thousand, two hundred, plus thirty-four"
# TODO: I get no comma before plus: check perl
words = p.number_to_words(555_1202, group=1, zero="oh")
# "five, five, five, one, two, oh, two"
words = p.number_to_words(555_1202, group=1, one="unity")
# "five, five, five, unity, two, oh, two"
words = p.number_to_words(123.456, group=1, decimal="mark")
# "one two three mark four five six"
# TODO: DOCBUG: perl gives commas here as do I
# LITERAL STYLE ONLY NAMES NUMBERS LESS THAN A CERTAIN THRESHOLD...
words = p.number_to_words(9, threshold=10) # "nine"
words = p.number_to_words(10, threshold=10) # "ten"
words = p.number_to_words(11, threshold=10) # "11"
words = p.number_to_words(1000, threshold=10) # "1,000"
# JOIN WORDS INTO A LIST:
mylist = p.join(("apple", "banana", "carrot"))
# "apple, banana, and carrot"
mylist = p.join(("apple", "banana"))
# "apple and banana"
mylist = p.join(("apple", "banana", "carrot"), final_sep="")
# "apple, banana and carrot"
# REQUIRE "CLASSICAL" PLURALS (EG: "focus"->"foci", "cherub"->"cherubim")
p.classical() # USE ALL CLASSICAL PLURALS
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"
# INTERPOLATE "plural()", "plural_noun()", "plural_verb()", "plural_adj()", "singular_noun()",
# a()", "an()", "num()" AND "ordinal()" WITHIN STRINGS:
print(p.inflect("The plural of {0} is plural('{0}')".format(word)))
print(p.inflect("The singular of {0} is singular_noun('{0}')".format(word)))
print(p.inflect("I saw {0} plural('cat',{0})".format(cat_count)))
print(
p.inflect(
"plural('I',{0}) "
"plural_verb('saw',{0}) "
"plural('a',{1}) "
"plural_noun('saw',{1})".format(N1, N2)
)
)
print(
p.inflect(
"num({0}, False)plural('I') "
"plural_verb('saw') "
"num({1}, False)plural('a') "
"plural_noun('saw')".format(N1, N2)
)
)
print(p.inflect("I saw num({0}) plural('cat')\nnum()".format(cat_count)))
print(p.inflect("There plural_verb('was',{0}) no('error',{0})".format(errors)))
print(p.inflect("There num({0}, False)plural_verb('was') no('error')".format(errors)))
print(p.inflect("Did you want a('{0}') or an('{1}')".format(thing, idea)))
print(p.inflect("It was ordinal('{0}') from the left".format(position)))
# ADD USER-DEFINED INFLECTIONS (OVERRIDING INBUILT RULES):
p.defnoun("VAX", "VAXen") # SINGULAR => PLURAL
p.defverb(
"will", # 1ST PERSON SINGULAR
"shall", # 1ST PERSON PLURAL
"will", # 2ND PERSON SINGULAR
"will", # 2ND PERSON PLURAL
"will", # 3RD PERSON SINGULAR
"will", # 3RD PERSON PLURAL
)
p.defadj("hir", "their") # SINGULAR => PLURAL
p.defa("h") # "AY HALWAYS SEZ 'HAITCH'!"
p.defan("horrendous.*") # "AN HORRENDOUS AFFECTATION"
DESCRIPTION
===========
The methods of the class ``engine`` in module ``inflect.py`` provide plural
inflections, singular noun inflections, "a"/"an" selection for English words,
and manipulation of numbers as words.
Plural forms of all nouns, most verbs, and some adjectives are
provided. Where appropriate, "classical" variants (for example: "brother" ->
"brethren", "dogma" -> "dogmata", etc.) are also provided.
Single forms of nouns are also provided. The gender of singular pronouns
can be chosen (for example "they" -> "it" or "she" or "he" or "they").
Pronunciation-based "a"/"an" selection is provided for all English
words, and most initialisms.
It is also possible to inflect numerals (1,2,3) to ordinals (1st, 2nd, 3rd)
and to English words ("one", "two", "three").
In generating these inflections, ``inflect.py`` follows the Oxford
English Dictionary and the guidelines in Fowler's Modern English
Usage, preferring the former where the two disagree.
The module is built around standard British spelling, but is designed
to cope with common American variants as well. Slang, jargon, and
other English dialects are *not* explicitly catered for.
Where two or more inflected forms exist for a single word (typically a
"classical" form and a "modern" form), ``inflect.py`` prefers the
more common form (typically the "modern" one), unless "classical"
processing has been specified
(see `MODERN VS CLASSICAL INFLECTIONS`).
FORMING PLURALS AND SINGULARS
=============================
Inflecting Plurals and Singulars
--------------------------------
All of the ``plural...`` plural inflection methods take the word to be
inflected as their first argument and return the corresponding inflection.
Note that all such methods expect the *singular* form of the word. The
results of passing a plural form are undefined (and unlikely to be correct).
Similarly, the ``si...`` singular inflection method expects the *plural*
form of the word.
The ``plural...`` methods also take an optional second argument,
which indicates the grammatical "number" of the word (or of another word
with which the word being inflected must agree). If the "number" argument is
supplied and is not ``1`` (or ``"one"`` or ``"a"``, or some other adjective that
implies the singular), the plural form of the word is returned. If the
"number" argument *does* indicate singularity, the (uninflected) word
itself is returned. If the number argument is omitted, the plural form
is returned unconditionally.
The ``si...`` method takes a second argument in a similar fashion. If it is
some form of the number ``1``, or is omitted, the singular form is returned.
Otherwise the plural is returned unaltered.
The various methods of ``inflect.engine`` are:
``plural_noun(word, count=None)``
The method ``plural_noun()`` takes a *singular* English noun or
pronoun and returns its plural. Pronouns in the nominative ("I" ->
"we") and accusative ("me" -> "us") cases are handled, as are
possessive pronouns ("mine" -> "ours").
``plural_verb(word, count=None)``
The method ``plural_verb()`` takes the *singular* form of a
conjugated verb (that is, one which is already in the correct "person"
and "mood") and returns the corresponding plural conjugation.
``plural_adj(word, count=None)``
The method ``plural_adj()`` takes the *singular* form of
certain types of adjectives and returns the corresponding plural form.
Adjectives that are correctly handled include: "numerical" adjectives
("a" -> "some"), demonstrative adjectives ("this" -> "these", "that" ->
"those"), and possessives ("my" -> "our", "cat's" -> "cats'", "child's"
-> "childrens'", etc.)
``plural(word, count=None)``
The method ``plural()`` takes a *singular* English noun,
pronoun, verb, or adjective and returns its plural form. Where a word
has more than one inflection depending on its part of speech (for
example, the noun "thought" inflects to "thoughts", the verb "thought"
to "thought"), the (singular) noun sense is preferred to the (singular)
verb sense.
Hence ``plural("knife")`` will return "knives" ("knife" having been treated
as a singular noun), whereas ``plural("knifes")`` will return "knife"
("knifes" having been treated as a 3rd person singular verb).
The inherent ambiguity of such cases suggests that,
where the part of speech is known, ``plural_noun``, ``plural_verb``, and
``plural_adj`` should be used in preference to ``plural``.
``singular_noun(word, count=None)``
The method ``singular_noun()`` takes a *plural* English noun or
pronoun and returns its singular. Pronouns in the nominative ("we" ->
"I") and accusative ("us" -> "me") cases are handled, as are
possessive pronouns ("ours" -> "mine"). When third person
singular pronouns are returned they take the neuter gender by default
("they" -> "it"), not ("they"-> "she") nor ("they" -> "he"). This can be
changed with ``gender()``.
Note that all these methods ignore any whitespace surrounding the
word being inflected, but preserve that whitespace when the result is
returned. For example, ``plural(" cat ")`` returns " cats ".
``gender(genderletter)``
The third person plural pronoun takes the same form for the female, male and
neuter (e.g. "they"). The singular however, depends upon gender (e.g. "she",
"he", "it" and "they" -- "they" being the gender neutral form.) By default
``singular_noun`` returns the neuter form, however, the gender can be selected with
the ``gender`` method. Pass the first letter of the gender to
``gender`` to return the f(eminine), m(asculine), n(euter) or t(hey)
form of the singular. e.g.
gender('f') followed by singular_noun('themselves') returns 'herself'.
Numbered plurals
----------------
The ``plural...`` methods return only the inflected word, not the count that
was used to inflect it. Thus, in order to produce "I saw 3 ducks", it
is necessary to use:
.. code-block:: python
print("I saw", N, p.plural_noun(animal, N))
Since the usual purpose of producing a plural is to make it agree with
a preceding count, inflect.py provides a method
(``no(word, count)``) which, given a word and a(n optional) count, returns the
count followed by the correctly inflected word. Hence the previous
example can be rewritten:
.. code-block:: python
print("I saw ", p.no(animal, N))
In addition, if the count is zero (or some other term which implies
zero, such as ``"zero"``, ``"nil"``, etc.) the count is replaced by the
word "no". Hence, if ``N`` had the value zero, the previous example
would print (the somewhat more elegant)::
I saw no animals
rather than::
I saw 0 animals
Note that the name of the method is a pun: the method
returns either a number (a *No.*) or a ``"no"``, in front of the
inflected word.
Reducing the number of counts required
--------------------------------------
In some contexts, the need to supply an explicit count to the various
``plural...`` methods makes for tiresome repetition. For example:
.. code-block:: python
print(
plural_adj("This", errors),
plural_noun(" error", errors),
plural_verb(" was", errors),
" fatal.",
)
inflect.py therefore provides a method
(``num(count=None, show=None)``) which may be used to set a persistent "default number"
value. If such a value is set, it is subsequently used whenever an
optional second "number" argument is omitted. The default value thus set
can subsequently be removed by calling ``num()`` with no arguments.
Hence we could rewrite the previous example:
.. code-block:: python
p.num(errors)
print(p.plural_adj("This"), p.plural_noun(" error"), p.plural_verb(" was"), "fatal.")
p.num()
Normally, ``num()`` returns its first argument, so that it may also
be "inlined" in contexts like:
.. code-block:: python
print(p.num(errors), p.plural_noun(" error"), p.plural_verb(" was"), " detected.")
if severity > 1:
print(
p.plural_adj("This"), p.plural_noun(" error"), p.plural_verb(" was"), "fatal."
)
However, in certain contexts (see `INTERPOLATING INFLECTIONS IN STRINGS`)
it is preferable that ``num()`` return an empty string. Hence ``num()``
provides an optional second argument. If that argument is supplied (that is, if
it is defined) and evaluates to false, ``num`` returns an empty string
instead of its first argument. For example:
.. code-block:: python
print(p.num(errors, 0), p.no("error"), p.plural_verb(" was"), " detected.")
if severity > 1:
print(
p.plural_adj("This"), p.plural_noun(" error"), p.plural_verb(" was"), "fatal."
)
Number-insensitive equality
---------------------------
inflect.py also provides a solution to the problem
of comparing words of differing plurality through the methods
``compare(word1, word2)``, ``compare_nouns(word1, word2)``,
``compare_verbs(word1, word2)``, and ``compare_adjs(word1, word2)``.
Each of these methods takes two strings, and compares them
using the corresponding plural-inflection method (``plural()``, ``plural_noun()``,
``plural_verb()``, and ``plural_adj()`` respectively).
The comparison returns true if:
- the strings are equal, or
- one string is equal to a plural form of the other, or
- the strings are two different plural forms of the one word.
Hence all of the following return true:
.. code-block:: python
p.compare("index", "index") # RETURNS "eq"
p.compare("index", "indexes") # RETURNS "s:p"
p.compare("index", "indices") # RETURNS "s:p"
p.compare("indexes", "index") # RETURNS "p:s"
p.compare("indices", "index") # RETURNS "p:s"
p.compare("indices", "indexes") # RETURNS "p:p"
p.compare("indexes", "indices") # RETURNS "p:p"
p.compare("indices", "indices") # RETURNS "eq"
As indicated by the comments in the previous example, the actual value
returned by the various ``compare`` methods encodes which of the
three equality rules succeeded: "eq" is returned if the strings were
identical, "s:p" if the strings were singular and plural respectively,
"p:s" for plural and singular, and "p:p" for two distinct plurals.
Inequality is indicated by returning an empty string.
It should be noted that two distinct singular words which happen to take
the same plural form are *not* considered equal, nor are cases where
one (singular) word's plural is the other (plural) word's singular.
Hence all of the following return false:
.. code-block:: python
p.compare("base", "basis") # ALTHOUGH BOTH -> "bases"
p.compare("syrinx", "syringe") # ALTHOUGH BOTH -> "syringes"
p.compare("she", "he") # ALTHOUGH BOTH -> "they"
p.compare("opus", "operas") # ALTHOUGH "opus" -> "opera" -> "operas"
p.compare("taxi", "taxes") # ALTHOUGH "taxi" -> "taxis" -> "taxes"
Note too that, although the comparison is "number-insensitive" it is *not*
case-insensitive (that is, ``plural("time","Times")`` returns false. To obtain
both number and case insensitivity, use the ``lower()`` method on both strings
(that is, ``plural("time".lower(), "Times".lower())`` returns true).
Related Functionality
=====================
Shout out to these libraries that provide related functionality:
* `WordSet <https://jaracotext.readthedocs.io/en/latest/#jaraco.text.WordSet>`_
parses identifiers like variable names into sets of words suitable for re-assembling
in another form.
* `word2number <https://pypi.org/project/word2number/>`_ converts words to
a number.
For Enterprise
==============
Available as part of the Tidelift Subscription.
This project and the maintainers of thousands of other packages are working with Tidelift to deliver one enterprise subscription that covers all of the open source you use.
`Learn more <https://tidelift.com/subscription/pkg/pypi-PROJECT?utm_source=pypi-PROJECT&utm_medium=referral&utm_campaign=github>`_.
Raw data
{
"_id": null,
"home_page": null,
"name": "inflect",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "\"Jason R. Coombs\" <jaraco@jaraco.com>",
"keywords": "plural, inflect, participle",
"author": null,
"author_email": "Paul Dyson <pwdyson@yahoo.com>",
"download_url": "https://files.pythonhosted.org/packages/e1/dc/02614acece4d578e709c606594c989cfd9f15cf6401444e5603e60df9b26/inflect-7.4.0.tar.gz",
"platform": null,
"description": ".. image:: https://img.shields.io/pypi/v/inflect.svg\n :target: https://pypi.org/project/inflect\n\n.. image:: https://img.shields.io/pypi/pyversions/inflect.svg\n\n.. image:: https://github.com/jaraco/inflect/actions/workflows/main.yml/badge.svg\n :target: https://github.com/jaraco/inflect/actions?query=workflow%3A%22tests%22\n :alt: tests\n\n.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json\n :target: https://github.com/astral-sh/ruff\n :alt: Ruff\n\n.. image:: https://readthedocs.org/projects/inflect/badge/?version=latest\n :target: https://inflect.readthedocs.io/en/latest/?badge=latest\n\n.. image:: https://img.shields.io/badge/skeleton-2024-informational\n :target: https://blog.jaraco.com/skeleton\n\n.. image:: https://tidelift.com/badges/package/pypi/inflect\n :target: https://tidelift.com/subscription/pkg/pypi-inflect?utm_source=pypi-inflect&utm_medium=readme\n\nNAME\n====\n\ninflect.py - Accurately generate plurals, singular nouns, ordinals, indefinite articles, and word-based representations of numbers. This functionality is limited to English.\n\nSYNOPSIS\n========\n\n.. code-block:: python\n\n import inflect\n\n p = inflect.engine()\n\n # METHODS:\n\n # plural plural_noun plural_verb plural_adj singular_noun no num\n # compare compare_nouns compare_nouns compare_adjs\n # a an\n # present_participle\n # ordinal number_to_words\n # join\n # inflect classical gender\n # defnoun defverb defadj defa defan\n\n\n # UNCONDITIONALLY FORM THE PLURAL\n\n print(\"The plural of \", word, \" is \", p.plural(word))\n\n\n # CONDITIONALLY FORM THE PLURAL\n\n print(\"I saw\", cat_count, p.plural(\"cat\", cat_count))\n\n\n # FORM PLURALS FOR SPECIFIC PARTS OF SPEECH\n\n print(\n p.plural_noun(\"I\", N1),\n p.plural_verb(\"saw\", N1),\n p.plural_adj(\"my\", N2),\n p.plural_noun(\"saw\", N2),\n )\n\n\n # FORM THE SINGULAR OF PLURAL NOUNS\n\n print(\"The singular of \", word, \" is \", p.singular_noun(word))\n\n # SELECT THE GENDER OF SINGULAR PRONOUNS\n\n print(p.singular_noun(\"they\")) # 'it'\n p.gender(\"feminine\")\n print(p.singular_noun(\"they\")) # 'she'\n\n\n # DEAL WITH \"0/1/N\" -> \"no/1/N\" TRANSLATION:\n\n print(\"There \", p.plural_verb(\"was\", errors), p.no(\" error\", errors))\n\n\n # USE DEFAULT COUNTS:\n\n print(\n p.num(N1, \"\"),\n p.plural(\"I\"),\n p.plural_verb(\" saw\"),\n p.num(N2),\n p.plural_noun(\" saw\"),\n )\n print(\"There \", p.num(errors, \"\"), p.plural_verb(\"was\"), p.no(\" error\"))\n\n\n # COMPARE TWO WORDS \"NUMBER-INSENSITIVELY\":\n\n if p.compare(word1, word2):\n print(\"same\")\n if p.compare_nouns(word1, word2):\n print(\"same noun\")\n if p.compare_verbs(word1, word2):\n print(\"same verb\")\n if p.compare_adjs(word1, word2):\n print(\"same adj.\")\n\n\n # ADD CORRECT \"a\" OR \"an\" FOR A GIVEN WORD:\n\n print(\"Did you want \", p.a(thing), \" or \", p.an(idea))\n\n\n # CONVERT NUMERALS INTO ORDINALS (i.e. 1->1st, 2->2nd, 3->3rd, etc.)\n\n print(\"It was\", p.ordinal(position), \" from the left\\n\")\n\n # CONVERT NUMERALS TO WORDS (i.e. 1->\"one\", 101->\"one hundred and one\", etc.)\n # RETURNS A SINGLE STRING...\n\n words = p.number_to_words(1234)\n # \"one thousand, two hundred and thirty-four\"\n words = p.number_to_words(p.ordinal(1234))\n # \"one thousand, two hundred and thirty-fourth\"\n\n\n # GET BACK A LIST OF STRINGS, ONE FOR EACH \"CHUNK\"...\n\n words = p.number_to_words(1234, wantlist=True)\n # (\"one thousand\",\"two hundred and thirty-four\")\n\n\n # OPTIONAL PARAMETERS CHANGE TRANSLATION:\n\n words = p.number_to_words(12345, group=1)\n # \"one, two, three, four, five\"\n\n words = p.number_to_words(12345, group=2)\n # \"twelve, thirty-four, five\"\n\n words = p.number_to_words(12345, group=3)\n # \"one twenty-three, forty-five\"\n\n words = p.number_to_words(1234, andword=\"\")\n # \"one thousand, two hundred thirty-four\"\n\n words = p.number_to_words(1234, andword=\", plus\")\n # \"one thousand, two hundred, plus thirty-four\"\n # TODO: I get no comma before plus: check perl\n\n words = p.number_to_words(555_1202, group=1, zero=\"oh\")\n # \"five, five, five, one, two, oh, two\"\n\n words = p.number_to_words(555_1202, group=1, one=\"unity\")\n # \"five, five, five, unity, two, oh, two\"\n\n words = p.number_to_words(123.456, group=1, decimal=\"mark\")\n # \"one two three mark four five six\"\n # TODO: DOCBUG: perl gives commas here as do I\n\n # LITERAL STYLE ONLY NAMES NUMBERS LESS THAN A CERTAIN THRESHOLD...\n\n words = p.number_to_words(9, threshold=10) # \"nine\"\n words = p.number_to_words(10, threshold=10) # \"ten\"\n words = p.number_to_words(11, threshold=10) # \"11\"\n words = p.number_to_words(1000, threshold=10) # \"1,000\"\n\n # JOIN WORDS INTO A LIST:\n\n mylist = p.join((\"apple\", \"banana\", \"carrot\"))\n # \"apple, banana, and carrot\"\n\n mylist = p.join((\"apple\", \"banana\"))\n # \"apple and banana\"\n\n mylist = p.join((\"apple\", \"banana\", \"carrot\"), final_sep=\"\")\n # \"apple, banana and carrot\"\n\n\n # REQUIRE \"CLASSICAL\" PLURALS (EG: \"focus\"->\"foci\", \"cherub\"->\"cherubim\")\n\n p.classical() # USE ALL CLASSICAL PLURALS\n\n p.classical(all=True) # USE ALL CLASSICAL PLURALS\n p.classical(all=False) # SWITCH OFF CLASSICAL MODE\n\n p.classical(zero=True) # \"no error\" INSTEAD OF \"no errors\"\n p.classical(zero=False) # \"no errors\" INSTEAD OF \"no error\"\n\n p.classical(herd=True) # \"2 buffalo\" INSTEAD OF \"2 buffalos\"\n p.classical(herd=False) # \"2 buffalos\" INSTEAD OF \"2 buffalo\"\n\n p.classical(persons=True) # \"2 chairpersons\" INSTEAD OF \"2 chairpeople\"\n p.classical(persons=False) # \"2 chairpeople\" INSTEAD OF \"2 chairpersons\"\n\n p.classical(ancient=True) # \"2 formulae\" INSTEAD OF \"2 formulas\"\n p.classical(ancient=False) # \"2 formulas\" INSTEAD OF \"2 formulae\"\n\n\n # INTERPOLATE \"plural()\", \"plural_noun()\", \"plural_verb()\", \"plural_adj()\", \"singular_noun()\",\n # a()\", \"an()\", \"num()\" AND \"ordinal()\" WITHIN STRINGS:\n\n print(p.inflect(\"The plural of {0} is plural('{0}')\".format(word)))\n print(p.inflect(\"The singular of {0} is singular_noun('{0}')\".format(word)))\n print(p.inflect(\"I saw {0} plural('cat',{0})\".format(cat_count)))\n print(\n p.inflect(\n \"plural('I',{0}) \"\n \"plural_verb('saw',{0}) \"\n \"plural('a',{1}) \"\n \"plural_noun('saw',{1})\".format(N1, N2)\n )\n )\n print(\n p.inflect(\n \"num({0}, False)plural('I') \"\n \"plural_verb('saw') \"\n \"num({1}, False)plural('a') \"\n \"plural_noun('saw')\".format(N1, N2)\n )\n )\n print(p.inflect(\"I saw num({0}) plural('cat')\\nnum()\".format(cat_count)))\n print(p.inflect(\"There plural_verb('was',{0}) no('error',{0})\".format(errors)))\n print(p.inflect(\"There num({0}, False)plural_verb('was') no('error')\".format(errors)))\n print(p.inflect(\"Did you want a('{0}') or an('{1}')\".format(thing, idea)))\n print(p.inflect(\"It was ordinal('{0}') from the left\".format(position)))\n\n\n # ADD USER-DEFINED INFLECTIONS (OVERRIDING INBUILT RULES):\n\n p.defnoun(\"VAX\", \"VAXen\") # SINGULAR => PLURAL\n\n p.defverb(\n \"will\", # 1ST PERSON SINGULAR\n \"shall\", # 1ST PERSON PLURAL\n \"will\", # 2ND PERSON SINGULAR\n \"will\", # 2ND PERSON PLURAL\n \"will\", # 3RD PERSON SINGULAR\n \"will\", # 3RD PERSON PLURAL\n )\n\n p.defadj(\"hir\", \"their\") # SINGULAR => PLURAL\n\n p.defa(\"h\") # \"AY HALWAYS SEZ 'HAITCH'!\"\n\n p.defan(\"horrendous.*\") # \"AN HORRENDOUS AFFECTATION\"\n\n\nDESCRIPTION\n===========\n\nThe methods of the class ``engine`` in module ``inflect.py`` provide plural\ninflections, singular noun inflections, \"a\"/\"an\" selection for English words,\nand manipulation of numbers as words.\n\nPlural forms of all nouns, most verbs, and some adjectives are\nprovided. Where appropriate, \"classical\" variants (for example: \"brother\" ->\n\"brethren\", \"dogma\" -> \"dogmata\", etc.) are also provided.\n\nSingle forms of nouns are also provided. The gender of singular pronouns\ncan be chosen (for example \"they\" -> \"it\" or \"she\" or \"he\" or \"they\").\n\nPronunciation-based \"a\"/\"an\" selection is provided for all English\nwords, and most initialisms.\n\nIt is also possible to inflect numerals (1,2,3) to ordinals (1st, 2nd, 3rd)\nand to English words (\"one\", \"two\", \"three\").\n\nIn generating these inflections, ``inflect.py`` follows the Oxford\nEnglish Dictionary and the guidelines in Fowler's Modern English\nUsage, preferring the former where the two disagree.\n\nThe module is built around standard British spelling, but is designed\nto cope with common American variants as well. Slang, jargon, and\nother English dialects are *not* explicitly catered for.\n\nWhere two or more inflected forms exist for a single word (typically a\n\"classical\" form and a \"modern\" form), ``inflect.py`` prefers the\nmore common form (typically the \"modern\" one), unless \"classical\"\nprocessing has been specified\n(see `MODERN VS CLASSICAL INFLECTIONS`).\n\nFORMING PLURALS AND SINGULARS\n=============================\n\nInflecting Plurals and Singulars\n--------------------------------\n\nAll of the ``plural...`` plural inflection methods take the word to be\ninflected as their first argument and return the corresponding inflection.\nNote that all such methods expect the *singular* form of the word. The\nresults of passing a plural form are undefined (and unlikely to be correct).\nSimilarly, the ``si...`` singular inflection method expects the *plural*\nform of the word.\n\nThe ``plural...`` methods also take an optional second argument,\nwhich indicates the grammatical \"number\" of the word (or of another word\nwith which the word being inflected must agree). If the \"number\" argument is\nsupplied and is not ``1`` (or ``\"one\"`` or ``\"a\"``, or some other adjective that\nimplies the singular), the plural form of the word is returned. If the\n\"number\" argument *does* indicate singularity, the (uninflected) word\nitself is returned. If the number argument is omitted, the plural form\nis returned unconditionally.\n\nThe ``si...`` method takes a second argument in a similar fashion. If it is\nsome form of the number ``1``, or is omitted, the singular form is returned.\nOtherwise the plural is returned unaltered.\n\n\nThe various methods of ``inflect.engine`` are:\n\n\n\n``plural_noun(word, count=None)``\n\n The method ``plural_noun()`` takes a *singular* English noun or\n pronoun and returns its plural. Pronouns in the nominative (\"I\" ->\n \"we\") and accusative (\"me\" -> \"us\") cases are handled, as are\n possessive pronouns (\"mine\" -> \"ours\").\n\n\n``plural_verb(word, count=None)``\n\n The method ``plural_verb()`` takes the *singular* form of a\n conjugated verb (that is, one which is already in the correct \"person\"\n and \"mood\") and returns the corresponding plural conjugation.\n\n\n``plural_adj(word, count=None)``\n\n The method ``plural_adj()`` takes the *singular* form of\n certain types of adjectives and returns the corresponding plural form.\n Adjectives that are correctly handled include: \"numerical\" adjectives\n (\"a\" -> \"some\"), demonstrative adjectives (\"this\" -> \"these\", \"that\" ->\n \"those\"), and possessives (\"my\" -> \"our\", \"cat's\" -> \"cats'\", \"child's\"\n -> \"childrens'\", etc.)\n\n\n``plural(word, count=None)``\n\n The method ``plural()`` takes a *singular* English noun,\n pronoun, verb, or adjective and returns its plural form. Where a word\n has more than one inflection depending on its part of speech (for\n example, the noun \"thought\" inflects to \"thoughts\", the verb \"thought\"\n to \"thought\"), the (singular) noun sense is preferred to the (singular)\n verb sense.\n\n Hence ``plural(\"knife\")`` will return \"knives\" (\"knife\" having been treated\n as a singular noun), whereas ``plural(\"knifes\")`` will return \"knife\"\n (\"knifes\" having been treated as a 3rd person singular verb).\n\n The inherent ambiguity of such cases suggests that,\n where the part of speech is known, ``plural_noun``, ``plural_verb``, and\n ``plural_adj`` should be used in preference to ``plural``.\n\n\n``singular_noun(word, count=None)``\n\n The method ``singular_noun()`` takes a *plural* English noun or\n pronoun and returns its singular. Pronouns in the nominative (\"we\" ->\n \"I\") and accusative (\"us\" -> \"me\") cases are handled, as are\n possessive pronouns (\"ours\" -> \"mine\"). When third person\n singular pronouns are returned they take the neuter gender by default\n (\"they\" -> \"it\"), not (\"they\"-> \"she\") nor (\"they\" -> \"he\"). This can be\n changed with ``gender()``.\n\nNote that all these methods ignore any whitespace surrounding the\nword being inflected, but preserve that whitespace when the result is\nreturned. For example, ``plural(\" cat \")`` returns \" cats \".\n\n\n``gender(genderletter)``\n\n The third person plural pronoun takes the same form for the female, male and\n neuter (e.g. \"they\"). The singular however, depends upon gender (e.g. \"she\",\n \"he\", \"it\" and \"they\" -- \"they\" being the gender neutral form.) By default\n ``singular_noun`` returns the neuter form, however, the gender can be selected with\n the ``gender`` method. Pass the first letter of the gender to\n ``gender`` to return the f(eminine), m(asculine), n(euter) or t(hey)\n form of the singular. e.g.\n gender('f') followed by singular_noun('themselves') returns 'herself'.\n\nNumbered plurals\n----------------\n\nThe ``plural...`` methods return only the inflected word, not the count that\nwas used to inflect it. Thus, in order to produce \"I saw 3 ducks\", it\nis necessary to use:\n\n.. code-block:: python\n\n print(\"I saw\", N, p.plural_noun(animal, N))\n\nSince the usual purpose of producing a plural is to make it agree with\na preceding count, inflect.py provides a method\n(``no(word, count)``) which, given a word and a(n optional) count, returns the\ncount followed by the correctly inflected word. Hence the previous\nexample can be rewritten:\n\n.. code-block:: python\n\n print(\"I saw \", p.no(animal, N))\n\nIn addition, if the count is zero (or some other term which implies\nzero, such as ``\"zero\"``, ``\"nil\"``, etc.) the count is replaced by the\nword \"no\". Hence, if ``N`` had the value zero, the previous example\nwould print (the somewhat more elegant)::\n\n I saw no animals\n\nrather than::\n\n I saw 0 animals\n\nNote that the name of the method is a pun: the method\nreturns either a number (a *No.*) or a ``\"no\"``, in front of the\ninflected word.\n\n\nReducing the number of counts required\n--------------------------------------\n\nIn some contexts, the need to supply an explicit count to the various\n``plural...`` methods makes for tiresome repetition. For example:\n\n.. code-block:: python\n\n print(\n plural_adj(\"This\", errors),\n plural_noun(\" error\", errors),\n plural_verb(\" was\", errors),\n \" fatal.\",\n )\n\ninflect.py therefore provides a method\n(``num(count=None, show=None)``) which may be used to set a persistent \"default number\"\nvalue. If such a value is set, it is subsequently used whenever an\noptional second \"number\" argument is omitted. The default value thus set\ncan subsequently be removed by calling ``num()`` with no arguments.\nHence we could rewrite the previous example:\n\n.. code-block:: python\n\n p.num(errors)\n print(p.plural_adj(\"This\"), p.plural_noun(\" error\"), p.plural_verb(\" was\"), \"fatal.\")\n p.num()\n\nNormally, ``num()`` returns its first argument, so that it may also\nbe \"inlined\" in contexts like:\n\n.. code-block:: python\n\n print(p.num(errors), p.plural_noun(\" error\"), p.plural_verb(\" was\"), \" detected.\")\n if severity > 1:\n print(\n p.plural_adj(\"This\"), p.plural_noun(\" error\"), p.plural_verb(\" was\"), \"fatal.\"\n )\n\nHowever, in certain contexts (see `INTERPOLATING INFLECTIONS IN STRINGS`)\nit is preferable that ``num()`` return an empty string. Hence ``num()``\nprovides an optional second argument. If that argument is supplied (that is, if\nit is defined) and evaluates to false, ``num`` returns an empty string\ninstead of its first argument. For example:\n\n.. code-block:: python\n\n print(p.num(errors, 0), p.no(\"error\"), p.plural_verb(\" was\"), \" detected.\")\n if severity > 1:\n print(\n p.plural_adj(\"This\"), p.plural_noun(\" error\"), p.plural_verb(\" was\"), \"fatal.\"\n )\n\n\n\nNumber-insensitive equality\n---------------------------\n\ninflect.py also provides a solution to the problem\nof comparing words of differing plurality through the methods\n``compare(word1, word2)``, ``compare_nouns(word1, word2)``,\n``compare_verbs(word1, word2)``, and ``compare_adjs(word1, word2)``.\nEach of these methods takes two strings, and compares them\nusing the corresponding plural-inflection method (``plural()``, ``plural_noun()``,\n``plural_verb()``, and ``plural_adj()`` respectively).\n\nThe comparison returns true if:\n\n- the strings are equal, or\n- one string is equal to a plural form of the other, or\n- the strings are two different plural forms of the one word.\n\n\nHence all of the following return true:\n\n.. code-block:: python\n\n p.compare(\"index\", \"index\") # RETURNS \"eq\"\n p.compare(\"index\", \"indexes\") # RETURNS \"s:p\"\n p.compare(\"index\", \"indices\") # RETURNS \"s:p\"\n p.compare(\"indexes\", \"index\") # RETURNS \"p:s\"\n p.compare(\"indices\", \"index\") # RETURNS \"p:s\"\n p.compare(\"indices\", \"indexes\") # RETURNS \"p:p\"\n p.compare(\"indexes\", \"indices\") # RETURNS \"p:p\"\n p.compare(\"indices\", \"indices\") # RETURNS \"eq\"\n\nAs indicated by the comments in the previous example, the actual value\nreturned by the various ``compare`` methods encodes which of the\nthree equality rules succeeded: \"eq\" is returned if the strings were\nidentical, \"s:p\" if the strings were singular and plural respectively,\n\"p:s\" for plural and singular, and \"p:p\" for two distinct plurals.\nInequality is indicated by returning an empty string.\n\nIt should be noted that two distinct singular words which happen to take\nthe same plural form are *not* considered equal, nor are cases where\none (singular) word's plural is the other (plural) word's singular.\nHence all of the following return false:\n\n.. code-block:: python\n\n p.compare(\"base\", \"basis\") # ALTHOUGH BOTH -> \"bases\"\n p.compare(\"syrinx\", \"syringe\") # ALTHOUGH BOTH -> \"syringes\"\n p.compare(\"she\", \"he\") # ALTHOUGH BOTH -> \"they\"\n\n p.compare(\"opus\", \"operas\") # ALTHOUGH \"opus\" -> \"opera\" -> \"operas\"\n p.compare(\"taxi\", \"taxes\") # ALTHOUGH \"taxi\" -> \"taxis\" -> \"taxes\"\n\nNote too that, although the comparison is \"number-insensitive\" it is *not*\ncase-insensitive (that is, ``plural(\"time\",\"Times\")`` returns false. To obtain\nboth number and case insensitivity, use the ``lower()`` method on both strings\n(that is, ``plural(\"time\".lower(), \"Times\".lower())`` returns true).\n\nRelated Functionality\n=====================\n\nShout out to these libraries that provide related functionality:\n\n* `WordSet <https://jaracotext.readthedocs.io/en/latest/#jaraco.text.WordSet>`_\n parses identifiers like variable names into sets of words suitable for re-assembling\n in another form.\n\n* `word2number <https://pypi.org/project/word2number/>`_ converts words to\n a number.\n\n\nFor Enterprise\n==============\n\nAvailable as part of the Tidelift Subscription.\n\nThis project and the maintainers of thousands of other packages are working with Tidelift to deliver one enterprise subscription that covers all of the open source you use.\n\n`Learn more <https://tidelift.com/subscription/pkg/pypi-PROJECT?utm_source=pypi-PROJECT&utm_medium=referral&utm_campaign=github>`_.\n",
"bugtrack_url": null,
"license": null,
"summary": "Correctly generate plurals, singular nouns, ordinals, indefinite articles",
"version": "7.4.0",
"project_urls": {
"Source": "https://github.com/jaraco/inflect"
},
"split_keywords": [
"plural",
" inflect",
" participle"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f7e0c5684d7c058d8f2a9210c322dee32bd025c11d19e5ba23c82ac9188253f9",
"md5": "3905d957ac748a76689b2c4337b7f90d",
"sha256": "85af0997ee2bda942b1c1eed8c8a827abda91aa3e22d1efaa0eea817f9350ce7"
},
"downloads": -1,
"filename": "inflect-7.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3905d957ac748a76689b2c4337b7f90d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 34781,
"upload_time": "2024-09-07T13:06:33",
"upload_time_iso_8601": "2024-09-07T13:06:33.461495Z",
"url": "https://files.pythonhosted.org/packages/f7/e0/c5684d7c058d8f2a9210c322dee32bd025c11d19e5ba23c82ac9188253f9/inflect-7.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e1dc02614acece4d578e709c606594c989cfd9f15cf6401444e5603e60df9b26",
"md5": "7201084aafe65ed5925a8f055f9281a7",
"sha256": "904baa17cc2cb74827a6c27b95692e95670dadc72b208b3e8c1c05aeed47026b"
},
"downloads": -1,
"filename": "inflect-7.4.0.tar.gz",
"has_sig": false,
"md5_digest": "7201084aafe65ed5925a8f055f9281a7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 72730,
"upload_time": "2024-09-07T13:06:35",
"upload_time_iso_8601": "2024-09-07T13:06:35.437865Z",
"url": "https://files.pythonhosted.org/packages/e1/dc/02614acece4d578e709c606594c989cfd9f15cf6401444e5603e60df9b26/inflect-7.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-07 13:06:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jaraco",
"github_project": "inflect",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "inflect"
}
