### Install coolname

Source: https://coolname.readthedocs.io/en/latest/index.html

Install the package via pip.

```bash
pip install coolname
```

--------------------------------

### Initialize RandomGenerator with Custom Config

Source: https://coolname.readthedocs.io/en/latest/randomization.html

This example demonstrates how to initialize a 'RandomGenerator' with a custom configuration, defining different lists and types of word sources for name generation.

```python
config = {
    'all': {
        'type': 'cartesian',
        'lists': ['price', 'color', 'object']
    },
    # 2 items
    'price': {
        'type': 'words',
        'words': ['cheap', 'expensive']
    },
    # 3 items
    'color': {
        'type': 'words',
        'words': ['black', 'white', 'red']
    },
    # 5 + 6 = 11 items
    'object': {
        'type': 'nested',
        'lists': ['footwear', 'hat']
    },
    # 5 items
    'footwear': {
        'type': 'words',
        'words': ['shoes', 'boots', 'sandals', 'sneakers', 'socks']
    },
    # 6 items
    'hat': {
        'type': 'phrases',
        'phrases': ['top hat', 'fedora', 'beret', 'cricket cap', 'panama', 'sombrero']
    }
}
import coolname
generator = coolname.RandomGenerator(config)
```

--------------------------------

### Words List Rule Example

Source: https://coolname.readthedocs.io/en/latest/_sources/customization.rst.txt

Example of a 'words' type rule for generating random colors, tastes, or fruits from predefined lists with equal probability.

```python
# This will produce random color
'color': {
    'type': 'words',
    'words': ['red', 'green', 'yellow']
},
# This will produce random taste
'taste': {
    'type': 'words',
    'words': ['sweet', 'sour']
},
# This will produce random fruit
'fruit': {
    'type': 'words',
    'words': ['apple', 'banana']
}
```

--------------------------------

### Constant Rule Example

Source: https://coolname.readthedocs.io/en/latest/_sources/customization.rst.txt

Example of a 'const' type rule, used for fixed values like prepositions.

```python
'of': {
    'type': 'const',
    'value': 'of'
}
```

--------------------------------

### Apply Hard max_length Constraint

Source: https://coolname.readthedocs.io/en/latest/customization.html

Example of a configuration that fails because a word exceeds the defined max_length.

```python
{
    "all": {
        "type": "words",
        "words": ["cat", "tiger", "jaguar"],
        "max_length": 5
    }
}
```

--------------------------------

### Nested List Rule Example

Source: https://coolname.readthedocs.io/en/latest/_sources/customization.rst.txt

Example of a 'nested' type rule that chooses a random element from child lists. Probability is proportional to the child list's length.

```python
# This will produce random adjective: color or taste
'adjective': {
    'type': 'nested',
    'lists': ['color', 'taste']
}
```

--------------------------------

### Apply Soft max_slug_length Constraint

Source: https://coolname.readthedocs.io/en/latest/customization.html

Example where combinations exceeding the max_slug_length are discarded during generation.

```python
{
    "adjective": {
        "type": "words",
        "words": ["red", "blue", "green"]
    },
    "noun": {
        "type": "words",
        "words": ["line", "square", "circle"]
    },
    "all": {
        "type": "cartesian",
        "lists": ["adjective", "noun"],
        "max_slug_length": 11
    }
}
```

--------------------------------

### Set environment variables from Python before import

Source: https://coolname.readthedocs.io/en/latest/environment-variables.html

If setting environment variables from within Python code, ensure it is done before importing the coolname library. This example shows how to set COOLNAME_DATA_MODULE and then import generate_slug.

```python
import os
os.environ['COOLNAME_DATA_MODULE'] = 'some.module'
from coolname import generate_slug
```

--------------------------------

### Cartesian List Rule Example

Source: https://coolname.readthedocs.io/en/latest/_sources/customization.rst.txt

Example of a 'cartesian' type rule that generates a list by picking one item from each specified child list. This functions like a slot machine.

```python
# This will produce a random list of 4 words,
# for example: ['my', 'banana', 'is', 'sweet']
'all': {
    'type': 'cartesian',
    'lists': ['my', 'fruit', 'is', 'adjective']
},
# Additional const definitions
'is': {
    'type': 'const',
    'value': 'is'
},
'my': {
    'type': 'const',
    'value': 'my'
}
```

--------------------------------

### PyInstaller Runtime Error Example

Source: https://coolname.readthedocs.io/en/latest/_sources/pyinstaller.rst.txt

This traceback indicates a ModuleNotFoundError for 'coolname.data', which occurs when PyInstaller does not correctly package the necessary data files for the coolname library. Ensure the module is explicitly included.

```bash
Traceback (most recent call last):
  File "myscript.py", line 1, in <module>
    from coolname import generate_slug
  File "pyimod02_importers.py", line 457, in exec_module
  File "coolname/__init__.py", line 7, in <module>
  File "pyimod02_importers.py", line 457, in exec_module
  File "coolname/impl.py", line 639, in <module>
  File "coolname/impl.py", line 631, in _create_default_generator
  File "importlib/__init__.py", line 88, in import_module
ModuleNotFoundError: No module named 'coolname.data'
[PYI-12311:ERROR] Failed to execute script 'myscript' due to unhandled exception!
```

--------------------------------

### Get combination counts

Source: https://coolname.readthedocs.io/en/latest/index.html

Retrieve the total number of possible combinations for a specific word count.

```python
>>> from coolname import get_combinations_count
>>> get_combinations_count(4)
83377588406
```

--------------------------------

### Load configuration from directory

Source: https://coolname.readthedocs.io/en/latest/customization.html

Use load_config to import rules from a directory structure.

```python
>>> from coolname.loader import load_config
>>> config = load_config('./my_config')
```

--------------------------------

### External configuration files

Source: https://coolname.readthedocs.io/en/latest/customization.html

Split configuration into a JSON file and separate text files for word lists.

```json
{
    "all": {
        "type": "cartesian",
        "lists": ["adjective", "noun"]
    }
}
```

```text
crouching
hidden
```

```text
dragon
tiger
```

--------------------------------

### Initialize and Use RandomGenerator

Source: https://coolname.readthedocs.io/en/latest/customization.html

Instantiate the generator with a configuration and produce random slugs.

```python
>>> from coolname import RandomGenerator
>>> generator = RandomGenerator(config)
>>> for i in range(3):
...     print(generator.generate_slug())
...
my-banana-is-sweet
my-apple-is-green
my-apple-is-sour
```

--------------------------------

### Verify loaded configuration

Source: https://coolname.readthedocs.io/en/latest/customization.html

Inspect the loaded configuration object and generate a slug.

```python
>>> config
{'adjective': {'words': ['crouching', 'hidden'], 'type': 'words'}, 'noun': {'words': ['dragon', 'tiger'], 'type': 'words'}, 'all': {'lists': ['adjective', 'noun'], 'type': 'cartesian'}}
>>> g = RandomGenerator(config)
>>> g.generate_slug()
'hidden-tiger'
```

--------------------------------

### Load Configuration from Directory

Source: https://coolname.readthedocs.io/en/latest/_sources/customization.rst.txt

Using load_config to aggregate a JSON config file and separate text files into a single configuration object.

```json
{
    "all": {
        "type": "cartesian",
        "lists": ["adjective", "noun"]
    }
}
```

```text
crouching
hidden
```

```text
dragon
tiger
```

```python
>>> from coolname.loader import load_config
>>> config = load_config('./my_config')
```

```python
>>> config
{'adjective': {'words': ['crouching', 'hidden'], 'type': 'words'}, 'noun': {'words': ['dragon', 'tiger'], 'type': 'words'}, 'all': {'lists': ['adjective', 'noun'], 'type': 'cartesian'}}
>>> g = RandomGenerator(config)
>>> g.generate_slug()
'hidden-tiger'
```

--------------------------------

### Use coolname via command line

Source: https://coolname.readthedocs.io/en/latest/index.html

Generate names directly from the terminal with custom word counts and separators.

```bash
$ coolname
prophetic-tireless-bullfrog-of-novelty
$ coolname 3 -n 2 -s '_'
wildebeest_of_original_champagne
ara_of_imminent_luck
```

--------------------------------

### Define Configuration Rules Structure

Source: https://coolname.readthedocs.io/en/latest/customization.html

The base structure for a configuration dictionary where 'all' is the mandatory root rule.

```python
{
    '<rule_id>': {
        'comment': 'Some info about this rule. Not mandatory.',
        'type': '<nested|cartesian|words|phrases|const>',
        # additional fields, depending on type
    },
    ...
}
```

--------------------------------

### Equivalent configuration dictionary

Source: https://coolname.readthedocs.io/en/latest/customization.html

The JSON representation of a word file with a max_length option.

```json
{
    'type': 'words',
    'words': ['one', 'two', 'three'],
    'max_length': 13
}
```

--------------------------------

### Initialize RandomGenerator with dictionary

Source: https://coolname.readthedocs.io/en/latest/customization.html

Directly pass a configuration dictionary to the RandomGenerator constructor.

```python
>>> from coolname import RandomGenerator
>>> config = {'all': {'type': 'cartesian', 'lists': ['adjective', 'noun']}, 'adjective': {'type':'words', 'words':['crouching','hidden']}, 'noun': {'type': 'words', 'words': ['tiger', 'dragon']}}
>>> g = RandomGenerator(config)
>>> g.generate_slug()
'hidden-dragon'
```

--------------------------------

### Text file format for words

Source: https://coolname.readthedocs.io/en/latest/customization.html

Basic text file format supporting comments and configuration options.

```text
# comment
one
two  # inline comment

# blank lines are OK
three
```

```text
max_length = 13
```

--------------------------------

### Define simple pattern

Source: https://coolname.readthedocs.io/en/latest/customization.html

A basic pattern definition using pipe-separated alternatives.

```text
(crouching|hidden) (tiger|dragon)
```

--------------------------------

### coolname.generate

Source: https://coolname.readthedocs.io/en/latest/classes-and-functions.html

Generates a random sequence of strings.

```APIDOC
## coolname.generate(pattern=None)

### Description
Returns a random sequence as a list of strings.

### Parameters
#### Query Parameters
- **pattern** (int) - Optional - Can be 2, 3 or 4.

### Response
- **Return type** (list of strings) - A list containing the generated random strings.
```

--------------------------------

### Generate name sequences

Source: https://coolname.readthedocs.io/en/latest/index.html

Generate names as lists of words or formatted strings.

```python
>>> from coolname import generate
>>> generate()
['beneficial', 'bronze', 'bee', 'of', 'glee']
>>> ' '.join(generate())
'limber transparent toad of luck'
>>> ''.join(x.capitalize() for x in generate())
'CalmRefreshingTerrierOfAttraction'
```

--------------------------------

### Create custom generators

Source: https://coolname.readthedocs.io/en/latest/index.html

Define custom rules and word lists using the RandomGenerator class.

```python
>>> from coolname import RandomGenerator
>>> generator = RandomGenerator({
...   'all': {
...     'type': 'cartesian',
...     'lists': ['first_name', 'last_name']
...   },
...   'first_name': {
...     'type': 'words',
...     'words': ['james', 'john']
...   },
...   'last_name': {
...     'type': 'words',
...     'words': ['smith', 'brown']
...   }
... })
>>> generator.generate_slug()
'james-brown'
```

--------------------------------

### Custom Generator Class

Source: https://coolname.readthedocs.io/en/latest/_sources/classes-and-functions.rst.txt

Details on how to use the `RandomGenerator` class for custom configurations.

```APIDOC
## Custom generators

### `RandomGenerator(config, random=None)`

Custom generator class.

### Method
POST

### Endpoint
/custom-generator

### Parameters
#### Request Body
- **config** (dict) - Required - Custom configuration dictionary.
- **random** (random.Random instance) - Optional - A :class:`random.Random` instance. If not provided, :func:`random.randrange` will be used.

### Request Example
```json
{
  "config": {"key": "value"},
  "random": "<random_instance_representation>"
}
```

### Response
#### Success Response (200)
- **message** (str) - Confirmation message.

### Response Example
```json
{
  "message": "Custom generator configured successfully."
}
```

## Custom generators

### `RandomGenerator.generate(pattern=None)`

Returns a random sequence as a list of strings using the custom generator.

### Method
GET

### Endpoint
/custom-generator/generate

### Parameters
#### Query Parameters
- **pattern** (any) - Optional - Not applicable by default. Can be configured.

### Response
#### Success Response (200)
- **result** (list of strings) - A list of strings representing the random sequence.

### Response Example
```json
{
  "result": ["custom_word1", "custom_word2"]
}
```

## Custom generators

### `RandomGenerator.generate_slug(pattern=None)`

Same as :meth:`generate`, but returns a slug as a string using the custom generator.

### Method
GET

### Endpoint
/custom-generator/generate-slug

### Parameters
#### Query Parameters
- **pattern** (any) - Optional - Not applicable by default. Can be configured.

### Response
#### Success Response (200)
- **result** (str) - A string representing the random custom slug.

### Response Example
```json
{
  "result": "custom-word1-custom-word2"
}
```

## Custom generators

### `RandomGenerator.get_combinations_count(pattern=None)`

Returns the number of possible combinations using the custom generator.

### Method
GET

### Endpoint
/custom-generator/combinations-count

### Parameters
#### Query Parameters
- **pattern** (any) - Optional - Not applicable by default. Can be configured.

### Response
#### Success Response (200)
- **count** (int) - The total number of possible combinations.

### Response Example
```json
{
  "count": 500
}
```
```

--------------------------------

### Text file format for phrases

Source: https://coolname.readthedocs.io/en/latest/customization.html

Files containing multi-word lines are automatically treated as phrase lists.

```text
one
two

# Here is the phrase
three four
```

--------------------------------

### Include coolname.data with PyInstaller

Source: https://coolname.readthedocs.io/en/latest/_sources/pyinstaller.rst.txt

When creating an executable with PyInstaller, use the --hidden-import flag to specify the coolname.data module. This prevents runtime errors related to missing modules.

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

--------------------------------

### Configure generator via Python environment variables

Source: https://coolname.readthedocs.io/en/latest/_sources/environment-variables.rst.txt

Set environment variables within Python code before importing the library to ensure the custom generator is initialized correctly.

```python
os.environ['COOLNAME_DATA_MODULE'] = 'some.module'
from coolname import generate_slug
```

--------------------------------

### coolname.get_combinations_count

Source: https://coolname.readthedocs.io/en/latest/classes-and-functions.html

Calculates the number of possible combinations.

```APIDOC
## coolname.get_combinations_count(pattern=None)

### Description
Returns the total number of possible combinations based on the pattern.

### Parameters
#### Query Parameters
- **pattern** (int) - Optional - Can be 2, 3 or 4.

### Response
- **Return type** (int) - The count of possible combinations.
```

--------------------------------

### Set environment variables for Coolname

Source: https://coolname.readthedocs.io/en/latest/environment-variables.html

Use these export commands in your shell to specify a custom data directory or module for the Coolname generator.

```bash
export COOLNAME_DATA_DIR=some/path
export COOLNAME_DATA_MODULE=some.module
```

--------------------------------

### Apply max_length to Phrases

Source: https://coolname.readthedocs.io/en/latest/customization.html

Demonstrates that spaces are not counted when applying max_length to phrase lists.

```python
{
    "all": {
        "type": "phrases",
        "phrases": ["big cat"],
        "max_length": 6
    }
}
```

--------------------------------

### Generate slugs with Django compatibility

Source: https://coolname.readthedocs.io/en/latest/index.html

Generate a single slug string ready for use in web applications.

```python
>>> from coolname import generate_slug
>>> generate_slug()
'qualified-agama-of-absolute-kindness'
```

--------------------------------

### coolname.generate_slug

Source: https://coolname.readthedocs.io/en/latest/classes-and-functions.html

Generates a random slug string.

```APIDOC
## coolname.generate_slug(pattern=None)

### Description
Returns a random sequence as a slug string.

### Parameters
#### Query Parameters
- **pattern** (int) - Optional - Can be 2, 3 or 4.

### Response
- **Return type** (str) - The generated slug string.
```

--------------------------------

### coolname.RandomGenerator

Source: https://coolname.readthedocs.io/en/latest/classes-and-functions.html

Class for creating custom random generators.

```APIDOC
## class coolname.RandomGenerator(config, random=None)

### Description
Initializes a custom generator with specific configuration.

### Parameters
- **config** (dict) - Required - Custom configuration dictionary.
- **random** (random.Random) - Optional - A random.Random instance.
```

--------------------------------

### Define Constant Rule

Source: https://coolname.readthedocs.io/en/latest/customization.html

Defines a static value, useful for prepositions or fixed connectors.

```python
'of': {
    'type': 'const',
    'value': 'of'
},
```

--------------------------------

### Generated phrase rule

Source: https://coolname.readthedocs.io/en/latest/customization.html

The resulting rule structure for the provided phrase file.

```json
{
    "type": "phrases",
    "phrases": [
        ["one"], ["two"], ["three", "four"]
    ]
}
```

--------------------------------

### Default Generator Functions

Source: https://coolname.readthedocs.io/en/latest/_sources/classes-and-functions.rst.txt

Functions for generating random sequences, slugs, and combination counts using the default generator.

```APIDOC
## Default generator

### `generate(pattern=None)`

Returns a random sequence as a list of strings.

### Method
GET

### Endpoint
/generate

### Parameters
#### Query Parameters
- **pattern** (int) - Optional - Can be 2, 3 or 4.

### Response
#### Success Response (200)
- **result** (list of strings) - A list of strings representing the random sequence.

### Response Example
```json
{
  "result": ["word1", "word2", "word3"]
}
```

## Default generator

### `generate_slug(pattern=None)`

Same as :func:`generate`, but returns a slug as a string.

### Method
GET

### Endpoint
/generate-slug

### Parameters
#### Query Parameters
- **pattern** (int) - Optional - Can be 2, 3 or 4.

### Response
#### Success Response (200)
- **result** (str) - A string representing the random slug.

### Response Example
```json
{
  "result": "word1-word2-word3"
}
```

## Default generator

### `get_combinations_count(pattern=None)`

Returns the number of possible combinations.

### Method
GET

### Endpoint
/combinations-count

### Parameters
#### Query Parameters
- **pattern** (int) - Optional - Can be 2, 3 or 4.

### Response
#### Success Response (200)
- **count** (int) - The total number of possible combinations.

### Response Example
```json
{
  "count": 1000
}
```

## Default generator

### `replace_random(random)`

Replaces the random number generator. It doesn't affect custom generators.

### Method
POST

### Endpoint
/replace-random

### Parameters
#### Request Body
- **random** (random.Random instance) - Required - The new random number generator instance.

### Request Example
```json
{
  "random": "<random_instance_representation>"
}
```

### Response
#### Success Response (200)
- **message** (str) - Confirmation message.

### Response Example
```json
{
  "message": "Random number generator replaced successfully."
}
```
```

--------------------------------

### Define Phrases List Rule

Source: https://coolname.readthedocs.io/en/latest/customization.html

Selects a random phrase, where phrases can be strings or lists of words.

```python
# This will produce random color
'color': {
    'type': 'phrases',
    'words': ['red', 'green', 'navy blue', ['royal', 'purple']]
}
```

--------------------------------

### Generate deterministic slugs with coolname-hash

Source: https://coolname.readthedocs.io/en/latest/_sources/deterministic-pseudohash.rst.txt

Uses the pseudohash_slug function to generate consistent slugs from various input types. Note that duplicates may occur even with a small number of items.

```python
>>> from coolname_hash import pseudohash_slug
>>> pseudohash_slug(123)
'hissing-sage-buzzard-of-faith'
>>> pseudohash_slug('qwerty')
'jumping-kickass-bumblebee-of-chaos'
>>> pseudohash_slug('\x00\x01\xFF')
'smooth-offbeat-hummingbird-from-avalon'
```

--------------------------------

### Generate random slugs

Source: https://coolname.readthedocs.io/en/latest/index.html

Use generate_slug to create random, human-readable strings suitable for URLs or identifiers.

```python
>>> from coolname import generate_slug
>>> generate_slug()
'tiny-optimal-crocodile-of-progress'
>>> generate_slug()
'cherubic-leopard-of-delightful-serendipity'
>>> generate_slug()
'wealthy-athletic-swift-of-tempest'
```

--------------------------------

### Specify hidden import with PyInstaller

Source: https://coolname.readthedocs.io/en/latest/pyinstaller.html

When creating an executable with PyInstaller, explicitly specify the 'coolname.data' module using the --hidden-import flag to ensure it's included in the package.

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

```

--------------------------------

### Define Words List Rule

Source: https://coolname.readthedocs.io/en/latest/customization.html

Selects a random word from a list with equal probability.

```python
# This will produce random color
'color': {
    'type': 'words',
    'words': ['red', 'green', 'yellow']
},
# This will produce random taste
'taste': {
    'type': 'words',
    'words': ['sweet', 'sour']
},
# This will produce random fruit
'fruit': {
    'type': 'words',
    'words': ['apple', 'banana']
},
```

--------------------------------

### Replace Random Generator for Instances

Source: https://coolname.readthedocs.io/en/latest/randomization.html

To use a custom random number generator for specific 'RandomGenerator' instances, pass an instance of 'random.Random' initialized with a seed to the constructor.

```python
from coolname import RandomGenerator
import random, os
seed = os.urandom(128)
generator = RandomGenerator(config, random=random.Random(seed))
```

--------------------------------

### Enforce word count constraint

Source: https://coolname.readthedocs.io/en/latest/customization.html

Use the number_of_words parameter to restrict the length of phrases. This constraint is strictly enforced during RandomGenerator initialization.

```json
{
    "all": {
        "type": "phrases",
        "phrases": [
            "washing machine",
            "microwave oven",
            "vacuum cleaner",
            "large hadron collider"
        ],
        "number_of_words": 2
    }
}
```

--------------------------------

### Generate names of specific length

Source: https://coolname.readthedocs.io/en/latest/index.html

Specify the number of words (2, 3, or 4) for the generated slug.

```python
>>> generate_slug(2)
'mottled-crab'
>>> generate_slug(3)
'fantastic-acoustic-whale'
>>> generate_slug(4)
'military-diamond-tuatara-of-endeavor'
```

--------------------------------

### PyInstaller runtime error: ModuleNotFoundError

Source: https://coolname.readthedocs.io/en/latest/pyinstaller.html

This traceback indicates a 'ModuleNotFoundError: No module named 'coolname.data'' which occurs when PyInstaller fails to include necessary data modules for the coolname library. Ensure 'coolname.data' is correctly specified.

```python
Traceback (most recent call last):
  File "myscript.py", line 1, in <module>
    from coolname import generate_slug
  File "pyimod02_importers.py", line 457, in exec_module
  File "coolname/__init__.py", line 7, in <module>
  File "pyimod02_importers.py", line 457, in exec_module
  File "coolname/impl.py", line 639, in <module>
  File "coolname/impl.py", line 631, in _create_default_generator
  File "importlib/__init__.py", line 88, in import_module
ModuleNotFoundError: No module named 'coolname.data'
[PYI-12311:ERROR] Failed to execute script 'myscript' due to unhandled exception!

```

--------------------------------

### Replace Random Generator Globally

Source: https://coolname.readthedocs.io/en/latest/randomization.html

To replace the random number generator used by 'coolname.generate()' and 'coolname.generate_slug()' globally, use the 'coolname.replace_random()' function with a seeded 'random.Random' instance.

```python
import coolname
import random, os
seed = os.urandom(128)
coolname.replace_random(random.Random(seed))
```

--------------------------------

### Re-seed Default Random Generator

Source: https://coolname.readthedocs.io/en/latest/randomization.html

To re-seed the default random number generator used by the standard 'random' module, call 'random.seed()' with a source of randomness like 'os.urandom(128)'.

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

--------------------------------

### Define Nested List Rule

Source: https://coolname.readthedocs.io/en/latest/customization.html

Chooses a random element from child lists with probability proportional to list length.

```python
# This will produce random adjective: color or taste
'adjective': {
    'type': 'nested',
    'lists': ['color', 'taste']
},
```

--------------------------------

### Define Cartesian List Rule

Source: https://coolname.readthedocs.io/en/latest/customization.html

Combines elements from multiple child lists to produce a sequence.

```python
# This will produce a random list of 4 words,
# for example: ['my', 'banana', 'is', 'sweet']
'all': {
    'type': 'cartesian',
    'lists': ['my', 'fruit', 'is', 'adjective']
},
# Additional const definitions
'is': {
    'type': 'const',
    'value': 'is'
},
'my': {
    'type': 'const',
    'value': 'my'
},
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.