wonderwords.random_word

The random_word module houses all classes and functions relating to the generation of single random words.

class wonderwords.random_word.Defaults

Bases: enum.Enum

This enum represents the default word lists. For example, if you want a random word generator with one category labeled ‘adj’ for adjectives, but want to use the default word list, you can do the following:

>>> from wonderwords import RandomWord, Defaults
>>> w = RandomWord(adj=Defaults.ADJECTIVES)
>>> w.word()
'red'

Options available:

  • Defaults.NOUNS: Represents a list of nouns
  • Defaults.VERBS: Represents a list of verbs
  • Defaults.ADJECTIVES: Represents a list of adjectives
  • Defaults.PROFANITIES: Represents a list of curse words
exception wonderwords.random_word.NoWordsToChoseFrom

Bases: Exception

NoWordsToChoseFrom is raised when there is an attempt to access more words than exist. This exception may be raised if the amount of random words to generate is larger than the amount of words that exist.

class wonderwords.random_word.RandomWord(**kwargs)

Bases: object

The RandomWord class encapsulates multiple methods dealing with the generation of random words and lists of random words.

Example:

>>> from wonderwords import RandomWord, Defaults
>>>
>>> r = RandomWord(noun=["apple", "orange"]) # Category 'noun' with
...     # the words 'apple' and 'orange'
>>> r2 = RandomWord() # Use the default word lists
>>> r3 = RandomWord(noun=Defaults.NOUNS) # Set the category 'noun' to
...     # the default list of nouns

Important

Wonderwords version 2.0 does not have custom categories. In fact there are only three categories: nouns, verbs, and adjectives. However, wonderwords will remain backwards compatible until version 3. Please note that the parts_of_speech attribute will soon be deprecated, along with other method-specific features.

Parameters:**kwargs – keyword arguments where each key is a category of words and value is a list of words in that category. You can also use a default list of words by using the Default enum instead.
filter(starts_with: str = '', ends_with: str = '', include_categories: Optional[List[str]] = None, include_parts_of_speech: Optional[List[str]] = None, word_min_length: Optional[int] = None, word_max_length: Optional[int] = None, regex: Optional[str] = None)

Return all existing words that match the criteria specified by the arguments.

Example:

>>> # Filter all nouns that start with a:
>>> r.filter(starts_with="a", include_categories=["noun"])

Important

The include_parts_of_speech argument will soon be deprecated. Use include_categories which performs the exact same role.

Parameters:
  • starts_with (str, optional) – the string each word should start with. Defaults to “”.
  • ends_with (str, optional) – the string each word should end with. Defaults to “”.
  • include_categories (list of strings, optional) – a list of strings denoting a part of speech. Each word returned will be in the category of at least one part of speech. By default, all parts of speech are enabled. Defaults to None.
  • include_parts_of_speech (list of strings, optional) – Same as include_categories, but will soon be deprecated.
  • word_min_length (int, optional) – the minimum length of each word. Defaults to None.
  • word_max_length (int, optional) – the maximum length of each word. Defaults to None.
  • regex (str, optional) – a custom regular expression which each word must fully match (re.fullmatch). Defaults to None.
Returns:

a list of unique words that match each of the criteria specified
Return type:

list of strings
random_words(amount: int = 1, starts_with: str = '', ends_with: str = '', include_categories: Optional[List[str]] = None, include_parts_of_speech: Optional[List[str]] = None, word_min_length: Optional[int] = None, word_max_length: Optional[int] = None, regex: Optional[str] = None, return_less_if_necessary: bool = False)

Generate a list of n random words specified by the amount parameter and fit the criteria specified.

Example:

>>> # Generate a list of 3 adjectives or nouns which start with
...     # "at"
>>> # and are at least 2 letters long
>>> r.random_words(
...     3,
...     starts_with="at",
...     include_parts_of_speech=["adjectives", "nouns"],
...     word_min_length=2
... )
Parameters:
  • amount (int, optional) – the amount of words to generate. Defaults to 1.
  • starts_with (str, optional) – the string each word should start with. Defaults to “”.
  • ends_with (str, optional) – the string each word should end with. Defaults to “”.
  • include_categories (list of strings, optional) – a list of strings denoting a part of speech. Each word returned will be in the category of at least one part of speech. By default, all parts of speech are enabled. Defaults to None.
  • include_parts_of_speech (list of strings, optional) – Same as include_categories, but will soon be deprecated.
  • word_min_length (int, optional) – the minimum length of each word. Defaults to None.
  • word_max_length (int, optional) – the maximum length of each word. Defaults to None.
  • regex (str, optional) – a custom regular expression which each word must fully match (re.fullmatch). Defaults to None.
  • return_less_if_necessary (bool, optional) – if set to True, if there aren’t enough words to statisfy the amount, instead of raising a NoWordsToChoseFrom exception, return all words that did statisfy the original query.
Raises:

NoWordsToChoseFrom – if there are less words to choose from than the amount that was requested, a NoWordsToChoseFrom exception is raised, unless return_less_if_necessary is set to True.
Returns:

a list of the words
Return type:

list of strings
word(starts_with: str = '', ends_with: str = '', include_categories: Optional[List[str]] = None, include_parts_of_speech: Optional[List[str]] = None, word_min_length: Optional[int] = None, word_max_length: Optional[int] = None, regex: Optional[str] = None)

Returns a random word that fits the criteria specified by the arguments.

Example:

>>> # Select a random noun that starts with y
>>> r.word(ends_with="y", include_parts_of_speech=["nouns"])
Parameters:
  • starts_with (str, optional) – the string each word should start with. Defaults to “”.
  • ends_with (str, optional) – the string the word should end with. Defaults to “”.
  • include_categories (list of strings, optional) – a list of strings denoting a part of speech. Each word returned will be in the category of at least one part of speech. By default, all parts of speech are enabled. Defaults to None.
  • include_parts_of_speech (list of strings, optional) – Same as include_categories, but will soon be deprecated.
  • word_min_length (int, optional) – the minimum length of the word. Defaults to None.
  • word_max_length (int, optional) – the maximum length of the word. Defaults to None.
  • regex (str, optional) – a custom regular expression which each word must fully match (re.fullmatch). Defaults to None.
Raises:

NoWordsToChoseFrom – if a word fitting the criteria doesn’t exist
Returns:

a word
Return type:

str