unique-namer 1.5.0

Generate unique, human-readable, and memorable names or identifiers

unique-namer

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 19 million unique names
• Nearly infinite unique identifiers
• 20+ 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,082	awful-deadline	19,186,668	1013
:frog:	animals	461	tan-octopus	1,094,414	1012
:department_store:	architecture	134	blowing-facade	318,116	1011
:telescope:	astronomy	124	ruthless-meteoroid	294,376	1011
:four_leaf_clover:	biology	730	shiny-centriole	1,733,020	1012
:test_tube:	chemistry	255	junior-peroxide	605,370	1012
:us:	countries	182	satisfying-tanzania	432,068	1011
:computer:	computer_science	333	funny-malware	790,542	1012
:moneybag:	economy	175	flowery-income	415,450	1011
:hamburger:	food	217	pretty-waffle	515,158	1011
:earth_americas:	geography	185	enjoyed-tsunami	439,190	1011
:star:	general	5,476	curvy-flight	13,000,024	1013
:european_castle:	history	156	cool-epoch	370,344	1011
:books:	literature	587	winning-limerick	1,393,538	1012
:triangular_ruler:	math	157	peachy-prime	372,718	1011
:hospital:	medicine	706	curly-diarrhea	1,676,044	1012
:bug:	microbiology	130	crazy-bacteria	308,620	1011
:microscope:	molecular_biology	220	retired-oligonucleotide	522,280	1011
:musical_note:	music	203	solid-contrabassoon	481,922	1011
:atom:	physics	147	terrible-pressure	348,978	1011
:sunflower:	plants	178	anonymous-cactus	422,572	1011
:electron:	science	876	golden-hertz	2,079,624	1012
:technologist:	scientists	101	gifted-newton	239,774	1011
:basketball:	sports	191	intergalactic-olympics	453,434	1011
:satellite:	technology	228	awesome-python	541,272	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']

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__             8082  young-phages           19,186,668  3e+13
animals              461  absurd-cuckoo           1,094,414  2e+12
architecture         134  mutual-loggia             318,116  5e+11
astronomy            124  grumpy-telescope          294,376  5e+11
biology              730  immature-commensalism   1,733,020  3e+12
chemistry            255  becoming-osmosis          605,370  1e+12
countries            182  quintessential-gambia     432,068  7e+11
computer_science     333  ruling-proxy              790,542  1e+12
economy              175  enjoyed-savings           415,450  7e+11
food                 217  amicable-pretzel          515,158  9e+11
geography            185  key-antarctic             439,190  7e+11
general             5476  regal-acappella        13,000,024  2e+13
history              156  minimal-tribe             370,344  6e+11
literature           587  prime-sestet            1,393,538  2e+12
math                 157  bustling-settheory        372,718  6e+11
medicine             706  phobic-lumbago          1,676,044  3e+12
microbiology         130  squeamish-virologists     308,620  5e+11
molecular_biology    220  merciless-betasheet       522,280  9e+11
music                203  prepared-chorus           481,922  8e+11
physics              147  likely-ohm                348,978  6e+11
plants               178  wide-gladiolus            422,572  7e+11
science              876  xenacious-ion           2,079,624  3e+12
scientists           101  sour-lamarck              239,774  4e+11
sports               191  concave-crew              453,434  8e+11
technology           228  zygotic-circuits          541,272  9e+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