py-friendly-words

Python package to generate random human-readable strings, e.g. project and experiment names. The word lists are taken from glitchdotcom/friendly-words and the package provides a convenient way to access it, as well as methods to easily generate combinations.

The package is simple, limited, and over-engineered at the same time. In other words, a weekend night side project. If you need a stable package with more extensive customization, uniqueness guarantees, bigger and/or custom dictionaries, check out alexanderlukanin13/coolname.

Features

No extra dependencies
Word lists are loaded once at import (~41KB in memory)
Customizable generation (see the examples below)
Custom separators
Can return as a list of words
Reproducible generation with your own random.Random instance
Fully typed public API

Quick guide

Install with PIP: pip install friendlywords

import friendlywords as fw

# generate random string that consists of N words (N > 0)
# if N is 1, the returned word is an object
# if N > 1, the first N-1 words are predicates
fw.generate(1)
>>> 'square'
fw.generate(4)
>>> 'southern florentine rain college'

# generate string that follow a given grammar
# p = predicate, o = object, t = team, c = collection
fw.generate('po')
>>> 'bittersweet curio'
fw.generate('pt')
>>> 'wood organization'
fw.generate('co')
>>> 'selection title'

# specify the separator
fw.generate('po', separator='-')
>>> 'better-tabletop'
fw.generate('ppp', separator=', ')
>>> 'elegant, skitter, sunny'
fw.generate(3, separator='/')
>>> 'winter/alkaline/handsaw' 

# return list of words instead of a string (ignores separator keyword)
fw.generate(5, as_list=True)
>>> ['laced', 'polyester', 'ossified', 'cyclic', 'chronometer']
fw.generate('pppoc', as_list=True)
>>> ['able', 'splendid', 'harvest', 'hedge', 'playlist']

# reproducible generation without touching the global random state
import random
fw.generate('po', rng=random.Random(42))
>>> 'tidal cardboard'

# lists of all predicates, objects, teams or collections
fw.predicates, fw.objects, fw.teams, fw.collections
>>> ['windy', ...], ['turnip', ...], ['alliance', ...], ['album', ...]

Notes

For reproducible output, pass your own random.Random instance via the rng keyword (setting the global random.seed() also still works).
The words are sampled with a non-cryptographic PRNG, so the generated names are readable, not unguessable — don't use them as secrets or unique identifiers.
fw.preload() is deprecated and is no longer needed: word lists are always loaded at import.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

friendlywords-1.3.0.tar.gz (27.5 kB view details)

Uploaded Aug 2, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

friendlywords-1.3.0-py3-none-any.whl (23.2 kB view details)

Uploaded Aug 2, 2026 Python 3

File details

Details for the file friendlywords-1.3.0.tar.gz.

File metadata

Download URL: friendlywords-1.3.0.tar.gz
Upload date: Aug 2, 2026
Size: 27.5 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for friendlywords-1.3.0.tar.gz
Algorithm	Hash digest
SHA256	`d6532b8d535b8d4dc55a774cbe9f2ad83e7d17a982dc8ac9e5d24a6b82fc664a`
MD5	`6cac18b99781a44d4cab7c0e40080cc6`
BLAKE2b-256	`2e2cddec5e055b54d2e48b4cba7fd7248fb8a0412ad5bb5348984b1ec33a51af`

See more details on using hashes here.

Provenance

The following attestation bundles were made for friendlywords-1.3.0.tar.gz:

Publisher: release.yml on the-lay/py-friendly-words

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: friendlywords-1.3.0.tar.gz
- Subject digest: d6532b8d535b8d4dc55a774cbe9f2ad83e7d17a982dc8ac9e5d24a6b82fc664a
- Sigstore transparency entry: 2321861560
- Sigstore integration time: Aug 2, 2026
Source repository:
- Permalink: the-lay/py-friendly-words@baa17f00e2fd38c11f6cd099ce87e376e972c2b8
- Branch / Tag: refs/tags/v1.3.0
- Owner: https://github.com/the-lay
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@baa17f00e2fd38c11f6cd099ce87e376e972c2b8
- Trigger Event: push