slugsmith

Modern, zero-dependency Python library for generating URL-friendly slugs from Unicode text.

A drop-in replacement for python-slugify with built-in transliteration, no external dependencies, and full type annotations.

Installation

pip install slugsmith

Quick Start

from slugsmith import slugify

slugify("Hello World")          # "hello-world"
slugify("café latte")           # "cafe-latte"
slugify("Ελληνικά")             # "ellinika"
slugify("Привет мир")           # "privet-mir"
slugify("北京")                  # "bei-jing"

Features

• Zero dependencies — built-in Unicode→ASCII transliteration; no text-unidecode or Unidecode required
• Drop-in replacement for python-slugify — same slugify() signature
• Language-aware — language-specific mappings for German, Turkish, Polish, Czech, Finnish, Swedish
• Type-safe — full type annotations, PEP 561 compliant, passes mypy strict
• MIT licensed — no GPL dependency concerns

API Reference

slugify(text, **options) -> str

Generate a URL-friendly slug from text.

Returns an empty string if text is empty.

Examples

Separator and case

slugify("Hello World", separator="_")           # "hello_world"
slugify("Hello World", lowercase=False)         # "Hello-World"
slugify("Hello World", separator="")            # "helloworld"

Length limiting

slugify("the quick brown fox", max_length=15)               # "the-quick-brow"
slugify("the quick brown fox", max_length=15, word_boundary=True)  # "the-quick"

Stopwords

slugify("the quick brown fox", stopwords=("the",))   # "quick-brown-fox"

Replacements

slugify("C++ is great", replacements=[("++", "pp")])  # "cpp-is-great"
slugify("$100 deal", replacements=[("$", "dollar")])   # "dollar100-deal"

Unicode passthrough

slugify("café au lait", allow_unicode=True)   # "café-au-lait"
slugify("北京 city", allow_unicode=True)       # "北京-city"

Language-specific transliteration

slugify("Ü-bung", lang="de")    # "ue-bung"   (German: ü→ue, ö→oe, ä→ae)
slugify("çalış", lang="tr")     # "calis"     (Turkish: ç→c, ş→s)
slugify("łódź", lang="pl")      # "lodz"      (Polish: ł→l, ó→o, ź→z)
slugify("říjen", lang="cs")     # "rijen"     (Czech: ř→r, í→i)

Supported language codes: de (German), tr (Turkish), pl (Polish), cs (Czech), fi (Finnish), sv (Swedish).

Script coverage

slugsmith's built-in transliteration covers a wide range of Unicode scripts without any external dependencies:

Characters not covered by the table are decomposed via NFKD normalisation; if decomposition yields ASCII, that is used. Remaining non-ASCII characters are silently dropped (same behaviour as text-unidecode).

Custom regex

# Allow only alphanumeric and hyphens (strip underscores too)
slugify("hello_world foo", regex_pattern=r"[^a-z0-9-]")  # "helloworld-foo"

Migration from python-slugify

slugsmith is a drop-in replacement:

# Before
from slugify import slugify

# After
from slugsmith import slugify

The slugify() signature is identical. No other code changes are needed.

Behavioural differences:

License

MIT