.. _misc-api-stability: ============ API の安定性 ============ :revision-up-to: 8961 (1.0) :ref:`Django 1.0 のリリース ` によって、 API の安定性と互換性 に一定の保証が与えられました。これはつまり、 Django 1.0 用に書いたコードは 何も変更せずに 1.1 でも動作し、以後の 1.X リリースではほんのわずかな変更し か必要ないということです。 .. _What "stable" means: APIの安定性とは =============== ここでいう「安定」とは、以下のような意味です: - 公開 API -- リンクからたどれるドキュメント内で開設されていて、メソッド 名がアンダースコアで始まらないもの -- の配置や名前を変更する場合には、 以前のバージョンとの互換性のための別名のメソッドを提供します。 - API に新たな機能を追加する場合 -- これはよくあることですが -- でも、 既存のメソッドの意味を無くしたり、変えたりすることはありません。換言す れば、「安定」していても (必ずしも) 「完全」ではない、ということです。 - すでに安定と宣言されている API を何らかの理由で削除したり移動したりせ ねばならない場合、それらのメソッドは撤廃 (deprecated) とみなされ、少な くとも二つのマイナーバージョン変更までは API 中に残します。撤廃された メソッドを呼び出した場合には警告メッセージを表示します。 Django のバージョン番号の定義と、どの機能が撤廃されているかは、 :ref:`official-releases` を参照してください。 - 深刻なバグやセキュリティホールによってやむを得ない場合に限り、これらの API に対して互換性のない変更を行います。 .. _Stable APIs: 安定な API ========== 全般的に、 :ref:`内部仕様 ` の中にあるドキュメントを除き、 ドキュメント中でカバーされている機能は、 1.0 の時点で安定な API と考えてか まいません。安定な API を以下に示します: - :ref:`認証 ` - :ref:`キャッシュ `. - :ref:`モデルの定義、マネジャ、クエリ、トランザクション ` - :ref:`e-mail の送信 `. - :ref:`アップロードファイルの操作と保存 ` - :ref:`フォーム ` - ファイルアップロード、ミドルウェア、セッション、 URL ディスパッチ、 ビュー、ショートカット API などを含む、 :ref:`HTTP リクエスト／レスポンスの操作 ` - :ref:`汎用ビュー `. - :ref:`国際化 `. - :ref:`ペジネーション ` - :ref:`シリアライゼーション ` - :ref:`シグナル ` - :ref:`テンプレート ` 。テンプレート言語、 Python の :ref:`テンプレート API ` 、 :ref:`カスタムテンプレートタグとライブラリ、 ` 今後、新たなテンプレートタグが登場すると、ユーザが定義したタグと名前 が衝突する可能性があります。そのため、新たなタグを追加するときは、同 じ名前のタグを他のテンプレートライブラリからロードしようとした時点で Django にエラーを送出させます。 - :ref:`テストフレームワーク ` - :ref:`django-admin ユーティリティ `. - :ref:`組み込みミドルウェア ` - :ref:`リクエスト／レスポンスオブジェクト `. - :ref:`設定ファイル ` 。ただし、現在の :ref:`組み込みの設定 ` はほぼ完璧だとは考えていますが、 将来新たな設定を登場させるかもしれません。これはまさに「安定」だけれ ども「完璧」ではない例ですね。 - :ref:`組み込みシグナル ` 設定と同様、将来新たなシグナル を登場させるかもしれませんが、既存のシグナルをなくすことはないでしょ う。 - :ref:`Unicode の操作 ` 。 - :ref:`HOWTO ガイド ` に書かれている内容。 .. _Exceptions: 例外 ===== 安定性や互換性の維持には、いくつか例外を設けています。 .. _Security fixes: セキュリティ上の問題の修正 ---------------------------- セキュリティ上の問題を認識した (理想的には :ref:`セキュリティレポートのポリシ ` に基づいて 報告された) 場合、必要な修正を行います。その結果、互換性が失われる可能性が あります。セキュリティ上の問題の解決は、互換性の保証よりも優先です。 コントリビュートアプリケーション (``django.contrib``) ---------------------------------------------------------- 私達は API を安定に保とうとあらゆる努力を注いでおり、現状では contrib のア プリケーションを変更するつもりはありませんが、 contrib はリリース間で変更さ れやすい分野ではあります。ウェブが進化すれば、Django もそれに合わせて進化せ ねばならないからです。 とはいえ、 contrib のアプリケーションの変更について保証していることがありま す。まず、 contrib のアプリケーションに変更を行う必要があった場合、古いバー ジョンのアプリケーションも使えるようにします。すなわち、仮に Django 1.5 で 以前のバージョンと互換性のない ``django.contrib.flatpages`` を出した場合、 Django 1.4 版の ``django.contrib.flatpages`` も Django 1.5 で使えるようにし ます。この措置によって、アップグレードを容易にします。 歴史的に、これまで ``django.contrib`` のアプリケーションはコア部分よりも安 定でした。したがって、おそらく上記のような例外的なことは起きないでしょう。 とはいえ、 ``django.contrib`` に依存してアプリケーションを開発しているなら、 覚えておくにこしたことはありません。 .. _APIs marked as internal: 内部 API ---------- API の中には、以下の二つの理由から「内部使用 (internal)」とマークされている ものがあります: - ドキュメント内で、内部使用の API について触れていることがあります。 ドキュメント上で内部使用であると書かれていれば、将来変更される余地が あると考えてください。 - アンダースコア (``_``) で始まる関数、メソッド、その他のオブジェクト。 アンダースコアを先頭に付けるのは、 Python でプライベートなものを示す のに使われる方法です。メソッドが ``_`` 一つで開始していたら、内部 API です。