randomname

import randomname

import randomname

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

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

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

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

# Access available categories
print(randomname.ADJECTIVES)
# Returns: ['speed', 'weather', 'shape', 'sound', ...]

def get_name(adj=ADJECTIVES, noun=NOUNS, sep='-', seed=None):
    """
    Generate a random adjective-noun name using specified categories.
    
    Args:
        adj (tuple or list): Adjective categories to use (default: all adjectives)
        noun (tuple or list): Noun categories to use (default: all nouns)
        sep (str): Separator between words (default: '-')
        seed (int, optional): Random seed for reproducible results
        
    Returns:
        str: Generated name like "sleek-voxel"
    """

def generate(*groups, sep='-', seed=None):
    """
    Generate words from a sequence of word class/categories.
    
    Args:
        *groups: Variable arguments specifying word categories
                Format: 'wordclass/category' (e.g., 'adj/colors', 'n/cats', 'v/fire')
                Aliases: 'a' (adjectives), 'n' (nouns), 'v' (verbs), 'nm' (names), 'ip' (ipsum)
        sep (str): Separator between words (default: '-')
        seed (int, optional): Random seed for reproducible results
        
    Returns:
        str: Generated name with words joined by separator
    """

def sample(*groups, n=10, sep='-', seed=None):
    """
    Generate multiple unique random names using specified groups.
    
    Args:
        *groups: Variable arguments specifying word categories (same format as generate)
        n (int): Number of names to generate (default: 10)
        sep (str): Separator between words (default: '-')
        seed (int, optional): Random seed for reproducible results
        
    Returns:
        set: Set of unique generated names
    """

def sample_names(n=10, adj=ADJECTIVES, noun=NOUNS, sep='-', seed=None):
    """
    Generate multiple unique adjective-noun combinations.
    
    Args:
        n (int): Number of names to generate (default: 10)
        adj (tuple or list): Adjective categories to use
        noun (tuple or list): Noun categories to use
        sep (str): Separator between words (default: '-')
        seed (int, optional): Random seed for reproducible results
        
    Returns:
        set: Set of unique generated names
    """

def sample_words(*groups, n=10, seed=None):
    """
    Get random sample of individual words from specified categories.
    
    Args:
        *groups: Variable arguments specifying word categories
        n (int): Number of words to sample (default: 10)
        seed (int, optional): Random seed for reproducible results
        
    Returns:
        list: List of individual words (sampled without replacement)
    """

def available(k=None):
    """
    Show available word categories for a word class.
    
    Args:
        k (str, optional): Word class key ('adjectives', 'nouns', 'verbs', 'names', 'ipsum')
                          Aliases accepted: 'a', 'adj', 'n', 'nn', 'v', 'vb', 'nm', 'ip'
                          
    Returns:
        dict or list: All available categories if k=None, or list of categories for specified class
    """

def main():
    """
    Main entry point for the randomname command line interface.
    Sets up Fire CLI with all available commands including:
    - get: Generate single names 
    - generate: Create custom patterns
    - sample: Generate multiple names
    - available: Show categories
    - sample_words: Sample individual words
    - sample_names: Sample name lists
    - saved: Access SavedList functionality
    - util: Access utility functions
    """

class SavedList:
    """
    Persistent list manager for storing and retrieving generated names.
    Automatically saves to ~/.randomname/ directory.
    """
    
    def __init__(self, name='default', groups=None, n=100, overwrite=False):
        """
        Initialize a saved list of names.
        
        Args:
            name (str): Name for the saved list (default: 'default')
            groups (list, optional): Word categories to use for generation
            n (int): Initial number of names to generate (default: 100)
            overwrite (bool): Whether to overwrite existing list (default: False)
        """
    
    def get(self, index):
        """
        Get name at specified index.
        
        Args:
            index (int): Index of name to retrieve
            
        Returns:
            str: Name at the specified index
        """
    
    def sample(self, n=100, **kwargs):
        """
        Clear and generate n new names.
        
        Args:
            n (int): Number of names to generate (default: 100)
            **kwargs: Additional arguments passed to sample function
            
        Returns:
            SavedList: Self for method chaining
        """
    
    def more(self, n=100, **kwargs):
        """
        Add n more names to existing list.
        
        Args:
            n (int): Number of additional names to generate (default: 100)
            **kwargs: Additional arguments passed to sample function
            
        Returns:
            SavedList: Self for method chaining
        """
        
    def atlen(self, n=100, **kwargs):
        """
        Ensure list has exactly n names.
        
        Args:
            n (int): Target number of names (default: 100)
            **kwargs: Additional arguments passed to sample function
            
        Returns:
            SavedList: Self for method chaining
        """
        
    def clear(self):
        """
        Clear all names and save.
        
        Returns:
            SavedList: Self for method chaining
        """
        
    def remove(self):
        """
        Clear names and delete saved file.
        
        Returns:
            SavedList: Self for method chaining
        """
        
    def save(self):
        """
        Save current state to disk.
        
        Returns:
            SavedList: Self for method chaining
        """
        
    def dump(self, index=True):
        """
        Return formatted string of all names.
        
        Args:
            index (bool): Whether to include index numbers (default: True)
            
        Returns:
            str: Formatted string with names, optionally with indices
        """
        
    @property
    def exists(self):
        """
        Check if saved file exists.
        
        Returns:
            bool: True if saved file exists on disk
        """

WORD_CLASSES: list
# Base word class names: ['adjectives', 'nouns', 'verbs', 'names', 'ipsum']

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

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

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

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

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

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

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

# Generate single names
randomname get
randomname get weather shopping,cats

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

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

# Show available categories
randomname available
randomname available nouns

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

# Access utility functions
randomname util

import randomname.util

def get_groups_list(fnames):
    """
    Get word lists from multiple word groups.
    
    Args:
        fnames: File names or word groups to load
        
    Returns:
        list: Combined list of words from all specified groups
    """

def doalias(fname):
    """
    Replace aliases in string with full word class names.
    
    Args:
        fname (str): String potentially containing aliases like 'a/colors'
        
    Returns:
        str: String with aliases replaced (e.g., 'adjectives/colors')
    """

def choose(items, n=None):
    """
    Choose one or more items from a list using randomname's RNG.
    
    Args:
        items: List of items to choose from
        n (int, optional): Number of items to choose
        
    Returns:
        item or list: Single item if n=None, otherwise list of n items
    """

def sample_unique(func, n, *args, n_fails=50, unique=True, **kwargs):
    """
    Generate n unique results by calling func repeatedly.
    
    Args:
        func: Function to call for generation
        n (int): Number of unique results desired
        *args: Arguments to pass to func
        n_fails (int): Maximum attempts per result (default: 50)
        unique (bool): Whether to enforce uniqueness (default: True)
        **kwargs: Keyword arguments to pass to func
        
    Returns:
        set: Set of unique results
    """

ALIASES: dict
# Mapping of short aliases to full word class names
# {'a': 'adjectives', 'n': 'nouns', 'v': 'verbs', 'nm': 'names', 'ip': 'ipsum', 
#  'adj': 'adjectives', 'nn': 'nouns', 'vb': 'verbs', 'u': 'uuid', 'uu': 'uuid'}

WORD_FUNCS: dict 
# Special generator functions like UUID
# {'uuid': uuid_}

try:
    name = randomname.generate('adj/invalidcategory')
except ValueError as e:
    print(e)  # "No matching wordlist 'adj/invalidcategory'. Did you mean 'adj/algorithms'?"

# Same seed always produces same result
name1 = randomname.get_name(seed=42)
name2 = randomname.get_name(seed=42)
assert name1 == name2  # True

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