Python Slugify: Robust Unicode Slug Generation in Python

Introduction

Python Slugify is a robust and highly customizable Python library designed to convert strings, especially those containing Unicode characters, into clean, URL-friendly "slugs." A slug is a simplified version of a title or name, typically used in URLs, that contains only letters, numbers, and hyphens. This library excels at handling complex character sets, ensuring your web content has consistent and readable identifiers.

It makes a best effort to create slugs from unicode strings while keeping it DRY. By default, it uses text-unidecode for its decoding needs, but also offers an alternative with Unidecode for those who prefer it, which can be installed as python-slugify[unidecode]. For more details, visit the official GitHub repository.

Installation

Installing Python Slugify is straightforward using pip:

pip install python-slugify

If you prefer to use the Unidecode package for decoding, you can install it with the following command:

pip install python-slugify[unidecode]

Examples

Python Slugify provides a flexible slugify function with numerous options to tailor the output to your specific needs. Here are some common use cases:

Basic Usage:

from slugify import slugify

txt = "This is a test ---"
r = slugify(txt)
print(r)
# Output: this-is-a-test

Handling Unicode Characters:

txt = '???'
r = slugify(txt)
print(r)
# Output: ying-shi-ma

txt = 'C\'est déjà l\'été.'
r = slugify(txt)
print(r)
# Output: c-est-deja-l-ete

txt = 'Nín h?o. W? shì zh?ng guó rén'
r = slugify(txt)
print(r)
# Output: nin-hao-wo-shi-zhong-guo-ren

txt = '?????????'
r = slugify(txt)
print(r)
# Output: kompiuter

Allowing Unicode in Slugs:

txt = '???'
r = slugify(txt, allow_unicode=True)
print(r)
# Output: ???

Limiting Length and Word Boundaries:

txt = 'jaja---lol-méméméoo--a'
r = slugify(txt, max_length=9)
print(r)
# Output: jaja-lol

txt = 'jaja---lol-méméméoo--a'
r = slugify(txt, max_length=15, word_boundary=True)
print(r)
# Output: jaja-lol-a

Custom Separators and Stopwords:

txt = 'jaja---lol-méméméoo--a'
r = slugify(txt, max_length=20, word_boundary=True, separator=".")
print(r)
# Output: jaja.lol.mememeoo.a

txt = 'the quick brown fox jumps over the lazy dog'
r = slugify(txt, stopwords=['the'])
print(r)
# Output: quick-brown-fox-jumps-over-lazy-dog

Custom Replacements:

txt = '10 | 20 %'
r = slugify(txt, replacements=[['|', 'or'], ['%', 'percent']])
print(r)
# Output: 10-or-20-percent

For more examples and advanced usage, refer to the project's test file.

Why Use It

Python Slugify stands out for several reasons, making it an excellent choice for developers needing robust slug generation:

Comprehensive Unicode Support: It effectively handles a wide array of international characters, converting them into readable ASCII equivalents or preserving them if allow_unicode is set.
High Customizability: With options for max_length, word_boundary, separator, stopwords, regex_pattern, lowercase, and replacements, you have fine-grained control over the generated slugs.
Ease of Use: The slugify function is intuitive and simple to integrate into any Python project.
Command-Line Tool: A convenient command-line utility is included, allowing for quick slug generation directly from your terminal.
Active Maintenance: The project is actively maintained, as indicated by its support matrix for various Python versions.

Whether you are building a blog, an e-commerce site, or any application that requires clean and SEO-friendly URLs, Python Slugify provides a reliable and flexible solution.