0
# randomname
1

2
Generate random memorable names using combinations of adjectives and nouns, similar to those used by Docker containers and GitHub repositories. The library provides both programmatic and command-line interfaces for creating unique, human-readable identifiers from curated word lists organized by semantic categories.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```python
14
import randomname
15
```
16

17
## Basic Usage
18

19
```python
20
import randomname
21

22
# Generate a simple adjective-noun name
23
name = randomname.get_name()
24
# Returns: "sleek-voxel"
25

26
# Generate from specific categories
27
name = randomname.get_name(adj=('colors',), noun=('cats', 'food'))
28
# Returns: "crimson-pasta"
29

30
# Generate custom patterns
31
name = randomname.generate('v/fire', 'adj/music_theory', 'n/cats')
32
# Returns: "toast-adagio-angora"
33

34
# Generate multiple names
35
names = randomname.sample(n=5)
36
# Returns: {"frayed-potentiality", "recursive-vector", ...}
37

38
# Access available categories
39
print(randomname.ADJECTIVES)
40
# Returns: ['speed', 'weather', 'shape', 'sound', ...]
41
```
42

43
## Capabilities
44

45
### Basic Name Generation
46

47
Generate simple adjective-noun combinations using default or specified word categories.
48

49
```python { .api }
50
def get_name(adj=ADJECTIVES, noun=NOUNS, sep='-', seed=None):
51
    """
52
    Generate a random adjective-noun name using specified categories.
53
    
54
    Args:
55
        adj (tuple or list): Adjective categories to use (default: all adjectives)
56
        noun (tuple or list): Noun categories to use (default: all nouns)
57
        sep (str): Separator between words (default: '-')
58
        seed (int, optional): Random seed for reproducible results
59
        
60
    Returns:
61
        str: Generated name like "sleek-voxel"
62
    """
63
```
64

65
### Advanced Pattern Generation
66

67
Create custom patterns using specific word categories and types with flexible formatting.
68

69
```python { .api }
70
def generate(*groups, sep='-', seed=None):
71
    """
72
    Generate words from a sequence of word class/categories.
73
    
74
    Args:
75
        *groups: Variable arguments specifying word categories
76
                Format: 'wordclass/category' (e.g., 'adj/colors', 'n/cats', 'v/fire')
77
                Aliases: 'a' (adjectives), 'n' (nouns), 'v' (verbs), 'nm' (names), 'ip' (ipsum)
78
        sep (str): Separator between words (default: '-')
79
        seed (int, optional): Random seed for reproducible results
80
        
81
    Returns:
82
        str: Generated name with words joined by separator
83
    """
84
```
85

86
### Bulk Generation
87

88
Generate multiple unique names efficiently with customizable quantity and patterns.
89

90
```python { .api }
91
def sample(*groups, n=10, sep='-', seed=None):
92
    """
93
    Generate multiple unique random names using specified groups.
94
    
95
    Args:
96
        *groups: Variable arguments specifying word categories (same format as generate)
97
        n (int): Number of names to generate (default: 10)
98
        sep (str): Separator between words (default: '-')
99
        seed (int, optional): Random seed for reproducible results
100
        
101
    Returns:
102
        set: Set of unique generated names
103
    """
104

105
def sample_names(n=10, adj=ADJECTIVES, noun=NOUNS, sep='-', seed=None):
106
    """
107
    Generate multiple unique adjective-noun combinations.
108
    
109
    Args:
110
        n (int): Number of names to generate (default: 10)
111
        adj (tuple or list): Adjective categories to use
112
        noun (tuple or list): Noun categories to use
113
        sep (str): Separator between words (default: '-')
114
        seed (int, optional): Random seed for reproducible results
115
        
116
    Returns:
117
        set: Set of unique generated names
118
    """
119

120
def sample_words(*groups, n=10, seed=None):
121
    """
122
    Get random sample of individual words from specified categories.
123
    
124
    Args:
125
        *groups: Variable arguments specifying word categories
126
        n (int): Number of words to sample (default: 10)
127
        seed (int, optional): Random seed for reproducible results
128
        
129
    Returns:
130
        list: List of individual words (sampled without replacement)
131
    """
132
```
133

134
### Category Discovery
135

136
Explore available word categories and find appropriate ones for your use case.
137

138
```python { .api }
139
def available(k=None):
140
    """
141
    Show available word categories for a word class.
142
    
143
    Args:
144
        k (str, optional): Word class key ('adjectives', 'nouns', 'verbs', 'names', 'ipsum')
145
                          Aliases accepted: 'a', 'adj', 'n', 'nn', 'v', 'vb', 'nm', 'ip'
146
                          
147
    Returns:
148
        dict or list: All available categories if k=None, or list of categories for specified class
149
    """
150
```
151

152
### Command Line Interface Entry Point
153

154
Main entry point function for the command line interface.
155

156
```python { .api }
157
def main():
158
    """
159
    Main entry point for the randomname command line interface.
160
    Sets up Fire CLI with all available commands including:
161
    - get: Generate single names 
162
    - generate: Create custom patterns
163
    - sample: Generate multiple names
164
    - available: Show categories
165
    - sample_words: Sample individual words
166
    - sample_names: Sample name lists
167
    - saved: Access SavedList functionality
168
    - util: Access utility functions
169
    """
170
```
171

172
### Persistent Name Lists
173

174
Manage and store collections of generated names for reuse across sessions.
175

176
```python { .api }
177
class SavedList:
178
    """
179
    Persistent list manager for storing and retrieving generated names.
180
    Automatically saves to ~/.randomname/ directory.
181
    """
182
    
183
    def __init__(self, name='default', groups=None, n=100, overwrite=False):
184
        """
185
        Initialize a saved list of names.
186
        
187
        Args:
188
            name (str): Name for the saved list (default: 'default')
189
            groups (list, optional): Word categories to use for generation
190
            n (int): Initial number of names to generate (default: 100)
191
            overwrite (bool): Whether to overwrite existing list (default: False)
192
        """
193
    
194
    def get(self, index):
195
        """
196
        Get name at specified index.
197
        
198
        Args:
199
            index (int): Index of name to retrieve
200
            
201
        Returns:
202
            str: Name at the specified index
203
        """
204
    
205
    def sample(self, n=100, **kwargs):
206
        """
207
        Clear and generate n new names.
208
        
209
        Args:
210
            n (int): Number of names to generate (default: 100)
211
            **kwargs: Additional arguments passed to sample function
212
            
213
        Returns:
214
            SavedList: Self for method chaining
215
        """
216
    
217
    def more(self, n=100, **kwargs):
218
        """
219
        Add n more names to existing list.
220
        
221
        Args:
222
            n (int): Number of additional names to generate (default: 100)
223
            **kwargs: Additional arguments passed to sample function
224
            
225
        Returns:
226
            SavedList: Self for method chaining
227
        """
228
        
229
    def atlen(self, n=100, **kwargs):
230
        """
231
        Ensure list has exactly n names.
232
        
233
        Args:
234
            n (int): Target number of names (default: 100)
235
            **kwargs: Additional arguments passed to sample function
236
            
237
        Returns:
238
            SavedList: Self for method chaining
239
        """
240
        
241
    def clear(self):
242
        """
243
        Clear all names and save.
244
        
245
        Returns:
246
            SavedList: Self for method chaining
247
        """
248
        
249
    def remove(self):
250
        """
251
        Clear names and delete saved file.
252
        
253
        Returns:
254
            SavedList: Self for method chaining
255
        """
256
        
257
    def save(self):
258
        """
259
        Save current state to disk.
260
        
261
        Returns:
262
            SavedList: Self for method chaining
263
        """
264
        
265
    def dump(self, index=True):
266
        """
267
        Return formatted string of all names.
268
        
269
        Args:
270
            index (bool): Whether to include index numbers (default: True)
271
            
272
        Returns:
273
            str: Formatted string with names, optionally with indices
274
        """
275
        
276
    @property
277
    def exists(self):
278
        """
279
        Check if saved file exists.
280
        
281
        Returns:
282
            bool: True if saved file exists on disk
283
        """
284
```
285

286
## Word Categories
287

288
### Category Constants
289

290
Pre-defined lists of available word categories for each word class.
291

292
```python { .api }
293
WORD_CLASSES: list
294
# Base word class names: ['adjectives', 'nouns', 'verbs', 'names', 'ipsum']
295

296
ADJECTIVES: list
297
# Available adjective categories: ['speed', 'weather', 'shape', 'sound', 'physics', 
298
# 'temperature', 'corporate_prefixes', 'complexity', 'colors', 'taste', 'quantity', 
299
# 'size', 'algorithms', 'geometry', 'materials', 'construction', 'music_theory', 
300
# 'appearance', 'linguistics', 'emotions', 'age', 'character']
301

302
NOUNS: list  
303
# Available noun categories: ['accounting', 'fortifications', 'typography', 'spirits',
304
# 'cotton', 'car_parts', 'shopping', 'chemistry', 'seasonings', 'gaming', 'cats',
305
# 'real_estate', 'wood', 'military_navy', 'wine', 'music_production', 'sports', 'meat',
306
# 'physics', 'physics_waves', 'corporate', 'web_development', 'condiments', 'design',
307
# 'automobiles', 'metals', 'fast_food', 'radio', 'physics_units', 'military_airforce',
308
# '3d_printing', '3d_graphics', 'travel', 'dogs', 'houses', 'astronomy', 'buildings',
309
# 'minerals', 'startups', 'algorithms', 'fruit', 'apex_predators', 'infrastructure',
310
# 'geometry', 'set_theory', 'ghosts', 'military_army', 'music_instruments', 'filmmaking',
311
# 'birds', 'construction', 'music_theory', 'corporate_job', 'driving', 'linear_algebra',
312
# 'fish', 'coding', 'architecture', 'writing', 'phones', 'machine_learning', 'furniture',
313
# 'history', 'plants', 'cheese', 'food', 'containers', 'vcs', 'water', 'storage',
314
# 'geography', 'physics_optics', 'data_structures', 'screenwriting', 'insurance']
315

316
VERBS: list
317
# Available verb categories: ['graphics', 'movement', 'music', 'cooking', 'thought',
318
# 'military_navy', 'music_production', 'manipulation', 'sports', 'corporate', 'creation',
319
# 'destruction', 'quantity', 'radio', '3d_graphics', 'look', 'fire', 'collection',
320
# 'programming', 'art', 'driving', 'vcs', 'communication', 'web']
321

322
NAMES: list
323
# Available name categories: ['cities', 'codenames'] and others
324

325
IPSUM: list  
326
# Available ipsum categories: ['corporate', 'hipster', 'blockchain', 'lorem', 'reddit']
327

328
AVAILABLE: dict
329
# Dictionary mapping word classes to their available categories
330
# Same as {'adjectives': ADJECTIVES, 'nouns': NOUNS, 'verbs': VERBS, 'names': NAMES, 'ipsum': IPSUM}
331

332
ALL_CATEGORIES: list
333
# Flat list of all available categories across all word classes in 'wordclass/category' format
334
# e.g., ['adjectives/colors', 'adjectives/speed', ..., 'nouns/cats', 'nouns/food', ...]
335
```
336

337
### Category Format Specifications
338

339
Word categories can be specified using several formats:
340

341
- **Full names**: `'adjectives/colors'`, `'nouns/cats'`
342
- **Aliases**: `'a/colors'`, `'n/cats'`, `'v/music'`, `'nm/cities'`, `'ip/lorem'`
343
- **Wildcards**: `'adj/*'`, `'n/music*'` (matches multiple categories)
344
- **Multiple categories**: `('colors', 'shapes')` or `'colors,shapes'`
345
- **Special functions**: `'uuid'` or `'u'` generates UUID strings
346

347
## Command Line Interface
348

349
The package provides a complete CLI interface for all functionality.
350

351
```bash
352
# Generate single names
353
randomname get
354
randomname get weather shopping,cats
355

356
# Generate custom patterns  
357
randomname generate adj/sound n/apex_predators
358
randomname generate v/art,v/thought a/sound n/apex_predators
359

360
# Generate multiple names
361
randomname sample adj/colors n/cats --n=5
362

363
# Show available categories
364
randomname available
365
randomname available nouns
366

367
# Sample individual words
368
randomname sample_words n/cats --n=10
369

370
# Access utility functions
371
randomname util
372
```
373

374
## Utility Module
375

376
The util module provides low-level functions and utilities used internally by randomname.
377

378
```python
379
import randomname.util
380
```
381

382
### Key Utility Functions
383

384
```python { .api }
385
def get_groups_list(fnames):
386
    """
387
    Get word lists from multiple word groups.
388
    
389
    Args:
390
        fnames: File names or word groups to load
391
        
392
    Returns:
393
        list: Combined list of words from all specified groups
394
    """
395

396
def doalias(fname):
397
    """
398
    Replace aliases in string with full word class names.
399
    
400
    Args:
401
        fname (str): String potentially containing aliases like 'a/colors'
402
        
403
    Returns:
404
        str: String with aliases replaced (e.g., 'adjectives/colors')
405
    """
406

407
def choose(items, n=None):
408
    """
409
    Choose one or more items from a list using randomname's RNG.
410
    
411
    Args:
412
        items: List of items to choose from
413
        n (int, optional): Number of items to choose
414
        
415
    Returns:
416
        item or list: Single item if n=None, otherwise list of n items
417
    """
418

419
def sample_unique(func, n, *args, n_fails=50, unique=True, **kwargs):
420
    """
421
    Generate n unique results by calling func repeatedly.
422
    
423
    Args:
424
        func: Function to call for generation
425
        n (int): Number of unique results desired
426
        *args: Arguments to pass to func
427
        n_fails (int): Maximum attempts per result (default: 50)
428
        unique (bool): Whether to enforce uniqueness (default: True)
429
        **kwargs: Keyword arguments to pass to func
430
        
431
    Returns:
432
        set: Set of unique results
433
    """
434
```
435

436
### Utility Constants
437

438
```python { .api }
439
ALIASES: dict
440
# Mapping of short aliases to full word class names
441
# {'a': 'adjectives', 'n': 'nouns', 'v': 'verbs', 'nm': 'names', 'ip': 'ipsum', 
442
#  'adj': 'adjectives', 'nn': 'nouns', 'vb': 'verbs', 'u': 'uuid', 'uu': 'uuid'}
443

444
WORD_FUNCS: dict 
445
# Special generator functions like UUID
446
# {'uuid': uuid_}
447
```
448

449
## Error Handling
450

451
The library provides helpful error messages for common issues:
452

453
- **Invalid categories**: Raises `ValueError` with suggestions for close matches
454
- **Missing wordlist files**: Raises `OSError` with specific file path information  
455
- **File system errors**: Handled gracefully in SavedList operations
456

457
Example error handling:
458

459
```python
460
try:
461
    name = randomname.generate('adj/invalidcategory')
462
except ValueError as e:
463
    print(e)  # "No matching wordlist 'adj/invalidcategory'. Did you mean 'adj/algorithms'?"
464
```
465

466
## Reproducible Generation
467

468
All generation functions support a `seed` parameter for reproducible results:
469

470
```python
471
# Same seed always produces same result
472
name1 = randomname.get_name(seed=42)
473
name2 = randomname.get_name(seed=42)
474
assert name1 == name2  # True
475

476
# Generate reproducible lists
477
names = randomname.sample(n=5, seed=123)
478
# Always returns the same 5 names for seed=123
479
```