0
# Haikunator
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: haikunator
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install haikunator`
10

11
## Core Imports
12

13
```python
14
from haikunator import Haikunator
15
```
16

17
Package import:
18

19
```python
20
import haikunator
21
# Access via haikunator.Haikunator
22
```
23

24
## Basic Usage
25

26
```python
27
from haikunator import Haikunator
28

29
# Create a new instance
30
haikunator = Haikunator()
31

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

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

42
# Generate without token
43
simple_name = haikunator.haikunate(token_length=0)  # "cold-wildflower"
44
```
45

46
## Capabilities
47

48
### Random Name Generation
49

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

52
```python { .api }
53
class Haikunator:
54
    def __init__(self, seed=None, adjectives=None, nouns=None):
55
        """
56
        Initialize new haikunator instance.
57

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

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

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

74
        Returns:
75
            str: Generated name (e.g., "wispy-dust-1337")
76
        """
77
```
78

79
### Seeded Generation
80

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

83
```python
84
from haikunator import Haikunator
85

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

90
name1 = h1.haikunate()  # "ancient-fire-7823"  
91
name2 = h2.haikunate()  # "ancient-fire-7823" (same result)
92
```
93

94
### Custom Word Lists
95

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

98
```python
99
from haikunator import Haikunator
100

101
# Create instance with custom words
102
haikunator = Haikunator(
103
    adjectives=['blazing', 'swift', 'mighty'],
104
    nouns=['falcon', 'tiger', 'dragon']
105
)
106

107
name = haikunator.haikunate()  # "swift-dragon-4729"
108
```
109

110
### Delimiter Customization
111

112
Customize the separator between name components for different formatting requirements.
113

114
```python
115
from haikunator import Haikunator
116

117
haikunator = Haikunator()
118

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

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

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

128
# Underscore delimiter
129
name4 = haikunator.haikunate(delimiter='_')  # "misty_moon_5647"
130
```
131

132
### Token Configuration
133

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

136
```python
137
from haikunator import Haikunator
138

139
haikunator = Haikunator()
140

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

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

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

150
# No token
151
no_token = haikunator.haikunate(token_length=0)    # "wild-forest"
152
```
153

154
## Configuration Examples
155

156
### Email-Friendly Names
157
```python
158
from haikunator import Haikunator
159

160
haikunator = Haikunator()
161
email_name = haikunator.haikunate(delimiter='-', token_length=4)  # "bold-river-1234"
162
```
163

164
### URL-Friendly Names
165
```python
166
from haikunator import Haikunator
167

168
haikunator = Haikunator()
169
url_name = haikunator.haikunate(delimiter='-', token_length=6)  # "quiet-mountain-789123"
170
```
171

172
### Database-Friendly Names
173
```python
174
from haikunator import Haikunator
175

176
haikunator = Haikunator()
177
db_name = haikunator.haikunate(delimiter='_', token_length=8)  # "ancient_cloud_45678901"
178
```
179

180
### Test Data Generation
181
```python
182
from haikunator import Haikunator
183

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

190
## Default Word Lists
191

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

194
- **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
195

196
- **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
197

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

200
## Error Handling
201

202
The library handles edge cases gracefully:
203

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