talkGooder documentation — talkGooder 0.0.post1.dev1+gdb789d0 documentation

# 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

`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.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 most 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.