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

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

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

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

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

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

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

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

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

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

Стабильные API

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

Исключения

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

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

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

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

Некоторые API-интерфейсы явно объявляются "внутренними" несколькими способами:

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

Copyright ©2020 All rights reserved