coolname

You can control how words are validated using word_regex and allow_whitespace:

• word_regex: A regular expression used to validate all words. The default is r'\w+' (Unicode letters, numbers, and underscores).
• allow_whitespace: If set to True, word_regex is applied only to the non-whitespace parts of the word. You can include whitespace in your regex (e.g., [a-z ]+) or keep it simple (e.g., [a-z]+) if allow_whitespace is enabled.

Parameters in coolname operate under two distinct scopes, indicated by specific icons in the documentation:

• Configuration Scope (✅): These parameters act when a RandomGenerator is created. They are used to configure the generator or perform load-time validation. If validation fails during this phase, a ConfigurationError is raised.
• Runtime Scope (🚀): These parameters act during every call to RandomGenerator.generate() or RandomGenerator.generate_slug(). They are used to silently discard combinations that do not meet the specified criteria (e.g., ensuring uniqueness or length constraints).

When coolname initializes, it selects a generator based on the following precedence order:

1. COOLNAME_DATA_DIR: If defined, not empty, and the directory exists, it is used.
2. COOLNAME_DATA_MODULE: If COOLNAME_DATA_DIR is not applicable, but this is defined and not empty, the module is imported and used.
3. Default Generator: If neither of the above conditions are met, the built-in default generator is used.

This hierarchy is designed to support packaging in bundles like PyInstaller. For standard usage, using COOLNAME_DATA_DIR is generally recommended as text files are easier to maintain than Python modules.

When deciding how to generate entity slugs, choose based on your persistence requirements:

1. Persistent Storage (Standard): Use the core coolname package's generate_slug function. Since these are random, you must store the slug in your database and use a UNIQUE constraint on the column. You must also implement logic to check for duplicates and retry generation if a collision occurs.

2. Stateless/Deterministic (Pseudohash): Use the coolname-hash package's pseudohash_slug function if you need to derive the same slug from an entity ID every time without storing the slug itself. This is useful for lightweight, stateless applications, but you must still account for the possibility of duplicates.

When bundling an application into an executable using PyInstaller, you must explicitly include the coolname.data module. PyInstaller's analysis may fail to detect this dependency, leading to a ModuleNotFoundError: No module named 'coolname.data' at runtime.

You can resolve this by using the --hidden-import flag in your CLI command or by adding the module to your PyInstaller .spec file.

pyinstaller myscript.py --hidden-import coolname.data

If you need to generate the same slug for a specific entity every time without storing the slug in a database, use the coolname-hash package. The pseudohash_slug function accepts integers, strings, or byte sequences and returns a deterministic slug based on that input.

Warning: Just like random generation, this method can still produce duplicates, especially with a small number of items. Ensure your system can handle potential collisions.

from coolname_hash import pseudohash_slug

# Using an integer
pseudohash_slug(123)
# Returns: 'hissing-sage-buzzard-of-faith'

# Using a string
pseudohash_slug('qwerty')
# Returns: 'jumping-kickass-bumblebee-of-chaos'

# Using bytes
pseudohash_slug(b'\x00\x01\xFF')
# Returns: 'smooth-offbeat-hummingbird-from-avalon'

Install the coolname package using pip. The library is written in pure Python, has no dependencies, and supports Python 3.10+ and PyPy.

pip install coolname

You can replace the default coolname generator by setting one or both of the following environment variables. If either is set and not empty, the default generator is not created, which saves memory.

• COOLNAME_DATA_DIR: A path to a directory containing config.json and *.txt files.
• COOLNAME_DATA_MODULE: A Python module name that is importable and contains a config dictionary.

Important: If you are setting these variables within a Python script, you must set them using os.environ before importing coolname.

import os
# Set environment variables BEFORE importing coolname
os.environ['COOLNAME_DATA_MODULE'] = 'some.module'
from coolname import generate_slug

The coolname library uses the standard Python random module (specifically random.randrange) as its source of randomness. To re-seed the default generator used by the library, call random.seed directly. Note that coolname itself never calls random.seed.

import os, random
random.seed(os.urandom(128))