unique-namer 1.1.2

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

unique-namer

A Python package and command-line utility to generate unique, human-readable, and memorable names (e.g., talented-toucan, naughty-watermelon) and identifiers (e.g., broken-radio-7ab4g) across various categories such as science, animals, biology, etc.

Features

• Over 16 million unique names
• Nearly infinite unique identifiers
• Ideal for naming temporary directories, user session IDs, gamer tags, project names, process names, submitted jobs, and more.

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. License

1. Categories

Categories enable customization of generated names to align with the specific topic or theme of the project.

-	Category	Nouns count	Example name	Possible combinations
Names	IDs (suffix 4)
	__all__	7043	awful-deadline	16,720,082	1013
:chipmunk:	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	604	shiny-centriole	1,433,896	1012
:test_tube:	chemistry	255	junior-peroxide	605,370	1012
:us:	countries	182	satisfying-tanzania	432,068	1011
:computer:	computer_science	280	funny-malware	664,720	1012
:hamburger:	food	217	pretty-waffle	515,158	1011
:earth_americas:	geography	186	enjoyed-tsunami	441,564	1011
:european_castle:	history	162	cool-epoch	384,588	1011
:triangular_ruler:	math	158	peachy-prime	375,092	1011
:hospital:	medicine	706	curly-diarrhea	1,676,044	1012
:bug:	microbiology	103	crazy-bacteria	244,522	1011
:gun:	misc	2823	curvy-flight	6,701,802	1013
:microscope:	molecular_biology	118	retired-oligonucleotide	280,132	1011
:musical_note:	music	202	solid-contrabassoon	479,548	1011
:atom:	physics	145	terrible-pressure	344,230	1011
:sunflower:	plants	178	anonymous-cactus	422,572	1011
:books:	science	745	golden-hertz	1,768,630	1012
:technologist:	scientists	101	gifted-newton	239,774	1011
:basketball:	sports	191	intergalactic-olympics	453,434	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 an empty string

By default, generate randomly selects one category to pick a noun from. Categories are selected with equal probability, regardless of the number of nouns they contain. You can specify one or more categories to restrict the selection.

import namer

name = namer.generate(category='astronomy')
print(name)   # Example: 'crazy-supernova'                 

name = namer.generate(category=['physics', 'molecular_biology'])
print(name)   # Example: 'pink-bacteria'

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', 'astronomy', 'biology', 
# 'chemistry', 'computer_science', 'countries', 'food',
# 'geography', 'history', 'math', 'medicine, 'misc', 
# 'microbiology', 'molecular_biology', 'music', 'physcics', 
# 'plants', 'science', 'scientists', '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__             7043  fertile-mazurka         16,720,082  3e+13
animals              461  understood-anglerfish    1,094,414  2e+12
architecture         134  zenzeroth-burjalarab       318,116  5e+11
astronomy            124  lavish-magnetosphere       294,376  5e+11
biology              604  makeshift-endonuclease   1,433,896  2e+12
chemistry            255  rancid-sodium              605,370  1e+12
countries            182  brown-elsalvador           432,068  7e+11
computer_science     280  abandoned-token            664,720  1e+12
food                 217  uninterested-parmesan      515,158  9e+11
geography            186  espressivo-taiga           441,564  7e+11
history              162  tiresome-valhalla          384,588  6e+11
math                 158  brutal-geometry            375,092  6e+11
medicine             706  vocal-gastroenterology   1,676,044  3e+12
microbiology         103  formidable-koch            244,522  4e+11
misc                2823  male-possibility         6,701,802  1e+13
molecular_biology    118  jumbled-centriole          280,132  5e+11
music                202  visiting-mp3               479,548  8e+11
physics              145  developing-meter           344,230  6e+11
plants               178  fermented-grain            422,572  7e+11
science              745  patient-receptor         1,768,630  3e+12
scientists           101  electoral-ramanujan        239,774  4e+11
sports               191  neighbouring-tag           453,434  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:

basic-mortise
focused-berry
uncommon-broth
decisive-dentil
kingly-afforestation

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 adheres to Semantic Versioning with the format MAJOR.MINOR.PATCH:

• MAJOR version is incremented for significant codebase changes, such as new features or major reorganizations.
• MINOR version is incremented for category-related updates, like adding or modifying categories.
• PATCH version is incremented for bug fixes, improvements, or vocabulary expansions without category changes.

8. License

MIT License