Install & Compatibility
Where this runs
tested against v3.0.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.089s · 30.4MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.1s · import 0.079s · 31MB
29MB installed
● package 29MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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}")
wonderwords --version
Debug
Known issues
breakingVersion 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.fixReview 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`.
affects: From v1.x to v2.0.0, and v2.0.0 to v2.2.0 (for custom categories).
deprecatedThe `include_parts_of_speech` argument in methods like `word()` is deprecated and will be removed in future versions.fixUse `include_categories` instead. For example, `rw.word(include_categories=["noun"])`.
affects: v2.x, v3.x
gotchaThe `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.fixLoosen filtering criteria or set `return_less_if_necessary=True` when calling `words_list()` if you anticipate fewer matches than requested.
affects: All versions
gotchaWord 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.fixCreate 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.
affects: All versions
Errors
Common errors & fixes
ImportError: cannot import name 'Wonderwords' from 'wonderwords'
In wonderwords v3, the main word generation class was renamed from 'Wonderwords' to 'RandomWord'.
fixfrom wonderwords import RandomWord
AttributeError: 'RandomWord' object has no attribute 'random_word'
In wonderwords v3, the method to get a single random word was renamed from `random_word()` to `word()`.
AttributeError: 'RandomWord' object has no attribute 'generate_words'
In wonderwords v3, the method to generate words was renamed and refactored; `generate_words()` no longer exists.
fixwords = r.word(amount=5)
TypeError: wonderwords.RandomWord.word() got an unexpected keyword argument 'include_categories'
In wonderwords v3, the parameter for filtering words by category was renamed from `include_categories` to `include_parts_of_speech`.
fixword = r.word(include_parts_of_speech=['noun'])
Upgrade
Version history
3.0.1latest on PyPI · released Oct 30, 2025
Audit
Dependencies
richoptionalOptional dependency for colorized command-line interface output.