unique-namer 0.9.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	touched-kilometer	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 output: '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 output: 'crazy-supernova'                 

name = namer.generate(category=['physics', 'molecular_biology'])
print(name)   # Example output: '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 output: '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 output: 'savage_judo'

style - str, one of capitalize, lowercase, uppercase

import namer

name = namer.generate(suffix_length=5, style='uppercase')
print(name)   # Example output: 'DAMAGED-ELECTRON-J20ZX'

name = namer.generate(separator=' ', style='capitalize')
print(name)   # Example output: 'Lazy Unicorn'

5.2. Customizing names

To tailor generated names to specific project requirements (e.g., adding date or project name), you can use the _generate function. This function returns a Python list of name components, which you can modify and format them into a string name.

import namer

name_parts = _generate(category='food', suffix_length=3)
print(name_parts)   # Example output: ['macho', 'pizza', '7dx']

# Create your own generate function
def my_generate(*args, separator='_', **kwargs):
    name_parts = namer_generate(*args, **kwargs)
    name_parts.insert(0, '2024')
    return separator.join(name_parts)

name = my_generate(category='food', suffix_length=3)
print(name)         # Example output: 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

You might want to provide your custom categories to use for generating unique names/IDs, in order to meet your project requirements. You can easily add your own categories by extending 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 output: 'devout-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 (suffix 4)
__all__             3150  associative_radian             7,465,500  1e+13
animals              450  pure_sheep                     1,066,500  2e+12
architecture         130  dapper_corbel                    308,100  5e+11
astronomy            124  dying_relativity                 293,880  5e+11
biology              832  braised_escherichia            1,971,840  3e+12
chemistry            127  compassionate_thermodynamics     300,990  5e+11
countries            182  arid_luxembourg                  431,340  7e+11
computer_science     277  strong_programmer                656,490  1e+12
food                 167  fluttering_stew                  395,790  7e+11
geography            183  moaning_glacier                  433,710  7e+11
history              149  inventive_chronicle              353,130  6e+11
math                 146  buoyant_involute                 346,020  6e+11
microbiology         101  chivalrous_microbiologist        239,370  4e+11
misc                 355  dying_compressor                 841,350  1e+12
molecular_biology    118  rapid_exonuclease                279,660  5e+11
music                182  fried_allegro                    431,340  7e+11
physics              135  abhorrent_quark                  319,950  5e+11
plants               163  coffee_cantaloupe                386,310  6e+11
science              605  hanging_momentum               1,433,850  2e+12
scientists           101  equivalent_bernoulli             239,370  4e+11
sports               123  acrid_javelin                    291,510  5e+11

6.2. Generating names

The generate command allows for creating customized lists 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 categories such as physics and biology, with a random suffix length of 3 characters, using _ as a separator, and converting to capitals:

namer generate 10 --category physics --category biology --suffix_length 3 -- \
separator _ --style capitalize

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