В процессе разработки мы часто сталкиваемся с моментами, похожими на «дежавю». Вы уверены, что знаете функцию, но, взглянув на путь `import`, понимаете, что это не та, которую вы ожидали. Для разработчиков Django `urlencode` — именно такая функция.

Те, кто уже работал с Django, знают, что `urlencode` находится в `django.utils.http`. Однако начинающие разработчики часто используют хорошо известную функцию `urllib.parse.urlencode` из стандартной библиотеки Python (я сам так делал).

Можно ли просто выбрать любую из этих функций, присутствующих как в стандартной библиотеке Python, так и в утилитах Django? Сразу скажу: **«нет»**. Ниже мы рассмотрим тонкие, но решающие различия между ними.

![a dev is being confused about choosing a method](/media/whitedec/blog_img/9215d69669ef4f36b9be389a5594ba1f.webp)

---

# Одно и то же имя, но разные результаты? Распространенные ошибки при использовании urlencode в разработке на Django

Хотя `urllib.parse.urlencode` из Python и `django.utils.http.urlencode` из Django кажутся одинаковыми по названию и назначению, версия Django является более продвинутой и предназначена для решения специфических задач веб-разработки.

## 1. Ключевые различия: краткий обзор {#sec-e4fba724ad11}

Основные различия между двумя функциями приведены в следующей таблице:

|**Признак**|**urllib.parse.urlencode**|**django.utils.http.urlencode**|
|---|---|---|
|**Принадлежность**|Стандартная библиотека Python|Встроенная утилита Django|
|**Метод реализации**|Самостоятельная реализация стандартной библиотеки|Внутренний вызов расширенной версии `urllib`|
|**Основное действие**|Преобразование словаря в строку запроса|**Оптимизировано для `QueryDict` и обработки множественных значений**|
|**Обработка списков**|Требуется опция `doseq=True`|**Безопасная обработка списков без дополнительных опций**|

---

## 2. Почему Django использует собственную версию? (Самая важная причина) {#sec-4eb8047c69f0}

У Django есть четкие причины для создания собственной версии `urlencode` вместо прямого использования стандартной библиотеки. Это связано с **надежностью** и **удобством** в веб-среде.

### Во-первых, «предохранитель» для обработки списков (множественных значений) {#sec-0927ecca7b1}

В веб-протоколах часто встречаются случаи, когда одному ключу соответствует несколько значений (например: `?tag=python&tag=django`). Стандартная версия `urllib` требует ручной установки опции `doseq=True` при кодировании списков. Если забыть об этом, сам объект списка будет преобразован в строку, что приведет к неверному результату, например, `tag=['python', 'django']`.

В то же время версия Django разработана с учетом предположения, что «в вебе списки передаются в развернутом виде», и поэтому безупречно кодирует данные списков без каких-либо дополнительных опций.

### Во-вторых, полная совместимость с `QueryDict` {#sec-fc334b880462}

Объект `request.GET` в Django — это не обычный словарь, а `QueryDict`. `QueryDict` — это специальный объект, который может содержать несколько значений для одного и того же ключа. `urlencode` в Django точно понимает особенности этого объекта и использует его внутренние методы для преобразования данных без потерь.

---

## 3. Практические примеры кодирования с использованием QueryDict {#sec-d12e4e553206}

Рассмотрим два сценария, в которых `urlencode` из Django демонстрирует свою эффективность в реальных проектах.

### Пример 1: Реализация пагинации с сохранением поисковых фильтров {#sec-6144c74d2640}

Когда необходимо сохранить несколько выбранных пользователем условий поиска при переходе между страницами, наиболее чистым решением является кодирование `request.GET` целиком.


```Python
from django.utils.http import urlencode

# Ситуация, когда пользователь ищет ?category=tech&category=life&q=django
def get_next_page_url(request):
    params = request.GET.copy()  # Копирование QueryDict
    params['page'] = 2           # Обновление только номера страницы
    
    # urlencode Django автоматически обрабатывает множественные значения QueryDict (2 категории)
    return f"/search/?{urlencode(params)}"

# Результат: /search/?category=tech&category=life&q=django&page=2
```

### Пример 2: Передача данных с множественным выбором из чекбоксов {#sec-5e6185fe793c}

Это полезно, когда необходимо закодировать данные из нескольких чекбоксов в виде словаря и передать их другому API или на другую страницу.


```Python
from django.utils.http import urlencode

data = {
    'user_id': 123,
    'selected_tags': ['python', 'backend', 'tips']
}

# В отличие от стандартного urllib, не нужно использовать doseq=True
query_string = urlencode(data)
print(query_string)

# Результат: user_id=123&selected_tags=python&selected_tags=backend&selected_tags=tips
```

---

## 4. В заключение: что выбрать? {#sec-eb673ad941be}

Критерии выбора очевидны:

1. Если вы работаете с `request.GET` или генерируете веб-URL **внутри проекта Django**?
    
    - Без колебаний используйте **`django.utils.http.urlencode`**.
        
2. Если вы пишете **независимый скрипт на Python, не связанный с Django**?
    
    - Используйте **`urllib.parse.urlencode`**, но не забудьте указать `doseq=True`, если у вас есть данные в виде списков.
        

В конечном итоге, версия Django — это «дружелюбный оберт(Wrapper)», который включает все функции стандарта и при этом минимизирует ошибки разработчиков. Помните, что даже небольшие различия могут значительно сократить время отладки!