unique-namer 1.1.0

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

• Nearly 10 million unique names
• Nearly infinite unique identifiers
• Ideal for naming temporary directories, user session IDs, gamer tags, project names, 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__	4188	awful-deadline	9,929,748	1013
:chipmunk:	animals	450	tan-octopus	1,066,950	1012
:department_store:	architecture	130	blowing-facade	308,230	1011
:telescope:	astronomy	124	ruthless-meteoroid	294,004	1011
:four_leaf_clover:	biology	585	shiny-centriole	1,387,035	1012
:test_tube:	chemistry	127	junior-peroxide	301,117	1011
:us:	countries	182	satisfying-tanzania	431,522	1011
:computer:	computer_science	277	funny-malware	656,767	1012
:hamburger:	food	167	pretty-waffle	395,957	1011
:earth_americas:	geography	182	enjoyed-tsunami	431,522	1011
:european_castle:	history	149	cool-epoch	353,279	1011
:triangular_ruler:	math	146	peachy-prime	346,166	1011
:hospital:	medicine	679	curly-diarrhea	1,609,909	1012
:bug:	microbiology	102	crazy-bacteria	241,842	1011
:gun:	misc	353	curvy-flight	836,963	1012
:microscope:	molecular_biology	117	retired-oligonucleotide	277,407	1011
:musical_note:	music	182	solid-contrabassoon	431,522	1011
:atom:	physics	135	terrible-pressure	320,085	1011
:sunflower:	plants	162	anonymous-cactus	384,102	1011
:books:	science	605	golden-hertz	1,434,455	1012
:technologist:	scientists	101	gifted-newton	239,471	1011
:basketball:	sports	123	intergalactic-olympics	291,633	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 customize generated names for specific project requirements (e.g., adding date or project name), use the _generate function. This function returns a Python list of name components, which you can modify and format into a string name.

import namer

# Generate name components
name_components = _generate(category='food', suffix_length=3)
print(name_components)   # Example: ['macho', 'pizza', '7dx']

# Create custom generate function
def my_generate(*args, separator='_', **kwargs):
    name_components = 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__             4188  arid_decomposition       9,929,748  2e+13
animals              450  spotty_swallow           1,066,950  2e+12
architecture         130  southern_triglyph          308,230  5e+11
astronomy            124  frayed_sirius              294,004  5e+11
biology              585  swarm_stanley            1,387,035  2e+12
chemistry            127  minimal_autoionization     301,117  5e+11
countries            182  agreed_afghanistan         431,522  7e+11
computer_science     277  abrasive_language          656,767  1e+12
food                 167  complete_ice               395,957  7e+11
geography            182  agricultural_world         431,522  7e+11
history              149  sunset_expedition          353,279  6e+11
math                 146  wilful_mapping             346,166  6e+11
medicine             679  protective_foreskin      1,609,909  3e+12
microbiology         102  fast_transmission          241,842  4e+11
misc                 353  earthy_canteen             836,963  1e+12
molecular_biology    117  acyclic_codon              277,407  5e+11
music                182  genteel_adagio             431,522  7e+11
physics              135  outrageous_conductor       320,085  5e+11
plants               162  dapper_peony               384,102  6e+11
science              605  full_koch                1,434,455  2e+12
scientists           101  urgent_planck              239,471  4e+11
sports               123  satisfactory_swim          291,633  5e+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