Generate unique, human-readable, and memorable names or identifiers
Project description
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 17 million unique names
- Nearly infinite unique identifiers
- 25 categories
- Customizable names and categories
Table of contents
- Categories
- Requirements
- Installation
- Using Without Installation
- Usage
- Command-line Utility
- Versioning
- Tests
- 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,199 | awful-deadline |
17,250,696 | 1013 | |
:frog: | animals | 461 | tan-octopus |
969,944 | 1012 |
:department_store: | architecture | 134 | blowing-facade |
281,936 | 1011 |
:art: | art | 177 | nonchalant-picasso |
372,408 | 1011 |
:telescope: | astronomy | 124 | ruthless-meteoroid |
260,896 | 1011 |
:four_leaf_clover: | biology | 730 | shiny-centriole |
1,535,920 | 1012 |
:test_tube: | chemistry | 255 | junior-peroxide |
536,520 | 1011 |
:us: | countries | 182 | satisfying-tanzania |
382,928 | 1011 |
:computer: | computer_science | 334 | funny-malware |
702,736 | 1012 |
:moneybag: | economy | 175 | flowery-income |
368,200 | 1011 |
:hamburger: | food | 217 | pretty-waffle |
456,568 | 1011 |
:earth_americas: | geography | 185 | enjoyed-tsunami |
389,240 | 1011 |
:star: | general | 5,476 | curvy-flight |
11,521,504 | 1013 |
:european_castle: | history | 156 | cool-epoch |
328,224 | 1011 |
:books: | literature | 587 | winning-limerick |
1,235,048 | 1012 |
:triangular_ruler: | math | 157 | peachy-prime |
330,328 | 1011 |
:hospital: | medicine | 706 | curly-diarrhea |
1,485,424 | 1012 |
:bug: | microbiology | 130 | crazy-bacteria |
273,520 | 1011 |
:microscope: | molecular_biology | 220 | retired-oligonucleotide |
462,880 | 1011 |
:musical_note: | music | 203 | solid-contrabassoon |
427,112 | 1011 |
:atom: | physics | 147 | terrible-pressure |
309,288 | 1011 |
:sunflower: | plants | 178 | anonymous-cactus |
374,512 | 1011 |
:electron: | science | 876 | golden-hertz |
1,843,104 | 1012 |
:technologist: | scientists | 101 | gifted-newton |
212,504 | 1011 |
:basketball: | sports | 191 | intergalactic-olympics |
401,864 | 1011 |
:satellite: | technology | 228 | awesome-drone |
479,712 | 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', 'technology']
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__ 8199 gabby-moscovium 17,250,696 3e+13
animals 461 ready-deer 969,944 2e+12
architecture 134 foolish-courtyard 281,936 5e+11
art 177 lonely-focal 372,408 6e+11
astronomy 124 brawny-neutrino 260,896 4e+11
biology 730 bewildered-genetics 1,535,920 3e+12
chemistry 255 gray-manganese 536,520 9e+11
countries 182 accessible-ghana 382,928 6e+11
computer_science 334 numerous-ip 702,736 1e+12
economy 175 exultant-globaltrade 368,200 6e+11
food 217 weird-pudding 456,568 8e+11
geography 185 insulated-oasis 389,240 7e+11
general 5476 inexpensive-poem 11,521,504 2e+13
history 156 trashy-lincoln 328,224 6e+11
literature 587 testy-motif 1,235,048 2e+12
math 157 figurative-thales 330,328 6e+11
medicine 706 labored-tarsus 1,485,424 2e+12
microbiology 130 correct-microbiota 273,520 5e+11
molecular_biology 220 undisturbed-chromosome 462,880 8e+11
music 203 flaky-raga 427,112 7e+11
physics 147 muffled-aperture 309,288 5e+11
plants 178 uncommon-echinacea 374,512 6e+11
science 876 worldwide-ionosphere 1,843,104 3e+12
scientists 101 staking-maxwell 212,504 4e+11
sports 191 retail-race 401,864 7e+11
technology 228 demonic-digitalization 479,712 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:
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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for unique_namer-1.6.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6e76751c0886244625b43a8e5e7c18168a9205f5a944c0dbbbd9eb219c4812f2 |
|
MD5 | 05aab05e53a07303bba6d84189cf763a |
|
BLAKE2b-256 | fb72e06078006bbc3635490b872e8647294cf5921f378634de43520012b7c09e |