A Python package and command-line utility to generate unique and memorable names (e.g., talented-toucan
, naughty-watermelon
) and IDs (e.g., broken-radio-7ab4g
). These names/IDs are ideal for naming temporary directories, user session IDs, gamer tags, project names, process names, or submitted jobs.
The generated names cover a wide range of thematic categories, including science, animals, or history, often with a humorous twist. While creating unique-namer, I was inspired by the creative names used by Docker for its containers and Nextflow for its processes.
- Over 19 million unique names
- Nearly infinite unique identifiers
- 25 categories
- Customizable names and categories
- Categories
- Requirements
- Installation
- Using Without Installation
- Usage
- Command-line Utility
- Versioning
- Tests
- License
Categories allow you to customize generated names to fit the specific topic or theme of your project. The default category, general
, includes widely recognized nouns and excludes more specialized or uncommon terms.
- | Category | Nouns count | Example name | Possible combinations | |
---|---|---|---|---|---|
Names | IDs (suffix 4) | ||||
__all__ | 8,199 | awful-deadline |
19,464,426 | 1013 | |
πΈ | animals | 461 | tan-octopus |
1,094,414 | 1012 |
π¬ | architecture | 134 | blowing-facade |
318,116 | 1011 |
π¨ | art | 176 | nonchalant-picasso |
417,824 | 1011 |
π | astronomy | 124 | ruthless-meteoroid |
294,376 | 1011 |
π | biology | 730 | shiny-centriole |
1,733,020 | 1012 |
π§ͺ | chemistry | 255 | junior-peroxide |
605,370 | 1012 |
πΊπΈ | countries | 182 | satisfying-tanzania |
432,068 | 1011 |
π» | computer_science | 334 | funny-malware |
792,916 | 1012 |
π° | economy | 175 | flowery-income |
415,450 | 1011 |
π | food | 217 | pretty-waffle |
515,158 | 1011 |
π | geography | 185 | enjoyed-tsunami |
439,190 | 1011 |
β | general | 5,476 | curvy-flight |
13,000,024 | 1013 |
π° | history | 156 | cool-epoch |
370,344 | 1011 |
π | literature | 587 | winning-limerick |
1,393,538 | 1012 |
π | math | 157 | peachy-prime |
372,718 | 1011 |
π₯ | medicine | 706 | curly-diarrhea |
1,676,044 | 1012 |
π | microbiology | 130 | crazy-bacteria |
308,620 | 1011 |
π¬ | molecular_biology | 220 | retired-oligonucleotide |
522,280 | 1011 |
π΅ | music | 203 | solid-contrabassoon |
481,922 | 1011 |
physics | 147 | terrible-pressure |
348,978 | 1011 | |
π» | plants | 178 | anonymous-cactus |
422,572 | 1011 |
science | 876 | golden-hertz |
2,079,624 | 1012 | |
π§βπ» | scientists | 101 | gifted-newton |
239,774 | 1011 |
π | sports | 191 | intergalactic-olympics |
453,434 | 1011 |
π‘ | technology | 228 | awesome-python |
541,272 | 1011 |
- Python version 3.6 or higher
- No external dependencies are required
Install unique-namer
from PyPI:
pip install unique-namer
Alternatively, you can install the latest version directly from GitHub:
pip install "git+https://github.com/aziele/unique-namer.git"
If you prefer to use unique-namer
without installation, you can clone or download the repository:
git clone https://github.com/aziele/unique-namer.git
cd unique-namer/src/
You can import namer
in Python:
python
>>> import namer
>>> namer.__doc__
'Generate unique, human-readable, and memorable names or identifiers'
You can also use unique-namer
as a command-line tool:
python -m namer
The generate
function returns a string with a randomly generated name consisting of an adjective and a noun.
import namer
name = namer.generate()
print(name) # Example: 'blushy-cyclist'
The generate
function selects nouns from the general
category by default. If category is provided as a list of categories, the function randomly chooses one category from the list to generate a noun. Each category is chosen with equal probability, regardless of the number of nouns it contains.
import namer
name = namer.generate(category='astronomy')
print(name) # Example: 'crazy-supernova'
name = namer.generate(category=['physics', 'biology'])
print(name) # Example: 'pink-bacteria'
To use all available categories, set the category
argument to __all__
.
import namer
name = namer.generate(category='__all__')
print(name) # Example: 'lonely-momentum'
Adds a random suffix of the specified length to the generated name to create a unique identifier. The suffix consists of alphanumeric characters (0-9a-z
).
import namer
name = namer.generate(category='history', suffix_length=3)
print(name) # Example: 'annoying-cleopatra-9a1'
Specifies the separator to use between the adjective, noun, and suffix in the generated name.
import namer
name = namer.generate(category='sports', separator='_')
print(name) # Example: 'savage_judo'
Specifies the text case format of the generated name.
import namer
name = namer.generate(suffix_length=5, style='uppercase')
print(name) # Example: 'DAMAGED-ELECTRON-J20ZX'
name = namer.generate(separator=' ', style='title')
print(name) # Example: 'Lazy Unicorn'
To tailor the generated names to your specific project needs, such as adding a date or project name, use the _generate
function. This function returns a Python list of name components and a separator. You can modify the list and then format it into a string.
Here's an example:
import namer
# Generate name components
name_components, separator = _generate(category='food', suffix_length=3)
print(name_components) # Example: ['macho', 'pizza', '7dx']
# Create custom generate function
def my_generate(*args, **kwargs):
name_components, separator = namer_generate(*args, **kwargs)
name_components.insert(0, '2024')
return separator.join(name_components)
name = my_generate(category='food', suffix_length=3)
print(name) # Example: 2024-macho-pizza-7dx
You can retrieve the list of available categories using the list_categories
function.
import namer
print(namer.list_categories())
# ['animals', 'architecture', ..., 'sports']
To generate names or IDs tailored to your project, you can add custom categories. Extend the namer.data.categories
dictionary with lists of words representing your custom category.
import namer
# Create two subcategories.
my_dogs = ['charlie', 'bella', 'biga']
my_cats = ['tommy', 'lucy']
# Add a custom category named 'my_pets' containing both dogs and cats
namer.data.categories['my_pets'] = [my_dogs, my_cats]
# Generate a name from the 'my_pets' category
name = namer.generate(category='pets')
print(name) # Example: 'thankful-tommy'
The tool is available as a command-line utility.
namer -h
or
python -m namer -h
The stats
command prints a table with name/ID statitics for each category.
namer stats
Output:
Category Nouns Example Name_combs ID_combs (4-char suffix)
__all__ 8199 inventive-matter 19,464,426 3e+13
animals 461 scintillating-meerkat 1,094,414 2e+12
architecture 134 full-vault 318,116 5e+11
art 176 ample-vellum 417,824 7e+11
astronomy 124 secret-jupiter 294,376 5e+11
biology 730 alleged-electrophoresis 1,733,020 3e+12
chemistry 255 proud-nitrogen 605,370 1e+12
countries 182 temperate-oman 432,068 7e+11
computer_science 334 antique-algorithm 792,916 1e+12
economy 175 humorous-supply 415,450 7e+11
food 217 snotty-dish 515,158 9e+11
geography 185 distraught-solifluction 439,190 7e+11
general 5476 vertical-proof 13,000,024 2e+13
history 156 hip-perseus 370,344 6e+11
literature 587 definite-horrornovel 1,393,538 2e+12
math 157 protestant-curve 372,718 6e+11
medicine 706 muddled-synovia 1,676,044 3e+12
microbiology 130 gainful-lysin 308,620 5e+11
molecular_biology 220 additional-bioenergetics 522,280 9e+11
music 203 belligerent-metronome 481,922 8e+11
physics 147 confidential-circuit 348,978 6e+11
plants 178 ultimate-lentil 422,572 7e+11
science 876 interesting-antimony 2,079,624 3e+12
scientists 101 qualified-copernicus 239,774 4e+11
sports 191 decent-ski 453,434 8e+11
technology 228 exultant-overclocking 541,272 9e+11
The generate
command creates a list of names or IDs based on specified parameters.
namer generate 5
Output:
telling-adrenaline
infinite-gonad
close-span
bloody-blow
puffy-biology
To generate 10 IDs from the physics
and biology
categories, with a random suffix of 3
characters, using _
as a separator, and converting name style to title, use
namer generate 10 --category physics --category biology --suffix_length 3 -- \
separator _ --style title
Output:
Visiting_Haploid_Eep
Eventual_Refraction_Cnr
Snugly_Monod_Sim
Cruel_Codon_46p
Relieved_Decibel_Cn5
Underground_Bug_7wf
Super_Acre_30r
Guttural_Farad_E1w
Lead_Stalk_Fi4
Formidable_Field_621
The package follows Semantic Versioning with the format MAJOR.MINOR.PATCH
:
- MAJOR version: significant changes (e.g., new features, major code reorganizations).
- MINOR version: category-related updates (e.g., adding/moving categories).
- PATCH version: bug fixes or vocabulary expansions without changing the list of categories.
To ensure that unique-namer works as expected, you can run tests using pytest.
pytest tests