| Name | unique-namer JSON |
| Version |
1.6.1
JSON |
| download |
| home_page | None |
| Summary | Generate unique, human-readable, and memorable names or identifiers |
| upload_time | 2024-08-13 11:51:29 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.6 |
| license | MIT License Copyright (c) 2024 Andrzej Zielezinski Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
random
unique
name
id
generate
namer
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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
1. [Categories](#1-categories)
2. [Requirements](#2-requirements)
3. [Installation](#3-installation)
4. [Using Without Installation](#4-using-without-installation)
5. [Usage](#5-usage)
1. [Generating Names](#51-generating-names)
2. [Customizing Names](#52-customizing-names)
3. [Getting Category List](#53-getting-category-list)
4. [Adding Custom Categories](#54-adding-custom-categories)
6. [Command-line Utility](#6-command-line-utility)
1. [Getting Statistics](#61-getting-statistics)
2. [Generating Names](#62-generating-names)
7. [Versioning](#7-versioning)
8. [Tests](#8-tests)
9. [License](#9-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.
<table>
<thead>
<tr>
<th rowspan="2">-</th>
<th rowspan="2">Category</th>
<th rowspan="2">Nouns count</th>
<th rowspan="2">Example name</th>
<th colspan="2">Possible combinations</th>
</tr>
<tr>
<th>Names</th>
<th>IDs (suffix 4)</th>
</tr>
</thead>
<tbody>
<tr>
<td></td>
<td>__all__</td>
<td>8,199</td>
<td><code>awful-deadline</code></td>
<td>17,250,696</td>
<td>10<sup>13</sup></td>
</tr>
<tr>
<td>:frog:</td>
<td>animals</td>
<td>461</td>
<td><code>tan-octopus</code></td>
<td>969,944</td>
<td>10<sup>12</sup></td>
</tr>
<tr>
<td>:department_store:</td>
<td>architecture</td>
<td>134</td>
<td><code>blowing-facade</code></td>
<td>281,936</td>
<td>10<sup>11</sup></td>
</tr>
<tr>
<td>:art:</td>
<td>art</td>
<td>177</td>
<td><code>nonchalant-picasso</code></td>
<td>372,408</td>
<td>10<sup>11</sup></td>
</tr>
<tr>
<td>:telescope:</td>
<td>astronomy</td>
<td>124</td>
<td><code>ruthless-meteoroid</code></td>
<td>260,896</td>
<td>10<sup>11</sup></td>
</tr>
<tr>
<td>:four_leaf_clover:</td>
<td>biology</td>
<td>730</td>
<td><code>shiny-centriole</code></td>
<td>1,535,920</td>
<td>10<sup>12</sup></td>
</tr>
<tr>
<td>:test_tube:</td>
<td>chemistry</td>
<td>255</td>
<td><code>junior-peroxide</code></td>
<td>536,520</td>
<td>10<sup>11</sup></td>
</tr>
<tr>
<td>:us:</td>
<td>countries</td>
<td>182</td>
<td><code>satisfying-tanzania</code></td>
<td>382,928</td>
<td>10<sup>11</sup></td>
</tr>
<tr>
<td>:computer:</td>
<td>computer_science</td>
<td>334</td>
<td><code>funny-malware</code></td>
<td>702,736</td>
<td>10<sup>12</sup></td>
</tr>
<tr>
<td>:moneybag:</td>
<td>economy</td>
<td>175</td>
<td><code>flowery-income</code></td>
<td>368,200</td>
<td>10<sup>11</sup></td>
</tr>
<tr>
<td>:hamburger:</td>
<td>food</td>
<td>217</td>
<td><code>pretty-waffle</code></td>
<td>456,568</td>
<td>10<sup>11</sup></td>
</tr>
<tr>
<td>:earth_americas:</td>
<td>geography</td>
<td>185</td>
<td><code>enjoyed-tsunami</code></td>
<td>389,240</td>
<td>10<sup>11</sup></td>
</tr>
<tr>
<td>:star:</td>
<td><b>general</b></td>
<td>5,476</td>
<td><code>curvy-flight</code></td>
<td>11,521,504</td>
<td>10<sup>13</sup></td>
</tr>
<tr>
<td>:european_castle:</td>
<td>history</td>
<td>156</td>
<td><code>cool-epoch</code></td>
<td>328,224</td>
<td>10<sup>11</sup></td>
</tr>
<tr>
<td>:books:</td>
<td>literature</td>
<td>587</td>
<td><code>winning-limerick</code></td>
<td>1,235,048</td>
<td>10<sup>12</sup></td>
</tr>
<tr>
<td>:triangular_ruler:</td>
<td>math</td>
<td>157</td>
<td><code>peachy-prime</code></td>
<td>330,328</td>
<td>10<sup>11</sup></td>
</tr>
<tr>
<td>:hospital:</td>
<td>medicine</td>
<td>706</td>
<td><code>curly-diarrhea</code></td>
<td>1,485,424</td>
<td>10<sup>12</sup></td>
</tr>
<tr>
<td>:bug:</td>
<td>microbiology</td>
<td>130</td>
<td><code>crazy-bacteria</code></td>
<td>273,520</td>
<td>10<sup>11</sup></td>
</tr>
<tr>
<td>:microscope:</td>
<td>molecular_biology</td>
<td>220</td>
<td><code>retired-oligonucleotide</code></td>
<td>462,880</td>
<td>10<sup>11</sup></td>
</tr>
<tr>
<td>:musical_note:</td>
<td>music</td>
<td>203</td>
<td><code>solid-contrabassoon</code></td>
<td>427,112</td>
<td>10<sup>11</sup></td>
</tr>
<tr>
<td>:atom:</td>
<td>physics</td>
<td>147</td>
<td><code>terrible-pressure</code></td>
<td>309,288</td>
<td>10<sup>11</sup></td>
</tr>
<tr>
<td>:sunflower:</td>
<td>plants</td>
<td>178</td>
<td><code>anonymous-cactus</code></td>
<td>374,512</td>
<td>10<sup>11</sup></td>
</tr>
<tr>
<td>:electron:</td>
<td>science</td>
<td>876</td>
<td><code>golden-hertz</code></td>
<td>1,843,104</td>
<td>10<sup>12</sup></td>
</tr>
<tr>
<td>:technologist:</td>
<td>scientists</td>
<td>101</td>
<td><code>gifted-newton</code></td>
<td>212,504</td>
<td>10<sup>11</sup></td>
</tr>
<tr>
<td>:basketball:</td>
<td>sports</td>
<td>191</td>
<td><code>intergalactic-olympics</code></td>
<td>401,864</td>
<td>10<sup>11</sup></td>
</tr>
<tr>
<td>:satellite:</td>
<td>technology</td>
<td>228</td>
<td><code>awesome-drone</code></td>
<td>479,712</td>
<td>10<sup>11</sup></td>
</tr>
</tbody>
</table>
## 2. Requirements
* Python version 3.6 or higher
* No external dependencies are required
## 3. Installation
Install `unique-namer` from [PyPI](https://pypi.org/project/unique-namer/):
```bash
pip install unique-namer
```
Alternatively, you can install the latest version directly from GitHub:
```bash
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:
```bash
git clone https://github.com/aziele/unique-namer.git
cd unique-namer/src/
```
You can import `namer` in Python:
```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:
```bash
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.
```python
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.
```python
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__`.
```python
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`).
```python
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.
```python
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.
```python
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:
```python
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.
```python
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.
```python
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.
```bash
namer -h
```
or
```bash
python -m namer -h
```
### 6.1. Getting statistics
The `stats` command prints a table with name/ID statitics for each category.
```bash
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
```bash
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
```bash
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
[MIT License](https://choosealicense.com/licenses/mit/)
Raw data
{
"_id": null,
"home_page": null,
"name": "unique-namer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "random, unique, name, id, generate, namer",
"author": null,
"author_email": "Andrzej Zielezinski <a.zielezinski@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/04/47/26e9f45b64ad2d7c77eefb48a0e84ae0c0070fa812bf6ab95584559ce53c/unique_namer-1.6.1.tar.gz",
"platform": null,
"description": "# unique-namer\n\n\n\n\n\n\nA 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.\n\nThe 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.\n\n### Features\n\n* Over 17 million unique names\n* Nearly infinite unique identifiers\n* 25 categories\n* Customizable names and categories\n\n## Table of contents\n\n1. [Categories](#1-categories)\n2. [Requirements](#2-requirements)\n3. [Installation](#3-installation)\n4. [Using Without Installation](#4-using-without-installation)\n5. [Usage](#5-usage)\n 1. [Generating Names](#51-generating-names)\n 2. [Customizing Names](#52-customizing-names)\n 3. [Getting Category List](#53-getting-category-list)\n 4. [Adding Custom Categories](#54-adding-custom-categories)\n6. [Command-line Utility](#6-command-line-utility)\n 1. [Getting Statistics](#61-getting-statistics)\n 2. [Generating Names](#62-generating-names)\n7. [Versioning](#7-versioning)\n8. [Tests](#8-tests)\n9. [License](#9-license)\n\n## 1. Categories\n\nCategories 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.\n\n<table>\n <thead>\n <tr>\n <th rowspan=\"2\">-</th>\n <th rowspan=\"2\">Category</th>\n <th rowspan=\"2\">Nouns count</th>\n <th rowspan=\"2\">Example name</th>\n <th colspan=\"2\">Possible combinations</th>\n </tr>\n <tr>\n <th>Names</th>\n <th>IDs (suffix 4)</th>\n </tr>\n </thead>\n <tbody>\n <tr>\n <td></td>\n <td>__all__</td>\n <td>8,199</td>\n <td><code>awful-deadline</code></td>\n <td>17,250,696</td>\n <td>10<sup>13</sup></td>\n </tr>\n <tr>\n <td>:frog:</td>\n <td>animals</td>\n <td>461</td>\n <td><code>tan-octopus</code></td>\n <td>969,944</td>\n <td>10<sup>12</sup></td>\n </tr>\n <tr>\n <td>:department_store:</td>\n <td>architecture</td>\n <td>134</td>\n <td><code>blowing-facade</code></td>\n <td>281,936</td>\n <td>10<sup>11</sup></td>\n </tr>\n <tr>\n <td>:art:</td>\n <td>art</td>\n <td>177</td>\n <td><code>nonchalant-picasso</code></td>\n <td>372,408</td>\n <td>10<sup>11</sup></td>\n </tr>\n <tr>\n <td>:telescope:</td>\n <td>astronomy</td>\n <td>124</td>\n <td><code>ruthless-meteoroid</code></td>\n <td>260,896</td>\n <td>10<sup>11</sup></td>\n </tr>\n <tr>\n <td>:four_leaf_clover:</td>\n <td>biology</td>\n <td>730</td>\n <td><code>shiny-centriole</code></td>\n <td>1,535,920</td>\n <td>10<sup>12</sup></td>\n </tr>\n <tr>\n <td>:test_tube:</td>\n <td>chemistry</td>\n <td>255</td>\n <td><code>junior-peroxide</code></td>\n <td>536,520</td>\n <td>10<sup>11</sup></td>\n </tr>\n <tr>\n <td>:us:</td>\n <td>countries</td>\n <td>182</td>\n <td><code>satisfying-tanzania</code></td>\n <td>382,928</td>\n <td>10<sup>11</sup></td>\n </tr>\n <tr>\n <td>:computer:</td>\n <td>computer_science</td>\n <td>334</td>\n <td><code>funny-malware</code></td>\n <td>702,736</td>\n <td>10<sup>12</sup></td>\n </tr>\n <tr>\n <td>:moneybag:</td>\n <td>economy</td>\n <td>175</td>\n <td><code>flowery-income</code></td>\n <td>368,200</td>\n <td>10<sup>11</sup></td>\n </tr>\n <tr>\n <td>:hamburger:</td>\n <td>food</td>\n <td>217</td>\n <td><code>pretty-waffle</code></td>\n <td>456,568</td>\n <td>10<sup>11</sup></td>\n </tr>\n <tr>\n <td>:earth_americas:</td>\n <td>geography</td>\n <td>185</td>\n <td><code>enjoyed-tsunami</code></td>\n <td>389,240</td>\n <td>10<sup>11</sup></td>\n </tr>\n <tr>\n <td>:star:</td>\n <td><b>general</b></td>\n <td>5,476</td>\n <td><code>curvy-flight</code></td>\n <td>11,521,504</td>\n <td>10<sup>13</sup></td>\n </tr>\n <tr>\n <td>:european_castle:</td>\n <td>history</td>\n <td>156</td>\n <td><code>cool-epoch</code></td>\n <td>328,224</td>\n <td>10<sup>11</sup></td>\n </tr>\n <tr>\n <td>:books:</td>\n <td>literature</td>\n <td>587</td>\n <td><code>winning-limerick</code></td>\n <td>1,235,048</td>\n <td>10<sup>12</sup></td>\n </tr>\n <tr>\n <td>:triangular_ruler:</td>\n <td>math</td>\n <td>157</td>\n <td><code>peachy-prime</code></td>\n <td>330,328</td>\n <td>10<sup>11</sup></td>\n </tr>\n <tr>\n <td>:hospital:</td>\n <td>medicine</td>\n <td>706</td>\n <td><code>curly-diarrhea</code></td>\n <td>1,485,424</td>\n <td>10<sup>12</sup></td>\n </tr>\n <tr>\n <td>:bug:</td>\n <td>microbiology</td>\n <td>130</td>\n <td><code>crazy-bacteria</code></td>\n <td>273,520</td>\n <td>10<sup>11</sup></td>\n </tr>\n <tr>\n <td>:microscope:</td>\n <td>molecular_biology</td>\n <td>220</td>\n <td><code>retired-oligonucleotide</code></td>\n <td>462,880</td>\n <td>10<sup>11</sup></td>\n </tr>\n <tr>\n <td>:musical_note:</td>\n <td>music</td>\n <td>203</td>\n <td><code>solid-contrabassoon</code></td>\n <td>427,112</td>\n <td>10<sup>11</sup></td>\n </tr>\n <tr>\n <td>:atom:</td>\n <td>physics</td>\n <td>147</td>\n <td><code>terrible-pressure</code></td>\n <td>309,288</td>\n <td>10<sup>11</sup></td>\n </tr>\n <tr>\n <td>:sunflower:</td>\n <td>plants</td>\n <td>178</td>\n <td><code>anonymous-cactus</code></td>\n <td>374,512</td>\n <td>10<sup>11</sup></td>\n </tr>\n <tr>\n <td>:electron:</td>\n <td>science</td>\n <td>876</td>\n <td><code>golden-hertz</code></td>\n <td>1,843,104</td>\n <td>10<sup>12</sup></td>\n </tr>\n <tr>\n <td>:technologist:</td>\n <td>scientists</td>\n <td>101</td>\n <td><code>gifted-newton</code></td>\n <td>212,504</td>\n <td>10<sup>11</sup></td>\n </tr>\n <tr>\n <td>:basketball:</td>\n <td>sports</td>\n <td>191</td>\n <td><code>intergalactic-olympics</code></td>\n <td>401,864</td>\n <td>10<sup>11</sup></td>\n </tr>\n <tr>\n <td>:satellite:</td>\n <td>technology</td>\n <td>228</td>\n <td><code>awesome-drone</code></td>\n <td>479,712</td>\n <td>10<sup>11</sup></td>\n </tr>\n </tbody>\n</table>\n\n## 2. Requirements\n\n* Python version 3.6 or higher\n* No external dependencies are required\n\n## 3. Installation\n\nInstall `unique-namer` from [PyPI](https://pypi.org/project/unique-namer/):\n\n```bash\npip install unique-namer\n```\n\nAlternatively, you can install the latest version directly from GitHub:\n\n```bash\npip install \"git+https://github.com/aziele/unique-namer.git\"\n```\n\n## 4. Using without installation\n\nIf you prefer to use `unique-namer` without installation, you can clone or download the repository:\n\n```bash\ngit clone https://github.com/aziele/unique-namer.git\ncd unique-namer/src/\n```\n\nYou can import `namer` in Python:\n\n```python\npython\n>>> import namer\n>>> namer.__doc__\n'Generate unique, human-readable, and memorable names or identifiers'\n```\n\nYou can also use `unique-namer` as a command-line tool:\n\n```bash\npython -m namer\n```\n\n## 5. Usage\n\n### 5.1. Generating names\n\nThe `generate` function returns a string with a randomly generated name consisting of an adjective and a noun.\n\n```python\nimport namer\n\nname = namer.generate()\nprint(name) # Example: 'blushy-cyclist'\n```\n\n#### `category` - str or list, default is `general`\n\nThe `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.\n\n```python\nimport namer\n\nname = namer.generate(category='astronomy')\nprint(name) # Example: 'crazy-supernova' \n\nname = namer.generate(category=['physics', 'biology'])\nprint(name) # Example: 'pink-bacteria'\n```\n\nTo use all available categories, set the `category` argument to `__all__`.\n\n```python\nimport namer\n\nname = namer.generate(category='__all__')\nprint(name) # Example: 'lonely-momentum'\n\n```\n\n#### `suffix_length` - int, default is `0`\n\nAdds 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`).\n\n```python\nimport namer\n\nname = namer.generate(category='history', suffix_length=3)\nprint(name) # Example: 'annoying-cleopatra-9a1'\n```\n\n#### `separator` - str, default is `'-'`\n\nSpecifies the separator to use between the adjective, noun, and suffix in the generated name.\n\n```python\nimport namer\n\nname = namer.generate(category='sports', separator='_')\nprint(name) # Example: 'savage_judo'\n```\n\n#### `style` - str, one of `title`, `lowercase`, `uppercase`\n\nSpecifies the text case format of the generated name.\n\n```python\nimport namer\n\nname = namer.generate(suffix_length=5, style='uppercase')\nprint(name) # Example: 'DAMAGED-ELECTRON-J20ZX'\n\nname = namer.generate(separator=' ', style='title')\nprint(name) # Example: 'Lazy Unicorn'\n```\n\n### 5.2. Customizing names\n\nTo 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.\n\nHere's an example:\n\n```python\nimport namer\n\n# Generate name components\nname_components, separator = _generate(category='food', suffix_length=3)\nprint(name_components) # Example: ['macho', 'pizza', '7dx']\n\n# Create custom generate function\ndef my_generate(*args, **kwargs):\n name_components, separator = namer_generate(*args, **kwargs)\n name_components.insert(0, '2024')\n return separator.join(name_components)\n\nname = my_generate(category='food', suffix_length=3)\nprint(name) # Example: 2024-macho-pizza-7dx\n```\n\n### 5.3. Getting category list\n\nYou can retrieve the list of available categories using the `list_categories` function.\n\n```python\nimport namer\n\nprint(namer.list_categories())\n# ['animals', 'architecture', ..., 'sports', 'technology']\n```\n\n### 5.4. Adding custom categories\n\nTo 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.\n\n```python\nimport namer\n\n# Create two subcategories.\nmy_dogs = ['charlie', 'bella', 'biga']\nmy_cats = ['tommy', 'lucy']\n\n# Add a custom category named 'my_pets' containing both dogs and cats\nnamer.data.categories['my_pets'] = [my_dogs, my_cats]\n\n# Generate a name from the 'my_pets' category\nname = namer.generate(category='pets')\nprint(name) # Example: 'thankful-tommy'\n```\n\n\n## 6. Command-line utility\n\nThe tool is available as a command-line utility.\n\n```bash\nnamer -h\n```\n\nor \n\n```bash\npython -m namer -h\n```\n\n### 6.1. Getting statistics\n\nThe `stats` command prints a table with name/ID statitics for each category.\n\n```bash\nnamer stats\n```\n\nOutput:\n\n```\nCategory Nouns Example Name_combs ID_combs (4-char suffix)\n__all__ 8199 gabby-moscovium 17,250,696 3e+13\nanimals 461 ready-deer 969,944 2e+12\narchitecture 134 foolish-courtyard 281,936 5e+11\nart 177 lonely-focal 372,408 6e+11\nastronomy 124 brawny-neutrino 260,896 4e+11\nbiology 730 bewildered-genetics 1,535,920 3e+12\nchemistry 255 gray-manganese 536,520 9e+11\ncountries 182 accessible-ghana 382,928 6e+11\ncomputer_science 334 numerous-ip 702,736 1e+12\neconomy 175 exultant-globaltrade 368,200 6e+11\nfood 217 weird-pudding 456,568 8e+11\ngeography 185 insulated-oasis 389,240 7e+11\ngeneral 5476 inexpensive-poem 11,521,504 2e+13\nhistory 156 trashy-lincoln 328,224 6e+11\nliterature 587 testy-motif 1,235,048 2e+12\nmath 157 figurative-thales 330,328 6e+11\nmedicine 706 labored-tarsus 1,485,424 2e+12\nmicrobiology 130 correct-microbiota 273,520 5e+11\nmolecular_biology 220 undisturbed-chromosome 462,880 8e+11\nmusic 203 flaky-raga 427,112 7e+11\nphysics 147 muffled-aperture 309,288 5e+11\nplants 178 uncommon-echinacea 374,512 6e+11\nscience 876 worldwide-ionosphere 1,843,104 3e+12\nscientists 101 staking-maxwell 212,504 4e+11\nsports 191 retail-race 401,864 7e+11\ntechnology 228 demonic-digitalization 479,712 8e+11\n```\n\n## 6.2. Generating names\n\nThe `generate` command creates a list of names or IDs based on specified parameters.\n\n### Example 1: Generating 5 names\n\n```bash\nnamer generate 5\n```\n\nOutput:\n\n```\ntelling-adrenaline\ninfinite-gonad\nclose-span\nbloody-blow\npuffy-biology\n```\n\n### Example 2: Generating 10 IDs with custom parameters\n\nTo 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\n\n```bash\nnamer generate 10 --category physics --category biology --suffix_length 3 -- \\\nseparator _ --style title\n```\n\nOutput:\n\n```\nVisiting_Haploid_Eep\nEventual_Refraction_Cnr\nSnugly_Monod_Sim\nCruel_Codon_46p\nRelieved_Decibel_Cn5\nUnderground_Bug_7wf\nSuper_Acre_30r\nGuttural_Farad_E1w\nLead_Stalk_Fi4\nFormidable_Field_621\n```\n\n## 7. Versioning\n\nThe package follows Semantic Versioning with the format `MAJOR.MINOR.PATCH`:\n\n* **MAJOR version**: significant changes (e.g., new features, major code reorganizations).\n* **MINOR version**: category-related updates (e.g., adding/moving categories).\n* **PATCH version**: bug fixes or vocabulary expansions without changing the list of categories.\n\n## 8. Tests\n\nTo ensure that unique-namer works as expected, you can run tests using pytest.\n\n```\npytest tests\n```\n\n## 9. License\n\n[MIT License](https://choosealicense.com/licenses/mit/)\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2024 Andrzej Zielezinski Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "Generate unique, human-readable, and memorable names or identifiers",
"version": "1.6.1",
"project_urls": {
"Homepage": "https://github.com/aziele/unique-namer"
},
"split_keywords": [
"random",
" unique",
" name",
" id",
" generate",
" namer"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fb72e06078006bbc3635490b872e8647294cf5921f378634de43520012b7c09e",
"md5": "05aab05e53a07303bba6d84189cf763a",
"sha256": "6e76751c0886244625b43a8e5e7c18168a9205f5a944c0dbbbd9eb219c4812f2"
},
"downloads": -1,
"filename": "unique_namer-1.6.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "05aab05e53a07303bba6d84189cf763a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 71111,
"upload_time": "2024-08-13T11:51:26",
"upload_time_iso_8601": "2024-08-13T11:51:26.920625Z",
"url": "https://files.pythonhosted.org/packages/fb/72/e06078006bbc3635490b872e8647294cf5921f378634de43520012b7c09e/unique_namer-1.6.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "044726e9f45b64ad2d7c77eefb48a0e84ae0c0070fa812bf6ab95584559ce53c",
"md5": "6a6c52f9b9653441e2ab8e329f2d95ea",
"sha256": "7f4e3143f923c24baaed56bb93726e10669333271caa71ffd5d8f1a928a5befe"
},
"downloads": -1,
"filename": "unique_namer-1.6.1.tar.gz",
"has_sig": false,
"md5_digest": "6a6c52f9b9653441e2ab8e329f2d95ea",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 73334,
"upload_time": "2024-08-13T11:51:29",
"upload_time_iso_8601": "2024-08-13T11:51:29.085808Z",
"url": "https://files.pythonhosted.org/packages/04/47/26e9f45b64ad2d7c77eefb48a0e84ae0c0070fa812bf6ab95584559ce53c/unique_namer-1.6.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-13 11:51:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aziele",
"github_project": "unique-namer",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "unique-namer"
}
