When developing with Django, working with strings is a common task. Various processes, such as sanitizing user input, generating URLs, and summarizing text, are necessary. django.utils.text is a module that collects powerful and convenient utility functions for these everyday text manipulations.🧰

In this post, we will explore the most useful and frequently used core functionalities of the django.utils.text module.

1. The Perfect Converter for URLs: slugify

This function is arguably the most famous one, as it encapsulates the very reason for the module’s existence. Slug refers to a simplified version of a title or string, primarily used as part of a URL.

slugify transforms strings as follows:

  • Converts to lowercase.
  • Replaces special characters (including spaces) with hyphens (-).
  • Removes characters other than letters, digits, hyphens, and underscores (_).

Example:

from django.utils.text import slugify

title = "Django 5.0 Release! What's new?"
slug = slugify(title)

print(slug)
# Result: 'django-50-release-whats-new'
# You can now use this value in your URL like /blog/django-50-release-whats-new/.

<Important> Support for CJK Languages (Chinese, Japanese, Korean) and Unicode: By default, slugify leaves only ASCII characters. To include Unicode characters from CJK languages in the slug, you must use the allow_unicode=True option.

title_ko = "장고 유틸리티 총정리"

# Default (Korean is removed)
print(slugify(title_ko))
# Result: '' (empty string)

# Allowing Unicode
print(slugify(title_ko, allow_unicode=True))
# Result: '장고-유틸리티-총정리'

2. Creating Safe Filenames: get_valid_filename

Saving uploaded filenames directly to the server can be very dangerous. Filenames might contain characters like ../ (path traversal) or special characters (:, *, ?) that are not allowed in Windows.

get_valid_filename ensures that these risky characters or system-reserved words are replaced with safe characters (mainly underscores _) to return only valid filenames.

Example:

from django.utils.text import get_valid_filename

# A maliciously uploaded filename
user_filename = "../../secrets/pa$$word.txt"
safe_name = get_valid_filename(user_filename)

print(safe_name)
# Result: '.._.._secrets_pa__word.txt'

# System reserved characters
windows_filename = "CON:MyFile.pdf"
safe_name_2 = get_valid_filename(windows_filename)
print(safe_name_2)
# Result: '_CON_MyFile.pdf'

3. Creating Clean Summaries: truncatechars / truncatewords

These functions are often used to preview long content on blog listing pages. Although well-known as Django template filters (|truncatechars:50), you can also use these functions directly at the Python code level.

  • truncatechars(text, length): Cuts the text based on length characters (including spaces) and appends ... (default) if truncated.
  • truncatewords(text, num): Cuts the text based on num words and appends ... if truncated.

Example:

from django.utils.text import truncatechars, truncatewords

long_text = "Django is a high-level Python web framework that encourages rapid development."

# 1. Based on character count (20 characters)
summary_chars = truncatechars(long_text, 20)
print(summary_chars)
# Result: 'Django is a high-le...'

# 2. Based on word count (5 words)
summary_words = truncatewords(long_text, 5)
print(summary_words)
# Result: 'Django is a high-level Python...'

4. Capitalize the First Letter: capfirst

A simple yet surprisingly frequently used utility. It changes only the first letter of the string to uppercase. It’s useful for minor formatting, such as displaying the verbose_name of a model in templates.

Example:

from django.utils.text import capfirst

label = "user name"
formatted_label = capfirst(label)

print(formatted_label)
# Result: 'User name'

5. Converting to a Natural List: get_text_list

This converts a Python list (list) into a human-readable sentence, adding "and" (or another conjunction) before the last item.

Example:

from django.utils.text import get_text_list

# When there are multiple items (default: 'and')
items_1 = ['Apple', 'Banana', 'Cherry']
print(get_text_list(items_1))
# Result: 'Apple, Banana and Cherry'

# Changing conjunction (e.g., 'or')
items_2 = ['Email', 'SMS']
print(get_text_list(items_2, 'or'))
# Result: 'Email or SMS'

# When there is one item
items_3 = ['Django']
print(get_text_list(items_3))
# Result: 'Django'

Summary

The django.utils.text module addresses nearly all 'fine-tuning' needed for handling text in Django development. Effectively utilizing this module can lead to cleaner code and help prevent potential security issues when dealing with URLs or filenames.

In particular, slugify and get_valid_filename are essential utilities for any Django project.