petname

petname is a small Python library and CLI utility that generates human-readable, pronounceable random names by combining adverbs, adjectives, and animal names, following an RFC1178-inspired naming convention. It’s commonly used to produce memorable identifiers for hosts, containers, VMs, and other ephemeral objects where a raw UUID would be hard to read or communicate.

The library ships with curated English word lists (adverbs, adjectives, animal names) and exposes a simple functional API (generate, adjective, adverb, name) alongside a petname console script, so it works equally well embedded in application code or invoked directly from the shell.

What You Get

• A generate() function with configurable word count, separator, and max letters per word
• Individual adjective(), adverb(), and name() helpers for building custom naming schemes
• A petname console script for shell scripting and one-off name generation
• Curated English word lists shipped as part of the package (no network calls or external data)
• Type hints (py.typed) for editor and type-checker support

Common Use Cases

• Naming ephemeral cloud VMs, containers, or Kubernetes pods with memorable identifiers
• Generating friendly default names for user-created objects (projects, workspaces, uploads)
• Producing unique-enough hostnames in test fixtures and local development environments
• Building CLI tools that need a quick, readable random identifier without integrating a full UUID/name-generation pipeline

Under The Hood

Architecture — petname is a flat, single-purpose package: petname/english.py holds the word lists (adverbs, adjectives, animal names) as plain Python lists, and petname/__init__.py implements four small functions (adverb, adjective, name, generate) that pick a random word under a length constraint and join them with a separator; __main__.py wraps generate() in an argparse CLI. There is no class hierarchy, no I/O, and no external state — every call is a pure, in-memory random choice.

Tech Stack — pure Python 3 with no runtime dependencies; it uses random.SystemRandom() when available for slightly better randomness, falling back to the standard random module. Packaging is plain setuptools (setup.py), and the package ships a py.typed marker plus inline type hints for mypy/editor support.

Code Quality — test.py covers all four public functions with unittest, checking membership in the word lists, backwards-compatible aliases (Adjective, Adverb, etc.), and length constraints; there’s no CI badge or coverage tooling visible, and the whole implementation is under 100 lines, so risk surface is small.

API Design — the API is intentionally minimal: one high-level generate(words, separator, letters) call covers the common case, with lower-level adjective()/adverb()/name() available for custom naming schemes; defaults are sensible (2 words, - separator) so most callers need zero configuration.