Стабильность API ¶
Django стремится к стабильности API и обратной совместимости. Вкратце, это означает, что код, который вы разрабатываете для версии Django, будет продолжать работать с будущими выпусками. Возможно, вам потребуется внести незначительные изменения при обновлении версии Django, которую использует ваш проект: см. Раздел «Обратно несовместимые изменения» в примечаниях к выпуску для версии или версий, до которых вы обновляетесь.
В то же время, делая стабильность API очень важным приоритетом, Django также стремится к постоянному совершенствованию, наряду с стремлением найти «один способ сделать это» (в конечном итоге) в API, которые мы предоставляем. Это означает, что, когда мы обнаруживаем явно превосходные способы делать что-то, мы осуждаем и в конечном итоге удаляем старые способы. Наша цель - предоставить современный, надежный веб-фреймворк высочайшего качества, который поощряет лучшие практики во всех проектах, которые его используют. Используя инкрементальные улучшения, мы стараемся избежать как застоя, так и серьезных критических обновлений.
Что означает «стабильный» ¶
В этом контексте стабильный означает:
Все общедоступные API (все в этой документации) не будут перемещены или переименованы без предоставления обратно совместимых псевдонимов.
Если к этим API-интерфейсам будут добавлены новые функции, что вполне возможно, они не нарушат и не изменят значение существующих методов. Другими словами, «стабильный» не (обязательно) означает «полный».
Если по какой-либо причине API, объявленный стабильным, необходимо удалить или заменить, он будет объявлен устаревшим, но останется в API как минимум для двух выпусков функций. Предупреждения будут выдаваться при вызове устаревшего метода.
См. Официальные выпуски для получения дополнительной информации о том, как работает схема нумерации версий Django, и как функции будут устаревать.
Мы нарушим обратную совместимость этих API без процесса устаревания только в том случае, если ошибка или дыра в безопасности сделают это полностью неизбежным.
Стабильные API ¶
В общем, все, что описано в документации, за исключением внутренних компонентов, считается стабильным.
Исключения ¶
Есть несколько исключений из этого обещания стабильности и обратной совместимости.
Исправления безопасности ¶
Если нам станет известно о проблеме безопасности - надеюсь, от кого-то, кто следует нашей политике отчетности о безопасности, - мы сделаем все необходимое, чтобы ее исправить. Это может означать нарушение обратной совместимости; безопасность важнее гарантии совместимости.
API, помеченные как внутренние ¶
Некоторые API-интерфейсы явно помечены как «внутренние» двумя способами:
- Некоторая документация ссылается на внутренние компоненты и упоминает их как таковые. Если в документации указано, что что-то внутреннее, мы оставляем за собой право изменить это.
- Функции, методы и другие объекты с префиксом подчеркивания (
_). Это стандартный способ Python указать, что что-то является частным; если какой-либо метод начинается с одного_, это внутренний API.
