Classes and functions

Default generator

coolname.generate(pattern: str | int | None = None) → list[str]

Generates and returns random name as a list of strings.

Parameters:

pattern – In the default generator, can be 2, 3, 4. In a custom generator, can be any list with "generator": true.

coolname.generate_slug(pattern: str | int | None = None) → str

Generates and returns random name as a slug.

Parameters:

pattern – In the default generator, can be 2, 3, 4. In a custom generator, can be any list with "generator": true.

coolname.get_combinations_count(pattern: str | int | None = None) → int

Returns the total theoretical number of unique combinations.

Actual number is a bit smaller, because some combinations are rejected and never generated. Examples: good-good-dog, swift-swift.

Parameters:

pattern – Return the number of combinations for the given pattern only.

coolname.replace_random(rand: RandomT | None = None) → None

Replaces random number generator (RNG) for the default RandomGenerator instance. See random property.

Custom generators

class coolname.RandomGenerator(config: CoolnameConfigT, rand: RandomT | None = None)

This class provides random name generation interface.

Create an instance of this class if you want to create custom configuration. Config dictionary is described by type alias CoolnameConfigT.

generate(pattern: str | int | None = None) → list[str]

Generates and returns random name as a list of strings.

Parameters:

pattern – In the default generator, can be 2, 3, 4. In a custom generator, can be any list with "generator": true.

generate_slug(pattern: str | int | None = None) → str

Generates and returns random name as a slug.

Parameters:

pattern – In the default generator, can be 2, 3, 4. In a custom generator, can be any list with "generator": true.

get_combinations_count(pattern: str | int | None = None) → int

Returns the total theoretical number of unique combinations.

Actual number is a bit smaller, because some combinations are rejected and never generated. Examples: good-good-dog, swift-swift.

Parameters:

pattern – Return the number of combinations for the given pattern only.

property random: RandomT | None

Random-like random number generator (RNG) to be used by this instance.

By default, the default RNG is used. You can also use something else, as long as it supports RandomT protocol.

render(pattern: str | int | None = None, *, indent: str | int = 2, max_items: int = 4, ids: bool = False) → str

Returns the generator’s tree-like structure as text. This is mostly for debugging purposes.

Text representation is the same as in write(). Arguments are also the same.

WARNING: text representation format itself is not part of the API, and may be changed without notice in future versions.

write(stream: TextIO, pattern: str | int | None = None, *, indent: str | int = 2, max_items: int = 4, ids: bool = False) → None

Writes the generator’s tree-like structure into a text stream. This is mostly for debugging purposes.

Text representation is the same as in render(). Arguments are also the same.

WARNING: text representation format itself is not part of the API, and may be changed without notice in future versions.

Parameters:

  • stream – Output stream to write into

  • pattern – Optional - meaning the same as in generate()

  • indent – Single indentation: any number of spaces, a tab, or anything you want. If int, a number of spaces.

  • max_items – Maximum number of words or phrases to display. If there are more, the remaining items are replaced with ellipsis.

  • ids – If True, display Python id() for each object. Could be useful to check which word/phrase lists are reused in more than one place in the tree.

class coolname.InitializationError

Base exception class for all coolname initialization errors (configuration files are missing, file reading error, etc.)

class coolname.ConfigurationError

Subclass of InitializationError, raised when coolname configuration is invalid.

Configuration

These functions are primarily intended for development.

coolname.loader.load_config(path: str | Path) → CoolnameConfigT

Loads configuration from a path, returns CoolnameConfigT.

Parameters:

path – standalone JSON file, or a directory containing config.json and zero or more *.txt files with word lists or phrase lists.

Raises InitializationError if something goes wrong.

coolname.loader.filter_config(config: CoolnameConfigT, word_filter: Callable[[str], bool]) → None

Filter words and phrases according to predicate.

It can be used in customized RandomGenerator initialization, but mostly it’s for config manipulation at development time.

How it works:

  • Keep only words with word_filter(x) == True.

  • Keep only phrases with all(word_filter(x) for x in phrase).

  • Types and values are not checked - assuming config is valid.

  • Any list becoming empty after filtering is considered an error.

Raises InitializationError if something goes wrong. Unexpected exceptions or silent errors may occur if config is invalid.

coolname.loader.save_config_as_module(config: CoolnameConfigT, filename: str | Path) → None

Save configuration dictionary as Python module (*.py file).

Types and Protocols

In advanced custom setup, you can use following protocols and types for typing:

coolname.types.CoolnameConfigT

Whole configuration as a dictionary that is passed to RandomGenerator constructor.

alias of dict[str, dict[str, str | int | bool | list[str] | list[list[str]] | list[tuple[str, …]]]]

coolname.types.CoolnameConfigListT

Top-level values of config dict - that is, list configurations. For example:

{
    "comment": "adjective-adjective-noun",
    "type": "cartesian",
    "lists": ["adj_far", "adj_near", "subj"]
}

alias of dict[str, str | int | bool | list[str] | list[list[str]] | list[tuple[str, …]]]

class coolname.types.RandomT(*args, **kwargs)

Protocol for random module, used in RandomGenerator constructor and in RandomGenerator.random property.

Similar to random.Random, but only requires two methods: seed() and randrange().

You may need this in your code if you are using a Random object and it’s not a standard random.Random instance.

randrange(start: int, stop: int | None = None, step: int = 1, /) → int

Return a randomly selected element from range(start, stop, step).

See documentation for randrange().

seed(a: RandomSeedArgT = None, version: int = 2) → None

Re-seed the random number generator.

See documentation for seed().

coolname.types.RandomSeedArgT: TypeAlias = None | int | float | str | bytes | bytearray

Type alias used by seed().