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
• Features
• Installation
• Usage
• API Reference
• Advanced Usage & Performance Tips
• Command-Line Interface (CLI)
• Development & Contributing
• Performance & Benchmarks
• License
• See Also

---

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:

1. Pre-stage replacements Apply replacement rules registered for the pre stage, before anything else touches the text.
2. decode_html_entities_and_refs(text) Decode named HTML entities (é) and decimal/hexadecimal character references.
3. normalize_unicode(text) Normalize to NFKD and strip combining marks, so Café becomes Cafe. Skipped for pure-ASCII input.
4. transliterate_text(text) Transliterate non-ASCII characters to ASCII where a mapping exists. Skipped for ASCII input, or when process_transliteration=False.
5. convert_emojis(text, separator) Replace emoji with their textual names. Requires the optional emoji extra and process_emoji=True (it is off by default).
6. 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.
7. extract_words(text, word_regex) Extract words using a customizable regex pattern.
8. filter_stopwords(words, stopwords, lowercase) Remove unwanted words (e.g. stopwords) from the list.
9. join_words(words, separator) Join words using the specified separator.
10. strip_separators(text, separator) Remove leading and trailing separators.
11. truncate_slug(text, max_length, word_boundary, separator) Optionally truncate the slug, at a word boundary by default.
12. 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'

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗