Petname

2.9 · active · verified Tue Apr 14

Petname is a Python library that generates human-readable, random names for objects by combining adverbs, adjectives, and common nouns. It's often used for generating unique hostnames or container names, providing memorable and pronounceable identifiers. The current version is 2.9, with a release cadence driven by bug fixes, security patches, and wordlist updates.

Warnings

breaking Critical DoS Vulnerability (CVE Candidate) in versions < 2.9: Word selection functions (`petname.adverb()`, `petname.adjective()`, `petname.name()`, and consequently `petname.generate()`) could hang indefinitely, consuming 100% CPU, if the `letters` (or `max_letters`) parameter was smaller than the shortest word in the internal word lists. For example, `petname.adverb(letters=3)` could cause an infinite loop in affected versions.
Fix: Upgrade immediately to version 2.9 or newer: `pip install --upgrade petname`.
gotcha Wordlist changes in version 2.8: Several words (e.g., `peacock`, `cockatoo`, `woodcock`) were removed from the internal names list to maintain consistency with upstream versions and avoid potentially awkward or unprofessional combinations. If your application relied on the exact composition of previous wordlists, this change might subtly alter generated names.
Fix: No direct fix needed unless specific word availability is critical; consider auditing generated names if this is a concern. If specific words are essential, external wordlists can be used via the `wordlist` parameter in `generate()`.
gotcha The `letters` parameter (now `max_letters` in `generate()`) can still lead to no names being found if constrained too strictly (e.g., `max_letters=1` when no single-letter words exist), resulting in an empty string or IndexError. While the infinite loop is fixed in 2.9, extreme constraints can still yield unexpected or empty results.
Fix: Ensure that `max_letters` (or `letters` in older direct calls) is set to a reasonable value that allows for word selection. Test your name generation with chosen constraints.

Install

pip install petname Install latest version

Imports

generate
```
import petname
petname.generate()
```
The primary function `generate` is typically accessed directly as a method of the imported `petname` module, not from an instantiated class. Older examples might show a class or direct functions like `adverb()` or `name()`, but `generate()` is the main entry point for a full name.
Adjective
```
import petname
petname.Adjective()
```
While `generate` is preferred for full names, individual word types can still be accessed directly.
Adverb
```
import petname
petname.Adverb()
```
Individual word types can be accessed directly.
Name
```
import petname
petname.Name()
```
Individual word types can be accessed directly.

Quickstart

Generate human-readable names with varying word counts and separators. The `generate()` function is the primary API. You can also access specific word types like adjectives, adverbs, or names directly.

import petname

# Generate a two-word name (default)
name1 = petname.generate()
print(f"Generated name: {name1}")

# Generate a three-word name with a custom separator
name2 = petname.generate(3, '_')
print(f"Generated name: {name2}")

# Generate a single-word name with max letters
name3 = petname.generate(1, max_letters=5)
print(f"Generated name: {name3}")

# Generate words from specific categories
adjective = petname.Adjective()
print(f"Random adjective: {adjective}")

view raw JSON →