unique-namer 1.0.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

• Over 7 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__	3150	awful-deadline	7,465,500	1013
:chipmunk:	animals	450	tan-octopus	1,066,500	1012
:department_store:	architecture	130	blowing-facade	308,100	1011
:telescope:	astronomy	124	ruthless-meteoroid	293,880	1011
:four_leaf_clover:	biology	832	shiny-centriole	1,971,840	1012
:test_tube:	chemistry	127	junior-peroxide	300,990	1011
:us:	countries	182	satisfying-tanzania	431,340	1011
:computer:	computer_science	277	funny-malware	656,490	1012
:hamburger:	food	167	pretty-waffle	395,790	1011
:earth_americas:	geography	183	enjoyed-tsunami	433,710	1011
:european_castle:	history	149	cool-epoch	353,130	1011
:triangular_ruler:	math	146	peachy-prime	346,020	1011
:bug:	microbiology	101	crazy-bacteria	239,370	1011
:gun:	misc	355	curvy-flight	841,350	1012
:microscope:	molecular_biology	118	retired-oligonucleotide	279,660	1011
:musical_note:	music	182	solid-contrabassoon	431,340	1011
:atom:	physics	135	terrible-pressure	319,950	1011
:sunflower:	plants	163	anonymous-cactus	386,310	1011
:books:	science	605	golden-hertz	1,433,850	1012
:technologist:	scientists	101	gifted-newton	239,370	1011
:basketball:	sports	123	intergalactic-olympics	291,510	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', '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__             3150  balanced_koch             7,465,500  1e+13
animals              450  given_barnacle            1,066,500  2e+12
architecture         130  allied_pelmet               308,100  5e+11
astronomy            124  extended_micrometeoroid     293,880  5e+11
biology              832  grandiose_hibiscus        1,971,840  3e+12
chemistry            127  irate_electrolyte           300,990  5e+11
countries            182  missing_ghana               431,340  7e+11
computer_science     277  gnarly_query                656,490  1e+12
food                 167  promoted_eggs               395,790  7e+11
geography            183  dark_mortlake               433,710  7e+11
history              149  lucky_caesar                353,130  6e+11
math                 146  moderate_flag               346,020  6e+11
microbiology         101  stiff_beijerinck            239,370  4e+11
misc                 355  isochoric_mansion           841,350  1e+12
molecular_biology    118  stirred_enzyme              279,660  5e+11
music                182  innate_deanmartin           431,340  7e+11
physics              135  left_power                  319,950  5e+11
plants               163  ascent_bulb                 386,310  6e+11
science              605  smoked_astronaut          1,433,850  2e+12
scientists           101  jumbled_heisenberg          239,370  4e+11
sports               123  zealous_athlete             291,510  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