wonderwords.random_word

The random_word module houses all classes and functions relating to the generation of single random 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(nouns: Optional[List[str]] = None, verbs: Optional[List[str]] = None, adjectives: Optional[List[str]] = None)

Bases: object

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

Example:

>>> r = RandomWord(nouns=["apple", "orange"])
>>> r2 = RandomWord()
Parameters:
  • nouns (list, optional) – a list of nouns that will be used to generate random nouns. Defaults to None.
  • verbs (list, optional) – a list of verbs that will be used to generate random verbs. Defaults to None.
  • adjectives (list, optional) – a list of adjectives that will be used to generate random adjectives. Defaults to None.
filter(starts_with: str = '', ends_with: str = '', 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_parts_of_speech=["nouns"])
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_parts_of_speech (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.
  • 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_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_parts_of_speech (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.
  • 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_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_parts_of_speech (list of strings, optional) – a list of strings denoting a part of speech. The returned will be in the category of at least one part of speech. By default, all parts of speech are enabled. Defaults to None.
  • 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