names_generator

Clone of the Moby/Docker random name generator as a Python package.

Installation

$ pip install names_generator

Or, with uv:

$ uv add names_generator

Usage

Python API

The API only really consists of a single function.

>>> from names_generator import generate_name
>>> generate_name()
'vigorous_goldstine'

Customize the formatting of the name by specifying a style, one of plain, capital, hyphen, or underscore (default).

>>> generate_name(style='capital')
'Hardcore Thompson'

Pin a seed value for the underlying PRNG to reproduce a given name. A seed is applied to a dedicated PRNG instance, so it never disturbs the global random state on your behalf.

>>> generate_name(seed=42) == generate_name(seed=42)
True

Note that a seed only guarantees reproducibility within a given release. Whenever the underlying name listings change to stay in sync with upstream, some seeds will map to a different name.

Command-line

The package also exposes a basic command-line interface for scripting outside of Python

$ names-generator
clever_matsumoto

$ names-generator --style=capital
Heuristic Einstein

$ names-generator --help
Usage:
  names-generator [-h] [-v] [--style NAME]
  Generate random name pairing.

Options:
  -s, --style    NAME    Formatting (default: underscore).
  -h, --help             Show this message and exit.
  -v, --version          Show the version and exit.

Documentation and issue tracking at:
https://github.com/glentner/names_generator

Because the command matches the distribution name, you can run it without installing anything:

$ uvx names-generator
clever_matsumoto

The command was originally installed as generate_name. That name is still installed and behaves identically, but names-generator is the canonical one and is what the documentation uses.

Development

This project uses uv.

$ uv sync
$ uv run pytest -v --cov

main is the only long-lived branch. Work happens on a branch taken from main and returns to it by pull request; main is protected and requires the test suite to pass, so it is never committed to directly. A release is a tag on main, which is what triggers publication to PyPI.

Upstream

The name listings in names_generator/names.py are a direct port of internal/namesgenerator from the Moby project, kept in the same order so the two can be diffed mechanically.

Upstream declared the listing frozen, so no new names are accepted here either. Changes to names.py are only made to bring this port back in sync with upstream.