Стабильность API

Django стремится к стабильности API и прямой совместимости. Короче говоря, это означает, что код, который вы разрабатываете для версии Django, будет продолжать работать с будущими выпусками. Вам может потребоваться внести незначительные изменения при обновлении версии Django, используемой вашим проектом: см. Раздел «Обратно несовместимые изменения» в разделе примечание к выпуску для версии или версий, до которых вы обновляетесь.

В то же время придавая стабильности API очень высокий приоритет, Django также стремится к постоянному совершенствованию, а также к «одному способу сделать это» (в конечном итоге) в предоставляемых нами API. Это означает, что, когда мы обнаружим явно превосходные способы ведения дел, мы устареем и в конечном итоге удалим старые способы. Наша цель - предоставить современную надежную веб-среду самого высокого качества, которая поощряет использование лучших практик во всех проектах, которые ее используют. Используя постепенные улучшения, мы стараемся избегать как стагнации, так и крупных критических обновлений.

Что значит «стабильный»

В этом контексте стабильный означает:

  • Все общедоступные API (все в этой документации) не будут перемещены или переименованы без предоставления обратно совместимых псевдонимов.

  • Если к этим API добавляются новые функции, что вполне возможно, они не нарушат и не изменят значение существующих методов. Другими словами, «стабильный» не означает (обязательно) «завершенный».

  • Если по какой-либо причине API, объявленный стабильным, должен быть удален или заменен, он будет объявлен устаревшим, но останется в API как минимум в двух выпусках функций. Предупреждения будут выпущены при вызове устаревшего метода.

    Смотрите Официальные релизы для получения дополнительной информации о том, как работает схема нумерации версий Django, и какие функции будут устаревшими.

  • Мы нарушим обратную совместимость этих API без процесса устаревания, если ошибка или дыра в безопасности делают ее совершенно неизбежной.

Стабильные API

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

Исключения

Есть несколько исключений из этого обещания стабильности и обратной совместимости.

Исправления безопасности

Если нам станет известно о проблеме безопасности - будем надеяться, что кто-то, следуя нашим правилам политика отчетности в области безопасности, – мы сделаем все необходимое для ее устранения. Это может означать нарушение обратной совместимости; безопасность превосходит гарантию совместимости.

API, помеченые как внутренние

Некоторые API явно помечены как «внутренние» несколькими способами:

  • Некоторая документация ссылается на внутренности и упоминает их как таковые. Если в документации сказано, что что-то является внутренним, мы оставляем за собой право изменить это.
  • Функции, методы и другие объекты с префиксом в начале подчеркивания (_). Это стандартный способ Python, указывающий, что что-то является приватным; если какой-либо метод начинается с одного _, это внутренний API.
Мета-документация и разное
Философии дизайна
Вернуться на верх