Wonderwords

3.0.1 · active · verified Sun Apr 12

Wonderwords is a Python library for generating random English words and structured sentences. It also includes a command-line interface. Currently at version 3.0.1, it maintains an active development and release cadence, with significant updates between major versions.

Warnings

breaking Version 2.0.0 introduced significant API refactoring, including naming convention changes and a new object-oriented model. Migrating from v1.x will likely require code adjustments. Additionally, v2.0.0 initially removed support for custom word categories, restricting generation to 'nouns', 'verbs', and 'adjectives'. Custom categories were re-introduced in v2.2.0.
Fix: Review the v2.0.0 and v2.2.0 changelogs and documentation. If using custom categories, ensure you are on v2.2.0 or newer, where they are passed as keyword arguments to `RandomWord`.
deprecated The `include_parts_of_speech` argument in methods like `word()` is deprecated and will be removed in future versions.
Fix: Use `include_categories` instead. For example, `rw.word(include_categories=["noun"])`.
gotcha The `NoWordsToChoseFrom` exception is raised if your filtering criteria (e.g., `starts_with`, `ends_with`, `word_min_length`, `include_categories`) are too restrictive, or if the requested `amount` of words in `words_list()` exceeds the number of available words matching the criteria.
Fix: Loosen filtering criteria or set `return_less_if_necessary=True` when calling `words_list()` if you anticipate fewer matches than requested.
gotcha Word lists are loaded once per `RandomWord` or `RandomSentence` instance. Creating multiple instances unnecessarily can introduce performance overhead during initialization, especially if you create them repeatedly within a loop or function.
Fix: Create a single instance of `RandomWord` or `RandomSentence` at the top level of your module or application and reuse it across your code to optimize performance.

Install

pip install wonderwords Install stable version
pip install wonderwords[cli] Install with CLI dependencies (Rich for colorized output)

Imports

RandomWord
```
from wonderwords import RandomWord
```
The `RandomWord` class encapsulates word generation functionality.
RandomSentence
```
from wonderwords import RandomSentence
```
The `RandomSentence` class provides methods for generating random sentences.
Defaults
```
from wonderwords import Defaults
```
Used to access default word lists for custom categories, e.g., Defaults.NOUNS.

Quickstart

This quickstart demonstrates how to initialize `RandomWord` and `RandomSentence` objects to generate individual words, filtered words, lists of words, and simple sentences.

from wonderwords import RandomWord, RandomSentence

rw = RandomWord()

# Generate a random word
word = rw.word()
print(f"Random word: {word}")

# Generate a random word that starts with 'a' and is an adjective
adj_word = rw.word(starts_with="a", include_categories=["adjective"])
print(f"Adjective starting with 'a': {adj_word}")

# Generate a list of 5 words that are nouns
noun_list = rw.words_list(amount=5, include_categories=["noun"])
print(f"5 random nouns: {noun_list}")

rs = RandomSentence()

# Generate a simple sentence
sentence = rs.simple_sentence()
print(f"Simple sentence: {sentence}")

view raw JSON →