or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/pypi-haikunator

Heroku-like random name generator for Python

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/haikunator@2.1.x

To install, run

npx @tessl/cli install tessl/pypi-haikunator@2.1.0

index.mddocs/

Haikunator

A Python library for generating Heroku-like random names. Creates memorable and pronounceable identifiers by combining adjectives and nouns with optional numeric or hexadecimal tokens. Ideal for generating unique identifiers, temporary names, test data, or user-friendly resource names in applications that need human-readable alternatives to UUIDs or random strings.

Package Information

  • Package Name: haikunator
  • Package Type: pypi
  • Language: Python
  • Installation: pip install haikunator

Core Imports

from haikunator import Haikunator

Package import:

import haikunator
# Access via haikunator.Haikunator

Basic Usage

from haikunator import Haikunator

# Create a new instance
haikunator = Haikunator()

# Generate a random name (default format: adjective-noun-number)
name = haikunator.haikunate()  # "wispy-dust-1337"

# Generate with custom configuration
custom_name = haikunator.haikunate(
    delimiter='.',          # Use dots instead of hyphens
    token_length=6,         # 6-digit token
    token_hex=True          # Use hexadecimal token
)  # "purple-breeze-a1b2c3"

# Generate without token
simple_name = haikunator.haikunate(token_length=0)  # "cold-wildflower"

Capabilities

Random Name Generation

Generate Heroku-like random names with extensive customization options including delimiters, token formats, and custom word lists.

class Haikunator:
    def __init__(self, seed=None, adjectives=None, nouns=None):
        """
        Initialize new haikunator instance.

        Args:
            seed: Seed for random number generator (any hashable type, optional)
            adjectives: Custom list of adjectives to replace defaults (list, optional)
            nouns: Custom list of nouns to replace defaults (list, optional)
        """

    def haikunate(self, delimiter='-', token_length=4, token_hex=False, token_chars='0123456789'):
        """
        Generate heroku-like random names.

        Args:
            delimiter: String to join name components (str, default='-')
            token_length: Length of numeric/hex token, 0 to exclude token (int, default=4)
            token_hex: Use hexadecimal characters (0-9, a-f) instead of numbers (bool, default=False)
            token_chars: Custom characters for token generation (str, default='0123456789')

        Returns:
            str: Generated name (e.g., "wispy-dust-1337")
        """

Seeded Generation

Generate reproducible random names by providing a seed value for consistent results across multiple runs.

from haikunator import Haikunator

# Create seeded instances for reproducible results
h1 = Haikunator(seed='consistent-seed')
h2 = Haikunator(seed='consistent-seed')

name1 = h1.haikunate()  # "ancient-fire-7823"  
name2 = h2.haikunate()  # "ancient-fire-7823" (same result)

Custom Word Lists

Replace default adjectives and nouns with custom word lists for domain-specific or branded name generation.

from haikunator import Haikunator

# Create instance with custom words
haikunator = Haikunator(
    adjectives=['blazing', 'swift', 'mighty'],
    nouns=['falcon', 'tiger', 'dragon']
)

name = haikunator.haikunate()  # "swift-dragon-4729"

Delimiter Customization

Customize the separator between name components for different formatting requirements.

from haikunator import Haikunator

haikunator = Haikunator()

# Dot delimiter
name1 = haikunator.haikunate(delimiter='.')  # "restless.sea.7976"

# Space delimiter  
name2 = haikunator.haikunate(delimiter=' ')  # "delicate haze 1234"

# No delimiter
name3 = haikunator.haikunate(delimiter='')   # "billowingleaf8834"

# Underscore delimiter
name4 = haikunator.haikunate(delimiter='_')  # "misty_moon_5647"

Token Configuration

Control the numeric/hexadecimal token portion with various options for length, format, and character sets.

from haikunator import Haikunator

haikunator = Haikunator()

# Custom token length
long_token = haikunator.haikunate(token_length=8)  # "gentle-brook-12345678"

# Hexadecimal token
hex_name = haikunator.haikunate(token_hex=True)    # "purple-breeze-a1b2"

# Custom character set for token
custom_chars = haikunator.haikunate(token_chars='ABCDEFGH')  # "summer-star-ABCD"

# No token
no_token = haikunator.haikunate(token_length=0)    # "wild-forest"

Configuration Examples

Email-Friendly Names

from haikunator import Haikunator

haikunator = Haikunator()
email_name = haikunator.haikunate(delimiter='-', token_length=4)  # "bold-river-1234"

URL-Friendly Names

from haikunator import Haikunator

haikunator = Haikunator()
url_name = haikunator.haikunate(delimiter='-', token_length=6)  # "quiet-mountain-789123"

Database-Friendly Names

from haikunator import Haikunator

haikunator = Haikunator()
db_name = haikunator.haikunate(delimiter='_', token_length=8)  # "ancient_cloud_45678901"

Test Data Generation

from haikunator import Haikunator

# Seeded for reproducible test data
test_haikunator = Haikunator(seed='test-seed-123')
test_names = [test_haikunator.haikunate() for _ in range(5)]
# Always generates the same 5 names for consistent testing

Default Word Lists

The library includes built-in word lists with 91 adjectives and 96 nouns (95 unique nouns due to duplicate "sun"):

  • Adjectives: aged, ancient, autumn, billowing, bitter, black, blue, bold, broad, broken, calm, cold, cool, crimson, curly, damp, dark, dawn, delicate, divine, dry, empty, falling, fancy, flat, floral, fragrant, frosty, gentle, green, hidden, holy, icy, jolly, late, lingering, little, lively, long, lucky, misty, morning, muddy, mute, nameless, noisy, odd, old, orange, patient, plain, polished, proud, purple, quiet, rapid, raspy, red, restless, rough, round, royal, shiny, shrill, shy, silent, small, snowy, soft, solitary, sparkling, spring, square, steep, still, summer, super, sweet, throbbing, tight, tiny, twilight, wandering, weathered, white, wild, winter, wispy, withered, yellow, young

  • Nouns: art, band, bar, base, bird, block, boat, bonus, bread, breeze, brook, bush, butterfly, cake, cell, cherry, cloud, credit, darkness, dawn, dew, disk, dream, dust, feather, field, fire, firefly, flower, fog, forest, frog, frost, glade, glitter, grass, hall, hat, haze, heart, hill, king, lab, lake, leaf, limit, math, meadow, mode, moon, morning, mountain, mouse, mud, night, paper, pine, poetry, pond, queen, rain, recipe, resonance, rice, river, salad, scene, sea, shadow, shape, silence, sky, smoke, snow, snowflake, sound, star, sun, sun, sunset, surf, term, thunder, tooth, tree, truth, union, unit, violet, voice, water, waterfall, wave, wildflower, wind, wood

Note: The words "dawn" and "morning" appear in both adjectives and nouns lists. The word "sun" appears twice in the nouns list.

Error Handling

The library handles edge cases gracefully:

  • Empty custom word lists return empty strings for missing components
  • Invalid parameters use default values
  • Random seed accepts any hashable type including strings, numbers, and tuples
  • Zero or negative token_length excludes the token from output