randomname

randomname generates human-readable, memorable identifiers by combining words from curated adjective, noun, verb, and name word lists — the same style of naming used by Docker containers (brave_einstein) and GitHub Codespaces. It’s useful anywhere a numeric or UUID identifier would be technically correct but hard for humans to remember, differentiate, or type.

The library ships dozens of themed word categories (colors, cats, algorithms, music theory, apex predators, and more) that can be mixed and matched via a simple CLI (randomname get) or imported directly into Python code (randomname.get_name()), with support for restricting to specific categories or injecting custom words into the generated name.

What You Get

• A randomname get CLI command for quick adjective-noun name generation from the terminal
• An importable randomname.get_name() / randomname.generate() Python API
• Dozens of themed word-list categories (colors, cats, algorithms, corporate, physics, music theory, and more)
• Ability to restrict generation to specific categories or mix in custom words
• PyInstaller hook support so the bundled wordlists survive packaging into a standalone executable

Common Use Cases

• Naming ephemeral resources (containers, sandboxes, temp folders) with memorable identifiers instead of UUIDs
• Generating friendly default names for user-created projects, workspaces, or sessions
• Producing themed codenames for internal releases, feature flags, or test fixtures
• Creating easy-to-communicate room or session codes for demos and support tickets

Under The Hood

Architecture - The package centers on core.py, which loads word lists from the wordlists/ directory (sourced from the external imsky/wordlists project) at import time and exposes get_name()/generate() functions that randomly sample from adjective/noun/verb/name/ipsum categories based on a simple category/subcategory string syntax (e.g. adj/colors). __main__.py wraps this in a fire-based CLI so the same generation logic backs both the importable API and the randomname console script. A __pyinstaller subpackage registers a hook so the data-heavy wordlists are correctly bundled when the package is frozen into an executable. Tech Stack - Pure Python with a single runtime dependency (fire, for CLI argument parsing); word data is stored as plain .txt files bundled as package data rather than a database or external service. Code Quality - The tests/ directory exercises the core generation functions and category resolution; the README explicitly documents that word lists are sourced from a third-party project and invites users to report offensive terms, showing awareness of the risk inherent to large curated word lists. API Design - The CLI and library API mirror each other closely (randomname get vs. randomname.get_name()), and the adj/category string shorthand keeps both invocation styles terse; sensible defaults mean randomname.get_name() with no arguments already produces a usable result.