{"id":19700262,"url":"https://github.com/mrmaxguns/wonderwordsmodule","last_synced_at":"2025-05-09T00:00:32.345Z","repository":{"id":42435312,"uuid":"248308016","full_name":"mrmaxguns/wonderwordsmodule","owner":"mrmaxguns","description":"Generate random words and sentences with ease in Python. Be on the lookout for bugfixes and speed improvements in 2.3","archived":false,"fork":false,"pushed_at":"2024-08-27T02:49:35.000Z","size":10006,"stargazers_count":60,"open_issues_count":19,"forks_count":11,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-19T12:10:25.248Z","etag":null,"topics":["cli","contributions-welcome","python","python3","python36","python37","python38","python39","random-generation","random-sentences","random-word-generator","random-words"],"latest_commit_sha":null,"homepage":"https://wonderwords.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mrmaxguns.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-03-18T18:11:17.000Z","updated_at":"2025-03-21T03:27:12.000Z","dependencies_parsed_at":"2024-04-09T17:39:45.809Z","dependency_job_id":"355becc2-22a2-4c22-bcfd-bc4d8b2372e6","html_url":"https://github.com/mrmaxguns/wonderwordsmodule","commit_stats":{"total_commits":146,"total_committers":3,"mean_commits":"48.666666666666664","dds":"0.21232876712328763","last_synced_commit":"80dcdf5a716f1a84982cadaf2dededed43788e11"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrmaxguns%2Fwonderwordsmodule","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrmaxguns%2Fwonderwordsmodule/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrmaxguns%2Fwonderwordsmodule/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrmaxguns%2Fwonderwordsmodule/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mrmaxguns","download_url":"https://codeload.github.com/mrmaxguns/wonderwordsmodule/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253166502,"owners_count":21864475,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","contributions-welcome","python","python3","python36","python37","python38","python39","random-generation","random-sentences","random-word-generator","random-words"],"created_at":"2024-11-11T21:04:57.757Z","updated_at":"2025-05-09T00:00:32.307Z","avatar_url":"https://github.com/mrmaxguns.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Wonderwords\n\n*Generate random words and sentences with ease in python*\n\n\u003cimg alt=\"PyPI - Downloads\" src=\"https://img.shields.io/pypi/dm/wonderwords?style=for-the-badge\"\u003e\n\u003cimg alt=\"Libraries.io SourceRank\" src=\"https://img.shields.io/librariesio/sourcerank/pypi/wonderwords?style=for-the-badge\"\u003e\n\u003cimg alt=\"PyPI - License\" src=\"https://img.shields.io/pypi/l/wonderwords?style=for-the-badge\"\u003e\n\n[GitHub Repository](https://github.com/mrmaxguns/wonderwordsmodule) |\n[PyPI](https://pypi.org/project/wonderwords) |\n[Documentation](https://wonderwords.readthedocs.io)\n\n***\n\nWonderwords is a Python package useful for generating random words and\nstructured random sentences. It also comes with a colorful command line\ninterface for quickly generating random words. The latest version is available\n[on GitHub](https://github.com/mrmaxguns/wonderwordsmodule) while the stable\nversion is available [on PyPI](https://pypi.org/project/wonderwords).\n\n## Table of Contents\n\n- [Features](#features)\n- [Installation](#installation)\n- [Usage](#usage)\n  - [The Wonderwords Python API](#the-wonderwords-python-api)\n  - [The Wonderwords CLI](#the-wonderwords-cli)\n- [Versioning](#versioning)\n- [License](#license)\n- [Contributing](#contributing)\n- [Credits](#credits)\n\n## Features\n\nHere's what Wonderwords is capable of:\n\n- Random word generation in English\n- Specify word length, what it starts and ends with, category, and even custom\n  regular expressions\n- Use custom word lists and define custom categories of words\n- Generate structured random sentences\n- Basic profanity filtering\n- Beautiful command line interface\n- Easy-to-use interface and comprehensive documentation\n- Open source!\n\n## Installation\n\nTo install the latest version of Wonderwords, use your favorite package manager\nfor the Python Package Index to install the ``wonderwords`` package. For example\nwith pip:\n\n```bash\npip install wonderwords\n```\n\nTo upgrade Wonderwords with pip use:\n\n```bash\npip install --upgrade wonderwords\n```\n\nTo verify that the installation worked, import Wonderwords in python:\n\n```python\nimport wonderwords\n```\n\nIf you get a `ModuleNotFound` error, make sure that you have installed\nWonderwords from the step above. For further issues,\n[open a new issue from the GitHub page](https://github.com/mrmaxguns/wonderwordsmodule/issues/new/choose).\n\n## Usage\n\nThis section will briefly describe Wonderwords usage. Since Wonderwords has\na command line interface and python module, you will find two subsections.\n\n### The Wonderwords Python API\n\nThe base random word generation class is the `RandomWord` class. You can\ngenerate words with the `word` method:\n\n```python\nfrom wonderwords import RandomWord\n\nr = RandomWord()\n\n# generate a random word\nr.word()\n\n# random word that starts with a and ends with en\nr.word(starts_with=\"a\", ends_with=\"en\")\n\n# generate a random noun or adjective, by default all parts of speech are included\nr.word(include_parts_of_speech=[\"nouns\", \"adjectives\"])\n\n# generate a random word between the length of 3 and 8 characters\nr.word(word_min_length=3, word_max_length=8)\n\n# generate a random word with a custom Python regular expression\nr.word(regex=\".*a\")\n\n# some of the words in the default word lists have spaces, such as 'contact lens'\n# this option disables them\nr.word(exclude_with_spaces=True)\n\n# you can combine multiple filtering options\nr.word(starts_with=\"ru\", word_max_length=10, include_parts_of_speech=[\"verbs\"])\n```\n\nYou can also get a list of all words matching some criteria using the `filter`\nmethod:\n\n```python\n# get a list of ALL words that start with \"am\"\nr.filter(starts_with=\"am\")\n\n# you can use all the options found in the word method:\nr.filter(ends_with=\"k\", include_parts_of_speech=[\"verbs\"], word_min_length=4)\n```\n\nYou can also generate a random list of words with the `random_words` method.\nThis is much like the filter method, except you specify the amount of words\nto return, and the words are randomly chosen. If there aren't enough words to\nsatisfy the amount, a `NoWordsToChooseFrom` exception is raised:\n\n```python\n# get a list of 3 random nouns\nr.random_words(3, include_parts_of_speech=[\"nouns\"])\n\n# you can use all the options found in the word method\nr.random_words(5, starts_with=\"o\", word_min_length=10)\n\n# if the amount of words you want to get is larger than the amount of words\n# there are, a NoWordsToChooseFrom exception is raised:\nr.random_words(100, starts_with=\"n\", word_min_length=16)\n# there are less than 100 words that are at least 16 letters long and start with\n# n, so an exception is raised\n\n# you can silence the NoWordsToChooseFrom exception and return all words even\n# if there are less, by setting return_less_if_necessary to True\nr.random_words(100, starts_with=\"n\", word_min_length=16, return_less_if_necessary=True)\n```\n\nGenerating random sentences is easy using the `RandomSentence` class:\n\n```python\nfrom wonderwords import RandomSentence\n\ns = RandomSentence()\n\n# Get a random bare-bone sentence\ns.bare_bone_sentence()\n\n# Get a random bare-bone sentence with a direct object\ns.simple_sentence()\n\n# Get a random bare-bone sentence with an adjective\ns.bare_bone_with_adjective()\n\n# Get a random sentence with a subject, predicate, direct object and adjective\ns.sentence()\n```\n\nWords are organized in categories, such as \"nouns\", \"verbs\", and \"adjectives\".\nWhat if you had your own categories of words? You can specify your custom\ncategories when instantiating the `RandomWord` class:\n\n```python\nfrom wonderwords import RandomWord\n\ncars = [\"Chevrolet\", \"Subaru\", \"Tesla\"]\nairplanes = [\"Boeing\", \"Airbus\", \"Cessna\"]\nw = RandomWord(cars=cars, airplanes=airplanes)\n\n# Will return a random car or airplane\nw.word()\n\n# Will return a random car\nw.word(include_categories=[\"cars\"])\n\n# You can also mix and match custom categories with defaults\nfrom wonderwords import Defaults\nproper_nouns = [\"Austin\", \"Seattle\", \"New York\"]\nw2 = RandomWord(proper_nouns=proper_nouns, common_nouns=Defaults.NOUNS)\n\n# Will return either Seattle or seat\nw.word(regex=\"[Ss]eat.*\")\n```\n\nFinally, starting with version 2.3, Wonderwords has explicit support for filtering\nout profanities from lists of words. At the moment, this is rudimentary:\n\n```python\nfrom wonderwords import is_profanity, filter_profanity\n\n# Test against words that could possibly be offensive. Good of user-facing apps.\nis_profanity(\"apple\") # False\n\n# Can be done with a list\nwords = [ ... ]\n# The function returns a generator, so we convert it to a list\nwords_clean = list(filter_profanity(words))\n```\n\nMore advanced usage (and a tutorial!) is found in the documentation, such as\nadding custom categories of words. The full documentation with all information\ncan be found at: https://wonderwords.readthedocs.io\n\n## The Wonderwords CLI\n\n**NOTE**: Before using the command-line interface (CLI), ensure that you installed\nall required dependencies for the CLI using `pip install wonderwords[cli]`.\nWonderwords normally requires no dependencies, but uses Rich for colorized\noutput in the command line.\n\nWonderwords provides a command line interface, too, which can be used with the\n`wonderwords` command. Usage:\n\n```\nusage: wonderwords [-h] [-w] [-f] [-l LIST] [-s {bb,ss,bba,s}] [-v] [-S STARTS_WITH] [-e ENDS_WITH]\n                   [-p {noun,verb,adjective,nouns,verbs,adjectives} [{noun,verb,adjective,nouns,verbs,adjectives} ...]]\n                   [-m WORD_MIN_LENGTH] [-M WORD_MAX_LENGTH] [-r REGEX] [-x] [-d DELIMITER] [-E]\n\nGenerate random words and sentences from the command line. Here is a full list of available commands. To learn more\nabout each command, go to the documentation at https://wonderwords.readthedocs.io\n\noptions:\n  -h, --help            show this help message and exit\n  -w, --word, --random-word\n                        generate a random word\n  -f, --filter          get a list of all known words matching the criteria specified\n  -l LIST, --list LIST  return a list of a certain length of random words\n  -s {bb,ss,bba,s}, --sentence {bb,ss,bba,s}\n                        return a sentence based on the structure chosen\n  -v, --version         print the version number and exit\n  -S STARTS_WITH, --starts-with STARTS_WITH\n                        strings the random word(s) should start with\n  -e ENDS_WITH, --ends-with ENDS_WITH\n                        strings the random word(s) should end with\n  -p {noun,verb,adjective,nouns,verbs,adjectives} [{noun,verb,adjective,nouns,verbs,adjectives} ...], --parts-of-speech {noun,verb,adjective,nouns,verbs,adjectives} [{noun,verb,adjective,nouns,verbs,adjectives} ...]\n                        only include certain parts of speech (by default all parts of speech are included)\n  -m WORD_MIN_LENGTH, --word-min-length WORD_MIN_LENGTH\n                        minimum length of the word(s)\n  -M WORD_MAX_LENGTH, --word-max-length WORD_MAX_LENGTH\n                        maximum length of the word(s)\n  -r REGEX, --regex REGEX, --re REGEX, --regular-expression REGEX\n                        a python-style regular expression for the word(s) to match\n  -x, --exclude-with-spaces\n                        exclude open compounds, such as 'contact lens'\n  -d DELIMITER, --delimiter DELIMITER\n                        specify the delimiter to put between a list of words, default is ', '\n  -E, --suppress-error-on-less\n                        suppress errors when less words are returned in a list then wanted\n```\n\nThe basic commands are:\n\n  * `-w`: generate a random word\n  * `-f`: which works much like the `filter` function to return all words matching\n    a certain criteria\n  * `-l LIST`: get a list of `LIST` random words\n  * `-s {bb,ss,bba,s}`: generate a random sentence:\n    * `bb`: bare bone sentence\n    * `ss`: simple sentence (bare bone sentence with direct object)\n    * `bba`: bare bone sentence with adjective\n    * `s`: generate a simple sentence with an adjective\n\n# Versioning\n\nDuring its early stages, Wonderwords didn't have a set versioning system and\ntherefore, versions before `v2.0.0-alpha` are in disarray. Starting with version\n2 alpha, Wonderwords uses **sematic versioning**.\n\n# License\n\nWonderwords is open source and is distributed under the MIT license. See LICENSE\nfor more details.\n\n# Contributing\n\nAll contributions are welcome, and we hope Wonderwords will continue growing.\nStart out by reading `CONTRIBUTING.md` for contributing guidelines and how to\nget started.\n\n# Credits\n\nWonderwords has been made possible thanks to the following works:\n\n- `profanitylist.txt` from\n  [RobertJGabriel/Google-profanity-words](https://github.com/RobertJGabriel/Google-profanity-words)\n  under the\n  [Apache-2.0 license](https://github.com/RobertJGabriel/Google-profanity-words/blob/master/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrmaxguns%2Fwonderwordsmodule","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmrmaxguns%2Fwonderwordsmodule","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrmaxguns%2Fwonderwordsmodule/lists"}