APIの安定性とは¶

ここでいう「安定」とは、以下のような意味です:

• 公開 API – リンクからたどれるドキュメント内で開設されていて、メソッド 名がアンダースコアで始まらないもの – の配置や名前を変更する場合には、 以前のバージョンとの互換性のための別名のメソッドを提供します。

• API に新たな機能を追加する場合 – これはよくあることですが – でも、 既存のメソッドの意味を無くしたり、変えたりすることはありません。換言す れば、「安定」していても (必ずしも) 「完全」ではない、ということです。

• すでに安定と宣言されている API を何らかの理由で削除したり移動したりせ ねばならない場合、それらのメソッドは撤廃 (deprecated) とみなされ、少な くとも二つのマイナーバージョン変更までは API 中に残します。撤廃された メソッドを呼び出した場合には警告メッセージを表示します。

  Django のバージョン番号の定義と、どの機能が撤廃されているかは、 公式リリース を参照してください。

• 深刻なバグやセキュリティホールによってやむを得ない場合に限り、これらの API に対して互換性のない変更を行います。

安定な API¶

全般的に、 内部仕様 の中にあるドキュメントを除き、 ドキュメント中でカバーされている機能は、 1.0 の時点で安定な API と考えてか まいません。安定な API を以下に示します:

• 認証
• キャッシュ.
• モデルの定義、マネジャ、クエリ、トランザクション
• e-mail の送信.
• アップロードファイルの操作と保存
• フォーム
• ファイルアップロード、ミドルウェア、セッション、 URL ディスパッチ、 ビュー、ショートカット API などを含む、 HTTP リクエスト／レスポンスの操作
• 汎用ビュー.
• 国際化.
• ペジネーション
• シリアライゼーション
• シグナル
• テンプレート 。テンプレート言語、 Python の テンプレート API 、 カスタムテンプレートタグとライブラリ、 今後、新たなテンプレートタグが登場すると、ユーザが定義したタグと名前 が衝突する可能性があります。そのため、新たなタグを追加するときは、同 じ名前のタグを他のテンプレートライブラリからロードしようとした時点で Django にエラーを送出させます。
• テストフレームワーク
• django-admin ユーティリティ.
• 組み込みミドルウェア
• リクエスト／レスポンスオブジェクト.
• 設定ファイル 。ただし、現在の 組み込みの設定 はほぼ完璧だとは考えていますが、 将来新たな設定を登場させるかもしれません。これはまさに「安定」だけれ ども「完璧」ではない例ですね。
• 組み込みシグナル 設定と同様、将来新たなシグナル を登場させるかもしれませんが、既存のシグナルをなくすことはないでしょ う。
• Unicode の操作 。
• HOWTO ガイド に書かれている内容。

例外¶

安定性や互換性の維持には、いくつか例外を設けています。