python-slugify

python-slugify converts arbitrary unicode text into URL- and filename-safe slugs, transliterating accented and non-Latin characters via text-unidecode (or the optional Unidecode backend), decoding HTML entities and numeric character references, and applying configurable rules for separators, max length, stopword removal, and word-boundary-safe truncation. It ships both as an importable slugify() function and as a small CLI (python -m slugify) for one-off shell usage.

What You Get

• A slugify(text, ...) function with keyword options for separator, max_length, word_boundary, stopwords, lowercase, and custom replacements
• Unicode transliteration via text-unidecode by default, or the more complete (GPL-licensed) Unidecode package as an opt-in extra
• HTML entity, decimal, and hexadecimal character-reference decoding before slugification
• A CLI entry point (python -m slugify) exposing every library option as a flag, including --stdin for piping text
• allow_unicode mode for producing IDN-style slugs that keep non-Latin characters instead of transliterating them

Common Use Cases

• Generating SEO-friendly, human-readable URL slugs from article or product titles in a CMS or e-commerce backend
• Producing safe filenames from user-supplied titles or metadata before writing to a filesystem or object store
• Normalizing free-text tags or categories in Django/Flask apps for use as lookup keys or route segments
• One-off shell scripting where a title or filename needs to be sanitized without writing custom Python code

Under The Hood

Architecture: the entire library lives in one small package, slugify/, with slugify.py (197 lines) implementing the core transformation pipeline — entity/decimal/hex decoding, transliteration dispatch, regex-based character filtering, then separator joining and truncation — and a thin __main__.py (98 lines) wrapping the same function behind an argparse CLI. Tech Stack: pure Python 3.10+, with a single runtime dependency (text-unidecode) and an optional Unidecode extra installed via pip install python-slugify[unidecode]; packaged with a classic setup.py plus pyproject.toml. Code Quality: a single 657-line test.py exercises the full option matrix (entities, stopwords, max_length, word_boundary, custom replacements, unicode passthrough) with plain unittest-style assertions; the codebase has no type-checked internals beyond function signatures, but its narrow scope keeps it easy to audit end to end. API Design: the single-function API (slugify(text, **options)) is close to zero-boilerplate for the common case, and every option has a sane default, so most callers need only slugify(my_title); the CLI mirrors the same options as flags, which keeps the two interfaces consistent rather than diverging.