Skip to content

Generate unique and memorable names and ids across various categories

License

Notifications You must be signed in to change notification settings

aziele/unique-namer

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

22 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

unique-namer

PyPI - Version tests workflow

cover

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.

Features

  • Over 17 million unique names
  • Nearly infinite unique identifiers
  • 25 categories
  • Customizable names and categories

Table of contents

  1. Categories
  2. Requirements
  3. Installation
  4. Using Without Installation
  5. Usage
    1. Generating Names
    2. Customizing Names
    3. Getting Category List
    4. Adding Custom Categories
  6. Command-line Utility
    1. Getting Statistics
    2. Generating Names
  7. Versioning
  8. Tests
  9. License

1. Categories

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 17,250,696 1013
🐸 animals 461 tan-octopus 969,944 1012
🏬 architecture 134 blowing-facade 281,936 1011
🎨 art 177 nonchalant-picasso 372,408 1011
πŸ”­ astronomy 124 ruthless-meteoroid 260,896 1011
πŸ€ biology 730 shiny-centriole 1,535,920 1012
πŸ§ͺ chemistry 255 junior-peroxide 536,520 1011
πŸ‡ΊπŸ‡Έ countries 182 satisfying-tanzania 382,928 1011
πŸ’» computer_science 334 funny-malware 702,736 1012
πŸ’° economy 175 flowery-income 368,200 1011
πŸ” food 217 pretty-waffle 456,568 1011
🌎 geography 185 enjoyed-tsunami 389,240 1011
⭐ general 5,476 curvy-flight 11,521,504 1013
🏰 history 156 cool-epoch 328,224 1011
πŸ“š literature 587 winning-limerick 1,235,048 1012
πŸ“ math 157 peachy-prime 330,328 1011
πŸ₯ medicine 706 curly-diarrhea 1,485,424 1012
πŸ› microbiology 130 crazy-bacteria 273,520 1011
πŸ”¬ molecular_biology 220 retired-oligonucleotide 462,880 1011
🎡 music 203 solid-contrabassoon 427,112 1011
:atom: physics 147 terrible-pressure 309,288 1011
🌻 plants 178 anonymous-cactus 374,512 1011
:electron: science 876 golden-hertz 1,843,104 1012
πŸ§‘β€πŸ’» scientists 101 gifted-newton 212,504 1011
πŸ€ sports 191 intergalactic-olympics 401,864 1011
πŸ“‘ technology 228 awesome-drone 479,712 1011

2. Requirements

  • Python version 3.6 or higher
  • No external dependencies are required

3. Installation

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"

4. Using without installation

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

5. Usage

5.1. Generating names

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'

category - str or list, default is general

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'

suffix_length - int, default is 0

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'

separator - str, default is '-'

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'

style - str, one of title, lowercase, uppercase

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'

5.2. Customizing names

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

5.3. Getting category list

You can retrieve the list of available categories using the list_categories function.

import namer

print(namer.list_categories())
# ['animals', 'architecture', ..., 'sports', 'technology']

5.4. Adding custom categories

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'

6. Command-line utility

The tool is available as a command-line utility.

namer -h

or

python -m namer -h

6.1. Getting statistics

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  gabby-moscovium         17,250,696  3e+13
animals              461  ready-deer                 969,944  2e+12
architecture         134  foolish-courtyard          281,936  5e+11
art                  177  lonely-focal               372,408  6e+11
astronomy            124  brawny-neutrino            260,896  4e+11
biology              730  bewildered-genetics      1,535,920  3e+12
chemistry            255  gray-manganese             536,520  9e+11
countries            182  accessible-ghana           382,928  6e+11
computer_science     334  numerous-ip                702,736  1e+12
economy              175  exultant-globaltrade       368,200  6e+11
food                 217  weird-pudding              456,568  8e+11
geography            185  insulated-oasis            389,240  7e+11
general             5476  inexpensive-poem        11,521,504  2e+13
history              156  trashy-lincoln             328,224  6e+11
literature           587  testy-motif              1,235,048  2e+12
math                 157  figurative-thales          330,328  6e+11
medicine             706  labored-tarsus           1,485,424  2e+12
microbiology         130  correct-microbiota         273,520  5e+11
molecular_biology    220  undisturbed-chromosome     462,880  8e+11
music                203  flaky-raga                 427,112  7e+11
physics              147  muffled-aperture           309,288  5e+11
plants               178  uncommon-echinacea         374,512  6e+11
science              876  worldwide-ionosphere     1,843,104  3e+12
scientists           101  staking-maxwell            212,504  4e+11
sports               191  retail-race                401,864  7e+11
technology           228  demonic-digitalization     479,712  8e+11

6.2. Generating names

The generate command creates a list of names or IDs based on specified parameters.

Example 1: Generating 5 names

namer generate 5

Output:

telling-adrenaline
infinite-gonad
close-span
bloody-blow
puffy-biology

Example 2: Generating 10 IDs with custom parameters

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

7. Versioning

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.

8. Tests

To ensure that unique-namer works as expected, you can run tests using pytest.

pytest tests

9. License

MIT License

About

Generate unique and memorable names and ids across various categories

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages