sluggi
sluggi — A Python library and CLI for turning any text into clean, URL-safe slugs. 20,000 strings in 0.74 seconds on the included benchmark, no runtime dependencies.
Inspired by slugify, rebuilt for Unicode and parallel batch processing. The first box out of blipbox, where agents draft and an engineer signs every release.
Table of Contents
How sluggi is built
sluggi is the first box out of blipbox, the open-source software factory run by nimbous.
- AI coding agents draft the code, the tests, and the docs, in pull requests.
- Atilla Guzel reads every change before it merges. Every change arrives as a pull request with CI passing on Python 3.10 to 3.13; the branch rules are public.
- Every release is built and signed with Sigstore by the release workflow, published to PyPI, and carries the name of the engineer who signed it off in CHANGELOG.md.
Features
- 🚀 Fast: 20,000 strings in 0.74 s serial, 0.037 ms per slug, measured in June 2025 (see Performance & Benchmarks). No runtime dependencies.
- 🌍 Unicode: NFKD normalization for Latin diacritics, built-in transliteration for Greek and Cyrillic, custom mappings for anything else. Emoji become their names with the optional
emoji extra.
- 🔧 Customizable: Define your own character mappings and rules.
- 🧵 Parallel Batch: True multi-core batch slugification (thread/process/serial modes).
- ⚡ Async Support: Full asyncio-compatible API for modern Python apps.
- 🖥️ CLI Tool: Powerful, colorized CLI for quick slug generation and batch jobs.
- 🔒 Safe Output: Always generates URL-safe, predictable slugs.
- 🧩 Extensible API: Easy to use and extend.
- ✅ CI & Pre-commit: Linting, formatting, and tests run automatically.
Modular Slugification Pipeline
sluggi processes text through a modular pipeline of single-responsibility functions, making the codebase more readable, maintainable, and extensible. Each step in the pipeline performs a distinct transformation, allowing for easy customization and extension.
The steps below are the pipeline that SlugPipeline.default_pipeline() builds,
in the order they actually run.
Pipeline Steps:
- Pre-stage replacements
Apply replacement rules registered for the
pre stage, before anything else touches the text.
- decode_html_entities_and_refs(text)
Decode named HTML entities (
é) and decimal/hexadecimal character references.
- normalize_unicode(text)
Normalize to NFKD and strip combining marks, so
Café becomes Cafe. Skipped for pure-ASCII input.
- transliterate_text(text)
Transliterate non-ASCII characters to ASCII where a mapping exists. Skipped for ASCII input, or when
process_transliteration=False.
- convert_emojis(text, separator)
Replace emoji with their textual names. Requires the optional
emoji extra and process_emoji=True (it is off by default).
- to_lowercase(text)
Lowercase the text when
lowercase=True. Note this happens before words are extracted, so a custom word_regex sees text that is already lowercased.
- extract_words(text, word_regex)
Extract words using a customizable regex pattern.
- filter_stopwords(words, stopwords, lowercase)
Remove unwanted words (e.g. stopwords) from the list.
- join_words(words, separator)
Join words using the specified separator.
- strip_separators(text, separator)
Remove leading and trailing separators.
- truncate_slug(text, max_length, word_boundary, separator)
Optionally truncate the slug, at a word boundary by default.
- Post-stage replacements
Apply replacement rules registered for the
post stage, once the slug is otherwise final.
Processing Flow:
Input Text
↓
pre-stage replacements
↓
decode_html_entities_and_refs
↓
normalize_unicode
↓
transliterate_text
↓
convert_emojis
↓
to_lowercase
↓
extract_words
↓
filter_stopwords
↓
join_words
↓
strip_separators
↓
truncate_slug
↓
post-stage replacements
↓
Final Slug
A note on replacements
Replacements are staged, not a single step. A rule carries a stage of
"pre", "post", or "both", and the pipeline runs the matching rules at the
two points shown above.
The custom_map argument is converted with stage="both", so a custom mapping
is applied twice — once before normalization and once after the slug is
assembled. That is why a mapping can rewrite the separator, which only exists
after join_words:
>>> from sluggi import slugify
>>> slugify("hello world", custom_map={"-": "+"})
'hello+world'
This is the beginning of the README. Read the rest at the original. Read the full README ↗
