talkGooder documentation
Talk Gooder
talkgooder
attempts to smooth out grammar, punctuation, and number-related corner cases when formatting text for human consumption. It is intended for applications where you know there’s a noun and are trying to generate text, but you don’t know much about it.
It handles:
Plurals
Possessives
Numbers to words
“There is” vs. “There are”
“A” vs. “An”
talkgooder
is currently specific to American English, but it is extensible to other languages.
Contributions are welcome at github.com/brianwarner/talkgooder!
Functions
Given a noun or noun-equivalent, determine whether the article is |
|
Given a quanity, determine if article should be |
|
Determine if an integer should be expanded to a word (per the APA style manual). |
|
Determine the plural of a noun depending upon quantity. |
|
Convert a noun to its possessive, because apostrophes can be hard. |
- talkgooder.aAn(noun: str | int | float, language='en-US') str [source]
Given a noun or noun-equivalent, determine whether the article is
a
oran
.Nouns and noun-equivalents with a soft vowel beginning generally use
an
, and everything else usesa
.Supported locales:
en-US
: American English
- Parameters:
noun (str | int | float) – A noun or noun-equivalent, as a word or a number.
language (str) – Which language rules to apply, specified by locale (default
en-US
).
- Returns:
a
oran
, as appropriate.- Return type:
String
- Raises:
TypeError – Noun must be a string, int, or float.
ValueError – Language must be a supported locale.
- talkgooder.isAre(number: int | float, language='en-US') str [source]
Given a quanity, determine if article should be
is
orare
.Given a quantity of nouns or noun-equivalents, determine whether the article should be
is
orare
. For example, “there is one cat,” and “there are two cats.”Supported locales:
en-US
: American English
- Parameters:
number (int | float) – Quantity of items.
language (str) – Which language rules to apply, specified by locale (default
en-US
).
- Returns:
is
orare
, as appropriate.- Return type:
String
- Raises:
TypeError – number must be an int or float.
ValueError – language must be a supported locale.
- talkgooder.num2word(number: int, language='en-US') str [source]
Determine if an integer should be expanded to a word (per the APA style manual).
The APA style manual specifies integers between 1 and 9 should be written out as a word. Everything else should be represented as digits.
Supported locales:
en-US
: American English
- Parameters:
number (int) – An integer.
language (str) – Which language rules to apply (default
en-US
).
- Returns:
The word or string-formatted number, as appropriate.
- Return type:
String
- Raises:
TypeError – Number must be an int.
ValueError – Language must be a supported locale.
- talkgooder.plural(text: str, number: int | float, language='en-US', addl_same=[], addl_special_s=[], addl_irregular={}, caps_mode=0) str [source]
Determine the plural of a noun depending upon quantity.
Given a quantity of nouns, return the most likely plural form. Language is complicated and pluralization rules are not always consistent, so this function supports user-supplied rules to accommodate exceptions specific to the situation.
Supported locales:
en-US
: American English
- Parameters:
text (str) – The noun to convert.
number (int or float) – The quantity of nouns.
language (str) – Which language rules to apply, specified by locale (default:
en-US
).addl_same (list) – Additional words where the singular and plural are the same.
addl_special_s (list) – Additional words that always end in s for odd reasons (e.g.,
["piano","hello",...]
).addl_irregular (dict) – Additional pairs of irregular plural nouns (e.g.,
{"mouse": "mice", "person": "people", ...}
).caps_mode (int) –
0
: Attempt to infer whether suffix is lower or upper case (default).1
: Force suffix to be upper case.2
: Force suffix to be lower case.
- Returns:
The plural of the provided noun.
- Return type:
String
- Raises:
TypeError – Text must be a string.
ValueError – Language must be a supported locale.
- talkgooder.possessive(text: str, language='en-US', caps_mode=0) str [source]
Convert a noun to its possessive, because apostrophes can be hard.
Supported locales:
en-US
: American English
- Parameters:
text (str) – A noun to be made possessive.
language (str) – Which language rules to apply (default
en-US
).caps_mode (int) –
0
: Attempt to infer whether suffix is lower or upper case (default).1
: Force suffix to be upper case.2
: Force suffix to be lower case.
- Returns:
The possessive of the provided string.
- Return type:
String
- Raises:
TypeError – Text must be a string.
ValueError – Language must be a supported locale.
- talkgooder.wasWere(number: int | float, language='en-US') str [source]
Given a quanity, determine if article should be
ws
orwere
.Given a quantity of nouns or noun-equivalents, determine whether the article should be
was
orwere
. For example, “there was one cat,” and “there were two cats.”Supported locales:
en-US
: American English
- Parameters:
number (int | float) – Quantity of items.
language (str) – Which language rules to apply, specified by locale (default
en-US
).
- Returns:
was
orwere
, as appropriate.- Return type:
String
- Raises:
TypeError – number must be an int or float.
ValueError – language must be a supported locale.