coolname 3.0.0
Random name and slug generator
License: BSD
Keywords: coolname

==============================
Random Name and Slug Generator
==============================

|pypi| |build| |coverage| |docs|

Do you want random human-readable strings?

.. code-block:: python

    >>> from coolname import generate_slug
    >>> generate_slug()
    'big-maize-loris-of-renovation'
    >>> generate_slug()
    'tunneling-amaranth-rhino-of-holiness'
    >>> generate_slug()
    'soft-cuddly-shrew-of-expertise'

Features
========

* Generate slugs, ready to use, Django-compatible.

    .. code-block:: python

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

* Generate names as sequences and do whatever you want with them.

    .. code-block:: 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'

* Generate names of specific length: 2, 3 or 4 words.

    .. code-block:: python

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

    *Note: without argument, it returns a random length, but probability of 4‑word name is much higher.*
    *Prepositions and articles (of, from, the) are not counted as words.*

* Use in command line:

    .. code-block:: bash

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

* Over 10\ :sup:`10`\  random names.

    ===== ============== =======================================
    Words Combinations   Example
    ===== ============== =======================================
    4     10\ :sup:`10`\ ``talented-enigmatic-bee-of-hurricane``
    3     10\ :sup:`8`\  ``ambitious-turaco-of-joviality``
    2     10\ :sup:`5`\  ``prudent-armadillo``
    ===== ============== =======================================

    .. code-block:: python

        >>> from coolname import get_combinations_count
        >>> get_combinations_count(4)
        64175336926

* Hand-picked vocabulary. ``sexy`` and ``demonic`` are about the most "offensive" words here -
  but there is only a pinch of them, for spice. Most words are either neutral, such as ``red``, or positive,
  such as ``brave``. And subject is always some animal, bird, fish, or insect - you can't be more neutral than
  Mother Nature.

* `Easy customization <http://coolname.readthedocs.io/en/latest/customization.html>`_. Create your own rules!

    .. code-block:: 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'

Installation
============

.. code-block:: bash

    pip install coolname

**coolname** is written in pure Python and has no dependencies. It works on any modern Python version (3.7+), including PyPy.


.. |pypi| image:: https://img.shields.io/pypi/v/coolname.svg
    :target: https://pypi.python.org/pypi/coolname
    :alt: pypi

.. |build| image:: https://github.com/alexanderlukanin13/coolname/actions/workflows/ci.yml/badge.svg?branch=master
    :target: https://github.com/alexanderlukanin13/coolname/actions/workflows/ci.yml
    :alt: build status

.. |coverage| image:: https://coveralls.io/repos/alexanderlukanin13/coolname/badge.svg?branch=master&service=github
    :target: https://coveralls.io/github/alexanderlukanin13/coolname?branch=master
    :alt: coverage

.. |docs| image:: https://img.shields.io/readthedocs/coolname.svg
    :target: http://coolname.readthedocs.io/en/latest/
    :alt: documentation




Release history
===============

3.0.0 (2026-01-29)
------------------

* **Breaking change:** Python 3.6 is not supported anymore. Tests cover Python 3.7-3.14 and PyPy 3.7-3.11.

* Better type hints (now checked with mypy)

* Minor bug fixed, concerning abnormal configs (most likely didn't affect anyone)

* More mythical animals + one mistake fixed + few other words

2.2.0 (2023-01-09)
------------------

* More dogs, cats and cows!

2.1.0 (2022-12-07)
------------------

* Support OpenSSL FIPS by using ``hashlib.md5(..., usedforsecurity=False)``

2.0.0 (2022-10-24)
------------------

* Support for old Python versions (<3.5) is dropped, because it's 2022

* Command line usage and pipx support.

* With additional owls and bitterns

1.1.0 (2018-08-02)
------------------

* 32-bit Python is supported.

1.0.4 (2018-02-17)
------------------

* **Breaking changes:**

    - Renamed ``RandomNameGenerator`` to ``RandomGenerator``.

    - ``randomize`` was removed, because it was just an alias to ``random.seed``.

* `Phrase lists <https://coolname.readthedocs.io/en/latest/customization.html#phrases-list>`_
  give you even more freedom when creating custom generators.

* You can seed or even replace the underlying ``random.Random`` instance, see
  `Randomization <https://coolname.readthedocs.io/en/latest/randomization.html>`_.

* Change the default generator using ``COOLNAME_DATA_DIR`` and ``COOLNAME_DATA_MODULE``. This also saves memory!

* Total number of combinations = 60 billions.


For earlier releases, see `History <https://coolname.readthedocs.io/en/latest/history.html>`_