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: “one cat” vs. “zero cats”

• Possessives: “the cat’s toy” vs. “both cats’ toys”

• Numbers to words: 2 == “two”, 16 == 16

• “There is” vs. “There are”: “There is one cat” vs. “There are two cats”

• “A” vs. “An”: “A cat” vs. “An orange cat”

• “Was” vs. “Were”: “There was one cat” vs. “There were two cats”

talkgooder is currently specific to American English, but it is extensible to other languages.

Contributions are welcome at github.com/brianwarner/talkgooder!

Functions

talkgooder.aAn	Given a noun or noun-equivalent, determine whether the article is a or an.
talkgooder.isAre	Given a quanity, determine if article should be is or are.
talkgooder.num2word	Determine if an integer should be expanded to a word (per the APA style manual).
talkgooder.plural	Determine the plural of a noun depending upon quantity.
talkgooder.possessive	Convert a noun to its possessive, because apostrophes can be hard.
talkgooder.wasWere	Given a quanity, determine if article should be ws or were.

---

talkgooder.aAn(noun: str | int | float, language='en-US') → str

Given a noun or noun-equivalent, determine whether the article is a or an.

Nouns and noun-equivalents with a soft vowel beginning generally use an, and everything else uses a.

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 or an, 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

Given a quanity, determine if article should be is or are.

Given a quantity of nouns or noun-equivalents, determine whether the article should be is or are. 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 or are, 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

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

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

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

Given a quanity, determine if article should be ws or were.

Given a quantity of nouns or noun-equivalents, determine whether the article should be was or were. 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 or were, as appropriate.

Return type:

String

Raises:

• TypeError – number must be an int or float.

• ValueError – language must be a supported locale.